From b55465e77cdc4d42d9c38894e1866f3d916ef2ca Mon Sep 17 00:00:00 2001
From: omermorad <omer.moradd@gmail.com>
Date: Mon, 28 Sep 2026 17:44:56 +0300
Subject: [PATCH] docs: replace ASCII flows with Codo SVG diagrams

---
 README.md                             |  38 +-------
 docs/diagrams/e2e-flow.svg            | 128 ++++++++++++++++++++++++++
 docs/diagrams/repository-contract.svg |  87 +++++++++++++++++
 3 files changed, 217 insertions(+), 36 deletions(-)
 create mode 100644 docs/diagrams/e2e-flow.svg
 create mode 100644 docs/diagrams/repository-contract.svg

diff --git a/README.md b/README.md
index b88b5aa..d133ac7 100644
--- a/README.md
+++ b/README.md
@@ -4,29 +4,7 @@ A portable GitHub Action and lightweight framework for running Playwright agains
 
 It keeps the application repository in control of its tests and services while providing a consistent CI engine: deterministic runner images, smart reuse, SUT lifecycle management, test filtering, Playwright reports, traces, portable artifacts, and a fail-closed result.
 
-```text
-pull request / main / manual
-              |
-      validate e2e/ci.yml
-              |
-      hash E2E runner inputs
-              |
-       +------+------+
-       |             |
- validated cache   cache miss
-       |          build runner
-       +------+------+
-              |
-      start Dockerized SUT
-              |
-     Playwright projects + tags
-              |
-       results + traces
-              |
-     HTML report + report image
-              |
-          E2E Gate
-```
+![E2E delivery flow from pull request, main, or manual trigger through runner reuse, Dockerized SUT testing, reports, and the required gate](docs/diagrams/e2e-flow.svg)
 
 ## Start from the template
 
@@ -86,19 +64,7 @@ The action fails at the end when tests fail or infrastructure is incomplete. A c
 
 The caller keeps these files:
 
-```text
-.
-+-- compose.e2e.yml
-+-- e2e/
-|   +-- ci.yml
-|   +-- Dockerfile
-|   +-- runner-entrypoint.mjs
-|   +-- package.json
-|   +-- pnpm-lock.yaml
-|   +-- playwright.config.ts
-|   +-- tests/
-+-- sut/                         # example only; use your real services
-```
+![Repository contract showing the root Compose file, E2E configuration and tests, and replaceable system services](docs/diagrams/repository-contract.svg)
 
 `e2e/ci.yml` is the CI contract:
 
diff --git a/docs/diagrams/e2e-flow.svg b/docs/diagrams/e2e-flow.svg
new file mode 100644
index 0000000..6426346
--- /dev/null
+++ b/docs/diagrams/e2e-flow.svg
@@ -0,0 +1,128 @@
+<svg width="1240" height="700" viewBox="0 0 1240 700" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title description">
+  <title id="title">Playwright E2E delivery flow</title>
+  <desc id="description">A change enters CI, configuration and runner inputs are validated, a cached runner is reused or rebuilt, the Dockerized system is tested, and results and reports feed the E2E gate.</desc>
+  <defs>
+    <pattern id="grid" width="50" height="50" patternUnits="userSpaceOnUse">
+      <path d="M 50 0 L 0 0 0 50" fill="none" stroke="#353535" stroke-width="1"/>
+    </pattern>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#28F89A"/>
+    </marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#181818" flood-opacity="0.32"/>
+    </filter>
+    <style>
+      .heading { font: 700 22px Inter, Geist, Arial, sans-serif; letter-spacing: 1.8px; fill: #28F89A; }
+      .subtitle { font: 400 15px Inter, Geist, Arial, sans-serif; fill: #D4D4D4; }
+      .label { font: 650 17px Inter, Geist, Arial, sans-serif; fill: #F6F6F6; }
+      .detail { font: 400 13px Inter, Geist, Arial, sans-serif; fill: #D4D4D4; }
+      .chip { font: 650 12px Inter, Geist, Arial, sans-serif; fill: #181818; letter-spacing: 0.4px; }
+      .gate { font: 750 19px Inter, Geist, Arial, sans-serif; fill: #181818; }
+      .gate-detail { font: 550 12px Inter, Geist, Arial, sans-serif; fill: #2A2A2A; }
+      .connector { stroke: #28F89A; stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
+      .branch { stroke: #23E18B; stroke-width: 2.5; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
+    </style>
+  </defs>
+
+  <rect x="1" y="1" width="1238" height="698" rx="24" fill="#2A2A2A" stroke="#424242" stroke-width="2"/>
+  <rect x="1" y="1" width="1238" height="698" rx="24" fill="url(#grid)" opacity="0.72"/>
+
+  <text x="52" y="55" class="heading">E2E DELIVERY FLOW</text>
+  <text x="52" y="82" class="subtitle">One portable action from change detection to a required test result</text>
+
+  <g filter="url(#shadow)">
+    <rect x="52" y="126" width="190" height="88" rx="14" fill="#333333" stroke="#D4D4D4" stroke-width="1.5"/>
+    <text x="72" y="159" class="label">Change enters CI</text>
+    <rect x="72" y="176" width="36" height="20" rx="10" fill="#28F89A"/>
+    <text x="82" y="190" class="chip">PR</text>
+    <rect x="116" y="176" width="48" height="20" rx="10" fill="#28F89A"/>
+    <text x="126" y="190" class="chip">main</text>
+    <rect x="172" y="176" width="58" height="20" rx="10" fill="#28F89A"/>
+    <text x="179" y="190" class="chip">manual</text>
+  </g>
+
+  <path d="M242 170 H292" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="294" y="126" width="190" height="88" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="314" y="159" class="label">Validate config</text>
+    <text x="314" y="184" class="detail">profile · paths · filters</text>
+  </g>
+
+  <path d="M484 170 H534" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="536" y="126" width="200" height="88" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="556" y="159" class="label">Hash runner inputs</text>
+    <text x="556" y="184" class="detail">tests · config · dependencies</text>
+  </g>
+
+  <path d="M736 170 H786" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="788" y="126" width="400" height="88" rx="14" fill="#22332F" stroke="#28F89A" stroke-width="2"/>
+    <text x="812" y="159" class="label">Resolve the Playwright runner</text>
+    <text x="812" y="184" class="detail">Content hash chooses validated reuse or a clean build</text>
+  </g>
+
+  <path d="M900 214 V252 H842 V276" class="branch"/>
+  <path d="M1076 214 V252 H1134 V276" class="branch"/>
+
+  <g filter="url(#shadow)">
+    <rect x="744" y="278" width="196" height="82" rx="14" fill="#333333" stroke="#28F89A" stroke-width="1.5"/>
+    <text x="766" y="310" class="label">Cache hit</text>
+    <text x="766" y="334" class="detail">Validate archive + image ID</text>
+  </g>
+  <g filter="url(#shadow)">
+    <rect x="1038" y="278" width="150" height="82" rx="14" fill="#333333" stroke="#28F89A" stroke-width="1.5"/>
+    <text x="1060" y="310" class="label">Cache miss</text>
+    <text x="1060" y="334" class="detail">Build image</text>
+  </g>
+
+  <path d="M842 360 V394 H946" class="branch"/>
+  <path d="M1113 360 V394 H1028" class="branch"/>
+
+  <g filter="url(#shadow)">
+    <rect x="900" y="380" width="180" height="66" rx="33" fill="#28F89A"/>
+    <text x="927" y="407" class="gate">Portable runner</text>
+    <text x="935" y="427" class="gate-detail">exact image for this run</text>
+  </g>
+
+  <path d="M990 446 V486 H147 V516" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="52" y="518" width="190" height="92" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="72" y="552" class="label">Start the SUT</text>
+    <text x="72" y="577" class="detail">Compose build · health wait</text>
+  </g>
+  <path d="M242 564 H286" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="288" y="518" width="202" height="92" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="308" y="552" class="label">Run Playwright</text>
+    <text x="308" y="577" class="detail">projects × tags × workers</text>
+  </g>
+  <path d="M490 564 H534" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="536" y="518" width="190" height="92" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="556" y="552" class="label">Collect results</text>
+    <text x="556" y="577" class="detail">traces · logs · attachments</text>
+  </g>
+  <path d="M726 564 H770" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="772" y="518" width="206" height="92" rx="14" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <text x="792" y="552" class="label">Publish reports</text>
+    <text x="792" y="577" class="detail">HTML + portable images</text>
+  </g>
+  <path d="M978 564 H1022" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="1024" y="510" width="164" height="108" rx="18" fill="#28F89A" stroke="#23E18B" stroke-width="2"/>
+    <text x="1057" y="555" class="gate">E2E Gate</text>
+    <text x="1049" y="582" class="gate-detail">pass or fail closed</text>
+  </g>
+
+  <text x="52" y="659" class="subtitle">Every path produces the same result contract and retained debugging artifacts.</text>
+</svg>
diff --git a/docs/diagrams/repository-contract.svg b/docs/diagrams/repository-contract.svg
new file mode 100644
index 0000000..bb4829f
--- /dev/null
+++ b/docs/diagrams/repository-contract.svg
@@ -0,0 +1,87 @@
+<svg width="1200" height="560" viewBox="0 0 1200 560" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title description">
+  <title id="title">Repository contract for the Playwright E2E action</title>
+  <desc id="description">The consumer repository contains a root Compose file, an e2e directory with the execution contract and tests, and the Dockerized services under test.</desc>
+  <defs>
+    <pattern id="grid" width="50" height="50" patternUnits="userSpaceOnUse">
+      <path d="M 50 0 L 0 0 0 50" fill="none" stroke="#353535" stroke-width="1"/>
+    </pattern>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#28F89A"/>
+    </marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#181818" flood-opacity="0.32"/>
+    </filter>
+    <style>
+      .heading { font: 700 22px Inter, Geist, Arial, sans-serif; letter-spacing: 1.8px; fill: #28F89A; }
+      .subtitle { font: 400 15px Inter, Geist, Arial, sans-serif; fill: #D4D4D4; }
+      .label { font: 650 17px Inter, Geist, Arial, sans-serif; fill: #F6F6F6; }
+      .detail { font: 400 13px Inter, Geist, Arial, sans-serif; fill: #D4D4D4; }
+      .file { font: 550 13px 'Azeret Mono', 'SFMono-Regular', Consolas, monospace; fill: #F6F6F6; }
+      .type { font: 700 11px Inter, Geist, Arial, sans-serif; fill: #181818; letter-spacing: 0.7px; }
+      .connector { stroke: #28F89A; stroke-width: 2.5; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
+    </style>
+  </defs>
+
+  <rect x="1" y="1" width="1198" height="558" rx="24" fill="#2A2A2A" stroke="#424242" stroke-width="2"/>
+  <rect x="1" y="1" width="1198" height="558" rx="24" fill="url(#grid)" opacity="0.72"/>
+
+  <text x="50" y="53" class="heading">REPOSITORY CONTRACT</text>
+  <text x="50" y="80" class="subtitle">The action is portable; the consuming repository owns these paths and their contents</text>
+
+  <g filter="url(#shadow)">
+    <rect x="425" y="110" width="350" height="68" rx="16" fill="#22332F" stroke="#28F89A" stroke-width="2"/>
+    <text x="451" y="140" class="label">Consumer repository</text>
+    <text x="451" y="161" class="detail">checked out before the action runs</text>
+  </g>
+
+  <path d="M600 178 V220 H178 V248" class="connector"/>
+  <path d="M600 178 V248" class="connector"/>
+  <path d="M600 178 V220 H1022 V248" class="connector"/>
+
+  <g filter="url(#shadow)">
+    <rect x="48" y="250" width="260" height="174" rx="16" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <rect x="68" y="270" width="58" height="22" rx="11" fill="#28F89A"/>
+    <text x="80" y="285" class="type">ROOT</text>
+    <text x="68" y="326" class="label">Compose topology</text>
+    <rect x="68" y="346" width="220" height="42" rx="9" fill="#424242"/>
+    <text x="84" y="372" class="file">compose.e2e.yml</text>
+    <text x="68" y="408" class="detail">Build, health, and service graph</text>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="330" y="250" width="540" height="258" rx="16" fill="#333333" stroke="#28F89A" stroke-width="1.5"/>
+    <rect x="350" y="270" width="92" height="22" rx="11" fill="#28F89A"/>
+    <text x="365" y="285" class="type">E2E DIR</text>
+    <text x="350" y="326" class="label">Runner, policy, and tests</text>
+
+    <rect x="350" y="346" width="150" height="42" rx="9" fill="#424242"/>
+    <text x="366" y="372" class="file">ci.yml</text>
+    <rect x="516" y="346" width="150" height="42" rx="9" fill="#424242"/>
+    <text x="532" y="372" class="file">Dockerfile</text>
+    <rect x="682" y="346" width="168" height="42" rx="9" fill="#424242"/>
+    <text x="698" y="372" class="file">runner-entrypoint</text>
+
+    <rect x="350" y="402" width="150" height="42" rx="9" fill="#424242"/>
+    <text x="366" y="428" class="file">package.json</text>
+    <rect x="516" y="402" width="150" height="42" rx="9" fill="#424242"/>
+    <text x="532" y="428" class="file">pnpm-lock.yaml</text>
+    <rect x="682" y="402" width="168" height="42" rx="9" fill="#424242"/>
+    <text x="698" y="428" class="file">playwright.config</text>
+
+    <rect x="350" y="458" width="500" height="30" rx="9" fill="#22332F" stroke="#28F89A"/>
+    <text x="366" y="479" class="file">tests/</text>
+    <text x="440" y="479" class="detail">suites · fixtures · helpers</text>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="892" y="250" width="260" height="174" rx="16" fill="#333333" stroke="#424242" stroke-width="1.5"/>
+    <rect x="912" y="270" width="60" height="22" rx="11" fill="#28F89A"/>
+    <text x="926" y="285" class="type">SUT</text>
+    <text x="912" y="326" class="label">System services</text>
+    <rect x="912" y="346" width="220" height="42" rx="9" fill="#424242"/>
+    <text x="928" y="372" class="file">sut/</text>
+    <text x="912" y="408" class="detail">Example only; use real services</text>
+  </g>
+
+  <text x="50" y="533" class="subtitle">The directory name and manifest path stay stable; implementation details remain application-owned.</text>
+</svg>