From 8842e2d2ca5d0b1edb330d8fa1097991e9ba379f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:04:38 +0200
Subject: [PATCH 01/78] feat(shared): let connector actions carry titles in
 every language

An action declares an English title and per-locale overrides
(i18n.<locale>.title), and a connector named with ordinary words its
localized display names (i18n.<locale>.displayName), on the locale
grammar every declared text already uses.
---
 .../shared/src/schemas/connectors.test.ts     | 56 +++++++++++++++++++
 packages/shared/src/schemas/connectors.ts     | 31 ++++++++++
 2 files changed, 87 insertions(+)

diff --git a/packages/shared/src/schemas/connectors.test.ts b/packages/shared/src/schemas/connectors.test.ts
index c919321257..dce944f3fe 100644
--- a/packages/shared/src/schemas/connectors.test.ts
+++ b/packages/shared/src/schemas/connectors.test.ts
@@ -207,6 +207,62 @@ describe('connectorSchema', () => {
     ).toBe(false);
   });
 
+  it('accepts an action title with per-locale overrides', () => {
+    const github = connectorSchema.parse(GITHUB);
+    const [create] = github.actions;
+    const titled = connectorSchema.parse({
+      ...github,
+      actions: [
+        {
+          ...create,
+          title: 'Create issue',
+          i18n: {
+            de: { title: 'Issue erstellen' },
+            fr: { title: 'Créer une issue' },
+            'de-CH': { title: 'Issue erstellen' },
+          },
+        },
+      ],
+    });
+    expect(titled.actions[0]?.title).toBe('Create issue');
+    expect(titled.actions[0]?.i18n?.fr?.title).toBe('Créer une issue');
+    // Untitled stays valid: a surface falls back to the action name.
+    expect(github.actions[0]?.title).toBeUndefined();
+  });
+
+  it.each([
+    ['a blank title', { title: '' }],
+    [
+      'a locale key outside the tag grammar',
+      { i18n: { german: { title: 'x' } } },
+    ],
+    ['an unknown key inside a locale', { i18n: { de: { label: 'x' } } }],
+    ['a title past 80 characters', { title: 'x'.repeat(81) }],
+  ])('refuses %s on an action', (_case, extra) => {
+    const github = connectorSchema.parse(GITHUB);
+    expect(
+      connectorSchema.safeParse({
+        ...github,
+        actions: [{ ...github.actions[0], ...extra }],
+      }).success,
+    ).toBe(false);
+  });
+
+  it('accepts per-locale display names on the connector, and only those', () => {
+    const mailbox = connectorSchema.parse(MAILBOX);
+    const named = connectorSchema.parse({
+      ...mailbox,
+      i18n: { de: { displayName: 'Postfach' }, fr: { displayName: 'Boîte' } },
+    });
+    expect(named.i18n?.de?.displayName).toBe('Postfach');
+    expect(
+      connectorSchema.safeParse({
+        ...mailbox,
+        i18n: { de: { description: 'Ein Postfach' } },
+      }).success,
+    ).toBe(false);
+  });
+
   it('requires a mock on every action', () => {
     const github = connectorSchema.parse(GITHUB);
     const noMock = {
diff --git a/packages/shared/src/schemas/connectors.ts b/packages/shared/src/schemas/connectors.ts
index afe7cc3638..b8fc22cb1c 100644
--- a/packages/shared/src/schemas/connectors.ts
+++ b/packages/shared/src/schemas/connectors.ts
@@ -49,6 +49,16 @@ const actionNameSchema = z
 
 const displayNameSchema = z.string().min(1).max(200);
 
+/** Locale keys of the per-entry `i18n` channels (`de`, `fr`, `de-CH`) — the
+ * grammar every declared text uses, as in the automation settings forms and
+ * the pack manifest. */
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+/** An action named for a person: a short verb phrase in sentence case
+ * ("List issues"), without the connector's name — a surface shows it beside
+ * the connector's display name ("GitHub · List issues"). */
+const actionTitleSchema = z.string().min(1).max(80);
+
 /**
  * The auth methods a connector accepts — discriminated on `method`, MULTIPLE
  * per connector, decoupled from the actions. A credential row references one
@@ -183,6 +193,18 @@ const jsonSchemaObjectSchema = z
 export const connectorActionSchema = z
   .object({
     name: actionNameSchema,
+    /** The action in words, in English. A surface without one shows the
+     * humanized action name instead. */
+    title: actionTitleSchema.optional(),
+    /** Per-locale overrides of `title`. The chain every declared text
+     * follows: the exact tag (`de-CH`), then its base language (`de`), then
+     * the English `title`. */
+    i18n: z
+      .record(
+        z.string().regex(LOCALE_RE),
+        z.object({ title: actionTitleSchema.optional() }).strict(),
+      )
+      .optional(),
     description: z.string().min(1).max(2000),
     /** JSON Schema for the action's `input` — machine-validated. */
     input: jsonSchemaObjectSchema,
@@ -211,6 +233,15 @@ export const connectorSchema = z
   .object({
     name: slugSchema,
     displayName: displayNameSchema,
+    /** Per-locale overrides of `displayName`, for a connector named with
+     * ordinary words ("Tasks") rather than a brand ("GitHub"), which keeps its
+     * name in every language. Same locale chain as an action's `title`. */
+    i18n: z
+      .record(
+        z.string().regex(LOCALE_RE),
+        z.object({ displayName: displayNameSchema.optional() }).strict(),
+      )
+      .optional(),
     description: z.string().min(1).max(2000),
     /** Grouping labels for the catalog (open vocabulary). */
     tags: z.array(z.string().min(1).max(64)).default([]),

From 880b651cfced46b68776937169871f46c1ff4e30 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:04:47 +0200
Subject: [PATCH 02/78] feat(platform): name connector actions in English,
 German and French
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each of the 121 shipped connector actions gets a sentence-case title
with German and French overrides, and the seven connectors named with
ordinary words (Tasks, Documents, Conversations, …) their German and
French display names. A guard fails a shipped action without its
titles, a sloppy one, a duplicate, and a new connector that is neither
a listed brand nor translated.
---
 .../connectors/confluence/connector.yml       |  12 +
 .../connectors/conversation/connector.yml     |  53 ++++
 .../system/connectors/discord/connector.yml   |  48 ++++
 .../system/connectors/document/connector.yml  |  17 ++
 .../system/connectors/github/connector.yml    | 132 +++++++++
 .../system/connectors/glitchtip/connector.yml |  18 ++
 .../system/connectors/gmail/connector.yml     |  60 +++++
 .../connectors/google-drive/connector.yml     |  12 +
 .../system/connectors/imap-smtp/connector.yml |  23 ++
 .../system/connectors/jev/connector.yml       |  11 +
 .../system/connectors/outlook/connector.yml   |  66 +++++
 .../system/connectors/sandbox/connector.yml   |  11 +
 .../system/connectors/shopify/connector.yml   |  54 ++++
 .../system/connectors/slack/connector.yml     |  42 +++
 .../system/connectors/task/connector.yml      |  65 +++++
 .../system/connectors/tavily/connector.yml    |  12 +
 .../system/connectors/teams/connector.yml     |  54 ++++
 .../system/connectors/twilio/connector.yml    |  42 +++
 .../system/connectors/webdav/connector.yml    |  29 ++
 .../lib/connectors/action-titles.test.ts      | 255 ++++++++++++++++++
 20 files changed, 1016 insertions(+)
 create mode 100644 services/platform/lib/connectors/action-titles.test.ts

diff --git a/configs/platform/system/connectors/confluence/connector.yml b/configs/platform/system/connectors/confluence/connector.yml
index 9993b3961e..411ffca78d 100644
--- a/configs/platform/system/connectors/confluence/connector.yml
+++ b/configs/platform/system/connectors/confluence/connector.yml
@@ -16,6 +16,12 @@ auth:
   - method: basic
 actions:
   - name: list_pages
+    title: List pages
+    i18n:
+      de:
+        title: Seiten auflisten
+      fr:
+        title: Lister les pages
     description: >-
       List a Confluence space's pages. Cursor pagination is handled internally
       (soft-capped; `truncated: true` beyond the cap). Archived pages are
@@ -141,6 +147,12 @@ actions:
         };
     exampleInput: { spaceKey: 'ENG' }
   - name: get_page
+    title: Get page
+    i18n:
+      de:
+        title: Seite abrufen
+      fr:
+        title: Récupérer une page
     description: >-
       Fetch a single page's rendered content by pageId, convert it to plain
       text, and store it as a text/plain file.
diff --git a/configs/platform/system/connectors/conversation/connector.yml b/configs/platform/system/connectors/conversation/connector.yml
index f3e3c47559..ffe894df7a 100644
--- a/configs/platform/system/connectors/conversation/connector.yml
+++ b/configs/platform/system/connectors/conversation/connector.yml
@@ -4,6 +4,11 @@
 # in one place. `platform` auth — nothing to connect.
 name: conversation
 displayName: Conversations
+i18n:
+  de:
+    displayName: Konversationen
+  fr:
+    displayName: Conversations
 description: >-
   Pull mailbox traffic into the org Inbox and expose a one-shot sync and a
   multi-credential inbox list for scheduled mail packs.
@@ -14,6 +19,12 @@ auth:
   - method: platform
 actions:
   - name: sync_mailbox
+    title: Sync mailboxes
+    i18n:
+      de:
+        title: Postfächer synchronisieren
+      fr:
+        title: Synchroniser les boîtes mail
     description: >-
       List new messages from every active credential on the named mail
       connector, fetch each body, and ingest them into conversations (inbound
@@ -50,6 +61,12 @@ actions:
       impl: conversation.sync_mailbox
     exampleInput: { connectorSlug: 'imap-smtp', limit: 25 }
   - name: list_mailbox_messages
+    title: List mailbox messages
+    i18n:
+      de:
+        title: Nachrichten der Postfächer auflisten
+      fr:
+        title: Lister les messages des boîtes mail
     description: >-
       List the newest inbox messages from every active credential on the named
       mail connector — what triage digests over. IMAP UIDs are scoped per
@@ -87,6 +104,12 @@ actions:
       impl: conversation.list_mailbox_messages
     exampleInput: { connectorSlug: 'imap-smtp', limit: 25 }
   - name: list_untriaged
+    title: List untriaged conversations
+    i18n:
+      de:
+        title: Nicht triagierte Konversationen auflisten
+      fr:
+        title: Lister les conversations à trier
     description: >-
       List the open Inbox conversations of one mail connector that are waiting
       on the team — the newest message is the customer's — and that no triage
@@ -128,6 +151,12 @@ actions:
       impl: conversation.list_untriaged
     exampleInput: { connectorSlug: 'gmail', limit: 25 }
   - name: record_triage
+    title: Record triage
+    i18n:
+      de:
+        title: Triage festhalten
+      fr:
+        title: Enregistrer le triage
     description: >-
       Record a triage pass on Inbox conversations: the verdict is stamped on
       each conversation, and its priority is set where no person has set one.
@@ -180,6 +209,12 @@ actions:
           ],
       }
   - name: ingest_emails
+    title: Import received emails
+    i18n:
+      de:
+        title: Empfangene E-Mails importieren
+      fr:
+        title: Importer les e-mails reçus
     description: Ingest already-fetched inbound emails into conversations.
     effects: write
     input:
@@ -222,6 +257,12 @@ actions:
           ],
       }
   - name: ingest_sent_emails
+    title: Import sent emails
+    i18n:
+      de:
+        title: Gesendete E-Mails importieren
+      fr:
+        title: Importer les e-mails envoyés
     description: Ingest already-fetched Sent-folder emails into conversations.
     effects: write
     input:
@@ -265,6 +306,12 @@ actions:
           ],
       }
   - name: draft_reply
+    title: Draft reply
+    i18n:
+      de:
+        title: Antwortentwurf erstellen
+      fr:
+        title: Rédiger un brouillon de réponse
     description: >-
       Propose a reply on a conversation and leave it for a person. The draft
       appears in the Inbox as a pending message; sending it is a human act, and
@@ -301,6 +348,12 @@ actions:
         body: 'Yes, we still have it in stock. Would you like us to hold one?',
       }
   - name: query_sync_cursor
+    title: Get last sync time
+    i18n:
+      de:
+        title: Zeitpunkt der letzten Synchronisierung abrufen
+      fr:
+        title: Récupérer l’heure de la dernière synchronisation
     description: The latest synced message timestamp for a mailbox direction.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/discord/connector.yml b/configs/platform/system/connectors/discord/connector.yml
index cdddb65e56..a7a40741b4 100644
--- a/configs/platform/system/connectors/discord/connector.yml
+++ b/configs/platform/system/connectors/discord/connector.yml
@@ -19,6 +19,12 @@ auth:
     scheme: Bot
 actions:
   - name: list_guilds
+    title: List servers
+    i18n:
+      de:
+        title: Server auflisten
+      fr:
+        title: Lister les serveurs
     description: List the guilds (servers) the bot is a member of.
     effects: read
     input:
@@ -46,6 +52,12 @@ actions:
         return { guilds: r.json() };
     exampleInput: { limit: 50 }
   - name: get_guild
+    title: Get server
+    i18n:
+      de:
+        title: Server abrufen
+      fr:
+        title: Récupérer un serveur
     description: Get a single guild (server) by ID.
     effects: read
     input:
@@ -66,6 +78,12 @@ actions:
         return { guild: r.json() };
     exampleInput: { guild_id: '100000000000000001' }
   - name: list_channels
+    title: List channels
+    i18n:
+      de:
+        title: Kanäle auflisten
+      fr:
+        title: Lister les salons
     description: List all channels in a guild.
     effects: read
     input:
@@ -86,6 +104,12 @@ actions:
         return { channels: r.json() };
     exampleInput: { guild_id: '100000000000000001' }
   - name: list_messages
+    title: List messages
+    i18n:
+      de:
+        title: Nachrichten auflisten
+      fr:
+        title: Lister les messages
     description: Fetch recent messages from a channel.
     effects: read
     input:
@@ -120,6 +144,12 @@ actions:
         return { messages: r.json() };
     exampleInput: { channel_id: '300000000000000001', limit: 20 }
   - name: send_message
+    title: Send message
+    i18n:
+      de:
+        title: Nachricht senden
+      fr:
+        title: Envoyer un message
     description: Send a message to a channel.
     effects: write
     input:
@@ -154,6 +184,12 @@ actions:
     exampleInput:
       { channel_id: '300000000000000001', content: 'Deploy finished ✅' }
   - name: get_user
+    title: Get user
+    i18n:
+      de:
+        title: Benutzer abrufen
+      fr:
+        title: Récupérer un utilisateur
     description: Get a Discord user by ID.
     effects: read
     input:
@@ -174,6 +210,12 @@ actions:
         return { user: r.json() };
     exampleInput: { user_id: '200000000000000001' }
   - name: list_members
+    title: List members
+    i18n:
+      de:
+        title: Mitglieder auflisten
+      fr:
+        title: Lister les membres
     description: List the members of a guild.
     effects: read
     input:
@@ -202,6 +244,12 @@ actions:
         return { members: r.json() };
     exampleInput: { guild_id: '100000000000000001', limit: 100 }
   - name: create_channel
+    title: Create channel
+    i18n:
+      de:
+        title: Kanal erstellen
+      fr:
+        title: Créer un salon
     description: Create a new channel in a guild.
     effects: write
     input:
diff --git a/configs/platform/system/connectors/document/connector.yml b/configs/platform/system/connectors/document/connector.yml
index bcc557f5c3..67fc7649ea 100644
--- a/configs/platform/system/connectors/document/connector.yml
+++ b/configs/platform/system/connectors/document/connector.yml
@@ -3,6 +3,11 @@
 # text) into a folder as a visible document. Native-backed; `platform` auth.
 name: document
 displayName: Documents
+i18n:
+  de:
+    displayName: Dokumente
+  fr:
+    displayName: Documents
 description: >-
   List a folder's stored files and file produced artifacts into folders —
   the platform's own document tree as automation steps.
@@ -12,6 +17,12 @@ auth:
   - method: platform
 actions:
   - name: list
+    title: List files in folder
+    i18n:
+      de:
+        title: Dateien im Ordner auflisten
+      fr:
+        title: Lister les fichiers d’un dossier
     description: >-
       The files stored inside one folder — direct children by default;
       recursive walks the subfolder tree and prefixes each file name with its
@@ -49,6 +60,12 @@ actions:
       impl: document.list
     exampleInput: { folderId: 'fld_1' }
   - name: create
+    title: Save document to folder
+    i18n:
+      de:
+        title: Dokument im Ordner ablegen
+      fr:
+        title: Enregistrer un document dans un dossier
     description: >-
       File a document into a folder: claim a harvested blob by storageId, or
       store inline text. Idempotent per (folder, name) — re-running refreshes
diff --git a/configs/platform/system/connectors/github/connector.yml b/configs/platform/system/connectors/github/connector.yml
index 165d563aa2..f560c99683 100644
--- a/configs/platform/system/connectors/github/connector.yml
+++ b/configs/platform/system/connectors/github/connector.yml
@@ -14,6 +14,12 @@ auth:
   - method: bearer
 actions:
   - name: list_repos
+    title: List repositories
+    i18n:
+      de:
+        title: Repositories auflisten
+      fr:
+        title: Lister les dépôts
     description: List repositories for the authenticated user.
     effects: read
     input:
@@ -46,6 +52,12 @@ actions:
         return { repos: r.json() };
     exampleInput: { visibility: 'all', per_page: 20 }
   - name: get_repo
+    title: Get repository
+    i18n:
+      de:
+        title: Repository abrufen
+      fr:
+        title: Récupérer un dépôt
     description: Get a single repository by owner and name.
     effects: read
     input:
@@ -70,6 +82,12 @@ actions:
         return { repo: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world' }
   - name: list_issues
+    title: List issues
+    i18n:
+      de:
+        title: Issues auflisten
+      fr:
+        title: Lister les issues
     description: List issues for a repository.
     effects: read
     input:
@@ -115,6 +133,12 @@ actions:
         return { issues: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', state: 'open' }
   - name: get_issue
+    title: Get issue
+    i18n:
+      de:
+        title: Issue abrufen
+      fr:
+        title: Récupérer une issue
     description: Get a single issue by number.
     effects: read
     input:
@@ -140,6 +164,12 @@ actions:
         return { issue: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', issue_number: 1 }
   - name: create_issue
+    title: Create issue
+    i18n:
+      de:
+        title: Issue erstellen
+      fr:
+        title: Créer une issue
     description: Create a new issue in a repository.
     effects: write
     input:
@@ -179,6 +209,12 @@ actions:
     exampleInput:
       { owner: 'octocat', repo: 'hello-world', title: 'Something is broken' }
   - name: list_pull_requests
+    title: List pull requests
+    i18n:
+      de:
+        title: Pull Requests auflisten
+      fr:
+        title: Lister les pull requests
     description: List pull requests for a repository.
     effects: read
     input:
@@ -229,6 +265,12 @@ actions:
         return { pull_requests: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', state: 'open' }
   - name: get_pull_request
+    title: Get pull request
+    i18n:
+      de:
+        title: Pull Request abrufen
+      fr:
+        title: Récupérer une pull request
     description: Get a single pull request by number.
     effects: read
     input:
@@ -254,6 +296,12 @@ actions:
         return { pull_request: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', pull_number: 1 }
   - name: create_pull_request
+    title: Create pull request
+    i18n:
+      de:
+        title: Pull Request erstellen
+      fr:
+        title: Créer une pull request
     description: Create a new pull request in a repository.
     effects: write
     input:
@@ -301,6 +349,12 @@ actions:
         base: 'main',
       }
   - name: merge_pull_request
+    title: Merge pull request
+    i18n:
+      de:
+        title: Pull Request mergen
+      fr:
+        title: Fusionner une pull request
     description: Merge a pull request into its base branch.
     effects: write
     input:
@@ -348,6 +402,12 @@ actions:
         merge_method: 'squash',
       }
   - name: get_pull_request_files
+    title: List pull request files
+    i18n:
+      de:
+        title: Dateien eines Pull Requests auflisten
+      fr:
+        title: Lister les fichiers d’une pull request
     description: List the files changed in a pull request (filename, status, additions, deletions, patch).
     effects: read
     input:
@@ -374,6 +434,12 @@ actions:
         return { files: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', pull_number: 1 }
   - name: get_pull_request_diff
+    title: Get pull request diff
+    i18n:
+      de:
+        title: Diff eines Pull Requests abrufen
+      fr:
+        title: Récupérer le diff d’une pull request
     description: Get the raw unified diff for a pull request.
     effects: read
     input:
@@ -395,6 +461,12 @@ actions:
         return { diff: r.text() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', pull_number: 1 }
   - name: create_pull_request_review
+    title: Submit pull request review
+    i18n:
+      de:
+        title: Review für einen Pull Request abgeben
+      fr:
+        title: Envoyer une revue de pull request
     description: Submit a review on a pull request (APPROVE, REQUEST_CHANGES, or COMMENT) with an optional body and inline comments.
     effects: write
     input:
@@ -444,6 +516,12 @@ actions:
         event: 'APPROVE',
       }
   - name: create_pull_request_review_comment
+    title: Add review comment
+    i18n:
+      de:
+        title: Review-Kommentar hinzufügen
+      fr:
+        title: Ajouter un commentaire de revue
     description: Add a single inline comment on a line of a pull request diff.
     effects: write
     input:
@@ -485,6 +563,12 @@ actions:
         path: 'src/index.ts',
       }
   - name: list_issue_comments
+    title: List issue comments
+    i18n:
+      de:
+        title: Kommentare eines Issues auflisten
+      fr:
+        title: Lister les commentaires d’une issue
     description: List comments on an issue or pull request conversation.
     effects: read
     input:
@@ -512,6 +596,12 @@ actions:
         return { comments: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world', issue_number: 1 }
   - name: create_issue_comment
+    title: Comment on issue
+    i18n:
+      de:
+        title: Issue kommentieren
+      fr:
+        title: Commenter une issue
     description: Add a comment to an issue or pull request conversation.
     effects: write
     input:
@@ -543,6 +633,12 @@ actions:
         body: 'Thanks for the report!',
       }
   - name: update_issue
+    title: Update issue
+    i18n:
+      de:
+        title: Issue aktualisieren
+      fr:
+        title: Mettre à jour une issue
     description: Update an issue's title, body, state, labels, assignees, or milestone.
     effects: write
     input:
@@ -584,6 +680,12 @@ actions:
         state: 'closed',
       }
   - name: add_labels_to_issue
+    title: Add labels to issue
+    i18n:
+      de:
+        title: Labels zu einem Issue hinzufügen
+      fr:
+        title: Ajouter des étiquettes à une issue
     description: Add labels to an issue or pull request (additive, does not remove existing labels).
     effects: write
     input:
@@ -614,6 +716,12 @@ actions:
         labels: ['bug', 'triage'],
       }
   - name: list_commits
+    title: List commits
+    i18n:
+      de:
+        title: Commits auflisten
+      fr:
+        title: Lister les commits
     description: List commits for a repository.
     effects: read
     input:
@@ -648,6 +756,12 @@ actions:
         return { commits: r.json() };
     exampleInput: { owner: 'octocat', repo: 'hello-world' }
   - name: search_code
+    title: Search code
+    i18n:
+      de:
+        title: Code durchsuchen
+      fr:
+        title: Rechercher du code
     description: Search for code across GitHub repositories.
     effects: read
     input:
@@ -676,6 +790,12 @@ actions:
         return { total_count: j.total_count, items: j.items };
     exampleInput: { q: 'addEventListener repo:octocat/hello-world' }
   - name: list_import_issues
+    title: List issues to import
+    i18n:
+      de:
+        title: Issues für den Import auflisten
+      fr:
+        title: Lister les issues à importer
     description: Read matching issues for task intake. Follows up to 20 pages per run, returning an opaque nextCursor for continuation without skipping a partially consumed page.
     effects: read
     input:
@@ -699,6 +819,12 @@ actions:
       impl: github.list_import_issues
     exampleInput: { owner: example, repo: web, limit: 100 }
   - name: get_import_issue
+    title: Refresh imported issue
+    i18n:
+      de:
+        title: Importiertes Issue aktualisieren
+      fr:
+        title: Actualiser une issue importée
     description: Refresh a previously imported issue by immutable source identity, including closed or resolved issues outside the discovery filter. Marks a missing source unavailable without changing its Tale task.
     effects: read
     input:
@@ -723,6 +849,12 @@ actions:
         externalId: example/web#1
         externalIssue: { id: '1', title: Example, description: Details, url: 'https://example.com/issues/1', state: open, syncedAt: 0 }
   - name: refresh_import_issues
+    title: Refresh imported issues
+    i18n:
+      de:
+        title: Importierte Issues aktualisieren
+      fr:
+        title: Actualiser les issues importées
     description: Refresh up to 500 linked source snapshots with bounded request concurrency. Closed and unavailable issues remain linked to their existing Tale tasks.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/glitchtip/connector.yml b/configs/platform/system/connectors/glitchtip/connector.yml
index 61f403273e..662e6fbd62 100644
--- a/configs/platform/system/connectors/glitchtip/connector.yml
+++ b/configs/platform/system/connectors/glitchtip/connector.yml
@@ -12,6 +12,12 @@ auth:
   - method: bearer
 actions:
   - name: list_import_issues
+    title: List issues to import
+    i18n:
+      de:
+        title: Issues für den Import auflisten
+      fr:
+        title: Lister les issues à importer
     description: Read matching issues for task intake. Follows up to 20 pages per run, returning an opaque nextCursor for continuation without skipping a partially consumed page.
     effects: read
     input:
@@ -35,6 +41,12 @@ actions:
       impl: glitchtip.list_import_issues
     exampleInput: { organization: example, project: web, limit: 100 }
   - name: get_import_issue
+    title: Refresh imported issue
+    i18n:
+      de:
+        title: Importiertes Issue aktualisieren
+      fr:
+        title: Actualiser une issue importée
     description: Refresh a previously imported issue by immutable source identity, including closed or resolved issues outside the discovery filter. Marks a missing source unavailable without changing its Tale task.
     effects: read
     input:
@@ -59,6 +71,12 @@ actions:
         externalId: example/web#1
         externalIssue: { id: '1', title: Example, description: Details, url: 'https://example.com/issues/1', state: open, syncedAt: 0 }
   - name: refresh_import_issues
+    title: Refresh imported issues
+    i18n:
+      de:
+        title: Importierte Issues aktualisieren
+      fr:
+        title: Actualiser les issues importées
     description: Refresh up to 500 linked source snapshots with bounded request concurrency. Closed and unavailable issues remain linked to their existing Tale tasks.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/gmail/connector.yml b/configs/platform/system/connectors/gmail/connector.yml
index 997e16232e..727503be39 100644
--- a/configs/platform/system/connectors/gmail/connector.yml
+++ b/configs/platform/system/connectors/gmail/connector.yml
@@ -23,6 +23,12 @@ auth:
       - https://www.googleapis.com/auth/gmail.modify
 actions:
   - name: list_messages
+    title: List messages
+    i18n:
+      de:
+        title: Nachrichten auflisten
+      fr:
+        title: Lister les messages
     description: List message and thread IDs from the mailbox, optionally filtered by a Gmail search query or labels. Draft messages are excluded.
     effects: read
     input:
@@ -58,6 +64,12 @@ actions:
         return { messages: j.messages || [], nextPageToken: j.nextPageToken || '' };
     exampleInput: { q: 'is:unread', maxResults: 25 }
   - name: get_message
+    title: Get message
+    i18n:
+      de:
+        title: Nachricht abrufen
+      fr:
+        title: Récupérer un message
     description: Fetch a single email message by ID with full headers, body, and attachment metadata. Optionally download and store all attachments.
     effects: read
     input:
@@ -108,6 +120,12 @@ actions:
         return { message, attachments };
     exampleInput: { messageId: '18c1a2b3c4d5e6f7', format: 'full' }
   - name: get_attachments
+    title: Download attachments
+    i18n:
+      de:
+        title: Anhänge herunterladen
+      fr:
+        title: Télécharger les pièces jointes
     description: Download every file attachment on a message and store each one. Returns a fileId and URL per attachment.
     effects: read
     input:
@@ -149,6 +167,12 @@ actions:
         return { attachments };
     exampleInput: { messageId: '18c1a2b3c4d5e6f7' }
   - name: search_messages
+    title: Search messages
+    i18n:
+      de:
+        title: Nachrichten durchsuchen
+      fr:
+        title: Rechercher des messages
     description: Search messages using Gmail query syntax and return the matching message and thread IDs.
     effects: read
     input:
@@ -179,6 +203,12 @@ actions:
         return { messages: j.messages || [], nextPageToken: j.nextPageToken || '' };
     exampleInput: { query: 'subject:invoice has:attachment', maxResults: 25 }
   - name: send_message
+    title: Send email
+    i18n:
+      de:
+        title: E-Mail senden
+      fr:
+        title: Envoyer un e-mail
     description: Compose and send an email message via Gmail. Supports replying into a thread and sending with file attachments.
     effects: write
     input:
@@ -275,6 +305,12 @@ actions:
         body: 'This is a test message.',
       }
   - name: get_profile
+    title: Get mailbox address
+    i18n:
+      de:
+        title: Adresse des Postfachs abrufen
+      fr:
+        title: Récupérer l’adresse de la boîte mail
     description: The address of the connected mailbox (the account the credential authorizes), as the mail sync reads it to tell the mailbox's own mail from a customer's.
     effects: read
     input:
@@ -292,6 +328,12 @@ actions:
         return { emailAddress: String(j.emailAddress || '') };
     exampleInput: {}
   - name: list_labels
+    title: List labels
+    i18n:
+      de:
+        title: Labels auflisten
+      fr:
+        title: Lister les libellés
     description: List all labels in the mailbox, including system labels (INBOX, SENT, etc.) and user-created labels.
     effects: read
     input:
@@ -309,6 +351,12 @@ actions:
         return { labels: j.labels || [] };
     exampleInput: {}
   - name: get_thread
+    title: Get thread
+    i18n:
+      de:
+        title: E-Mail-Verlauf abrufen
+      fr:
+        title: Récupérer un fil de discussion
     description: Fetch a complete email thread (conversation) with all of its messages.
     effects: read
     input:
@@ -333,6 +381,12 @@ actions:
         return { thread: r.json() };
     exampleInput: { threadId: '18c1a2b3c4d5e6f7' }
   - name: list_drafts
+    title: List drafts
+    i18n:
+      de:
+        title: Entwürfe auflisten
+      fr:
+        title: Lister les brouillons
     description: List draft messages in the mailbox.
     effects: read
     input:
@@ -359,6 +413,12 @@ actions:
         return { drafts: j.drafts || [], nextPageToken: j.nextPageToken || '' };
     exampleInput: { maxResults: 25 }
   - name: get_attachment
+    title: Download attachment
+    i18n:
+      de:
+        title: Anhang herunterladen
+      fr:
+        title: Télécharger une pièce jointe
     description: Download a single email attachment by message ID and attachment ID, storing it through file storage.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/google-drive/connector.yml b/configs/platform/system/connectors/google-drive/connector.yml
index ecc2de5f8b..64365d5cac 100644
--- a/configs/platform/system/connectors/google-drive/connector.yml
+++ b/configs/platform/system/connectors/google-drive/connector.yml
@@ -19,6 +19,12 @@ auth:
       - https://www.googleapis.com/auth/drive.readonly
 actions:
   - name: list_files
+    title: List files
+    i18n:
+      de:
+        title: Dateien auflisten
+      fr:
+        title: Lister les fichiers
     description: List files in a Google Drive folder. Pagination is handled internally — the operation returns the complete file list in one call. When recursive is true, subfolders are traversed breadth-first and each file's relative path is reported as subfolderPath.
     effects: read
     input:
@@ -113,6 +119,12 @@ actions:
         return { files, truncated };
     exampleInput: { folderId: '1AbCdEfGhIjKlMnOpQrStUvWxYz', recursive: false }
   - name: download_file
+    title: Download file
+    i18n:
+      de:
+        title: Datei herunterladen
+      fr:
+        title: Télécharger un fichier
     description: Download a single binary file by Drive fileId and store it in file storage. Native Google Workspace formats (Docs/Sheets/Slides) are not supported by this operation.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/imap-smtp/connector.yml b/configs/platform/system/connectors/imap-smtp/connector.yml
index 7b35b1433d..63a967836e 100644
--- a/configs/platform/system/connectors/imap-smtp/connector.yml
+++ b/configs/platform/system/connectors/imap-smtp/connector.yml
@@ -6,6 +6,11 @@
 # server/port config the native module reads.
 name: imap-smtp
 displayName: IMAP / SMTP Mailbox
+i18n:
+  de:
+    displayName: IMAP-/SMTP-Postfach
+  fr:
+    displayName: Boîte mail IMAP / SMTP
 description: >-
   Connect a private IMAP + SMTP mail server to Conversations — no Gmail or
   Outlook account required. Optional separate SMTP login for a relay
@@ -58,6 +63,12 @@ auth:
   - method: basic
 actions:
   - name: list_messages
+    title: List messages
+    i18n:
+      de:
+        title: Nachrichten auflisten
+      fr:
+        title: Lister les messages
     description: >-
       Fetch messages from an IMAP mailbox as standard email objects (from, to,
       subject, body, attachments). Omit mailbox for INBOX; pass `sent` to read
@@ -99,6 +110,12 @@ actions:
       impl: imap-smtp.list_messages
     exampleInput: { mailbox: 'INBOX', limit: 25 }
   - name: get_message
+    title: Get message
+    i18n:
+      de:
+        title: Nachricht abrufen
+      fr:
+        title: Récupérer un message
     description: >-
       Fetch one message by IMAP UID with plain/HTML body, file attachments
       (metadata plus base64 content when under 100 MiB; a larger part is
@@ -142,6 +159,12 @@ actions:
       impl: imap-smtp.get_message
     exampleInput: { uid: '42', mailbox: 'INBOX' }
   - name: send
+    title: Send email
+    i18n:
+      de:
+        title: E-Mail senden
+      fr:
+        title: Envoyer un e-mail
     description: Send an email through the configured SMTP server.
     effects: write
     input:
diff --git a/configs/platform/system/connectors/jev/connector.yml b/configs/platform/system/connectors/jev/connector.yml
index 502070aaa4..2a09a51556 100644
--- a/configs/platform/system/connectors/jev/connector.yml
+++ b/configs/platform/system/connectors/jev/connector.yml
@@ -11,6 +11,11 @@
 # tokens are free, so a decision costs a fraction of the chat call it replaces.
 name: jev
 displayName: Jev decisions
+i18n:
+  de:
+    displayName: Jev-Entscheidungen
+  fr:
+    displayName: Décisions Jev
 description: >-
   Ask typed questions about a piece of state and get back calibrated answers —
   a choice from a fixed set, a score against ordered levels, or the probability
@@ -25,6 +30,12 @@ auth:
   - method: api-key
 actions:
   - name: decide
+    title: Make a decision
+    i18n:
+      de:
+        title: Entscheidung treffen
+      fr:
+        title: Prendre une décision
     description: >-
       Judge one piece of state against named questions, all answered in a
       single pass. Use it to gate an action — whether to send, escalate, or
diff --git a/configs/platform/system/connectors/outlook/connector.yml b/configs/platform/system/connectors/outlook/connector.yml
index 4d0dfb82ec..f7a22f75ff 100644
--- a/configs/platform/system/connectors/outlook/connector.yml
+++ b/configs/platform/system/connectors/outlook/connector.yml
@@ -26,6 +26,12 @@ auth:
       - User.Read
 actions:
   - name: list_messages
+    title: List messages
+    i18n:
+      de:
+        title: Nachrichten auflisten
+      fr:
+        title: Lister les messages
     description: List messages from the mailbox, newest first. Draft messages are excluded.
     effects: read
     input:
@@ -164,6 +170,12 @@ actions:
         return { messages, nextLink: j['@odata.nextLink'] || '' };
     exampleInput: { top: 25 }
   - name: get_message
+    title: Get message
+    i18n:
+      de:
+        title: Nachricht abrufen
+      fr:
+        title: Récupérer un message
     description: Fetch a single email message by ID, optionally downloading and storing its file attachments.
     effects: read
     input:
@@ -228,6 +240,12 @@ actions:
         return { message, attachments };
     exampleInput: { messageId: 'AAMkAGI2THk...', includeAttachments: true }
   - name: get_attachments
+    title: Download attachments
+    i18n:
+      de:
+        title: Anhänge herunterladen
+      fr:
+        title: Télécharger les pièces jointes
     description: Download every file attachment on a message and store each one. Returns a fileId and URL per attachment.
     effects: read
     input:
@@ -277,6 +295,12 @@ actions:
         return { attachments };
     exampleInput: { messageId: 'AAMkAGI2THk...' }
   - name: search_messages
+    title: Search messages
+    i18n:
+      de:
+        title: Nachrichten durchsuchen
+      fr:
+        title: Rechercher des messages
     description: Search the mailbox by keyword across subject, body, and sender.
     effects: read
     input:
@@ -323,6 +347,12 @@ actions:
         return { messages: j.value || [], nextLink: j['@odata.nextLink'] || '' };
     exampleInput: { query: 'invoice', top: 25 }
   - name: send_message
+    title: Send email
+    i18n:
+      de:
+        title: E-Mail senden
+      fr:
+        title: Envoyer un e-mail
     description: Send an email message, optionally with file attachments. The message is composed as a draft so its internet message ID can be returned, then sent.
     effects: write
     input:
@@ -394,6 +424,12 @@ actions:
         body: 'This is a test message.',
       }
   - name: get_profile
+    title: Get mailbox address
+    i18n:
+      de:
+        title: Adresse des Postfachs abrufen
+      fr:
+        title: Récupérer l’adresse de la boîte mail
     description: The address of the connected mailbox (the signed-in account's mail address, else its principal name), as the mail sync reads it to tell the mailbox's own mail from a customer's.
     effects: read
     input:
@@ -412,6 +448,12 @@ actions:
         return { emailAddress: String(j.mail || j.userPrincipalName || '') };
     exampleInput: {}
   - name: list_events
+    title: List events
+    i18n:
+      de:
+        title: Termine auflisten
+      fr:
+        title: Lister les événements
     description: List calendar events, earliest start first, optionally within a date range.
     effects: read
     input:
@@ -468,6 +510,12 @@ actions:
         endDateTime: '2025-06-30T23:59:59',
       }
   - name: get_event
+    title: Get event
+    i18n:
+      de:
+        title: Termin abrufen
+      fr:
+        title: Récupérer un événement
     description: Fetch a single calendar event by ID.
     effects: read
     input:
@@ -503,6 +551,12 @@ actions:
         return { event: r.json() };
     exampleInput: { eventId: 'AAMkAGI2TG93...' }
   - name: create_event
+    title: Create event
+    i18n:
+      de:
+        title: Termin erstellen
+      fr:
+        title: Créer un événement
     description: Create a calendar event, optionally with a location and attendees.
     effects: write
     input:
@@ -580,6 +634,12 @@ actions:
         timeZone: 'Europe/Berlin',
       }
   - name: list_contacts
+    title: List contacts
+    i18n:
+      de:
+        title: Kontakte auflisten
+      fr:
+        title: Lister les contacts
     description: List contacts from the default contacts folder, ordered by display name.
     effects: read
     input:
@@ -634,6 +694,12 @@ actions:
         return { contacts: j.value || [], nextLink: j['@odata.nextLink'] || '' };
     exampleInput: { top: 25, search: 'Ada' }
   - name: get_contact
+    title: Get contact
+    i18n:
+      de:
+        title: Kontakt abrufen
+      fr:
+        title: Récupérer un contact
     description: Fetch a single contact by ID.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/sandbox/connector.yml b/configs/platform/system/connectors/sandbox/connector.yml
index f1749ad3c4..62e5cd513f 100644
--- a/configs/platform/system/connectors/sandbox/connector.yml
+++ b/configs/platform/system/connectors/sandbox/connector.yml
@@ -6,6 +6,11 @@
 # so there is no credential and nothing to connect.
 name: sandbox
 displayName: Sandbox scripts
+i18n:
+  de:
+    displayName: Sandbox-Skripte
+  fr:
+    displayName: Scripts de sandbox
 description: >-
   Run a deterministic script from a skill bundle in the organization's
   sandbox: staged input folders in, harvested output files and a parsed
@@ -16,6 +21,12 @@ auth:
   - method: platform
 actions:
   - name: run_script
+    title: Run script
+    i18n:
+      de:
+        title: Skript ausführen
+      fr:
+        title: Exécuter un script
     description: >-
       Run one script that ships inside an org skill bundle, inside the
       automation run's sandbox session. The bundle is staged at
diff --git a/configs/platform/system/connectors/shopify/connector.yml b/configs/platform/system/connectors/shopify/connector.yml
index 89f0af053a..3fa892919a 100644
--- a/configs/platform/system/connectors/shopify/connector.yml
+++ b/configs/platform/system/connectors/shopify/connector.yml
@@ -17,6 +17,12 @@ auth:
   - method: api-key
 actions:
   - name: list_products
+    title: List products
+    i18n:
+      de:
+        title: Produkte auflisten
+      fr:
+        title: Lister les produits
     description: List products in the store, newest first, with cursor pagination.
     effects: read
     input:
@@ -80,6 +86,12 @@ actions:
         return { products: r.json().products || [], nextPageInfo: m ? m[1] : '' };
     exampleInput: { limit: 50, status: 'active' }
   - name: get_product
+    title: Get product
+    i18n:
+      de:
+        title: Produkt abrufen
+      fr:
+        title: Récupérer un produit
     description: Get a single product by ID, including its variants and images.
     effects: read
     input:
@@ -114,6 +126,12 @@ actions:
         return { product: r.json().product };
     exampleInput: { resourceId: '8123456789012' }
   - name: list_customers
+    title: List customers
+    i18n:
+      de:
+        title: Kunden auflisten
+      fr:
+        title: Lister les clients
     description: List customers of the store with cursor pagination.
     effects: read
     input:
@@ -172,6 +190,12 @@ actions:
         return { customers: r.json().customers || [], nextPageInfo: m ? m[1] : '' };
     exampleInput: { limit: 50 }
   - name: get_customer
+    title: Get customer
+    i18n:
+      de:
+        title: Kunden abrufen
+      fr:
+        title: Récupérer un client
     description: Get a single customer by ID, including contact details and order totals.
     effects: read
     input:
@@ -207,6 +231,12 @@ actions:
         return { customer: r.json().customer };
     exampleInput: { resourceId: '7123456789012' }
   - name: list_orders
+    title: List orders
+    i18n:
+      de:
+        title: Bestellungen auflisten
+      fr:
+        title: Lister les commandes
     description: List orders in the store with cursor pagination.
     effects: read
     input:
@@ -270,6 +300,12 @@ actions:
         return { orders: r.json().orders || [], nextPageInfo: m ? m[1] : '' };
     exampleInput: { limit: 50, status: 'any' }
   - name: get_order
+    title: Get order
+    i18n:
+      de:
+        title: Bestellung abrufen
+      fr:
+        title: Récupérer une commande
     description: Get a single order by ID, including its line items and totals.
     effects: read
     input:
@@ -305,6 +341,12 @@ actions:
         return { order: r.json().order };
     exampleInput: { resourceId: '5123456789012' }
   - name: count_products
+    title: Count products
+    i18n:
+      de:
+        title: Produkte zählen
+      fr:
+        title: Compter les produits
     description: Get the total number of products in the store.
     effects: read
     input:
@@ -324,6 +366,12 @@ actions:
         if (!r.status || r.status >= 400) throw new Error(`Shopify count_products failed (${r.status}): ${r.text()}`);
         return { count: r.json().count || 0 };
   - name: count_customers
+    title: Count customers
+    i18n:
+      de:
+        title: Kunden zählen
+      fr:
+        title: Compter les clients
     description: Get the total number of customers in the store.
     effects: read
     input:
@@ -343,6 +391,12 @@ actions:
         if (!r.status || r.status >= 400) throw new Error(`Shopify count_customers failed (${r.status}): ${r.text()}`);
         return { count: r.json().count || 0 };
   - name: count_orders
+    title: Count orders
+    i18n:
+      de:
+        title: Bestellungen zählen
+      fr:
+        title: Compter les commandes
     description: Get the total number of orders in the store.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/slack/connector.yml b/configs/platform/system/connectors/slack/connector.yml
index 30fc7016ee..2ccda5d871 100644
--- a/configs/platform/system/connectors/slack/connector.yml
+++ b/configs/platform/system/connectors/slack/connector.yml
@@ -33,6 +33,12 @@ auth:
       - files:write
 actions:
   - name: list_channels
+    title: List channels
+    i18n:
+      de:
+        title: Channels auflisten
+      fr:
+        title: Lister les canaux
     description: List the conversations (channels, DMs, group messages) the bot can see.
     effects: read
     input:
@@ -62,6 +68,12 @@ actions:
         return { channels: j.channels || [], next_cursor: (j.response_metadata && j.response_metadata.next_cursor) || null };
     exampleInput: { types: 'public_channel', limit: 100 }
   - name: get_channel
+    title: Get channel
+    i18n:
+      de:
+        title: Channel abrufen
+      fr:
+        title: Récupérer un canal
     description: Get the details of one channel.
     effects: read
     input:
@@ -84,6 +96,12 @@ actions:
         return { channel: j.channel };
     exampleInput: { channel: 'C01234ABCDE' }
   - name: list_messages
+    title: List messages
+    i18n:
+      de:
+        title: Nachrichten auflisten
+      fr:
+        title: Lister les messages
     description: Fetch the message history of a channel.
     effects: read
     input:
@@ -122,6 +140,12 @@ actions:
         return { messages: j.messages || [], has_more: !!j.has_more, next_cursor: (j.response_metadata && j.response_metadata.next_cursor) || null };
     exampleInput: { channel: 'C01234ABCDE', limit: 50 }
   - name: send_message
+    title: Send message
+    i18n:
+      de:
+        title: Nachricht senden
+      fr:
+        title: Envoyer un message
     description: Send a message to a Slack channel or thread.
     effects: write
     input:
@@ -160,6 +184,12 @@ actions:
         return { channel: j.channel, ts: j.ts };
     exampleInput: { channel: 'C01234ABCDE', text: 'Deploy finished.' }
   - name: list_users
+    title: List workspace members
+    i18n:
+      de:
+        title: Workspace-Mitglieder auflisten
+      fr:
+        title: Lister les membres de l’espace de travail
     description: List the members of the Slack workspace.
     effects: read
     input:
@@ -186,6 +216,12 @@ actions:
         return { users: j.members || [], next_cursor: (j.response_metadata && j.response_metadata.next_cursor) || null };
     exampleInput: { limit: 100 }
   - name: get_user
+    title: Get user
+    i18n:
+      de:
+        title: Benutzer abrufen
+      fr:
+        title: Récupérer un utilisateur
     description: Get the profile of one workspace user.
     effects: read
     input:
@@ -208,6 +244,12 @@ actions:
         return { user: j.user };
     exampleInput: { user: 'U01234ABCDE' }
   - name: upload_file
+    title: Upload file
+    i18n:
+      de:
+        title: Datei hochladen
+      fr:
+        title: Téléverser un fichier
     description: Upload a text file and share it to a Slack channel.
     effects: write
     input:
diff --git a/configs/platform/system/connectors/task/connector.yml b/configs/platform/system/connectors/task/connector.yml
index 62f96e76a1..0f7aa4c03b 100644
--- a/configs/platform/system/connectors/task/connector.yml
+++ b/configs/platform/system/connectors/task/connector.yml
@@ -5,6 +5,11 @@
 # connect.
 name: task
 displayName: Tasks
+i18n:
+  de:
+    displayName: Aufgaben
+  fr:
+    displayName: Tâches
 description: >-
   Read a task, move its status, write or read its discussion comments, put
   its project agent to work, and keep a scheduled issue import's position
@@ -15,6 +20,12 @@ auth:
   - method: platform
 actions:
   - name: get
+    title: Get task
+    i18n:
+      de:
+        title: Aufgabe abrufen
+      fr:
+        title: Récupérer une tâche
     description: Read one task's title, status, project, and external linkage.
     effects: read
     input:
@@ -39,6 +50,12 @@ actions:
       impl: task.get
     exampleInput: { taskId: 'tsk_1' }
   - name: update_status
+    title: Change task status
+    i18n:
+      de:
+        title: Aufgabenstatus ändern
+      fr:
+        title: Changer le statut de la tâche
     description: >-
       Move a task to a new status. The automation acts as the workflow actor.
       Completing is not on offer — done stays reserved for the human review
@@ -63,6 +80,12 @@ actions:
       impl: task.update_status
     exampleInput: { taskId: 'tsk_1', status: 'in_progress' }
   - name: comment
+    title: Comment on task
+    i18n:
+      de:
+        title: Aufgabe kommentieren
+      fr:
+        title: Commenter la tâche
     description: Post a comment on the task's discussion timeline.
     effects: write
     input:
@@ -91,6 +114,12 @@ actions:
       impl: task.comment
     exampleInput: { taskId: 'tsk_1', body: 'Prepared the return.' }
   - name: list_comments
+    title: List task comments
+    i18n:
+      de:
+        title: Kommentare der Aufgabe auflisten
+      fr:
+        title: Lister les commentaires de la tâche
     description: >-
       Read the task's discussion comments, optionally only those newer than
       the last comment containing a marker (a delivery anchor) and only from
@@ -124,6 +153,12 @@ actions:
       impl: task.list_comments
     exampleInput: { taskId: 'tsk_1', authorTypes: [user], limit: 20 }
   - name: start_agent
+    title: Start project agent
+    i18n:
+      de:
+        title: Projektagenten starten
+      fr:
+        title: Lancer l’agent de projet
     description: >-
       Put the task's project agent to work, or first assign it to the agent
       named by agentId (an agent of the same project), and answer the run it
@@ -176,6 +211,12 @@ actions:
       impl: task.start_agent
     exampleInput: { taskId: 'tsk_1', feedback: 'Scheduled occurrence 2026-09-30 09:00 Europe/Zurich.' }
   - name: upsert
+    title: Import issue as task
+    i18n:
+      de:
+        title: Issue als Aufgabe importieren
+      fr:
+        title: Importer une issue comme tâche
     description: Import an external issue into a project's backlog, reusing its existing task on repeat imports. Keeps local status, assignee, and non-empty description. A title over 200 or a description over 20,000 UTF-16 code units is cut to that length, ending in "…"; a blank title is refused. Returns the title the task carries. Does not start an agent.
     effects: write
     input:
@@ -208,6 +249,12 @@ actions:
       impl: task.upsert
     exampleInput: { projectId: 'proj_mock', externalSystem: github, externalId: 'octocat/demo#1', title: Example issue }
   - name: list_external_issues
+    title: List imported issues
+    i18n:
+      de:
+        title: Importierte Issues auflisten
+      fr:
+        title: Lister les issues importées
     description: List previously imported issue sources for this project and immutable upstream repository/project. Oldest snapshots come first so repeated runs make progress through large boards.
     effects: read
     input:
@@ -230,6 +277,12 @@ actions:
       impl: task.list_external_issues
     exampleInput: { projectId: proj_mock, externalSystem: github, repositoryId: 1 }
   - name: get_import_cursor
+    title: Get import position
+    i18n:
+      de:
+        title: Importposition abrufen
+      fr:
+        title: Récupérer la position de l’import
     description: >-
       Where a scheduled issue import of this project's source resumes: the
       cursor its last saved batch left, so each occurrence imports one bounded
@@ -262,6 +315,12 @@ actions:
       impl: task.get_import_cursor
     exampleInput: { projectId: proj_mock, externalSystem: github, source: example/web }
   - name: save_import_cursor
+    title: Save import position
+    i18n:
+      de:
+        title: Importposition speichern
+      fr:
+        title: Enregistrer la position de l’import
     description: >-
       Record how far a scheduled issue import got: revision is the one
       get_import_cursor answered for this batch, and next the importer's
@@ -290,6 +349,12 @@ actions:
       impl: task.save_import_cursor
     exampleInput: { projectId: proj_mock, externalSystem: github, source: example/web, revision: '1', next: '' }
   - name: upsert_issues
+    title: Import issues as tasks
+    i18n:
+      de:
+        title: Issues als Aufgaben importieren
+      fr:
+        title: Importer des issues comme tâches
     description: Atomically import or refresh a batch of issue snapshots. New tasks require an open source; repeat sync keeps Tale edits and status. Titles and descriptions are cut to 200 and 20,000 UTF-16 code units, ending in "…"; a blank title refuses the batch, naming the item. Returns one result per source with the title its task carries, and taskId null when a closed source has no task.
     effects: write
     input:
diff --git a/configs/platform/system/connectors/tavily/connector.yml b/configs/platform/system/connectors/tavily/connector.yml
index f9de82434b..500a6e77f5 100644
--- a/configs/platform/system/connectors/tavily/connector.yml
+++ b/configs/platform/system/connectors/tavily/connector.yml
@@ -13,6 +13,12 @@ auth:
   - method: api-key
 actions:
   - name: search
+    title: Search the web
+    i18n:
+      de:
+        title: Im Web suchen
+      fr:
+        title: Rechercher sur le web
     description: >-
       Search the open web via Tavily. Returns top results with title, URL,
       content snippet, and score. Use 'basic' depth for quick facts,
@@ -84,6 +90,12 @@ actions:
         search_depth: 'advanced',
       }
   - name: extract
+    title: Extract page text
+    i18n:
+      de:
+        title: Seitentext extrahieren
+      fr:
+        title: Extraire le texte des pages
     description: >-
       Fetch cleaned main-article text for one or more URLs. Use for deep reads
       of the most promising search results.
diff --git a/configs/platform/system/connectors/teams/connector.yml b/configs/platform/system/connectors/teams/connector.yml
index 09db565d3f..cb294753ae 100644
--- a/configs/platform/system/connectors/teams/connector.yml
+++ b/configs/platform/system/connectors/teams/connector.yml
@@ -26,6 +26,12 @@ auth:
       - Chat.ReadWrite
 actions:
   - name: list_teams
+    title: List teams
+    i18n:
+      de:
+        title: Teams auflisten
+      fr:
+        title: Lister les équipes
     description: List the teams the authenticated user has joined.
     effects: read
     input:
@@ -43,6 +49,12 @@ actions:
         return { teams: j.value || [], nextLink: j['@odata.nextLink'] || null };
     exampleInput: {}
   - name: get_team
+    title: Get team
+    i18n:
+      de:
+        title: Team abrufen
+      fr:
+        title: Récupérer une équipe
     description: Get a single team by ID.
     effects: read
     input:
@@ -63,6 +75,12 @@ actions:
         return { team: r.json() };
     exampleInput: { teamId: '19:team-demo@thread.tacv2' }
   - name: list_channels
+    title: List channels
+    i18n:
+      de:
+        title: Kanäle auflisten
+      fr:
+        title: Lister les canaux
     description: List all channels in a team.
     effects: read
     input:
@@ -84,6 +102,12 @@ actions:
         return { channels: j.value || [], nextLink: j['@odata.nextLink'] || null };
     exampleInput: { teamId: '19:team-demo@thread.tacv2' }
   - name: get_channel
+    title: Get channel
+    i18n:
+      de:
+        title: Kanal abrufen
+      fr:
+        title: Récupérer un canal
     description: Get a single channel by ID.
     effects: read
     input:
@@ -111,6 +135,12 @@ actions:
         channelId: '19:channel-general@thread.tacv2',
       }
   - name: list_messages
+    title: List channel messages
+    i18n:
+      de:
+        title: Kanalnachrichten auflisten
+      fr:
+        title: Lister les messages d’un canal
     description: Fetch messages from a channel.
     effects: read
     input:
@@ -147,6 +177,12 @@ actions:
         top: 20,
       }
   - name: send_message
+    title: Send channel message
+    i18n:
+      de:
+        title: Nachricht im Kanal senden
+      fr:
+        title: Envoyer un message dans un canal
     description: Send a message to a channel.
     effects: write
     input:
@@ -183,6 +219,12 @@ actions:
         content: 'Deploy finished.',
       }
   - name: list_members
+    title: List team members
+    i18n:
+      de:
+        title: Teammitglieder auflisten
+      fr:
+        title: Lister les membres de l’équipe
     description: List the members of a team.
     effects: read
     input:
@@ -212,6 +254,12 @@ actions:
         return { members: j.value || [], nextLink: j['@odata.nextLink'] || null };
     exampleInput: { teamId: '19:team-demo@thread.tacv2', top: 100 }
   - name: list_chats
+    title: List chats
+    i18n:
+      de:
+        title: Chats auflisten
+      fr:
+        title: Lister les conversations
     description: List the chats the authenticated user is part of.
     effects: read
     input:
@@ -233,6 +281,12 @@ actions:
         return { chats: j.value || [], nextLink: j['@odata.nextLink'] || null };
     exampleInput: { top: 20 }
   - name: send_chat_message
+    title: Send chat message
+    i18n:
+      de:
+        title: Chatnachricht senden
+      fr:
+        title: Envoyer un message dans une conversation
     description: Send a message to a chat.
     effects: write
     input:
diff --git a/configs/platform/system/connectors/twilio/connector.yml b/configs/platform/system/connectors/twilio/connector.yml
index b33a1b5b72..9ac5f02deb 100644
--- a/configs/platform/system/connectors/twilio/connector.yml
+++ b/configs/platform/system/connectors/twilio/connector.yml
@@ -16,6 +16,12 @@ auth:
   - method: basic
 actions:
   - name: send_sms
+    title: Send SMS
+    i18n:
+      de:
+        title: SMS senden
+      fr:
+        title: Envoyer un SMS
     description: Send an SMS message via Twilio.
     effects: write
     input:
@@ -52,6 +58,12 @@ actions:
         body: 'Your order has shipped.',
       }
   - name: list_messages
+    title: List SMS messages
+    i18n:
+      de:
+        title: SMS auflisten
+      fr:
+        title: Lister les SMS
     description: List SMS messages, optionally filtered by number or send date.
     effects: read
     input:
@@ -96,6 +108,12 @@ actions:
         return { messages: j.messages || [], next_page_uri: j.next_page_uri || null };
     exampleInput: { to: '+15551234567', pageSize: 20 }
   - name: get_message
+    title: Get SMS message
+    i18n:
+      de:
+        title: SMS abrufen
+      fr:
+        title: Récupérer un SMS
     description: Get one SMS message by its SID.
     effects: read
     input:
@@ -118,6 +136,12 @@ actions:
         return { message: r.json() };
     exampleInput: { messageSid: 'SM1234567890abcdef1234567890abcdef' }
   - name: list_calls
+    title: List calls
+    i18n:
+      de:
+        title: Anrufe auflisten
+      fr:
+        title: Lister les appels
     description: List voice calls, optionally filtered by number or status.
     effects: read
     input:
@@ -161,6 +185,12 @@ actions:
         return { calls: j.calls || [], next_page_uri: j.next_page_uri || null };
     exampleInput: { status: 'completed', pageSize: 20 }
   - name: make_call
+    title: Start call
+    i18n:
+      de:
+        title: Anruf starten
+      fr:
+        title: Lancer un appel
     description: Start an outbound voice call via Twilio.
     effects: write
     input:
@@ -201,6 +231,12 @@ actions:
         url: 'https://example.com/twiml/greeting.xml',
       }
   - name: get_account
+    title: Get account
+    i18n:
+      de:
+        title: Konto abrufen
+      fr:
+        title: Récupérer le compte
     description: Get the Twilio account the credential belongs to.
     effects: read
     input:
@@ -219,6 +255,12 @@ actions:
         return { account: r.json() };
     exampleInput: {}
   - name: list_phone_numbers
+    title: List phone numbers
+    i18n:
+      de:
+        title: Telefonnummern auflisten
+      fr:
+        title: Lister les numéros de téléphone
     description: List the incoming phone numbers the Twilio account owns.
     effects: read
     input:
diff --git a/configs/platform/system/connectors/webdav/connector.yml b/configs/platform/system/connectors/webdav/connector.yml
index 8155f5cefa..0aa1c32fbd 100644
--- a/configs/platform/system/connectors/webdav/connector.yml
+++ b/configs/platform/system/connectors/webdav/connector.yml
@@ -5,6 +5,11 @@
 # Basic auth carries a WebDAV app password.
 name: webdav
 displayName: WebDAV Files
+i18n:
+  de:
+    displayName: WebDAV-Dateien
+  fr:
+    displayName: Fichiers WebDAV
 description: >-
   Read, write, and list files in the organization's WebDAV store — the same
   files the /dav endpoint serves.
@@ -14,6 +19,12 @@ auth:
   - method: basic
 actions:
   - name: list
+    title: List folder contents
+    i18n:
+      de:
+        title: Ordnerinhalt auflisten
+      fr:
+        title: Lister le contenu d’un dossier
     description: List the entries directly under a folder path.
     effects: read
     input:
@@ -36,6 +47,12 @@ actions:
       impl: webdav.list
     exampleInput: { path: '/reports' }
   - name: read
+    title: Read file
+    i18n:
+      de:
+        title: Datei lesen
+      fr:
+        title: Lire un fichier
     description: Read a file's contents.
     effects: read
     input:
@@ -51,6 +68,12 @@ actions:
       impl: webdav.read
     exampleInput: { path: '/reports/q3.md' }
   - name: write
+    title: Write file
+    i18n:
+      de:
+        title: Datei schreiben
+      fr:
+        title: Écrire un fichier
     description: Create or overwrite a file with the given contents.
     effects: write
     input:
@@ -69,6 +92,12 @@ actions:
       impl: webdav.write
     exampleInput: { path: '/reports/summary.md', content: '# Summary' }
   - name: delete
+    title: Delete file or folder
+    i18n:
+      de:
+        title: Datei oder Ordner löschen
+      fr:
+        title: Supprimer un fichier ou un dossier
     description: Delete a file or folder.
     effects: write
     input:
diff --git a/services/platform/lib/connectors/action-titles.test.ts b/services/platform/lib/connectors/action-titles.test.ts
new file mode 100644
index 0000000000..7062e82b07
--- /dev/null
+++ b/services/platform/lib/connectors/action-titles.test.ts
@@ -0,0 +1,255 @@
+/**
+ * Every shipped connector action is named for people in every language the
+ * app ships: an English `title` plus German and French overrides, written the
+ * way the rest of the product writes labels. The automation canvas shows a
+ * connector node as "{connector} · {title}" ("GitHub · List issues"), so an
+ * action without its titles would put a raw `github.list_issues` (or an
+ * English phrase in a German canvas) in front of the reader.
+ *
+ * The connectors themselves are named the same way: a brand ("GitHub") keeps
+ * its name everywhere, and a connector named with ordinary words ("Tasks")
+ * carries its German and French display names. Each shipped connector is one
+ * or the other, so a new one has to be classified when it lands.
+ */
+
+import path from 'node:path';
+
+import type { Connector } from '@tale/shared/schemas/connectors';
+import { describe, expect, it } from 'vitest';
+
+import { loadConnectorDefinitions } from './catalog';
+
+const SYSTEM_ROOT = path.join(
+  path.dirname(new URL(import.meta.url).pathname),
+  '../../../../configs/platform/system',
+);
+
+/** The full locales beside English, each of which every title must carry. */
+const REQUIRED_LOCALES = ['de', 'fr'] as const;
+
+/** Every locale an override may name: the full ones and the sparse Swiss
+ * German overlay. A key outside it would be text nobody can ever read. */
+const KNOWN_LOCALES = new Set(['de', 'fr', 'de-CH']);
+
+/** Connectors named after a product: the name is the same in every
+ * language, so they carry no display-name overrides. */
+const BRAND_CONNECTORS = new Set([
+  'confluence',
+  'discord',
+  'github',
+  'glitchtip',
+  'gmail',
+  'google-drive',
+  'outlook',
+  'shopify',
+  'slack',
+  'tavily',
+  'teams',
+  'twilio',
+]);
+
+/** A title's casing in English and French: the first letter upper case, every
+ * later word lower case unless it is an acronym ("Send SMS"). German is left
+ * out — its nouns are capitalised. */
+function sentenceCaseProblem(title: string): string | undefined {
+  const words = title.split(/\s+/);
+  const first = words[0] ?? '';
+  if (first.charAt(0) !== first.charAt(0).toLocaleUpperCase()) {
+    return 'does not start with a capital letter';
+  }
+  for (const word of words.slice(1)) {
+    const letters = word.replaceAll(/[^\p{L}]/gu, '');
+    const isAcronym = letters.length >= 2 && letters === letters.toUpperCase();
+    if (!isAcronym && word.charAt(0) !== word.charAt(0).toLocaleLowerCase()) {
+      return `is not sentence case ("${word}")`;
+    }
+  }
+  return undefined;
+}
+
+/** What is wrong with one title in one language, or undefined. */
+function titleProblem(title: string, locale: string): string | undefined {
+  if (title !== title.trim()) return 'has surrounding whitespace';
+  if (/[.:;!?]$/.test(title)) return 'ends in punctuation';
+  if (locale === 'fr' && title.includes("'")) {
+    return 'uses a straight apostrophe (French titles use ’)';
+  }
+  if (locale === 'en' || locale === 'fr') return sentenceCaseProblem(title);
+  const first = title.charAt(0);
+  return first === first.toLocaleUpperCase()
+    ? undefined
+    : 'does not start with a capital letter';
+}
+
+/** Every problem with one connector's display data, as readable lines. */
+function displayProblems(connector: Connector): string[] {
+  const problems: string[] = [];
+  const titles = new Map<string, Map<string, string>>();
+  const note = (locale: string, action: string, title: string) => {
+    const seen = titles.get(locale) ?? new Map<string, string>();
+    const other = seen.get(title);
+    if (other !== undefined) {
+      problems.push(
+        `${connector.name}.${action}: ${locale} title "${title}" is also ${other}'s`,
+      );
+    }
+    seen.set(title, action);
+    titles.set(locale, seen);
+  };
+
+  for (const action of connector.actions) {
+    const at = `${connector.name}.${action.name}`;
+    if (action.title === undefined) {
+      problems.push(`${at}: has no title`);
+    } else {
+      const problem = titleProblem(action.title, 'en');
+      if (problem !== undefined) problems.push(`${at}: en title ${problem}`);
+      note('en', action.name, action.title);
+    }
+    for (const locale of Object.keys(action.i18n ?? {})) {
+      if (!KNOWN_LOCALES.has(locale)) {
+        problems.push(
+          `${at}: names a locale the app does not ship (${locale})`,
+        );
+      }
+    }
+    for (const locale of REQUIRED_LOCALES) {
+      const title = action.i18n?.[locale]?.title;
+      if (title === undefined) {
+        problems.push(`${at}: has no ${locale} title`);
+        continue;
+      }
+      const problem = titleProblem(title, locale);
+      if (problem !== undefined)
+        problems.push(`${at}: ${locale} title ${problem}`);
+      note(locale, action.name, title);
+    }
+    // Swiss German writes ss for ß: a German title that needs one carries
+    // its de-CH override.
+    const german = action.i18n?.de?.title;
+    const swiss = action.i18n?.['de-CH']?.title;
+    if (
+      german?.includes('ß') === true &&
+      (swiss === undefined || swiss.includes('ß'))
+    ) {
+      problems.push(`${at}: de title has ß but no de-CH title without it`);
+    }
+  }
+
+  if (BRAND_CONNECTORS.has(connector.name)) {
+    if (connector.i18n !== undefined) {
+      problems.push(
+        `${connector.name}: a brand keeps its name, yet it carries display-name overrides`,
+      );
+    }
+  } else {
+    for (const locale of REQUIRED_LOCALES) {
+      if (connector.i18n?.[locale]?.displayName === undefined) {
+        problems.push(
+          `${connector.name}: is not a listed brand and has no ${locale} display name`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+const shipped = loadConnectorDefinitions({ root: SYSTEM_ROOT });
+
+describe('connector display data', () => {
+  it('names every shipped action in English, German and French, as labels are written', () => {
+    expect(shipped.flatMap(displayProblems)).toEqual([]);
+    // The guard read the whole catalog, not an empty directory.
+    expect(shipped.flatMap((c) => c.actions).length).toBeGreaterThan(100);
+  });
+
+  it('names every shipped connector for its readers: a brand as itself, the rest translated', () => {
+    for (const connector of shipped) {
+      const named =
+        BRAND_CONNECTORS.has(connector.name) ||
+        REQUIRED_LOCALES.every(
+          (locale) => connector.i18n?.[locale]?.displayName !== undefined,
+        );
+      expect(named, connector.name).toBe(true);
+    }
+  });
+
+  it('bites: an action that lands without its titles, or with a sloppy one, is named', () => {
+    const github = shipped.find((c) => c.name === 'github');
+    if (github === undefined) throw new Error('github ships with the platform');
+    const [first, second] = github.actions;
+    if (first === undefined || second === undefined) {
+      throw new Error('github ships more than one action');
+    }
+    const broken: Connector = {
+      ...github,
+      actions: [
+        { ...first, title: undefined, i18n: undefined },
+        {
+          ...second,
+          title: 'Get A repository.',
+          i18n: {
+            de: { title: 'Repository abrufen' },
+            fr: { title: "Récupérer l'issue" },
+            'de-AT': { title: 'Repository abrufen' },
+          },
+        },
+      ],
+    };
+    expect(displayProblems(broken)).toEqual([
+      `github.${first.name}: has no title`,
+      `github.${first.name}: has no de title`,
+      `github.${first.name}: has no fr title`,
+      `github.${second.name}: en title ends in punctuation`,
+      `github.${second.name}: names a locale the app does not ship (de-AT)`,
+      `github.${second.name}: fr title uses a straight apostrophe (French titles use ’)`,
+    ]);
+  });
+
+  it('bites: duplicate titles, a lowercase start, a word in title case, a ß without its Swiss form', () => {
+    const github = shipped.find((c) => c.name === 'github');
+    if (github === undefined) throw new Error('github ships with the platform');
+    const [first, second] = github.actions;
+    if (first === undefined || second === undefined) {
+      throw new Error('github ships more than one action');
+    }
+    const broken: Connector = {
+      ...github,
+      actions: [
+        {
+          ...first,
+          title: 'List Issues',
+          i18n: {
+            de: { title: 'issues auflisten' },
+            fr: { title: 'Lister les issues' },
+          },
+        },
+        {
+          ...second,
+          title: 'Get issue',
+          i18n: {
+            de: { title: 'Issue schließen' },
+            fr: { title: 'Lister les issues' },
+          },
+        },
+      ],
+    };
+    expect(displayProblems(broken)).toEqual([
+      `github.${first.name}: en title is not sentence case ("Issues")`,
+      `github.${first.name}: de title does not start with a capital letter`,
+      `github.${second.name}: fr title "Lister les issues" is also ${first.name}'s`,
+      `github.${second.name}: de title has ß but no de-CH title without it`,
+    ]);
+  });
+
+  it('bites: a new connector that is neither a listed brand nor translated', () => {
+    const task = shipped.find((c) => c.name === 'task');
+    if (task === undefined) throw new Error('task ships with the platform');
+    expect(
+      displayProblems({ ...task, name: 'calendar', i18n: undefined }),
+    ).toEqual([
+      'calendar: is not a listed brand and has no de display name',
+      'calendar: is not a listed brand and has no fr display name',
+    ]);
+  });
+});

From 2a5460ae97ee4b8986d773de8fdb8ee20c30466c Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:05:06 +0200
Subject: [PATCH 03/78] feat(platform): serve action titles and connector icons
 in the catalog

GET /automations/catalog/node-types answers, per connector action, its
connector and its title with the German and French overrides, and once
per connector its display name, overrides and shipped icon as a data
URL. The registry carries the display data on the engine's connector
surface; the app parses the answer with one zod schema instead of
casting it, and the editor and run page read its nodeTypes.
---
 .../components/automation-editor.tsx          |   4 +-
 .../components/run-detail.test.tsx            |   5 +-
 .../automations/components/run-detail.tsx     |   4 +-
 .../app/features/automations/hooks/backend.ts |  12 +-
 .../app/lib/backend/automations.test.ts       |  77 ++++++++++-
 .../platform/app/lib/backend/automations.ts   |  27 +++-
 .../app/lib/backend/contract/automations.ts   |  11 +-
 .../connector_catalog.ts                      |   7 +
 .../automations/routes.catalog.test.ts        | 130 ++++++++++++++++++
 .../backend/domains/automations/routes.ts     |  35 ++++-
 .../platform/lib/connectors/registry.test.ts  |  13 ++
 services/platform/lib/connectors/registry.ts  |   5 +
 services/platform/lib/engine/core/slots.ts    |  14 ++
 .../lib/shared/schemas/node-type-catalog.ts   |  53 +++++++
 14 files changed, 366 insertions(+), 31 deletions(-)
 create mode 100644 services/platform/backend/domains/automations/routes.catalog.test.ts
 create mode 100644 services/platform/lib/shared/schemas/node-type-catalog.ts

diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 2e36dd446b..2b5ef18000 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -424,8 +424,8 @@ function AutomationEditorScope({
   );
 
   const nodeTypes = useMemo(
-    () => mergeNodeTypes(catalogQuery.data),
-    [catalogQuery.data],
+    () => mergeNodeTypes(catalogQuery.data?.nodeTypes),
+    [catalogQuery.data?.nodeTypes],
   );
 
   // ── Problems ──────────────────────────────────────────────────────────
diff --git a/services/platform/app/features/automations/components/run-detail.test.tsx b/services/platform/app/features/automations/components/run-detail.test.tsx
index 50fe23d20d..effa589d56 100644
--- a/services/platform/app/features/automations/components/run-detail.test.tsx
+++ b/services/platform/app/features/automations/components/run-detail.test.tsx
@@ -75,7 +75,10 @@ vi.mock('../hooks/queries', async (importOriginal) => {
         : state.versionError === undefined
           ? { data: { document: state.versionDocument }, isError: false }
           : { data: undefined, isError: true, error: state.versionError },
-    useNodeTypeCatalog: () => ({ data: [], isError: false }),
+    useNodeTypeCatalog: () => ({
+      data: { nodeTypes: [], connectors: [] },
+      isError: false,
+    }),
     useRunPendingAsk: () => ({ data: null }),
     useRunInDoubt: () => ({
       data: {
diff --git a/services/platform/app/features/automations/components/run-detail.tsx b/services/platform/app/features/automations/components/run-detail.tsx
index 51628f4a4d..becda333bf 100644
--- a/services/platform/app/features/automations/components/run-detail.tsx
+++ b/services/platform/app/features/automations/components/run-detail.tsx
@@ -195,8 +195,8 @@ function RunDetailBody({
     [graph.nodes, projection, run],
   );
   const nodeTypes = useMemo(
-    () => mergeNodeTypes(catalogQuery.data),
-    [catalogQuery.data],
+    () => mergeNodeTypes(catalogQuery.data?.nodeTypes),
+    [catalogQuery.data?.nodeTypes],
   );
 
   const runMissing = isMissingAutomationRead({
diff --git a/services/platform/app/features/automations/hooks/backend.ts b/services/platform/app/features/automations/hooks/backend.ts
index 83b77c1085..0cc1de91cf 100644
--- a/services/platform/app/features/automations/hooks/backend.ts
+++ b/services/platform/app/features/automations/hooks/backend.ts
@@ -1,4 +1,4 @@
-import type { ItemOf } from '@/app/lib/backend/contract';
+import type { ReturnsOf } from '@/app/lib/backend/contract';
 import { nodeTypes } from '@/lib/engine/core/slots';
 
 /**
@@ -17,14 +17,16 @@ import { nodeTypes } from '@/lib/engine/core/slots';
  */
 
 /**
- * Every node type the engine has registered — core types plus one per
- * connector action. An action: reading the connector catalog needs the
- * deployment's config tree.
+ * Every connector action the engine has registered, plus the connectors they
+ * belong to (display name and icon, once each). An action: reading the
+ * connector catalog needs the deployment's config tree.
  */
 export const listNodeTypesRef = 'automations/catalog:listNodeTypes';
 
 /** One node type as the editor needs it — the server's own return shape. */
-export type NodeTypeSummary = ItemOf<typeof listNodeTypesRef>;
+export type NodeTypeSummary = ReturnsOf<
+  typeof listNodeTypesRef
+>['nodeTypes'][number];
 
 /** The core node types, read from the engine's own registry so the editor
  * never carries a hand-written copy of the node grammar. */
diff --git a/services/platform/app/lib/backend/automations.test.ts b/services/platform/app/lib/backend/automations.test.ts
index 210263333f..776dc34e9c 100644
--- a/services/platform/app/lib/backend/automations.test.ts
+++ b/services/platform/app/lib/backend/automations.test.ts
@@ -2,7 +2,11 @@
 import { QueryClient } from '@tanstack/react-query';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { automationReadAdapters, automationWriteAdapters } from './automations';
+import {
+  automationActionQueryAdapters,
+  automationReadAdapters,
+  automationWriteAdapters,
+} from './automations';
 import { backendKey } from './query-keys';
 
 /**
@@ -251,3 +255,74 @@ describe('in-doubt adapters', () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 });
+
+describe('node-type catalog adapter', () => {
+  const ROW = {
+    type: 'github.list_issues',
+    kind: 'connector',
+    description: 'List issues for a repository.',
+    allowedFields: ['input', 'credential'],
+    requiredFields: ['input'],
+    outputKind: 'structured',
+    hasEffect: false,
+    connector: 'github',
+    title: 'List issues',
+    i18n: { de: { title: 'Issues auflisten' } },
+  };
+
+  it('reads the actions and the connectors they belong to', async () => {
+    const fetchSpy = vi.spyOn(window, 'fetch').mockResolvedValue(
+      jsonResponse(200, {
+        nodeTypes: [ROW],
+        connectors: [
+          {
+            name: 'github',
+            displayName: 'GitHub',
+            iconUrl: 'data:image/svg+xml;base64,PHN2Zy8+',
+          },
+        ],
+      }),
+    );
+    const fetchCatalog = automationActionQueryAdapters[
+      'automations/catalog:listNodeTypes'
+    ]?.({ organizationId: 'org1' }, {});
+    await expect(fetchCatalog?.()).resolves.toEqual({
+      nodeTypes: [ROW],
+      connectors: [
+        {
+          name: 'github',
+          displayName: 'GitHub',
+          iconUrl: 'data:image/svg+xml;base64,PHN2Zy8+',
+        },
+      ],
+    });
+    expect(fetchSpy.mock.calls[0]?.[0]).toBe(
+      '/api/app/automations/catalog/node-types?orgId=org1',
+    );
+  });
+
+  it('refuses an answer in a shape it does not read, instead of casting it', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(window, 'fetch').mockResolvedValue(
+      jsonResponse(200, { nodeTypes: [{ ...ROW, kind: 'plugin' }] }),
+    );
+    const fetchCatalog = automationActionQueryAdapters[
+      'automations/catalog:listNodeTypes'
+    ]?.({ organizationId: 'org1' }, {});
+    await expect(fetchCatalog?.()).rejects.toThrow(/unreadable shape/);
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it('reads an answer without connectors as none', async () => {
+    vi.spyOn(window, 'fetch').mockResolvedValue(
+      jsonResponse(200, { nodeTypes: [ROW] }),
+    );
+    const fetchCatalog = automationActionQueryAdapters[
+      'automations/catalog:listNodeTypes'
+    ]?.({ organizationId: 'org1' }, {});
+    await expect(fetchCatalog?.()).resolves.toEqual({
+      nodeTypes: [ROW],
+      connectors: [],
+    });
+  });
+});
diff --git a/services/platform/app/lib/backend/automations.ts b/services/platform/app/lib/backend/automations.ts
index 67b4840d53..29ce285eb1 100644
--- a/services/platform/app/lib/backend/automations.ts
+++ b/services/platform/app/lib/backend/automations.ts
@@ -8,6 +8,10 @@
  */
 
 import type { ReturnsOf } from '@/app/lib/backend/contract';
+import {
+  nodeTypeCatalogSchema,
+  type NodeTypeCatalog,
+} from '@/lib/shared/schemas/node-type-catalog';
 
 import type {
   ActionQueryAdapter,
@@ -28,7 +32,6 @@ type RunInDoubtResult = ReturnsOf<'automations/queries:getRunInDoubt'>;
 type OrgAutomationMetricsResult =
   ReturnsOf<'automations/queries:getOrgAutomationMetrics'>;
 type ApprovalResult = ReturnsOf<'approvals/queries:getApproval'>;
-type NodeTypesResult = ReturnsOf<'automations/catalog:listNodeTypes'>;
 type AutomationCapabilitiesResult =
   ReturnsOf<'chat/composer:listAutomationCapabilities'>;
 type SaveAutomationResult = ReturnsOf<'automations/mutations:saveAutomation'>;
@@ -283,6 +286,21 @@ export const automationReadAdapters: Record<string, ReadAdapter> = {
   },
 };
 
+/** The node-type catalog, parsed at the boundary: an answer in a shape this
+ * app does not read is a failed read (the editor then works from the core
+ * types alone), never a cast. */
+function readNodeTypeCatalog(body: unknown): NodeTypeCatalog {
+  const parsed = nodeTypeCatalogSchema.safeParse(body);
+  if (!parsed.success) {
+    console.warn(
+      '[automations] the node-type catalog answered in a shape this app does not read',
+      parsed.error.issues,
+    );
+    throw new Error('The node-type catalog answered in an unreadable shape.');
+  }
+  return parsed.data;
+}
+
 /** pg run rows carry `id`; the 0.4 wire uses `_id`. */
 function mapRunIds(rows: unknown[]): unknown[] {
   return rows.map((row) =>
@@ -298,10 +316,9 @@ export const automationActionQueryAdapters: Record<string, ActionQueryAdapter> =
       const orgId = orgOf(args, ctx);
       if (orgId === undefined) return null;
       return () =>
-        backendFetch<{ nodeTypes: NodeTypesResult }>(
-          '/automations/catalog/node-types',
-          { orgId },
-        ).then((body) => body.nodeTypes);
+        backendFetch<unknown>('/automations/catalog/node-types', {
+          orgId,
+        }).then(readNodeTypeCatalog);
     },
     'chat/composer:listAutomationCapabilities': (args, ctx) => {
       const orgId = orgOf(args, ctx);
diff --git a/services/platform/app/lib/backend/contract/automations.ts b/services/platform/app/lib/backend/contract/automations.ts
index ebebe33e84..8a0603559a 100644
--- a/services/platform/app/lib/backend/contract/automations.ts
+++ b/services/platform/app/lib/backend/contract/automations.ts
@@ -10,6 +10,7 @@
 import type { LegacyRunQuarantine } from '@/lib/engine/api/dispatch';
 export type { LegacyRunQuarantine } from '@/lib/engine/api/dispatch';
 
+import type { NodeTypeCatalog } from '@/lib/shared/schemas/node-type-catalog';
 import type { QuestionSet } from '@/lib/shared/schemas/questions';
 
 /** What a `waiting` run is parked on. `approval`, `ask` and `in_doubt`
@@ -73,15 +74,7 @@ export interface AutomationsContract {
   'automations/catalog:listNodeTypes': {
     kind: 'action';
     args: { organizationId: string };
-    returns: Array<{
-      hasEffect?: boolean;
-      type: string;
-      kind: 'connector' | 'core';
-      description: string;
-      allowedFields: string[];
-      requiredFields: string[];
-      outputKind: 'structured' | 'unstructured';
-    }>;
+    returns: NodeTypeCatalog;
   };
   'automations/human_asks:answerAsk': {
     kind: 'mutation';
diff --git a/services/platform/backend/core/connector_credentials/connector_catalog.ts b/services/platform/backend/core/connector_credentials/connector_catalog.ts
index 27738c9445..4d265c6b33 100644
--- a/services/platform/backend/core/connector_credentials/connector_catalog.ts
+++ b/services/platform/backend/core/connector_credentials/connector_catalog.ts
@@ -87,6 +87,13 @@ function readConnectorIcon(
   }
 }
 
+/** A shipped connector's icon as an inline data URL, or `undefined` when it
+ * ships none — the same image the settings catalog shows, for the other
+ * surfaces that name a connector (the automation node-type catalog). */
+export function connectorIconUrl(slug: string): string | undefined {
+  return readConnectorIcon(resolveConnectorsDir(), slug);
+}
+
 /**
  * The shipped connectors as the settings page lists them — slug, display copy,
  * grouping tags, endpoint mode, accepted auth methods (in declaration order),
diff --git a/services/platform/backend/domains/automations/routes.catalog.test.ts b/services/platform/backend/domains/automations/routes.catalog.test.ts
new file mode 100644
index 0000000000..5381dcac1f
--- /dev/null
+++ b/services/platform/backend/domains/automations/routes.catalog.test.ts
@@ -0,0 +1,130 @@
+import { Hono, type Context } from 'hono';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { nodeTypeCatalogSchema } from '../../../lib/shared/schemas/node-type-catalog.ts';
+import type { OrgEnv } from '../../auth/org.ts';
+
+/**
+ * The node-type catalog the automation editor works against:
+ * `GET /catalog/node-types` answers one row per shipped connector action and
+ * the connectors themselves, once each, with what a person reads on a node —
+ * the action's title in English, German and French, the connector's display
+ * name and its icon. Read from the shipped catalog, not a stub, so the answer
+ * is the one a deployment gives.
+ */
+
+const io = vi.hoisted(() => ({ role: 'developer' }));
+vi.mock('../../auth/session.ts', () => ({
+  requireSession:
+    () => async (c: Context<OrgEnv>, next: () => Promise<void>) => {
+      c.set('sessionBundle', { user: { id: 'u1' } } as never);
+      await next();
+    },
+}));
+vi.mock('../../auth/org.ts', async (original) => ({
+  ...(await original<typeof import('../../auth/org.ts')>()),
+  requireOrgMember:
+    () => async (c: Context<OrgEnv>, next: () => Promise<void>) => {
+      c.set('orgId', 'o1');
+      c.set('orgMember', { role: io.role } as never);
+      await next();
+    },
+}));
+
+import { createAutomationRoutes } from './routes.ts';
+
+async function getCatalog() {
+  const app = new Hono().route(
+    '/api/app/automations',
+    createAutomationRoutes({ sql: {} as never, auth: {} as never }),
+  );
+  return app.request('/api/app/automations/catalog/node-types');
+}
+
+beforeEach(() => {
+  io.role = 'developer';
+});
+
+describe('GET /catalog/node-types', () => {
+  it('refuses a member: the catalog serves the people who author automations', async () => {
+    io.role = 'member';
+    expect((await getCatalog()).status).toBe(403);
+  });
+
+  it('answers each action with its connector and its title in every shipped language', async () => {
+    const response = await getCatalog();
+    expect(response.status).toBe(200);
+    // The answer is the shape the app parses: the server and the client
+    // read one schema.
+    const catalog = nodeTypeCatalogSchema.parse(await response.json());
+
+    const listIssues = catalog.nodeTypes.find(
+      (row) => row.type === 'github.list_issues',
+    );
+    expect(listIssues).toMatchObject({
+      kind: 'connector',
+      connector: 'github',
+      title: 'List issues',
+      i18n: {
+        de: { title: 'Issues auflisten' },
+        fr: { title: 'Lister les issues' },
+      },
+      hasEffect: false,
+    });
+    expect(
+      catalog.nodeTypes.find((row) => row.type === 'github.create_issue')
+        ?.hasEffect,
+    ).toBe(true);
+
+    for (const row of catalog.nodeTypes) {
+      expect(row.kind, row.type).toBe('connector');
+      expect(row.type.startsWith(`${row.connector}.`), row.type).toBe(true);
+      expect(row.title, row.type).toBeTruthy();
+      expect(row.i18n?.de?.title, row.type).toBeTruthy();
+      expect(row.i18n?.fr?.title, row.type).toBeTruthy();
+    }
+    const types = catalog.nodeTypes.map((row) => row.type);
+    expect(types).toEqual([...types].sort((a, b) => a.localeCompare(b)));
+  });
+
+  it('names every connector once, with its display name, translations and icon', async () => {
+    const catalog = nodeTypeCatalogSchema.parse(
+      await (await getCatalog()).json(),
+    );
+    const names = catalog.connectors.map((connector) => connector.name);
+    expect(new Set(names).size).toBe(names.length);
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+    // Every row's connector is among them, so a face never misses its name.
+    for (const row of catalog.nodeTypes) {
+      expect(names, row.type).toContain(row.connector);
+    }
+
+    const github = catalog.connectors.find((c) => c.name === 'github');
+    expect(github?.displayName).toBe('GitHub');
+    // A brand keeps its name in every language.
+    expect(github?.i18n).toBeUndefined();
+    // The shipped icon, inline: no extra request, no static route.
+    expect(github?.iconUrl).toMatch(/^data:image\/svg\+xml;base64,/);
+    const svg = Buffer.from(
+      github?.iconUrl?.split(',')[1] ?? '',
+      'base64',
+    ).toString('utf8');
+    expect(svg).toContain('<svg');
+
+    const tasks = catalog.connectors.find((c) => c.name === 'task');
+    expect(tasks).toMatchObject({
+      displayName: 'Tasks',
+      i18n: {
+        de: { displayName: 'Aufgaben' },
+        fr: { displayName: 'Tâches' },
+      },
+    });
+    // A connector that ships no icon answers without one; the face falls
+    // back to its own glyph.
+    const conversations = catalog.connectors.find(
+      (c) => c.name === 'conversation',
+    );
+    expect(conversations).toBeDefined();
+    expect(conversations?.iconUrl).toBeUndefined();
+  });
+});
diff --git a/services/platform/backend/domains/automations/routes.ts b/services/platform/backend/domains/automations/routes.ts
index d042832145..2bab9e4c5f 100644
--- a/services/platform/backend/domains/automations/routes.ts
+++ b/services/platform/backend/domains/automations/routes.ts
@@ -6,6 +6,7 @@ import { registerConnector } from '../../../lib/connectors/registry.ts';
 import { dispatch } from '../../../lib/engine/api/dispatch.ts';
 import { nodeTypes } from '../../../lib/engine/core/slots.ts';
 import { AppError } from '../../../lib/shared/errors/app-error';
+import type { NodeTypeCatalog } from '../../../lib/shared/schemas/node-type-catalog.ts';
 import { isRecord } from '../../../lib/utils/type-utils.ts';
 import type { Auth } from '../../auth/auth.ts';
 import { isAdminOrDeveloperRole } from '../../auth/membership.ts';
@@ -13,6 +14,7 @@ import { requireOrgMember, type OrgEnv } from '../../auth/org.ts';
 import { requireSession } from '../../auth/session.ts';
 import { assembleAutomationAuthoringHost } from '../../core/automations/authoring_host.ts';
 import {
+  connectorIconUrl,
   findConnector,
   loadConnectorDefinitions,
 } from '../../core/connector_credentials/connector_catalog.ts';
@@ -447,17 +449,22 @@ export function createAutomationRoutes(deps: {
   });
 
   /** Node-type catalog (the 0.4 `catalog.listNodeTypes` — connector types
-   * only; the editor folds its own core floor over these). */
+   * only; the editor folds its own core floor over these). Each action
+   * carries its connector and its title in every language it ships in; each
+   * connector, once, its display name and its icon as a data URL, so a node
+   * reads "GitHub · List issues" in the reader's language. */
   app.get('/catalog/node-types', async (c) => {
     const denied = requireAuthor(c);
     if (denied) return denied;
-    for (const connector of loadConnectorDefinitions()) {
+    const definitions = loadConnectorDefinitions();
+    for (const connector of definitions) {
       registerConnector(connector);
     }
-    const summaries = [];
+    const nodeTypeRows: NodeTypeCatalog['nodeTypes'] = [];
     for (const def of nodeTypes().values()) {
       if (def.kind !== 'connector') continue;
-      summaries.push({
+      const display = def.connector?.display;
+      nodeTypeRows.push({
         type: def.type,
         kind: def.kind,
         description: def.description,
@@ -465,10 +472,26 @@ export function createAutomationRoutes(deps: {
         requiredFields: [...def.requiredFields],
         outputKind: def.outputKind,
         hasEffect: def.connector?.hasEffect ?? false,
+        ...(display !== undefined && { connector: display.connector }),
+        ...(display?.title !== undefined && { title: display.title }),
+        ...(display?.i18n !== undefined && { i18n: display.i18n }),
       });
     }
-    summaries.sort((a, b) => a.type.localeCompare(b.type));
-    return c.json({ nodeTypes: summaries });
+    nodeTypeRows.sort((a, b) => a.type.localeCompare(b.type));
+    const connectors: NodeTypeCatalog['connectors'] = [];
+    for (const connector of definitions) {
+      const row: NodeTypeCatalog['connectors'][number] = {
+        name: connector.name,
+        displayName: connector.displayName,
+      };
+      if (connector.i18n !== undefined) row.i18n = connector.i18n;
+      const iconUrl = connectorIconUrl(connector.name);
+      if (iconUrl !== undefined) row.iconUrl = iconUrl;
+      connectors.push(row);
+    }
+    connectors.sort((a, b) => a.name.localeCompare(b.name));
+    const body: NodeTypeCatalog = { nodeTypes: nodeTypeRows, connectors };
+    return c.json(body);
   });
 
   /** Run KPIs for the metrics page (member-readable, like the 0.4 query). */
diff --git a/services/platform/lib/connectors/registry.test.ts b/services/platform/lib/connectors/registry.test.ts
index 1114fc7b38..d7b46f552a 100644
--- a/services/platform/lib/connectors/registry.test.ts
+++ b/services/platform/lib/connectors/registry.test.ts
@@ -55,6 +55,19 @@ describe('connector registry', () => {
     expect(def?.connector?.outputSignature).toContain('number');
   });
 
+  it('carries the connector and the localized title for display, nothing the engine reads', () => {
+    const display = nodeTypes().get(nodeTypeFor('github', 'list_issues'))
+      ?.connector?.display;
+    expect(display).toEqual({
+      connector: 'github',
+      title: 'List issues',
+      i18n: {
+        de: { title: 'Issues auflisten' },
+        fr: { title: 'Lister les issues' },
+      },
+    });
+  });
+
   it('marks write actions as effectful and read actions as not', () => {
     expect(
       nodeTypes().get(nodeTypeFor('github', 'create_issue'))?.connector
diff --git a/services/platform/lib/connectors/registry.ts b/services/platform/lib/connectors/registry.ts
index 8125a873d3..e2366437d4 100644
--- a/services/platform/lib/connectors/registry.ts
+++ b/services/platform/lib/connectors/registry.ts
@@ -48,6 +48,11 @@ function toConnector(
     exampleInput: action.exampleInput,
     hasEffect: action.effects === 'write',
     tags: connector.tags,
+    display: {
+      connector: connector.name,
+      ...(action.title !== undefined && { title: action.title }),
+      ...(action.i18n !== undefined && { i18n: action.i18n }),
+    },
     mock: (input) =>
       codeRunner().runBody(
         action.mock,
diff --git a/services/platform/lib/engine/core/slots.ts b/services/platform/lib/engine/core/slots.ts
index ae406e8863..00ca13d424 100644
--- a/services/platform/lib/engine/core/slots.ts
+++ b/services/platform/lib/engine/core/slots.ts
@@ -34,6 +34,8 @@ export interface ConnectorLike {
    * and effect recording). */
   hasEffect: boolean;
   tags?: string[];
+  /** How a person reads a node of this type; never read by the engine. */
+  display?: ConnectorActionDisplay;
   /**
    * Deterministic mock: same input → same output, no IO.
    *
@@ -45,6 +47,18 @@ export interface ConnectorLike {
   live?(input: unknown, ctx: ConnectorContext): Promise<unknown>;
 }
 
+/**
+ * The display half of a connector action: the connector it belongs to (its
+ * catalog slug, the first half of the node type) and the action's title in
+ * English with its per-locale overrides (`de`, `fr`, `de-CH`). Surfaces such
+ * as the automation canvas name a node "GitHub · List issues" from it.
+ */
+export interface ConnectorActionDisplay {
+  connector: string;
+  title?: string;
+  i18n?: Record<string, { title?: string }>;
+}
+
 /**
  * A blob the host persisted on a connector's behalf. `id` is how the platform
  * addresses it afterwards; `url` is present only when the store can expose a
diff --git a/services/platform/lib/shared/schemas/node-type-catalog.ts b/services/platform/lib/shared/schemas/node-type-catalog.ts
new file mode 100644
index 0000000000..c6d2b290c7
--- /dev/null
+++ b/services/platform/lib/shared/schemas/node-type-catalog.ts
@@ -0,0 +1,53 @@
+/**
+ * The node-type catalog as the automation editor reads it off the wire
+ * (`GET /api/app/automations/catalog/node-types`): one row per connector
+ * action, and the connectors those actions belong to, once each.
+ *
+ * Besides what the editor validates a node against (fields, output kind,
+ * whether it writes), a row carries what a person reads on the canvas: the
+ * connector it belongs to and the action's title in English with its
+ * per-locale overrides. The connector rows carry the display name (with its
+ * overrides, for a connector named with ordinary words rather than a brand)
+ * and the shipped icon as a data URL. The route builds this shape and the app
+ * parses it at the boundary, so a foreign answer is a failed read, never a
+ * cast; keys this build does not know are stripped.
+ */
+
+import { z } from 'zod';
+
+const nodeTypeSummarySchema = z.object({
+  type: z.string(),
+  kind: z.enum(['connector', 'core']),
+  description: z.string(),
+  allowedFields: z.array(z.string()),
+  requiredFields: z.array(z.string()),
+  outputKind: z.enum(['structured', 'unstructured']),
+  hasEffect: z.boolean().optional(),
+  /** The connector's catalog slug — the first half of `type`. */
+  connector: z.string().optional(),
+  /** The action in words, in English ("List issues"). */
+  title: z.string().optional(),
+  /** Per-locale overrides of `title`: the exact tag, then its base language,
+   * then the English. */
+  i18n: z
+    .record(z.string(), z.object({ title: z.string().optional() }))
+    .optional(),
+});
+
+const connectorDisplaySchema = z.object({
+  name: z.string(),
+  displayName: z.string(),
+  /** Per-locale overrides of `displayName`; a brand has none. */
+  i18n: z
+    .record(z.string(), z.object({ displayName: z.string().optional() }))
+    .optional(),
+  /** The shipped `icon.svg` as a data URL; absent when none ships. */
+  iconUrl: z.string().optional(),
+});
+
+export const nodeTypeCatalogSchema = z.object({
+  nodeTypes: z.array(nodeTypeSummarySchema),
+  connectors: z.array(connectorDisplaySchema).default([]),
+});
+
+export type NodeTypeCatalog = z.infer<typeof nodeTypeCatalogSchema>;

From e775355e3f8665f8d55cc61fac00a6952e0f4931 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:05:15 +0200
Subject: [PATCH 04/78] docs: describe connector action titles and translated
 display names

The connector contract pages in English, German and French list the
action's title and its i18n overrides, and say when a connector carries
translated display names and when a brand keeps its own.
---
 docs/de/develop/connectors.md | 3 +++
 docs/en/develop/connectors.md | 3 +++
 docs/fr/develop/connectors.md | 3 +++
 3 files changed, 9 insertions(+)

diff --git a/docs/de/develop/connectors.md b/docs/de/develop/connectors.md
index cd3c789ef9..498af61aeb 100644
--- a/docs/de/develop/connectors.md
+++ b/docs/de/develop/connectors.md
@@ -25,6 +25,8 @@ auth:
   - method: api-key
 ```
 
+Ein Connector, dessen Name aus gewöhnlichen Wörtern besteht, etwa `task` (Tasks), deklariert zusätzlich `i18n.de.displayName` und `i18n.fr.displayName`. Ein Connector, der nach einem Produkt heißt, etwa Tavily, behält seinen Namen in jeder Sprache.
+
 ### Erlaubte Ziele festlegen
 
 | Feld | Bedeutung |
@@ -47,6 +49,7 @@ Ein neuer Connector ist ein Quellcodebeitrag. Die Laufzeit liest den Plattformka
 | Feld | Vertrag für Autor und Aufrufer |
 | --- | --- |
 | `name`, `description` | Stabiler Aktionsname in snake_case und eine Erklärung zum Einsatzzweck |
+| `title`, `i18n` | Die Aktion in Worten für Menschen: ein kurzer englischer `title`, nur am Anfang großgeschrieben und ohne den Namen des Connectors („List issues“), dazu `i18n.de.title` und `i18n.fr.title` (und `de-CH`, wo die Schweizer Schreibung abweicht, etwa beim ß). Der Automatisierungs-Canvas zeigt eine Node als „GitHub · Issues auflisten“ in der Sprache der Lesenden; fehlt einer mitgelieferten Aktion einer der drei, schlagen die Tests des Katalogs fehl |
 | `input` | Objekt-JSON-Schema, vor der Ausführung validiert; Felder beschreiben und Pflichtfelder markieren |
 | `output` | Ergebnissignatur im TypeScript-Stil; Dokumentation, keine Laufzeitvalidierung der Ausgabe |
 | `effects` | `read` oder `write`; Schreibaktionen durchlaufen die Genehmigungsrichtlinie |
diff --git a/docs/en/develop/connectors.md b/docs/en/develop/connectors.md
index 2d4cc00851..d7f5a628b6 100644
--- a/docs/en/develop/connectors.md
+++ b/docs/en/develop/connectors.md
@@ -25,6 +25,8 @@ auth:
   - method: api-key
 ```
 
+A connector named with ordinary words, such as `task` (Tasks), also declares `i18n.de.displayName` and `i18n.fr.displayName`. A connector named after a product, such as Tavily, keeps its name in every language.
+
 ### Set the destination boundary
 
 | Field | Meaning |
@@ -47,6 +49,7 @@ Adding a connector is a source contribution. The runtime reads the platform cata
 | Field | Contract for the author and caller |
 | --- | --- |
 | `name`, `description` | Stable snake_case action name and an explanation of when to use it |
+| `title`, `i18n` | The action in words for people: a short English `title` in sentence case, without the connector's name ("List issues"), plus `i18n.de.title` and `i18n.fr.title` (and `de-CH` where the Swiss spelling differs). The automation canvas shows a node as "GitHub · List issues" in the reader's language; a shipped action without all three fails the catalog's tests |
 | `input` | Object JSON Schema, validated before execution; describe fields and mark required ones |
 | `output` | TypeScript-style signature describing the result; this is documentation, not a runtime output validator |
 | `effects` | `read` or `write`; writes pass through approval policy |
diff --git a/docs/fr/develop/connectors.md b/docs/fr/develop/connectors.md
index 4766be4305..e8f74f6437 100644
--- a/docs/fr/develop/connectors.md
+++ b/docs/fr/develop/connectors.md
@@ -25,6 +25,8 @@ auth:
   - method: api-key
 ```
 
+Un connector dont le nom est fait de mots courants, comme `task` (Tasks), déclare aussi `i18n.de.displayName` et `i18n.fr.displayName`. Un connector qui porte le nom d’un produit, comme Tavily, garde ce nom dans toutes les langues.
+
 ### Définir les destinations autorisées
 
 | Champ | Signification |
@@ -47,6 +49,7 @@ Ajouter un connector demande une contribution au code source. L'exécution lit l
 | Champ | Contrat pour l'auteur et l'appelant |
 | --- | --- |
 | `name`, `description` | Nom stable en snake_case et explication de l'usage de l'action |
+| `title`, `i18n` | L’action en mots pour les personnes : un `title` anglais court, avec une seule majuscule initiale et sans le nom du connector (« List issues »), plus `i18n.de.title` et `i18n.fr.title` (et `de-CH` quand l’orthographe suisse diffère). Le canevas d’automatisation affiche un nœud sous la forme « GitHub · Lister les issues » dans la langue du lecteur ; une action fournie à laquelle il en manque un fait échouer les tests du catalogue |
 | `input` | Schéma JSON objet, validé avant exécution ; décrire les champs et signaler ceux requis |
 | `output` | Signature du résultat au style TypeScript ; documentation, pas validation des sorties à l'exécution |
 | `effects` | `read` ou `write` ; les écritures passent par la politique d'approbation |

From f2ee1b18bbfca29a640e40cf14418726f4307546 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:19:29 +0200
Subject: [PATCH 05/78] feat(ui): colour every code block with one AA palette

Read-only code (chat, docs, the guides) used Shiki's min-light and
min-dark themes, whose comments, parameters, constants and string
expressions fell below 4.5:1. The --code-* variables in globals.css now
hold one palette, corrected to AA on every code surface in both themes,
and Shiki reads it through its css-variables theme: one highlight serves
light and dark, so a theme switch no longer tokenizes again.

Template-aware grammars (tale-template, json-template, yaml-template,
markdown-template) highlight {{ js }} expressions as JavaScript, and
only under their own roots, so plain YAML keeps Helm or Jinja braces as
text. code-palette.test.ts measures every token on each surface.
---
 packages/ui/src/globals.css                   |  75 ++++++
 packages/ui/src/lib/code-palette.test.ts      | 222 ++++++++++++++++
 packages/ui/src/lib/code-roles.ts             |  82 ++++++
 .../ui/src/markdown/highlighted-code.test.tsx |  17 +-
 packages/ui/src/markdown/highlighted-code.tsx |  56 ++--
 .../src/markdown/shiki-template-grammars.ts   |  82 ++++++
 packages/ui/src/markdown/shiki.test.ts        | 180 ++++++++++---
 packages/ui/src/markdown/shiki.ts             | 240 ++++++++++--------
 8 files changed, 772 insertions(+), 182 deletions(-)
 create mode 100644 packages/ui/src/lib/code-palette.test.ts
 create mode 100644 packages/ui/src/lib/code-roles.ts
 create mode 100644 packages/ui/src/markdown/shiki-template-grammars.ts

diff --git a/packages/ui/src/globals.css b/packages/ui/src/globals.css
index 8b277f00bf..1817c5baad 100644
--- a/packages/ui/src/globals.css
+++ b/packages/ui/src/globals.css
@@ -253,6 +253,44 @@
   --chart-primary: 217 91% 60%;
   --radius: 0.5rem;
   --chat-max-width: 48rem;
+
+  /* Code: one palette for every renderer. Shiki's read-only blocks (its
+     css-variables theme, prefix `--code-`) and the code editor's highlight
+     style both read these roles, so a value reads the same while it is
+     edited and while it is shown. Every token colour clears 4.5:1 on
+     `--background`, `--color-bg-elevated` (the code-block surface) and
+     `--card`, and on the template tint over each — `code-palette.test.ts`
+     holds the line. They started from Shiki's min-light, whose comments
+     (1.69:1), parameters, constants and string expressions failed AA. */
+  --code-foreground: #24292e;
+  --code-background: transparent;
+  --code-token-keyword: #c62828;
+  --code-token-string: #2b5581;
+  --code-token-string-expression: #1f7a35;
+  --code-token-constant: #1565c0;
+  --code-token-function: #6f42c1;
+  --code-token-parameter: #9a5b00;
+  --code-token-comment: #5f6b76;
+  --code-token-punctuation: #212121;
+  --code-token-link: #1565c0;
+  --code-token-inserted: #1f7a35;
+  --code-token-deleted: #b31d28;
+  --code-token-changed: #005cc5;
+  --code-invalid: hsl(var(--destructive));
+  /* Editor chrome. The line numbers match `.code-block-numbered`; the
+     squiggles are non-text marks and keep 3:1 on every code surface and on
+     the template tint (amber-600 drops to 2.8:1 on the tint, so the warning
+     takes amber-700, the colour of the warning glyph). */
+  --code-line-number: var(--color-fg-subtle);
+  --code-line-number-active: hsl(var(--foreground));
+  --code-active-line: hsl(var(--foreground) / 0.04);
+  --code-selection: hsl(var(--info-foreground) / 0.18);
+  --code-selection-inactive: hsl(var(--foreground) / 0.08);
+  --code-template-tint: hsl(var(--info-foreground) / 0.05);
+  --code-match: hsl(var(--info-foreground) / 0.15);
+  --code-squiggle-error: hsl(var(--destructive));
+  --code-squiggle-warning: #b45309;
+  --code-squiggle-info: hsl(var(--info-foreground));
 }
 
 .dark {
@@ -334,6 +372,43 @@
   --chart-warning: 43 96% 56%;
   --chart-neutral: 0 0% 55%;
   --chart-primary: 213 94% 68%;
+
+  /* Code (dark). From Shiki's min-dark; plain text is neutral instead of
+     min-dark's purple, so a prompt written in prose reads as text, and
+     comments lift to 5:1. */
+  --code-foreground: #e1e4e8;
+  --code-token-keyword: #f97583;
+  --code-token-string: #9db1c5;
+  --code-token-string-expression: #ffab70;
+  --code-token-constant: #79b8ff;
+  --code-token-function: #b392f0;
+  --code-token-parameter: #ff9800;
+  --code-token-comment: #8b949e;
+  --code-token-punctuation: #bbbbbb;
+  --code-token-link: #ffab70;
+  --code-token-inserted: #85e89d;
+  --code-token-deleted: #f97583;
+  --code-token-changed: #79b8ff;
+  --code-active-line: hsl(var(--foreground) / 0.05);
+  --code-selection: hsl(var(--info-foreground) / 0.3);
+  --code-selection-inactive: hsl(var(--foreground) / 0.12);
+  --code-template-tint: hsl(var(--info-foreground) / 0.1);
+  --code-match: hsl(var(--info-foreground) / 0.25);
+  --code-squiggle-warning: #f59e0b;
+}
+
+/* Windows contrast themes repaint text in their own colours; the selection
+   and the problem underlines follow the system's highlight and text colours
+   so they stay visible. */
+@media (forced-colors: active) {
+  :root,
+  .dark {
+    --code-selection: Highlight;
+    --code-selection-inactive: Highlight;
+    --code-squiggle-error: CanvasText;
+    --code-squiggle-warning: CanvasText;
+    --code-squiggle-info: CanvasText;
+  }
 }
 
 @media (prefers-reduced-motion: reduce) {
diff --git a/packages/ui/src/lib/code-palette.test.ts b/packages/ui/src/lib/code-palette.test.ts
new file mode 100644
index 0000000000..2405abd91e
--- /dev/null
+++ b/packages/ui/src/lib/code-palette.test.ts
@@ -0,0 +1,222 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The code palette (`--code-*` in `globals.css`) is read by every code
+ * surface: Shiki's read-only blocks in chat, docs and the guides, and the
+ * code editor. Shiki's min-light and min-dark failed AA there (comments
+ * 1.69:1 on the code-block surface, parameters 2.06:1, constants 4.40:1),
+ * so every token colour here must clear 4.5:1 on each surface code sits on
+ * — the page, the code-block surface and a card — and on the template tint
+ * over each, in both themes. The editor's line numbers are text (4.5:1);
+ * its problem underlines are marks (3:1).
+ */
+
+// Comments name tokens too (`--background: …` in prose); read declarations only.
+const css = readFileSync(join(__dirname, '..', 'globals.css'), 'utf8').replace(
+  /\/\*[\s\S]*?\*\//g,
+  '',
+);
+
+type Rgb = [number, number, number];
+
+function block(selector: string): string {
+  const start = css.indexOf(`\n${selector} {`);
+  if (start < 0) throw new Error(`no ${selector} block in globals.css`);
+  return css.slice(start, css.indexOf('\n}', start));
+}
+
+const THEME_BLOCK = (() => {
+  const start = css.indexOf('@theme {');
+  return css.slice(start, css.indexOf('\n}', start));
+})();
+
+function declared(scope: string, name: string): string | undefined {
+  const match = new RegExp(`--${name}:\\s*([^;]+);`).exec(scope);
+  return match?.[1].trim();
+}
+
+/** HSL → sRGB 0..255, the CSS Color 4 algorithm. */
+function hslToRgb(h: number, s: number, l: number): Rgb {
+  const sat = s / 100;
+  const light = l / 100;
+  const f = (n: number) => {
+    const k = (n + h / 30) % 12;
+    const a = sat * Math.min(light, 1 - light);
+    return light - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [f(0), f(8), f(4)].map((v) => Math.round(v * 255)) as Rgb;
+}
+
+function hexToRgb(hex: string): Rgb {
+  const digits = hex.replace('#', '');
+  return [0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16)) as Rgb;
+}
+
+interface Paint {
+  rgb: Rgb;
+  alpha: number;
+}
+
+/**
+ * Resolves a declared colour in a theme: a hex, `hsl(var(--x))`,
+ * `hsl(var(--x) / a)` or `var(--color-…)`, following variables through the
+ * theme's block, then `:root`, then `@theme`.
+ */
+function resolve(theme: 'light' | 'dark', value: string): Paint {
+  const scopes =
+    theme === 'dark' ? [block('.dark'), block(':root')] : [block(':root')];
+  const lookup = (name: string): string => {
+    for (const scope of [...scopes, THEME_BLOCK]) {
+      const found = declared(scope, name);
+      if (found !== undefined) return found;
+    }
+    throw new Error(`--${name} is not declared`);
+  };
+  const hex = /^#[0-9a-f]{6}$/i.exec(value);
+  if (hex) return { rgb: hexToRgb(value), alpha: 1 };
+  // The legacy tokens hold a bare HSL triple: `0 0% 3.92%`.
+  const triple = /^([\d.]+)\s+([\d.]+)%\s+([\d.]+)%$/.exec(value);
+  if (triple) {
+    return {
+      rgb: hslToRgb(Number(triple[1]), Number(triple[2]), Number(triple[3])),
+      alpha: 1,
+    };
+  }
+  const hsl = /^hsl\(var\(--([a-z-]+)\)(?:\s*\/\s*([\d.]+))?\)$/.exec(value);
+  if (hsl) {
+    const [h, s, l] = lookup(hsl[1])
+      .replaceAll('%', '')
+      .split(/\s+/)
+      .map(Number);
+    return { rgb: hslToRgb(h, s, l), alpha: hsl[2] ? Number(hsl[2]) : 1 };
+  }
+  const variable = /^var\(--([a-z-]+)\)$/.exec(value);
+  if (variable) return resolve(theme, lookup(variable[1]));
+  throw new Error(`cannot resolve ${value}`);
+}
+
+function token(theme: 'light' | 'dark', name: string): Paint {
+  const scopes =
+    theme === 'dark'
+      ? [block('.dark'), block(':root'), THEME_BLOCK]
+      : [block(':root'), THEME_BLOCK];
+  for (const scope of scopes) {
+    const found = declared(scope, name);
+    if (found !== undefined) return resolve(theme, found);
+  }
+  throw new Error(`--${name} is not declared`);
+}
+
+function over(top: Paint, base: Rgb): Rgb {
+  return top.rgb.map((c, i) =>
+    Math.round(c * top.alpha + base[i] * (1 - top.alpha)),
+  ) as Rgb;
+}
+
+function luminance(rgb: Rgb): number {
+  const [r, g, b] = rgb.map((c) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrast(a: Rgb, b: Rgb): number {
+  const la = luminance(a);
+  const lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * The surfaces code sits on, with the template tint over the editor's. The
+ * tint is the editor's chip behind a `{{ }}` expression; read-only blocks
+ * draw none, and `muted` is a read-only surface only (the chat's code
+ * blocks, the document preview).
+ */
+function surfaces(theme: 'light' | 'dark'): Array<[string, Rgb]> {
+  const editor: Array<[string, Rgb]> = [
+    ['background', token(theme, 'background').rgb],
+    ['bg-elevated', token(theme, 'color-bg-elevated').rgb],
+    ['card', token(theme, 'card').rgb],
+  ];
+  const tint = token(theme, 'code-template-tint');
+  return [
+    ...editor,
+    ...editor.map(([name, rgb]): [string, Rgb] => [
+      `${name} + template`,
+      over(tint, rgb),
+    ]),
+    ['muted', token(theme, 'muted').rgb],
+  ];
+}
+
+const TOKENS = [
+  'code-foreground',
+  'code-token-keyword',
+  'code-token-string',
+  'code-token-string-expression',
+  'code-token-constant',
+  'code-token-function',
+  'code-token-parameter',
+  'code-token-comment',
+  'code-token-punctuation',
+  'code-token-link',
+  'code-token-inserted',
+  'code-token-deleted',
+  'code-token-changed',
+  'code-invalid',
+];
+
+const MARKS = [
+  'code-squiggle-error',
+  'code-squiggle-warning',
+  'code-squiggle-info',
+];
+
+describe.each(['light', 'dark'] as const)('the %s code palette', (theme) => {
+  it.each(TOKENS)('--%s clears 4.5:1 on every code surface', (name) => {
+    const colour = token(theme, name).rgb;
+    for (const [surface, rgb] of surfaces(theme)) {
+      expect(
+        contrast(colour, rgb),
+        `--${name} on ${surface}`,
+      ).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+
+  it('keeps the line numbers at 4.5:1 on the editor and code-block surfaces', () => {
+    for (const name of ['code-line-number', 'code-line-number-active']) {
+      const colour = token(theme, name).rgb;
+      for (const [surface, rgb] of surfaces(theme).slice(0, 3)) {
+        expect(
+          contrast(colour, rgb),
+          `--${name} on ${surface}`,
+        ).toBeGreaterThanOrEqual(4.5);
+      }
+    }
+  });
+
+  it.each(MARKS)('--%s keeps 3:1 as a mark, tint included', (name) => {
+    const colour = token(theme, name).rgb;
+    for (const [surface, rgb] of surfaces(theme)) {
+      expect(
+        contrast(colour, rgb),
+        `--${name} on ${surface}`,
+      ).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  it('keeps selected text readable', () => {
+    const selection = token(theme, 'code-selection');
+    const foreground = token(theme, 'code-foreground').rgb;
+    for (const [surface, rgb] of surfaces(theme).slice(0, 3)) {
+      expect(
+        contrast(foreground, over(selection, rgb)),
+        `foreground on the selection over ${surface}`,
+      ).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+});
diff --git a/packages/ui/src/lib/code-roles.ts b/packages/ui/src/lib/code-roles.ts
new file mode 100644
index 0000000000..653ef5a9e8
--- /dev/null
+++ b/packages/ui/src/lib/code-roles.ts
@@ -0,0 +1,82 @@
+/**
+ * The colour roles of highlighted code — the one vocabulary the read-only
+ * renderer (Shiki) and the code editor (CodeMirror) share.
+ *
+ * Each role is a CSS variable in `globals.css` (`:root` and `.dark`). Shiki
+ * reads them through its css-variables theme (prefix `--code-`, so its own
+ * names line up with ours); the editor's highlight style maps its syntax tags
+ * onto the same variables. A value therefore has one colour wherever it
+ * shows, and a theme switch changes the variables, not the highlighted HTML.
+ */
+
+/**
+ * What a code field holds, for the editor and for read-only highlighting.
+ *
+ * - `javascript` — a script: statements, a top-level `return` (a transform
+ *   node's code).
+ * - `expression` — one JavaScript expression (a bare condition).
+ * - `json`, `yaml`.
+ * - `markdown` — GitHub-flavoured Markdown, highlighted only (no preview).
+ * - `template` — text with `{{ js }}` expressions in it.
+ * - `text` — plain text.
+ */
+export type CodeLanguage =
+  | 'javascript'
+  | 'expression'
+  | 'json'
+  | 'yaml'
+  | 'markdown'
+  | 'template'
+  | 'text';
+
+export const CODE_LANGUAGES: readonly CodeLanguage[] = [
+  'javascript',
+  'expression',
+  'json',
+  'yaml',
+  'markdown',
+  'template',
+  'text',
+];
+
+export const CODE_ROLES = [
+  'foreground',
+  'keyword',
+  'string',
+  'string-expression',
+  'constant',
+  'function',
+  'parameter',
+  'comment',
+  'punctuation',
+  'link',
+  'inserted',
+  'deleted',
+  'changed',
+  'invalid',
+] as const;
+
+export type CodeRole = (typeof CODE_ROLES)[number];
+
+/** The CSS variable that holds a role's colour. */
+function codeRoleVariable(role: CodeRole): string {
+  if (role === 'foreground') return '--code-foreground';
+  if (role === 'invalid') return '--code-invalid';
+  return `--code-token-${role}`;
+}
+
+const ROLE_BY_VARIABLE = new Map<string, CodeRole>(
+  CODE_ROLES.map((role) => [codeRoleVariable(role), role]),
+);
+
+/**
+ * The role a highlighted token's colour names (`var(--code-token-keyword)`
+ * → `keyword`); `null` for a colour outside the palette. Shiki's
+ * css-variables theme writes exactly these values.
+ */
+export function codeRoleOfColor(color: string | undefined): CodeRole | null {
+  if (color === undefined) return null;
+  const match = /^var\((--code-[a-z-]+)(?:,[^)]*)?\)$/i.exec(color.trim());
+  if (match === null) return null;
+  return ROLE_BY_VARIABLE.get(match[1].toLowerCase()) ?? null;
+}
diff --git a/packages/ui/src/markdown/highlighted-code.test.tsx b/packages/ui/src/markdown/highlighted-code.test.tsx
index 6448fb7ab9..7e7cf363c0 100644
--- a/packages/ui/src/markdown/highlighted-code.test.tsx
+++ b/packages/ui/src/markdown/highlighted-code.test.tsx
@@ -86,7 +86,7 @@ describe('HighlightedCode viewport work', () => {
       <HighlightedCode code={'warm\n'} language="js" />,
     );
     expect(container.querySelector('code span')).toHaveTextContent('warm');
-    expect(peekHighlightedCode).toHaveBeenCalledWith('warm', 'js', 'light');
+    expect(peekHighlightedCode).toHaveBeenCalledWith('warm', 'js');
     await setVisible(true);
     expect(highlightCode).not.toHaveBeenCalled();
   });
@@ -116,7 +116,7 @@ describe('HighlightedCode viewport work', () => {
     expect(container.querySelector('code span')).toBeNull();
     expect(highlightCode).toHaveBeenCalledOnce();
     await setVisible(true);
-    expect(highlightCode).toHaveBeenLastCalledWith('new', 'js', 'light');
+    expect(highlightCode).toHaveBeenLastCalledWith('new', 'js');
     expect(highlightCode).toHaveBeenCalledTimes(2);
   });
 
@@ -129,21 +129,22 @@ describe('HighlightedCode viewport work', () => {
     rerender(<HighlightedCode code="value" language="py" />);
     expect(container.querySelector('code span')).toBeNull();
     await setVisible(true);
-    expect(highlightCode).toHaveBeenLastCalledWith('value', 'py', 'light');
+    expect(highlightCode).toHaveBeenLastCalledWith('value', 'py');
     expect(highlightCode).toHaveBeenCalledTimes(2);
   });
 
-  it('invalidates cached decoration for a different theme', async () => {
+  // The highlight colours through the `--code-*` variables, which the theme
+  // switches; tokenizing again on a theme switch flashed plain text.
+  it('keeps its highlight across a theme switch', async () => {
     const { container, rerender } = render(
       <HighlightedCode code="value" language="js" className="light" />,
     );
     await setVisible(true);
-    await setVisible(false);
     theme.value = 'dark';
     rerender(<HighlightedCode code="value" language="js" className="dark" />);
-    expect(container.querySelector('code span')).toBeNull();
+    expect(container.querySelector('code span')).not.toBeNull();
+    await setVisible(false);
     await setVisible(true);
-    expect(highlightCode).toHaveBeenLastCalledWith('value', 'js', 'dark');
-    expect(highlightCode).toHaveBeenCalledTimes(2);
+    expect(highlightCode).toHaveBeenCalledOnce();
   });
 });
diff --git a/packages/ui/src/markdown/highlighted-code.tsx b/packages/ui/src/markdown/highlighted-code.tsx
index 97ceb98fc3..d36ce99c1b 100644
--- a/packages/ui/src/markdown/highlighted-code.tsx
+++ b/packages/ui/src/markdown/highlighted-code.tsx
@@ -4,7 +4,6 @@ import { memo, useEffect, useMemo, useState } from 'react';
 import { useViewportVisibility } from '../hooks/use-viewport-visibility';
 import { useT } from '../i18n/client';
 import { cn } from '../lib/cn';
-import { useTheme } from '../theme';
 import { highlightCode, peekHighlightedCode } from './shiki';
 
 const LINE_NUMBER_THRESHOLD = 3;
@@ -59,7 +58,6 @@ export const HighlightedCode = memo(function HighlightedCode({
   className,
 }: HighlightedCodeProps) {
   const { t } = useT('markdownCopy');
-  const { resolvedTheme } = useTheme();
   const { ref, isVisible } = useViewportVisibility<HTMLDivElement>();
   const [copied, setCopied] = useState(false);
 
@@ -72,19 +70,19 @@ export const HighlightedCode = memo(function HighlightedCode({
     () => (code.endsWith('\n') ? code.slice(0, -1) : code),
     [code],
   );
-  // A snippet highlighted before shows highlighted from the first frame.
+  // A snippet highlighted before shows highlighted from the first frame. The
+  // HTML colours through the `--code-*` variables, so a theme switch repaints
+  // it without highlighting again.
   const [highlighted, setHighlighted] = useState<{
     code: string;
     language: string | undefined;
-    theme: string;
     html: string;
   } | null>(() => {
-    const known = peekHighlightedCode(normalisedCode, language, resolvedTheme);
+    const known = peekHighlightedCode(normalisedCode, language);
     if (known === null) return null;
     return {
       code: normalisedCode,
       language,
-      theme: resolvedTheme,
       html:
         known.language === 'diff'
           ? applyDiffLineBackgrounds(known.html)
@@ -96,40 +94,34 @@ export const HighlightedCode = memo(function HighlightedCode({
     if (!isVisible) return undefined;
     if (
       highlighted?.code === normalisedCode &&
-      highlighted.language === language &&
-      highlighted.theme === resolvedTheme
+      highlighted.language === language
     )
       return undefined;
     let cancelled = false;
-    void highlightCode(normalisedCode, language, resolvedTheme).then(
-      (result) => {
-        if (cancelled) return;
-        if (!result) {
-          // Oversized input or highlighter init failure — drop the cached
-          // html so the plain `<pre>` fallback renders the new source.
-          setHighlighted(null);
-          return;
-        }
-        setHighlighted({
-          code: normalisedCode,
-          language,
-          theme: resolvedTheme,
-          html:
-            result.language === 'diff'
-              ? applyDiffLineBackgrounds(result.html)
-              : result.html,
-        });
-      },
-    );
+    void highlightCode(normalisedCode, language).then((result) => {
+      if (cancelled) return;
+      if (!result) {
+        // Oversized input or highlighter init failure — drop the cached
+        // html so the plain `<pre>` fallback renders the new source.
+        setHighlighted(null);
+        return;
+      }
+      setHighlighted({
+        code: normalisedCode,
+        language,
+        html:
+          result.language === 'diff'
+            ? applyDiffLineBackgrounds(result.html)
+            : result.html,
+      });
+    });
     return () => {
       cancelled = true;
     };
-  }, [normalisedCode, language, resolvedTheme, isVisible, highlighted]);
+  }, [normalisedCode, language, isVisible, highlighted]);
 
   const html =
-    highlighted?.code === normalisedCode &&
-    highlighted.language === language &&
-    highlighted.theme === resolvedTheme
+    highlighted?.code === normalisedCode && highlighted.language === language
       ? highlighted.html
       : null;
 
diff --git a/packages/ui/src/markdown/shiki-template-grammars.ts b/packages/ui/src/markdown/shiki-template-grammars.ts
new file mode 100644
index 0000000000..b44f8fcdcd
--- /dev/null
+++ b/packages/ui/src/markdown/shiki-template-grammars.ts
@@ -0,0 +1,82 @@
+import type { LanguageRegistration } from 'shiki/core';
+
+/**
+ * Read-only highlighting for Tale's `{{ js }}` templates.
+ *
+ * One injection grammar finds `{{ … }}` and highlights its body as a
+ * JavaScript expression; four wrapper languages decide where it may fire:
+ *
+ * - `tale-template` — plain text with templates (a forEach, a prompt line);
+ * - `json-template` — templates inside JSON strings (a connector's input);
+ * - `yaml-template` — templates inside YAML scalars (an automation file);
+ * - `markdown-template` — templates anywhere in Markdown but its comments.
+ *
+ * The injection only fires under these wrappers' own root scopes, so a
+ * Helm, Jinja or Go-template YAML file in a chat answer (plain `yaml`) keeps
+ * its braces as text. The body uses the JavaScript grammar's `expression`
+ * rules, which consume brackets and strings, so `{{ "}}" }}` and
+ * `{{ ({ a: { b: 1 } }) }}` close at the right brace. A template the line
+ * ends inside stops at the end of that line — display only; the editor and
+ * the engine judge where a template really ends.
+ */
+
+const INJECTION_SCOPE = 'tale.template.injection';
+
+const templateInjection: LanguageRegistration = {
+  name: 'tale-template-injection',
+  scopeName: INJECTION_SCOPE,
+  injectTo: [
+    'source.tale-template',
+    'source.tale-json',
+    'source.tale-yaml',
+    'text.tale-markdown',
+  ],
+  injectionSelector:
+    'L:source.tale-template, L:source.tale-json string, L:source.tale-yaml string, L:text.tale-markdown -comment',
+  embeddedLangs: ['javascript'],
+  patterns: [{ include: '#template' }],
+  repository: {
+    template: {
+      begin: '\\{\\{',
+      end: '\\}\\}|$',
+      name: 'meta.template.expression.tale',
+      beginCaptures: {
+        0: { name: 'punctuation.definition.template-expression.begin.tale' },
+      },
+      endCaptures: {
+        0: { name: 'punctuation.definition.template-expression.end.tale' },
+      },
+      contentName: 'meta.embedded.expression.tale source.js',
+      patterns: [{ include: 'source.js#expression' }],
+    },
+  },
+};
+
+function wrapper(
+  name: string,
+  scopeName: string,
+  include: string,
+  base: string[],
+): LanguageRegistration {
+  return {
+    name,
+    scopeName,
+    patterns: include === '' ? [] : [{ include }],
+    repository: {},
+    embeddedLangs: [...base, 'tale-template-injection'],
+  };
+}
+
+/**
+ * Every grammar the template languages need, the injection first. Register
+ * them together with `javascript`, `json`, `yaml` and `markdown`.
+ */
+export const TEMPLATE_GRAMMARS: readonly LanguageRegistration[] = [
+  templateInjection,
+  wrapper('tale-template', 'source.tale-template', '', []),
+  wrapper('json-template', 'source.tale-json', 'source.json', ['json']),
+  wrapper('yaml-template', 'source.tale-yaml', 'source.yaml', ['yaml']),
+  wrapper('markdown-template', 'text.tale-markdown', 'text.html.markdown', [
+    'markdown',
+  ]),
+];
diff --git a/packages/ui/src/markdown/shiki.test.ts b/packages/ui/src/markdown/shiki.test.ts
index e7868d38de..36fc6c4f1b 100644
--- a/packages/ui/src/markdown/shiki.test.ts
+++ b/packages/ui/src/markdown/shiki.test.ts
@@ -1,33 +1,66 @@
 import { describe, expect, it } from 'vitest';
 
+import { CODE_LANGUAGES, codeRoleOfColor } from '../lib/code-roles';
 import {
   highlightCode,
   peekHighlightedCode,
   resolveLanguage,
   resolveShikiTheme,
+  shikiLanguageFor,
 } from './shiki';
 
-describe('resolveShikiTheme', () => {
-  it('maps light aliases onto min-light', () => {
-    expect(resolveShikiTheme('light')).toBe('min-light');
-    expect(resolveShikiTheme('github-light')).toBe('min-light');
-    expect(resolveShikiTheme('min-light')).toBe('min-light');
-  });
+/** The text of every `<span style="color:var(--code-…)">` with its role. */
+function roles(html: string): Array<[string, string | null]> {
+  const out: Array<[string, string | null]> = [];
+  for (const match of html.matchAll(
+    /<span style="color:([^;"]+)[^"]*">([^<]*)<\/span>/g,
+  )) {
+    const text = match[2]
+      .replaceAll('&#x3C;', '<')
+      .replaceAll('&#x26;', '&')
+      .replaceAll('&quot;', '"')
+      .replaceAll('&#x27;', "'");
+    out.push([text, codeRoleOfColor(match[1])]);
+  }
+  return out;
+}
 
-  it('maps dark aliases onto min-dark', () => {
-    expect(resolveShikiTheme('dark')).toBe('min-dark');
-    expect(resolveShikiTheme('github-dark')).toBe('min-dark');
-    expect(resolveShikiTheme('min-dark')).toBe('min-dark');
+function roleOf(html: string, text: string): string | null | undefined {
+  return roles(html).find(([token]) => token.trim() === text)?.[1];
+}
+
+describe('resolveShikiTheme', () => {
+  it.each([
+    'light',
+    'dark',
+    'github-light',
+    'github-dark',
+    'min-light',
+    'min-dark',
+  ] as const)('maps %s onto the one css-variables theme', (alias) => {
+    expect(resolveShikiTheme(alias)).toBe('tale-code');
   });
 });
 
-describe('highlightCode themes', () => {
-  it('emits min-* theme classes for github-* aliases (#2785)', async () => {
-    const dark = await highlightCode('const x = 1;', 'ts', 'github-dark');
-    expect(dark?.html).toContain('class="shiki min-dark"');
+describe('highlightCode palette', () => {
+  // The read-only blocks failed AA with min-light/min-dark (comments 1.69:1).
+  // They now colour through the `--code-*` variables, the editor's palette.
+  it('colours tokens through the --code-* variables, never a hex value', async () => {
+    const result = await highlightCode(
+      'const x = 1; // note\nreturn "a";',
+      'ts',
+    );
+    expect(result?.html).toContain('class="shiki tale-code"');
+    expect(result?.html).toContain('var(--code-token-keyword)');
+    expect(result?.html).toContain('var(--code-token-comment)');
+    expect(result?.html).not.toMatch(/color:#[0-9a-f]{3,8}/i);
+  });
 
-    const light = await highlightCode('{"a":1}', 'json', 'github-light');
-    expect(light?.html).toContain('class="shiki min-light"');
+  it('gives light and dark the same HTML, cached once', async () => {
+    const code = 'const theme = "any"; // one cache entry';
+    const light = await highlightCode(code, 'ts', 'light');
+    expect(peekHighlightedCode(code, 'ts', 'dark')).toBe(light);
+    expect(await highlightCode(code, 'ts', 'github-dark')).toBe(light);
   });
 });
 
@@ -37,22 +70,18 @@ describe('diff highlighting', () => {
     expect(resolveLanguage('diff')).toBe('diff');
   });
 
-  // REGRESSION: the min-* themes ship no colors for the diff scopes, so a
-  // previewed .patch file rendered fully monochrome. The extended themes must
-  // give added and removed lines distinct colors.
+  // REGRESSION: a theme without colours for the diff scopes rendered a
+  // previewed .patch file fully monochrome. Added and removed lines must keep
+  // distinct colours, and the hunk range its own.
   it('colors added and removed lines distinctly', async () => {
     const result = await highlightCode(
       '@@ -1,2 +1,2 @@\n-const a = 1;\n+const a = 2;\n',
       'patch',
-      'light',
     );
     expect(result?.language).toBe('diff');
-    expect(result?.html).toContain('#22863A');
-    expect(result?.html).toContain('#B31D28');
-
-    const dark = await highlightCode('-old\n+new\n', 'diff', 'dark');
-    expect(dark?.html).toContain('#85E89D');
-    expect(dark?.html).toContain('#F97583');
+    expect(result?.html).toContain('var(--code-token-inserted)');
+    expect(result?.html).toContain('var(--code-token-deleted)');
+    expect(result?.html).toContain('var(--code-token-function)');
   });
 });
 
@@ -61,22 +90,18 @@ describe('remembered highlights', () => {
   // it plain until the highlight arrived.
   it('answers a snippet highlighted before, the same result, from memory', async () => {
     const code = 'export const answer = 42; // remembered';
-    expect(peekHighlightedCode(code, 'ts', 'light')).toBeNull();
+    expect(peekHighlightedCode(code, 'ts')).toBeNull();
 
-    const first = await highlightCode(code, 'ts', 'light');
+    const first = await highlightCode(code, 'ts');
     expect(first).not.toBeNull();
-    expect(peekHighlightedCode(code, 'typescript', 'github-light')).toBe(first);
-    expect(await highlightCode(code, 'ts', 'light')).toBe(first);
+    expect(peekHighlightedCode(code, 'typescript')).toBe(first);
+    expect(await highlightCode(code, 'ts')).toBe(first);
   });
 
-  it('keeps the language and the theme apart', async () => {
-    const code = 'const theme = "dark"; // remembered per theme';
-    const light = await highlightCode(code, 'ts', 'light');
-    expect(peekHighlightedCode(code, 'ts', 'dark')).toBeNull();
-    expect(peekHighlightedCode(code, 'js', 'light')).toBeNull();
-    const dark = await highlightCode(code, 'ts', 'dark');
-    expect(dark?.html).not.toBe(light?.html);
-    expect(peekHighlightedCode(code, 'ts', 'dark')).toBe(dark);
+  it('keeps languages apart', async () => {
+    const code = 'const lang = "ts"; // remembered per language';
+    await highlightCode(code, 'ts');
+    expect(peekHighlightedCode(code, 'js')).toBeNull();
   });
 
   it('remembers nothing for a snippet too large to highlight', async () => {
@@ -85,3 +110,82 @@ describe('remembered highlights', () => {
     expect(peekHighlightedCode(code, 'text')).toBeNull();
   });
 });
+
+describe('template grammars', () => {
+  it('names a grammar for every code language', () => {
+    expect(
+      Object.fromEntries(
+        CODE_LANGUAGES.map((language) => [
+          language,
+          [shikiLanguageFor(language), shikiLanguageFor(language, true)],
+        ]),
+      ),
+    ).toEqual({
+      javascript: ['javascript', 'javascript'],
+      expression: ['javascript', 'javascript'],
+      json: ['json', 'json-template'],
+      yaml: ['yaml', 'yaml-template'],
+      markdown: ['markdown', 'markdown-template'],
+      template: ['tale-template', 'tale-template'],
+      text: ['text', 'tale-template'],
+    });
+  });
+
+  it('resolves the template aliases', () => {
+    expect(resolveLanguage('template')).toBe('tale-template');
+    expect(resolveLanguage('json+template')).toBe('json-template');
+    expect(resolveLanguage('yml+template')).toBe('yaml-template');
+    expect(resolveLanguage('md+template')).toBe('markdown-template');
+  });
+
+  it('highlights the body of a template as JavaScript', async () => {
+    const result = await highlightCode(
+      'Hello {{ nodes.triage.output.name }}!',
+      'tale-template',
+    );
+    expect(result?.language).toBe('tale-template');
+    const html = result?.html ?? '';
+    expect(roleOf(html, '{{')).toBe('keyword');
+    expect(roleOf(html, '}}')).toBe('keyword');
+    expect(roleOf(html, 'nodes')).toBe('constant');
+    expect(roleOf(html, 'Hello')).toBe('foreground');
+  });
+
+  it('closes a template at the brace the expression leaves open', async () => {
+    const html =
+      (await highlightCode('{{ "}}" }} tail', 'tale-template'))?.html ?? '';
+    expect(roleOf(html, '"}}"')).toBe('string-expression');
+    expect(roleOf(html, 'tail')).toBe('foreground');
+  });
+
+  it('finds templates inside JSON strings, not in plain JSON', async () => {
+    const code = '{"to": "{{ input.email }}"}';
+    const templated = (await highlightCode(code, 'json-template'))?.html ?? '';
+    expect(roleOf(templated, 'input')).toBe('constant');
+    const plain = (await highlightCode(code, 'json'))?.html ?? '';
+    expect(roleOf(plain, 'input')).toBeUndefined();
+  });
+
+  // Helm, Jinja and Go templates in a chat answer are `yaml`: their braces
+  // must stay text there.
+  it('leaves templates in plain YAML alone', async () => {
+    const code = 'prompt: hi {{ item.x }}\n';
+    const templated = (await highlightCode(code, 'yaml-template'))?.html ?? '';
+    expect(roleOf(templated, '{{')).toBe('keyword');
+    expect(roleOf(templated, 'item')).toBe('constant');
+    const plain = (await highlightCode(code, 'yaml'))?.html ?? '';
+    expect(roleOf(plain, '{{')).toBeUndefined();
+    expect(roleOf(plain, 'item')).toBeUndefined();
+  });
+
+  it('highlights templates in Markdown prose', async () => {
+    const html =
+      (
+        await highlightCode(
+          'Use {{ nodes.a.output }} *now*',
+          'markdown-template',
+        )
+      )?.html ?? '';
+    expect(roleOf(html, 'nodes')).toBe('constant');
+  });
+});
diff --git a/packages/ui/src/markdown/shiki.ts b/packages/ui/src/markdown/shiki.ts
index f67a61eae3..6def4a5a56 100644
--- a/packages/ui/src/markdown/shiki.ts
+++ b/packages/ui/src/markdown/shiki.ts
@@ -1,46 +1,45 @@
 /**
  * Shared Shiki highlighter singleton.
  *
- * Strategy: the engine, the themes and 39 common grammars load together the
+ * Strategy: the engine, the theme and 39 common grammars load together the
  * first time code is highlighted (or `preloadHighlighter` asks), not with the
  * page: a chat or a docs page without code never needs them. Anything else is
  * lazy-loaded on demand via a runtime dynamic import. Shiki's JS regex engine
  * keeps the bundle off the WASM oniguruma path.
+ *
+ * Colours come from the `--code-*` variables in `globals.css` (Shiki's
+ * css-variables theme), the palette the code editor reads too. One
+ * highlight therefore serves light and dark alike: a theme switch repaints
+ * the variables and never tokenizes again.
  */
 
 import type { HighlighterCore, ThemeRegistration } from 'shiki/core';
 
+import type { CodeLanguage } from '../lib/code-roles';
+import { TEMPLATE_GRAMMARS } from './shiki-template-grammars';
+
 let highlighterPromise: Promise<HighlighterCore> | null = null;
 
+/** The one theme the highlighter loads. */
+export const SHIKI_THEME = 'tale-code';
+
 /**
- * The min-* themes define no colors for the diff grammar's scopes, so a
- * rendered `.patch`/`.diff` file (and every ```diff fence) came out
- * monochrome. Extend a theme with the standard add/del/hunk palette; the
- * theme keeps its name, so `codeToHtml` resolves it unchanged.
+ * The css-variables theme colours a unified diff's added, removed and
+ * changed lines; the hunk ranges and file headers get the function and
+ * changed roles, as the min-* themes' diff colours did before.
  */
-function withDiffColors(
-  theme: ThemeRegistration,
-  palette: { inserted: string; deleted: string; range: string; header: string },
-): ThemeRegistration {
+function withDiffScopes(theme: ThemeRegistration): ThemeRegistration {
   return {
     ...theme,
     tokenColors: [
       ...(theme.tokenColors ?? []),
-      {
-        scope: ['markup.inserted'],
-        settings: { foreground: palette.inserted },
-      },
-      {
-        scope: ['markup.deleted'],
-        settings: { foreground: palette.deleted },
-      },
       {
         scope: ['meta.diff.range', 'punctuation.definition.range.diff'],
-        settings: { foreground: palette.range },
+        settings: { foreground: 'var(--code-token-function)' },
       },
       {
         scope: ['meta.diff.header', 'meta.diff.index'],
-        settings: { foreground: palette.header },
+        settings: { foreground: 'var(--code-token-changed)' },
       },
     ],
   };
@@ -52,69 +51,66 @@ function getHighlighter(): Promise<HighlighterCore> {
       import('shiki/core'),
       import('shiki/engine/javascript'),
     ])
-      .then(([{ createHighlighterCore }, { createJavaScriptRegexEngine }]) =>
-        createHighlighterCore({
-          themes: [
-            import('shiki/themes/min-dark.mjs').then((m) =>
-              withDiffColors(m.default, {
-                inserted: '#85e89d',
-                deleted: '#f97583',
-                range: '#b392f0',
-                header: '#79b8ff',
-              }),
-            ),
-            import('shiki/themes/min-light.mjs').then((m) =>
-              withDiffColors(m.default, {
-                inserted: '#22863a',
-                deleted: '#b31d28',
-                range: '#6f42c1',
-                header: '#005cc5',
-              }),
-            ),
-          ],
-          langs: [
-            import('shiki/langs/bash.mjs'),
-            import('shiki/langs/c.mjs'),
-            import('shiki/langs/cpp.mjs'),
-            import('shiki/langs/csharp.mjs'),
-            import('shiki/langs/css.mjs'),
-            import('shiki/langs/diff.mjs'),
-            import('shiki/langs/docker.mjs'),
-            import('shiki/langs/dotenv.mjs'),
-            import('shiki/langs/elixir.mjs'),
-            import('shiki/langs/go.mjs'),
-            import('shiki/langs/graphql.mjs'),
-            import('shiki/langs/hcl.mjs'),
-            import('shiki/langs/html.mjs'),
-            import('shiki/langs/http.mjs'),
-            import('shiki/langs/ini.mjs'),
-            import('shiki/langs/java.mjs'),
-            import('shiki/langs/javascript.mjs'),
-            import('shiki/langs/json.mjs'),
-            import('shiki/langs/jsx.mjs'),
-            import('shiki/langs/kotlin.mjs'),
-            import('shiki/langs/lua.mjs'),
-            import('shiki/langs/markdown.mjs'),
-            import('shiki/langs/nginx.mjs'),
-            import('shiki/langs/php.mjs'),
-            import('shiki/langs/powershell.mjs'),
-            import('shiki/langs/prisma.mjs'),
-            import('shiki/langs/python.mjs'),
-            import('shiki/langs/ruby.mjs'),
-            import('shiki/langs/rust.mjs'),
-            import('shiki/langs/scala.mjs'),
-            import('shiki/langs/scss.mjs'),
-            import('shiki/langs/sql.mjs'),
-            import('shiki/langs/swift.mjs'),
-            import('shiki/langs/toml.mjs'),
-            import('shiki/langs/tsx.mjs'),
-            import('shiki/langs/typescript.mjs'),
-            import('shiki/langs/xml.mjs'),
-            import('shiki/langs/yaml.mjs'),
-            import('shiki/langs/zig.mjs'),
-          ],
-          engine: createJavaScriptRegexEngine(),
-        }),
+      .then(
+        ([
+          { createCssVariablesTheme, createHighlighterCore },
+          { createJavaScriptRegexEngine },
+        ]) =>
+          createHighlighterCore({
+            themes: [
+              withDiffScopes(
+                createCssVariablesTheme({
+                  name: SHIKI_THEME,
+                  variablePrefix: '--code-',
+                  fontStyle: true,
+                }),
+              ),
+            ],
+            langs: [
+              import('shiki/langs/bash.mjs'),
+              import('shiki/langs/c.mjs'),
+              import('shiki/langs/cpp.mjs'),
+              import('shiki/langs/csharp.mjs'),
+              import('shiki/langs/css.mjs'),
+              import('shiki/langs/diff.mjs'),
+              import('shiki/langs/docker.mjs'),
+              import('shiki/langs/dotenv.mjs'),
+              import('shiki/langs/elixir.mjs'),
+              import('shiki/langs/go.mjs'),
+              import('shiki/langs/graphql.mjs'),
+              import('shiki/langs/hcl.mjs'),
+              import('shiki/langs/html.mjs'),
+              import('shiki/langs/http.mjs'),
+              import('shiki/langs/ini.mjs'),
+              import('shiki/langs/java.mjs'),
+              import('shiki/langs/javascript.mjs'),
+              import('shiki/langs/json.mjs'),
+              import('shiki/langs/jsx.mjs'),
+              import('shiki/langs/kotlin.mjs'),
+              import('shiki/langs/lua.mjs'),
+              import('shiki/langs/markdown.mjs'),
+              import('shiki/langs/nginx.mjs'),
+              import('shiki/langs/php.mjs'),
+              import('shiki/langs/powershell.mjs'),
+              import('shiki/langs/prisma.mjs'),
+              import('shiki/langs/python.mjs'),
+              import('shiki/langs/ruby.mjs'),
+              import('shiki/langs/rust.mjs'),
+              import('shiki/langs/scala.mjs'),
+              import('shiki/langs/scss.mjs'),
+              import('shiki/langs/sql.mjs'),
+              import('shiki/langs/swift.mjs'),
+              import('shiki/langs/toml.mjs'),
+              import('shiki/langs/tsx.mjs'),
+              import('shiki/langs/typescript.mjs'),
+              import('shiki/langs/xml.mjs'),
+              import('shiki/langs/yaml.mjs'),
+              import('shiki/langs/zig.mjs'),
+              // After javascript, json, yaml and markdown, which they embed.
+              ...TEMPLATE_GRAMMARS,
+            ],
+            engine: createJavaScriptRegexEngine(),
+          }),
       )
       .catch((error: unknown) => {
         highlighterPromise = null;
@@ -183,6 +179,14 @@ const LANG_ALIASES: Record<string, string> = {
   tf: 'hcl',
   // Unified diffs: `.patch`/`.diff` files share the one `diff` grammar.
   patch: 'diff',
+  // Tale's `{{ js }}` templates (see `shiki-template-grammars.ts`).
+  template: 'tale-template',
+  'text+template': 'tale-template',
+  'json+template': 'json-template',
+  'yaml+template': 'yaml-template',
+  'yml+template': 'yaml-template',
+  'markdown+template': 'markdown-template',
+  'md+template': 'markdown-template',
 };
 
 export function resolveLanguage(input: string | undefined): string {
@@ -191,6 +195,33 @@ export function resolveLanguage(input: string | undefined): string {
   return LANG_ALIASES[lower] ?? lower;
 }
 
+/**
+ * The Shiki language that shows a code field's text the way the code editor
+ * highlights it: an expression and a script are both JavaScript, and a field
+ * that may hold `{{ js }}` templates gets its template-aware grammar.
+ * `templates` is implied by `template` and ignored for JavaScript.
+ */
+export function shikiLanguageFor(
+  language: CodeLanguage,
+  templates = false,
+): string {
+  switch (language) {
+    case 'javascript':
+    case 'expression':
+      return 'javascript';
+    case 'template':
+      return 'tale-template';
+    case 'json':
+      return templates ? 'json-template' : 'json';
+    case 'yaml':
+      return templates ? 'yaml-template' : 'yaml';
+    case 'markdown':
+      return templates ? 'markdown-template' : 'markdown';
+    case 'text':
+      return templates ? 'tale-template' : 'text';
+  }
+}
+
 /**
  * Cap on the input size we'll synchronously tokenize on the main thread.
  * Above this, callers should fall back to a plain-text render — Shiki's
@@ -204,7 +235,11 @@ export interface HighlightResult {
   language: string;
 }
 
-type ShikiTheme =
+/**
+ * The theme names callers passed before the palette moved into CSS
+ * variables. Every one of them still works and means the same now.
+ */
+export type ShikiTheme =
   | 'light'
   | 'dark'
   | 'github-light'
@@ -213,14 +248,13 @@ type ShikiTheme =
   | 'min-dark';
 
 /**
- * Map every theme alias a caller may still pass (including the historical
- * `github-*` names) onto the one light/dark pair the highlighter actually
- * loads — the flatter `min-*` themes (#2785).
+ * Map every theme alias a caller may still pass (light or dark, and the
+ * historical `github-*` and `min-*` names) onto the one theme the
+ * highlighter loads. Its colours are CSS variables that follow the page's
+ * theme, so the light/dark choice no longer reaches Shiki at all.
  */
-export function resolveShikiTheme(theme: ShikiTheme): 'min-dark' | 'min-light' {
-  return theme === 'dark' || theme === 'github-dark' || theme === 'min-dark'
-    ? 'min-dark'
-    : 'min-light';
+export function resolveShikiTheme(_theme?: ShikiTheme): typeof SHIKI_THEME {
+  return SHIKI_THEME;
 }
 
 /**
@@ -234,12 +268,9 @@ const highlighted = new Map<string, HighlightResult>();
 let highlightedChars = 0;
 const HIGHLIGHTED_MAX_CHARS = 4_000_000;
 
-function highlightKey(
-  code: string,
-  lang: string | undefined,
-  theme: ShikiTheme,
-): string {
-  return `${resolveShikiTheme(theme)}\u0000${resolveLanguage(lang)}\u0000${code}`;
+/** One entry per snippet and language: the HTML is the same in both themes. */
+function highlightKey(code: string, lang: string | undefined): string {
+  return `${resolveLanguage(lang)}\u0000${code}`;
 }
 
 function remember(key: string, result: HighlightResult): void {
@@ -265,9 +296,9 @@ function remember(key: string, result: HighlightResult): void {
 export function peekHighlightedCode(
   code: string,
   lang: string | undefined,
-  theme: ShikiTheme = 'light',
+  _theme?: ShikiTheme,
 ): HighlightResult | null {
-  return highlighted.get(highlightKey(code, lang, theme)) ?? null;
+  return highlighted.get(highlightKey(code, lang)) ?? null;
 }
 
 /**
@@ -278,21 +309,23 @@ export function peekHighlightedCode(
  * Languages outside the eager list are lazy-loaded on first request and
  * cached for subsequent calls. Unknown grammars fall back to plaintext. A
  * snippet highlighted before answers from {@link peekHighlightedCode}'s
- * store without tokenizing again.
+ * store without tokenizing again. The HTML colours through the `--code-*`
+ * variables, so it is right in either theme; `_theme` is accepted for
+ * callers that still pass one.
  */
 export async function highlightCode(
   code: string,
   lang: string | undefined,
-  theme: ShikiTheme = 'light',
+  _theme?: ShikiTheme,
 ): Promise<HighlightResult | null> {
   if (code.length > MAX_SHIKI_BYTES) return null;
-  const key = highlightKey(code, lang, theme);
+  const key = highlightKey(code, lang);
   const known = highlighted.get(key);
   if (known !== undefined) {
     remember(key, known);
     return known;
   }
-  const result = await tokenize(code, lang, theme);
+  const result = await tokenize(code, lang);
   if (result !== null) remember(key, result);
   return result;
 }
@@ -300,7 +333,6 @@ export async function highlightCode(
 async function tokenize(
   code: string,
   lang: string | undefined,
-  theme: ShikiTheme,
 ): Promise<HighlightResult | null> {
   let highlighter: HighlighterCore;
   try {
@@ -310,7 +342,7 @@ async function tokenize(
     return null;
   }
 
-  const resolvedTheme = resolveShikiTheme(theme);
+  const resolvedTheme = SHIKI_THEME;
   const resolvedLang = resolveLanguage(lang);
 
   // Shiki's `text` grammar is a built-in no-highlight pass — there is no

From c00b7fe153774b8457f0032884b7636e87253e26 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:57:01 +0200
Subject: [PATCH 06/78] feat(ui): let a widget claim Escape inside dialogs and
 sheets

A widget that uses Escape itself, such as a code editor closing its
completion list, sat inside dialogs, sheets and popovers whose layer
closed on the same key: Radix hears Escape first, in the capture phase.

A widget now marks itself with data-claims-escape while it needs the
key, and every @tale/ui overlay passes its onEscapeKeyDown through
respectEscapeClaims, which keeps the layer open for a claimed Escape.
---
 packages/ui/src/components/dialog/dialog.tsx  |   2 +
 .../overlays/claims-escape.test.tsx           | 168 ++++++++++++++++++
 .../src/components/overlays/claims-escape.ts  |  40 +++++
 .../src/components/overlays/dropdown-menu.tsx |   2 +
 .../ui/src/components/overlays/popover.tsx    |   2 +
 .../components/overlays/responsive-dialog.tsx |   3 +
 packages/ui/src/components/overlays/sheet.tsx |   2 +
 7 files changed, 219 insertions(+)
 create mode 100644 packages/ui/src/components/overlays/claims-escape.test.tsx
 create mode 100644 packages/ui/src/components/overlays/claims-escape.ts

diff --git a/packages/ui/src/components/dialog/dialog.tsx b/packages/ui/src/components/dialog/dialog.tsx
index d6933bf3da..23437eb8da 100644
--- a/packages/ui/src/components/dialog/dialog.tsx
+++ b/packages/ui/src/components/dialog/dialog.tsx
@@ -10,6 +10,7 @@ import { ChevronLeft, X } from 'lucide-react';
 import * as React from 'react';
 
 import { CLOSE_BUTTON_CLASS } from '../overlays/close-button-class';
+import { respectEscapeClaims } from '../overlays/claims-escape';
 import { PagePointerPin } from '../overlays/page-pointer-pin';
 
 // Tracks dialog nesting so a child Dialog opened from inside another
@@ -309,6 +310,7 @@ export function Dialog({
               else restoreFocus(event);
               onCloseAutoFocus?.(event);
             }}
+            onEscapeKeyDown={respectEscapeClaims()}
           >
             <PagePointerPin />
             {/* Close sits in the header row when headerActions exist, so it
diff --git a/packages/ui/src/components/overlays/claims-escape.test.tsx b/packages/ui/src/components/overlays/claims-escape.test.tsx
new file mode 100644
index 0000000000..87b1d66b85
--- /dev/null
+++ b/packages/ui/src/components/overlays/claims-escape.test.tsx
@@ -0,0 +1,168 @@
+import { fireEvent } from '@testing-library/react';
+import { useState, type ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { render, screen } from '@/tests/utils/render';
+
+import { Dialog } from '../dialog/dialog';
+import { isEscapeClaimed, respectEscapeClaims } from './claims-escape';
+import { DropdownMenu } from './dropdown-menu';
+import { Popover } from './popover';
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogTitle,
+} from './responsive-dialog';
+import { Sheet } from './sheet';
+
+/**
+ * A widget that uses Escape itself (a code editor with its completion list
+ * open) claims it with `data-claims-escape`; the layer it sits in must stay
+ * open for a claimed Escape and close for any other.
+ */
+
+function Claimant({ claims }: { claims: boolean }) {
+  return (
+    <div {...(claims ? { 'data-claims-escape': '' } : {})}>
+      <input aria-label="Widget" />
+    </div>
+  );
+}
+
+function pressEscape(): void {
+  const widget = screen.getByRole('textbox', { name: 'Widget' });
+  widget.focus();
+  fireEvent.keyDown(widget, { key: 'Escape', code: 'Escape' });
+}
+
+type Layer = (props: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children: ReactNode;
+}) => ReactNode;
+
+const LAYERS: Array<[string, Layer]> = [
+  [
+    'Dialog',
+    ({ open, onOpenChange, children }) => (
+      <Dialog open={open} onOpenChange={onOpenChange} title="Edit">
+        {children}
+      </Dialog>
+    ),
+  ],
+  [
+    'Sheet',
+    ({ open, onOpenChange, children }) => (
+      <Sheet open={open} onOpenChange={onOpenChange} title="Edit">
+        {children}
+      </Sheet>
+    ),
+  ],
+  [
+    'ResponsiveDialog',
+    ({ open, onOpenChange, children }) => (
+      <ResponsiveDialog open={open} onOpenChange={onOpenChange}>
+        <ResponsiveDialogContent>
+          <ResponsiveDialogTitle>Edit</ResponsiveDialogTitle>
+          {children}
+        </ResponsiveDialogContent>
+      </ResponsiveDialog>
+    ),
+  ],
+  [
+    'Popover',
+    ({ open, onOpenChange, children }) => (
+      <Popover
+        open={open}
+        onOpenChange={onOpenChange}
+        trigger={<button type="button">Open</button>}
+        aria-label="Edit"
+      >
+        {children}
+      </Popover>
+    ),
+  ],
+];
+
+function Harness({ Layer, claims }: { Layer: Layer; claims: boolean }) {
+  const [open, setOpen] = useState(true);
+  return (
+    <>
+      <p>{open ? 'open' : 'closed'}</p>
+      <Layer open={open} onOpenChange={setOpen}>
+        <Claimant claims={claims} />
+      </Layer>
+    </>
+  );
+}
+
+describe('respectEscapeClaims', () => {
+  it('cancels a claimed Escape and passes any other to the handler', () => {
+    const handler = vi.fn();
+    const wrapped = respectEscapeClaims(handler);
+    const claimant = document.createElement('div');
+    claimant.setAttribute('data-claims-escape', '');
+    const inner = document.createElement('input');
+    claimant.append(inner);
+    document.body.append(claimant);
+
+    const claimed = new KeyboardEvent('keydown', {
+      key: 'Escape',
+      cancelable: true,
+    });
+    inner.dispatchEvent(claimed);
+    wrapped(claimed);
+    expect(claimed.defaultPrevented).toBe(true);
+    expect(handler).not.toHaveBeenCalled();
+    expect(isEscapeClaimed(claimed)).toBe(true);
+
+    const free = new KeyboardEvent('keydown', {
+      key: 'Escape',
+      cancelable: true,
+    });
+    document.body.dispatchEvent(free);
+    wrapped(free);
+    expect(free.defaultPrevented).toBe(false);
+    expect(handler).toHaveBeenCalledOnce();
+    claimant.remove();
+  });
+
+  it.each(LAYERS)('%s stays open for a claimed Escape', (_name, Layer) => {
+    render(<Harness Layer={Layer} claims />);
+    pressEscape();
+    expect(screen.getByText('open')).toBeInTheDocument();
+  });
+
+  it.each(LAYERS)('%s closes for an unclaimed Escape', (_name, Layer) => {
+    render(<Harness Layer={Layer} claims={false} />);
+    pressEscape();
+    expect(screen.getByText('closed')).toBeInTheDocument();
+  });
+
+  it('DropdownMenu stays open while its content claims Escape', () => {
+    function Menu() {
+      const [open, setOpen] = useState(true);
+      return (
+        <>
+          <p>{open ? 'open' : 'closed'}</p>
+          <DropdownMenu
+            open={open}
+            onOpenChange={setOpen}
+            trigger={<button type="button">Actions</button>}
+            items={[[{ type: 'item', label: 'Rename', onClick: () => {} }]]}
+          />
+        </>
+      );
+    }
+    render(<Menu />);
+    const menu = screen.getByRole('menu');
+    menu.setAttribute('data-claims-escape', '');
+    const item = screen.getByRole('menuitem', { name: 'Rename' });
+    item.focus();
+    fireEvent.keyDown(item, { key: 'Escape' });
+    expect(screen.getByText('open')).toBeInTheDocument();
+    menu.removeAttribute('data-claims-escape');
+    fireEvent.keyDown(item, { key: 'Escape' });
+    expect(screen.getByText('closed')).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/overlays/claims-escape.ts b/packages/ui/src/components/overlays/claims-escape.ts
new file mode 100644
index 0000000000..48c62a183a
--- /dev/null
+++ b/packages/ui/src/components/overlays/claims-escape.ts
@@ -0,0 +1,40 @@
+/**
+ * Widgets that use Escape themselves — a code editor closing its completion
+ * list, then arming "leave" — sit inside dialogs, sheets and popovers whose
+ * layer closes on Escape. Radix hears Escape first (it listens on the
+ * document in the capture phase), so without a convention the first Escape
+ * in a sheet closed the whole sheet under an open list.
+ *
+ * The convention: while a widget needs Escape, an element around the focus
+ * carries `data-claims-escape`. Every `@tale/ui` overlay passes its
+ * `onEscapeKeyDown` through `respectEscapeClaims`, which cancels the layer's
+ * dismissal for a claimed Escape; the widget handles the key, and once it
+ * drops the claim the next Escape closes the layer as usual.
+ */
+
+export const CLAIMS_ESCAPE_ATTRIBUTE = 'data-claims-escape';
+
+/** Whether a widget around the event's target has claimed Escape. */
+export function isEscapeClaimed(event: Event): boolean {
+  const target = event.target;
+  return (
+    target instanceof Element &&
+    target.closest(`[${CLAIMS_ESCAPE_ATTRIBUTE}]`) !== null
+  );
+}
+
+/**
+ * Wraps an overlay's `onEscapeKeyDown`: a claimed Escape is cancelled (the
+ * layer stays open, `handler` does not run); any other reaches `handler`.
+ */
+export function respectEscapeClaims<E extends Event>(
+  handler?: (event: E) => void,
+): (event: E) => void {
+  return (event) => {
+    if (isEscapeClaimed(event)) {
+      event.preventDefault();
+      return;
+    }
+    handler?.(event);
+  };
+}
diff --git a/packages/ui/src/components/overlays/dropdown-menu.tsx b/packages/ui/src/components/overlays/dropdown-menu.tsx
index 8449fa57d6..e6f0085718 100644
--- a/packages/ui/src/components/overlays/dropdown-menu.tsx
+++ b/packages/ui/src/components/overlays/dropdown-menu.tsx
@@ -12,6 +12,7 @@ import {
 } from 'react';
 
 import { cn } from '../../lib/cn';
+import { respectEscapeClaims } from './claims-escape';
 import { TooltipContent } from './tooltip';
 
 export interface DropdownMenuActionItem {
@@ -479,6 +480,7 @@ export function DropdownMenu({
           collisionPadding={collisionPadding ?? 16}
           onClick={(e) => e.stopPropagation()}
           onPointerDownOutside={keepTriggerPointerDown}
+          onEscapeKeyDown={respectEscapeClaims()}
           style={{
             maxHeight:
               'min(80vh, var(--radix-dropdown-menu-content-available-height, 80vh))',
diff --git a/packages/ui/src/components/overlays/popover.tsx b/packages/ui/src/components/overlays/popover.tsx
index 8ce6493aab..0901f572fe 100644
--- a/packages/ui/src/components/overlays/popover.tsx
+++ b/packages/ui/src/components/overlays/popover.tsx
@@ -4,6 +4,7 @@ import * as PopoverPrimitive from '@radix-ui/react-popover';
 import { type ReactNode } from 'react';
 
 import { cn } from '../../lib/cn';
+import { respectEscapeClaims } from './claims-escape';
 
 interface PopoverProps {
   trigger: ReactNode;
@@ -71,6 +72,7 @@ export function Popover({
           onOpenAutoFocus={onOpenAutoFocus}
           onCloseAutoFocus={onCloseAutoFocus}
           onInteractOutside={onInteractOutside}
+          onEscapeKeyDown={respectEscapeClaims()}
           aria-labelledby={ariaLabelledby}
           aria-label={ariaLabel}
           className={cn(CONTENT_CLASSES, contentClassName)}
diff --git a/packages/ui/src/components/overlays/responsive-dialog.tsx b/packages/ui/src/components/overlays/responsive-dialog.tsx
index 282e3f001d..3bb0afe0b7 100644
--- a/packages/ui/src/components/overlays/responsive-dialog.tsx
+++ b/packages/ui/src/components/overlays/responsive-dialog.tsx
@@ -19,6 +19,7 @@ import { useRestoreFocus } from '../../hooks/use-restore-focus';
 import { useT } from '../../i18n/client';
 import { cn } from '../../lib/cn';
 import { CLOSE_BUTTON_CLASS } from './close-button-class';
+import { respectEscapeClaims } from './claims-escape';
 import { PagePointerPin } from './page-pointer-pin';
 
 /**
@@ -221,6 +222,7 @@ export const ResponsiveDialogContent = forwardRef<
             onPointerDownOutside={preventDatePickerDismiss}
             onInteractOutside={preventDatePickerDismiss}
             onFocusOutside={preventDatePickerDismiss}
+            onEscapeKeyDown={respectEscapeClaims()}
             className={cn(
               // `outline-none`, as on `Dialog`: when Radix parks focus on the
               // panel itself (nothing to start in, or the content it held
@@ -297,6 +299,7 @@ export const ResponsiveDialogContent = forwardRef<
           onPointerDownOutside={preventDatePickerDismiss}
           onInteractOutside={preventDatePickerDismiss}
           onFocusOutside={preventDatePickerDismiss}
+          onEscapeKeyDown={respectEscapeClaims()}
           className={cn(
             'bg-background fixed top-1/2 left-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl border p-6 shadow-lg outline-none',
             // Never exceed the viewport: cap at 90dvh and scroll internally so a
diff --git a/packages/ui/src/components/overlays/sheet.tsx b/packages/ui/src/components/overlays/sheet.tsx
index 699d27813e..92cd7d1945 100644
--- a/packages/ui/src/components/overlays/sheet.tsx
+++ b/packages/ui/src/components/overlays/sheet.tsx
@@ -19,6 +19,7 @@ import {
   type RefObject,
 } from 'react';
 
+import { respectEscapeClaims } from './claims-escape';
 import { PagePointerPin } from './page-pointer-pin';
 
 // Safe-area padding is layered into the design `p-6` via per-edge calc() so
@@ -231,6 +232,7 @@ export function Sheet({
           style={widthStyle}
           onOpenAutoFocus={onOpenAutoFocus}
           onCloseAutoFocus={restoreFocus}
+          onEscapeKeyDown={respectEscapeClaims()}
           // Without a description, opt out of Radix's default
           // `aria-describedby` (which would otherwise point at a
           // `Description` id that is never rendered — a dangling ARIA

From d63055a98934c24ba4b85d44a947b7642028fe9f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:57:15 +0200
Subject: [PATCH 07/78] feat(ui): name contenteditable controls and pass go-to
 its part

A code editor's text is a contenteditable element, which <label for>
cannot name or focus. Field now gives its label an id and names a child
that declares fieldLabelling = 'labelledby' with aria-labelledby; Label
focuses a target that is not labelable when it is clicked.

A go-to request for a part of a registered anchor (/nodes/0/input/to on
/nodes/0/input) now reaches a custom target with that part: the rest of
the path and the range, which is offsets into the part, so a JSON or
YAML editor can select it. Element targets ignore it, as before.
---
 .../ui/src/components/forms/field.test.tsx    | 33 +++++++++++++++++
 packages/ui/src/components/forms/field.tsx    | 32 +++++++++++++++--
 .../forms/issue-focus.browser.test.tsx        | 21 +++++++++++
 .../ui/src/components/forms/issue-focus.tsx   | 36 ++++++++++++++++---
 .../ui/src/components/forms/label.test.tsx    | 26 ++++++++++++++
 packages/ui/src/components/forms/label.tsx    | 30 +++++++++++++++-
 6 files changed, 170 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/components/forms/field.test.tsx b/packages/ui/src/components/forms/field.test.tsx
index ccb1624a12..ee5a4f199e 100644
--- a/packages/ui/src/components/forms/field.test.tsx
+++ b/packages/ui/src/components/forms/field.test.tsx
@@ -136,6 +136,39 @@ describe('Field', () => {
     });
   });
 
+  // A contenteditable control (a code editor) is not labelable: `<label
+  // for>` names nothing, so Field points `aria-labelledby` at its label.
+  describe('controls named by aria-labelledby', () => {
+    function Editable(props: Record<string, unknown>) {
+      return <div role="textbox" tabIndex={0} {...props} />;
+    }
+    const Named = Object.assign(Editable, {
+      fieldLabelling: 'labelledby' as const,
+    });
+
+    it('names the control by its label', () => {
+      const { getByRole } = render(
+        <Field label="Code" htmlFor="code">
+          <Named id="code" aria-labelledby="extra" />
+        </Field>,
+      );
+      expect(getByRole('textbox', { name: 'Code' })).toBeInTheDocument();
+      const labelledBy =
+        getByRole('textbox').getAttribute('aria-labelledby') ?? '';
+      expect(labelledBy.split(' ')[0]).toBe('extra');
+    });
+
+    it('leaves an ordinary control to <label for>', () => {
+      const { getByRole } = render(
+        <Field label="Email" htmlFor="email">
+          <Input id="email" />
+        </Field>,
+      );
+      expect(getByRole('textbox')).not.toHaveAttribute('aria-labelledby');
+      expect(getByRole('textbox', { name: 'Email' })).toBeInTheDocument();
+    });
+  });
+
   describe('accessibility', () => {
     it('passes axe audit with label + description', async () => {
       const { container } = render(
diff --git a/packages/ui/src/components/forms/field.tsx b/packages/ui/src/components/forms/field.tsx
index 3b31d26eb9..0fd6bab00e 100644
--- a/packages/ui/src/components/forms/field.tsx
+++ b/packages/ui/src/components/forms/field.tsx
@@ -36,6 +36,22 @@ export interface FieldProps {
   className?: string;
 }
 
+/**
+ * A control that cannot be named by `<label for>` — a code editor's text
+ * is a contenteditable element, not a labelable one — declares
+ * `static fieldLabelling = 'labelledby'`, and `Field` names it with
+ * `aria-labelledby` pointing at its label instead.
+ */
+function namedByLabelledBy(element: unknown): boolean {
+  if (!isValidElement(element)) return false;
+  const type: unknown = element.type;
+  return (
+    (typeof type === 'function' ||
+      (typeof type === 'object' && type !== null)) &&
+    (type as { fieldLabelling?: unknown }).fieldLabelling === 'labelledby'
+  );
+}
+
 export function Field({
   label,
   htmlFor,
@@ -46,6 +62,7 @@ export function Field({
   className,
 }: FieldProps) {
   const baseId = useId();
+  const labelId = label ? `${baseId}-label` : undefined;
   const descriptionId = description ? `${baseId}-description` : undefined;
   const errorId = error ? `${baseId}-error` : undefined;
   const issuesId = fieldIssueDescribedBy(baseId, issues);
@@ -64,9 +81,11 @@ export function Field({
   // props, leaving existing behavior.
   let enhancedChildren: ReactNode = children;
   const onlyChild = Children.count(children) === 1 ? children : null;
+  const labelledBy =
+    labelId !== undefined && namedByLabelledBy(onlyChild) ? labelId : undefined;
   if (
     isValidElement<Record<string, unknown>>(onlyChild) &&
-    (describedBy || invalid)
+    (describedBy || invalid || labelledBy)
   ) {
     const childProps = onlyChild.props;
     const rawDescribedBy = childProps['aria-describedby'];
@@ -78,9 +97,18 @@ export function Field({
     const fallbackInvalid =
       typeof rawInvalid === 'boolean' ? rawInvalid : undefined;
     const rawClassName = childProps['className'];
+    const rawLabelledBy = childProps['aria-labelledby'];
     enhancedChildren = cloneElement(onlyChild, {
       'aria-describedby': merged,
       'aria-invalid': invalid ? true : fallbackInvalid,
+      ...(labelledBy !== undefined && {
+        'aria-labelledby': [
+          typeof rawLabelledBy === 'string' ? rawLabelledBy : undefined,
+          labelledBy,
+        ]
+          .filter(Boolean)
+          .join(' '),
+      }),
       ...(invalid && {
         className: cn(
           typeof rawClassName === 'string' ? rawClassName : undefined,
@@ -98,7 +126,7 @@ export function Field({
       className={className}
       label={
         label ? (
-          <Label htmlFor={htmlFor}>
+          <Label id={labelId} htmlFor={htmlFor}>
             {label}
             {null}
           </Label>
diff --git a/packages/ui/src/components/forms/issue-focus.browser.test.tsx b/packages/ui/src/components/forms/issue-focus.browser.test.tsx
index 5b9d7c091c..56cd25e674 100644
--- a/packages/ui/src/components/forms/issue-focus.browser.test.tsx
+++ b/packages/ui/src/components/forms/issue-focus.browser.test.tsx
@@ -260,6 +260,27 @@ describe('useRequestIssueFocus', () => {
     expect(focus).toHaveBeenCalledWith([1, 2]);
   });
 
+  // A code editor showing JSON finds the key inside its value itself: a
+  // request for a part of its anchor reaches it with the rest of the path
+  // and the range, which is offsets into that part.
+  it('hands a custom target the part a deeper request names', () => {
+    const focus = vi.fn();
+    function Custom() {
+      useIssueFocusTarget('/nodes/0/input', { focus });
+      return null;
+    }
+    render(
+      <Surface>
+        <Custom />
+      </Surface>,
+    );
+    act(() => request('/nodes/0/input/to/name', [2, 5]));
+    expect(focus).toHaveBeenCalledWith(undefined, {
+      rest: '/to/name',
+      range: [2, 5],
+    });
+  });
+
   it('forgets a target that unmounted', () => {
     function Toggle() {
       const [shown, setShown] = useState(true);
diff --git a/packages/ui/src/components/forms/issue-focus.tsx b/packages/ui/src/components/forms/issue-focus.tsx
index 62107fa9a9..9309714204 100644
--- a/packages/ui/src/components/forms/issue-focus.tsx
+++ b/packages/ui/src/components/forms/issue-focus.tsx
@@ -15,14 +15,27 @@ import {
 /** Offsets into the text a control shows, start inclusive, end exclusive. */
 export type IssueFocusRange = readonly [number, number];
 
+/**
+ * A request for a part of a target: the rest of the requested anchor below
+ * the target's own (`/to` when `/nodes/0/input/to` lands on
+ * `/nodes/0/input`), and the range the request carried, which is offsets
+ * into that part's value.
+ */
+export interface IssueFocusPart {
+  rest: string;
+  range: IssueFocusRange | undefined;
+}
+
 /** Something a reader can be taken to: a control, a heading, a panel. */
 export interface IssueFocusTarget {
   /**
    * Moves focus here. `range` is passed only when the request names this
    * target's own anchor exactly — a request for a part of it (a key inside a
-   * JSON value) has offsets into that part, not into this control.
+   * JSON value) has offsets into that part, not into this control, and comes
+   * as `part` instead: a target that can find the part in its text (a code
+   * editor showing JSON or YAML) selects it; any other ignores it.
    */
-  focus(range?: IssueFocusRange): void;
+  focus(range?: IssueFocusRange, part?: IssueFocusPart): void;
   /** Makes the target visible first: opens the disclosure or tab it sits in. */
   reveal?(): void;
 }
@@ -163,15 +176,28 @@ class IssueFocusRegistry {
     const registration = this.targets.get(best)?.at(-1);
     const target = registration?.resolve() ?? null;
     if (registration === undefined || target === null) return false;
-    const exactRange = best === anchor ? range : undefined;
+    const exact = best === anchor;
+    const exactRange = exact ? range : undefined;
+    const part: IssueFocusPart | undefined = exact
+      ? undefined
+      : {
+          rest: anchor.slice(
+            best.endsWith('/') ? best.length - 1 : best.length,
+          ),
+          range,
+        };
+    const go = () => {
+      if (part === undefined) target.focus(exactRange);
+      else target.focus(exactRange, part);
+    };
     const reveal = registration.reveal() ?? target.reveal?.bind(target);
     if (reveal === undefined) {
-      target.focus(exactRange);
+      go();
       return true;
     }
     reveal();
     // Let what the reveal opened render before the target takes focus.
-    requestAnimationFrame(() => target.focus(exactRange));
+    requestAnimationFrame(go);
     return true;
   }
 }
diff --git a/packages/ui/src/components/forms/label.test.tsx b/packages/ui/src/components/forms/label.test.tsx
index 53869d3fee..c3712a97b5 100644
--- a/packages/ui/src/components/forms/label.test.tsx
+++ b/packages/ui/src/components/forms/label.test.tsx
@@ -44,6 +44,32 @@ describe('Label', () => {
     });
   });
 
+  // A click on a label whose target is not labelable (a code editor's
+  // contenteditable text) still moves focus there.
+  describe('a target that is not labelable', () => {
+    it('takes focus when the label is clicked', async () => {
+      const { user } = render(
+        <>
+          <Label htmlFor="editable">Code</Label>
+          <div id="editable" role="textbox" tabIndex={0} contentEditable />
+        </>,
+      );
+      await user.click(screen.getByText('Code'));
+      expect(screen.getByRole('textbox')).toHaveFocus();
+    });
+
+    it('leaves a labelable target to the browser', async () => {
+      const { user } = render(
+        <>
+          <Label htmlFor="plain">Name</Label>
+          <input id="plain" />
+        </>,
+      );
+      await user.click(screen.getByText('Name'));
+      expect(screen.getByRole('textbox')).toHaveFocus();
+    });
+  });
+
   describe('info tooltip', () => {
     it('renders a keyboard-focusable info button with an aria-label', () => {
       render(<Label info="Use a public domain.">Domain</Label>);
diff --git a/packages/ui/src/components/forms/label.tsx b/packages/ui/src/components/forms/label.tsx
index c76eb91f2e..63a5e7ea97 100644
--- a/packages/ui/src/components/forms/label.tsx
+++ b/packages/ui/src/components/forms/label.tsx
@@ -30,14 +30,42 @@ interface LabelProps extends ComponentPropsWithoutRef<
   info?: ReactNode;
 }
 
+/**
+ * Elements a `<label for>` focuses by itself. Any other target — a code
+ * editor's contenteditable text — gets focus from the label's click handler.
+ */
+const LABELABLE = new Set([
+  'BUTTON',
+  'INPUT',
+  'METER',
+  'OUTPUT',
+  'PROGRESS',
+  'SELECT',
+  'TEXTAREA',
+]);
+
+function focusUnlabelableTarget(htmlFor: string | undefined): boolean {
+  if (htmlFor === undefined || typeof document === 'undefined') return false;
+  const target = document.getElementById(htmlFor);
+  if (target === null || LABELABLE.has(target.tagName)) return false;
+  target.focus();
+  return document.activeElement === target;
+}
+
 export const Label = forwardRef<
   ComponentRef<typeof LabelPrimitive.Root>,
   LabelProps
->(({ className, required, error, info, children, ...props }, ref) => {
+>(({ className, required, error, info, children, onClick, ...props }, ref) => {
   const { t } = useT('common');
   const labelEl = (
     <LabelPrimitive.Root
       ref={ref}
+      onClick={(event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented && focusUnlabelableTarget(props.htmlFor)) {
+          event.preventDefault();
+        }
+      }}
       className={cn(
         'text-foreground text-xs leading-none font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70 md:text-sm',
         error && 'text-destructive',

From cb5b136a57080c334a19871d61b3f90d9e81382a Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 08:57:26 +0200
Subject: [PATCH 08/78] feat(ui): add a CodeEditor for code, JSON, YAML and
 templates

@tale/ui/code-editor is the one control for code-ish fields, on
CodeMirror 6 behind a lazy chunk: the light module draws the frame and a
same-size placeholder, registers with IssueFocus and queues focus until
the editor arrives, so a page without a code field never loads it.

- Languages: a script, one expression, JSON, YAML, Markdown (from
  @lezer/markdown, so no HTML or CSS language comes along), templates and
  text. {{ js }} templates parse as JavaScript inside text, JSON and YAML
  strings and Markdown, drawn as one tinted chip; typing {{ opens a pair.
- Colours: the --code-* palette Shiki reads; a parity test compares the
  role of every character with the read-only highlight.
- Keyboard: Tab indents, Esc then Tab leaves, Mod-Enter submits; a
  one-line editor never takes Tab. A claimed Escape is handled before any
  overlay, so the first Escape in a sheet never closes it.
- Field and IssueFocus: named by its label, described by the field's
  problems, and a go-to lands on the exact range, also inside a JSON or
  YAML value (locate*Pointer).
- Every CodeMirror phrase is translated (en, de, fr, de-CH); guards keep
  one copy of @codemirror/state and view and refuse the language bundles.
---
 .github/renovate.json                         |   5 +
 bun.lock                                      |  12 +
 packages/ui/package.json                      |  16 +
 .../forms/code-editor/code-editor-view.tsx    | 530 +++++++++++++
 .../code-editor/code-editor.browser.test.tsx  | 700 ++++++++++++++++++
 .../code-editor.loading.browser.test.tsx      |  98 +++
 .../forms/code-editor/code-editor.tsx         | 369 +++++++++
 .../code-editor/code-roles.parity.test.ts     | 250 +++++++
 .../components/forms/code-editor/deps.test.ts |  62 ++
 .../forms/code-editor/extensions/highlight.ts |  69 ++
 .../forms/code-editor/extensions/keyboard.ts  | 298 ++++++++
 .../code-editor/extensions/language-styles.ts |  42 ++
 .../forms/code-editor/extensions/languages.ts | 233 ++++++
 .../code-editor/extensions/member-objects.ts  |  85 +++
 .../forms/code-editor/extensions/phrases.ts   |  40 +
 .../code-editor/extensions/template/chips.ts  |  70 ++
 .../code-editor/extensions/template/input.ts  | 135 ++++
 .../code-editor/extensions/template/parser.ts | 229 ++++++
 .../forms/code-editor/extensions/theme.ts     | 174 +++++
 .../forms/code-editor/extensions/tree-walk.ts |  33 +
 .../forms/code-editor/icon-sprite.tsx         | 126 ++++
 .../forms/code-editor/locate.test.ts          | 197 +++++
 .../components/forms/code-editor/locate.ts    | 398 ++++++++++
 .../forms/code-editor/phrases.test.ts         |  89 +++
 .../forms/code-editor/providers.test.ts       | 131 ++++
 .../components/forms/code-editor/providers.ts | 226 ++++++
 .../forms/code-editor/template-scan.test.ts   |  82 ++
 .../forms/code-editor/template-scan.ts        | 195 +++++
 .../src/components/forms/code-editor/types.ts | 119 +++
 packages/ui/src/i18n/messages/de-CH.yml       |   4 +
 packages/ui/src/i18n/messages/de.yml          |  40 +
 packages/ui/src/i18n/messages/en.yml          |  40 +
 packages/ui/src/i18n/messages/fr.yml          |  40 +
 packages/ui/src/lib/code-roles.ts             | 111 +++
 34 files changed, 5248 insertions(+)
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor-view.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor.loading.browser.test.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/deps.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/highlight.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/language-styles.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/languages.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/member-objects.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/phrases.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/template/chips.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/template/input.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/template/parser.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/theme.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/tree-walk.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/icon-sprite.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/locate.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/locate.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/phrases.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/providers.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/providers.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/template-scan.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/template-scan.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/types.ts

diff --git a/.github/renovate.json b/.github/renovate.json
index 9049c1dfd5..dafd3efbf1 100644
--- a/.github/renovate.json
+++ b/.github/renovate.json
@@ -59,6 +59,11 @@
       ],
       "minimumReleaseAge": null,
       "groupName": "better-auth"
+    },
+    {
+      "description": "CodeMirror and Lezer move together: @tale/ui's code editor and Milkdown share one copy of each, and two copies of @codemirror/state or @codemirror/view break the editor (packages/ui/src/components/forms/code-editor/deps.test.ts)",
+      "matchPackageNames": ["/^@codemirror\\//", "/^@lezer\\//"],
+      "groupName": "codemirror"
     }
   ]
 }
diff --git a/bun.lock b/bun.lock
index a2243d00a1..dc8d9b593c 100644
--- a/bun.lock
+++ b/bun.lock
@@ -131,10 +131,22 @@
         "tale-seo-compile": "./bin/seo-compile.ts",
       },
       "dependencies": {
+        "@codemirror/autocomplete": "6.20.3",
+        "@codemirror/commands": "6.10.4",
+        "@codemirror/lang-javascript": "6.2.5",
+        "@codemirror/lang-json": "6.0.2",
+        "@codemirror/lang-yaml": "6.1.3",
+        "@codemirror/language": "6.12.4",
+        "@codemirror/search": "6.7.1",
+        "@codemirror/state": "6.7.1",
+        "@codemirror/view": "6.43.8",
         "@fontsource/inter": "5.2.8",
         "@hookform/resolvers": "5.2.2",
         "@iconify-json/lucide": "1.2.122",
         "@iconify/react": "6.0.2",
+        "@lezer/common": "1.5.2",
+        "@lezer/highlight": "1.2.3",
+        "@lezer/markdown": "1.7.2",
         "@microlink/react-json-view": "1.31.18",
         "@radix-ui/react-checkbox": "1.3.3",
         "@radix-ui/react-dialog": "1.1.15",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 8e8d9e0b6a..f2a132fbf9 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -48,6 +48,10 @@
     "./checkbox-group": "./src/components/forms/checkbox-group.tsx",
     "./cn": "./src/lib/cn.ts",
     "./code-block": "./src/components/data-display/code-block.tsx",
+    "./code-editor": "./src/components/forms/code-editor/code-editor.tsx",
+    "./code-editor/locate": "./src/components/forms/code-editor/locate.ts",
+    "./code-editor/providers": "./src/components/forms/code-editor/providers.ts",
+    "./code-editor/template-scan": "./src/components/forms/code-editor/template-scan.ts",
     "./collapsible-details": "./src/components/navigation/collapsible-details.tsx",
     "./container": "./src/components/layout/container.tsx",
     "./content-area": "./src/components/layout/content-area.tsx",
@@ -426,10 +430,22 @@
     "test:browser": "bunx vitest --run --project browser"
   },
   "dependencies": {
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.10.4",
+    "@codemirror/lang-javascript": "6.2.5",
+    "@codemirror/lang-json": "6.0.2",
+    "@codemirror/lang-yaml": "6.1.3",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/search": "6.7.1",
+    "@codemirror/state": "6.7.1",
+    "@codemirror/view": "6.43.8",
     "@fontsource/inter": "5.2.8",
     "@hookform/resolvers": "5.2.2",
     "@iconify-json/lucide": "1.2.122",
     "@iconify/react": "6.0.2",
+    "@lezer/common": "1.5.2",
+    "@lezer/highlight": "1.2.3",
+    "@lezer/markdown": "1.7.2",
     "@microlink/react-json-view": "1.31.18",
     "@radix-ui/react-checkbox": "1.3.3",
     "@radix-ui/react-dialog": "1.1.15",
diff --git a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
new file mode 100644
index 0000000000..26f6e8d6bb
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
@@ -0,0 +1,530 @@
+'use client';
+
+/**
+ * The CodeMirror implementation behind `CodeEditor` — loaded lazily, the
+ * first time a code field mounts (or `preloadCodeEditor()` asks). Nothing
+ * outside this module and its `extensions/` imports CodeMirror, so a page
+ * without a code field never downloads it.
+ */
+
+import {
+  closeBrackets,
+  closeBracketsKeymap,
+  startCompletion,
+} from '@codemirror/autocomplete';
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+import {
+  bracketMatching,
+  codeFolding,
+  foldGutter,
+  foldKeymap,
+  indentOnInput,
+  indentUnit,
+} from '@codemirror/language';
+import {
+  highlightSelectionMatches,
+  search,
+  searchKeymap,
+} from '@codemirror/search';
+import {
+  Annotation,
+  Compartment,
+  EditorSelection,
+  EditorState,
+  Prec,
+  Transaction,
+  type Extension,
+} from '@codemirror/state';
+import {
+  drawSelection,
+  EditorView,
+  highlightActiveLine,
+  highlightActiveLineGutter,
+  highlightSpecialChars,
+  keymap,
+  lineNumbers,
+  placeholder as placeholderExtension,
+} from '@codemirror/view';
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+import { useT } from '../../../i18n/client';
+import type { IssueFocusPart, IssueFocusRange } from '../issue-focus';
+import { codeHighlighting } from './extensions/highlight';
+import { keyboard, type KeyboardWords } from './extensions/keyboard';
+import { languageExtension, templatesOn } from './extensions/languages';
+import { memberObjects } from './extensions/member-objects';
+import { editorPhrases } from './extensions/phrases';
+import { templateChips } from './extensions/template/chips';
+import { templateInput } from './extensions/template/input';
+import { codeEditorTheme } from './extensions/theme';
+import { editorIcon, EditorIconSprite } from './icon-sprite';
+import { locateJsonPointer, locateYamlPointer } from './locate';
+import type { CodeEditorProps } from './types';
+
+/** What the light wrapper drives once the view exists. */
+export interface CodeEditorViewHandle {
+  view: EditorView;
+  /**
+   * Focuses and selects `range` (offsets into the text), or the `part` of a
+   * JSON or YAML value a problem names (`/to` inside the field's value).
+   */
+  focus(range?: IssueFocusRange, part?: IssueFocusPart): void;
+  getSelection(): readonly [number, number] | null;
+  openCompletion(): void;
+  nextDiagnostic(direction: 1 | -1): void;
+}
+
+export interface CodeEditorViewProps extends CodeEditorProps {
+  /** The ids the editor's content is described by, merged by the wrapper. */
+  describedBy: string | undefined;
+  reducedMotion: boolean;
+  onView: (handle: CodeEditorViewHandle | null) => void;
+}
+
+/** Marks a transaction that applies the `value` prop (not the reader typing). */
+const external = Annotation.define<boolean>();
+
+/** The smallest change that turns `from` into `to`: common prefix and suffix kept. */
+function minimalChange(
+  from: string,
+  to: string,
+): { from: number; to: number; insert: string } {
+  const max = Math.min(from.length, to.length);
+  let start = 0;
+  while (start < max && from.charCodeAt(start) === to.charCodeAt(start))
+    start++;
+  let end = 0;
+  while (
+    end < max - start &&
+    from.charCodeAt(from.length - 1 - end) ===
+      to.charCodeAt(to.length - 1 - end)
+  ) {
+    end++;
+  }
+  return {
+    from: start,
+    to: from.length - end,
+    insert: to.slice(start, to.length - end),
+  };
+}
+
+function clampRange(
+  state: EditorState,
+  range: readonly [number, number],
+): [number, number] {
+  const length = state.doc.length;
+  const from = Math.min(Math.max(range[0], 0), length);
+  const to = Math.min(Math.max(range[1], from), length);
+  return [from, to];
+}
+
+const CODE_LANGUAGES = new Set(['javascript', 'expression', 'json', 'yaml']);
+
+/** A stable number per template scanner, for the language signature. */
+const scannerIds = new WeakMap<object, number>();
+let scannerCount = 0;
+function scannerId(scanner: unknown): number {
+  if (typeof scanner !== 'function') return 0;
+  const known = scannerIds.get(scanner);
+  if (known !== undefined) return known;
+  scannerCount += 1;
+  scannerIds.set(scanner, scannerCount);
+  return scannerCount;
+}
+
+type SlotName =
+  | 'language'
+  | 'editable'
+  | 'gutters'
+  | 'wrap'
+  | 'placeholder'
+  | 'attributes'
+  | 'keyboard'
+  | 'search'
+  | 'templates'
+  | 'phrases'
+  | 'selection';
+
+const SLOT_NAMES: readonly SlotName[] = [
+  'language',
+  'editable',
+  'gutters',
+  'wrap',
+  'placeholder',
+  'attributes',
+  'keyboard',
+  'search',
+  'templates',
+  'phrases',
+  'selection',
+];
+
+/** One reconfigurable part: rebuilt only when its signature changes. */
+interface Slot {
+  signature: string;
+  build: () => Extension;
+}
+
+export default function CodeEditorView(props: CodeEditorViewProps) {
+  const { t } = useT('codeEditor');
+  const host = useRef<HTMLDivElement>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  const latest = useRef(props);
+  const pendingValue = useRef<string | null>(null);
+  const compartments = useRef<Record<SlotName, Compartment> | null>(null);
+  compartments.current ??= {
+    language: new Compartment(),
+    editable: new Compartment(),
+    gutters: new Compartment(),
+    wrap: new Compartment(),
+    placeholder: new Compartment(),
+    attributes: new Compartment(),
+    keyboard: new Compartment(),
+    search: new Compartment(),
+    templates: new Compartment(),
+    phrases: new Compartment(),
+    selection: new Compartment(),
+  };
+  const applied = useRef<Partial<Record<SlotName, string>>>({});
+
+  useLayoutEffect(() => {
+    latest.current = props;
+  });
+
+  const words: KeyboardWords = {
+    leaveArmed: t('leaveArmed'),
+    tabFocusOn: t('tabFocusOn'),
+    tabFocusOff: t('tabFocusOff'),
+  };
+  const wordsRef = useRef(words);
+  useLayoutEffect(() => {
+    wordsRef.current = words;
+  });
+
+  const {
+    language,
+    templates = false,
+    templateScanner,
+    readOnly = false,
+    disabled = false,
+    disabledReason,
+    placeholder,
+    singleLine = false,
+    lineNumbers: showLineNumbers = false,
+    fold = showLineNumbers,
+    search: withSearch = false,
+    wrap,
+    font = 'mono',
+    fillHeight = false,
+    id,
+    required,
+    describedBy,
+    reducedMotion,
+  } = props;
+  const softDisabled = disabled && hasReason(disabledReason);
+  const editable = !disabled && !readOnly;
+  const live = templatesOn(language, templates);
+  const isCode = CODE_LANGUAGES.has(language);
+  const wraps = wrap ?? (singleLine || !isCode);
+
+  const contentAttributes: Record<string, string> = {
+    ...(id !== undefined ? { id } : {}),
+    ...(props['aria-label'] !== undefined
+      ? { 'aria-label': props['aria-label'] }
+      : {}),
+    ...(props['aria-labelledby'] !== undefined
+      ? { 'aria-labelledby': props['aria-labelledby'] }
+      : {}),
+    ...(describedBy !== undefined ? { 'aria-describedby': describedBy } : {}),
+    ...(props['aria-invalid'] ? { 'aria-invalid': 'true' } : {}),
+    ...(required ? { 'aria-required': 'true' } : {}),
+    ...(readOnly ? { 'aria-readonly': 'true', inputmode: 'none' } : {}),
+    ...(disabled ? { 'aria-disabled': 'true' } : {}),
+    ...(softDisabled || (readOnly && !disabled) ? { tabindex: '0' } : {}),
+    'aria-multiline': singleLine ? 'false' : 'true',
+    'aria-roledescription': t('roleDescription'),
+    spellcheck: font === 'prose' ? 'true' : 'false',
+    autocorrect: font === 'prose' ? 'on' : 'off',
+    autocapitalize: 'off',
+    ...(isCode ? { translate: 'no', dir: 'ltr' } : {}),
+  };
+  const rootClass = [
+    font === 'prose' ? 'cm-prose' : '',
+    fillHeight ? 'cm-fill' : '',
+    readOnly || disabled ? 'cm-readonly' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const phrases = editorPhrases(t);
+
+  const slots: Record<SlotName, Slot> = {
+    language: {
+      signature: `${language}|${templates}|${scannerId(templateScanner)}`,
+      build: () => languageExtension(language, templates, templateScanner),
+    },
+    editable: {
+      signature: `${readOnly}|${disabled}`,
+      build: () => [
+        EditorState.readOnly.of(!editable),
+        EditorView.editable.of(!disabled),
+      ],
+    },
+    gutters: {
+      signature: `${showLineNumbers}|${fold}`,
+      build: () => [
+        showLineNumbers ? [lineNumbers(), highlightActiveLineGutter()] : [],
+        fold
+          ? [
+              codeFolding(),
+              foldGutter({
+                markerDOM: (open) =>
+                  editorIcon(open ? 'chevron-down' : 'chevron-right'),
+              }),
+              keymap.of(foldKeymap),
+            ]
+          : [],
+      ],
+    },
+    wrap: {
+      signature: String(wraps),
+      build: () => (wraps ? EditorView.lineWrapping : []),
+    },
+    placeholder: {
+      signature: placeholder ?? '',
+      build: () =>
+        placeholder !== undefined && placeholder !== ''
+          ? placeholderExtension(placeholder)
+          : [],
+    },
+    attributes: {
+      signature: JSON.stringify([contentAttributes, rootClass]),
+      build: () => [
+        EditorView.contentAttributes.of(contentAttributes),
+        EditorView.editorAttributes.of({ class: rootClass }),
+      ],
+    },
+    keyboard: {
+      signature: String(singleLine),
+      build: () =>
+        keyboard({
+          singleLine,
+          words: () => wordsRef.current,
+          submit: () => {
+            const onSubmit = latest.current.onSubmit;
+            if (onSubmit === undefined) return null;
+            return (view) => onSubmit(view.state.doc.toString());
+          },
+        }),
+    },
+    search: {
+      signature: String(withSearch),
+      build: () =>
+        withSearch
+          ? [
+              search({ top: true }),
+              highlightSelectionMatches(),
+              keymap.of(searchKeymap),
+            ]
+          : [],
+    },
+    templates: {
+      signature: `${live}|${language}`,
+      // The chip is the outer element, so a coloured name inside it never
+      // splits it into pieces.
+      build: () =>
+        live ? [Prec.lowest(templateChips), templateInput(language)] : [],
+    },
+    phrases: {
+      signature: JSON.stringify(phrases),
+      build: () => EditorState.phrases.of(phrases),
+    },
+    selection: {
+      signature: String(reducedMotion),
+      build: () => drawSelection({ cursorBlinkRate: reducedMotion ? 0 : 1200 }),
+    },
+  };
+  const slotsRef = useRef(slots);
+  useLayoutEffect(() => {
+    slotsRef.current = slots;
+  });
+
+  // Create the view once; props flow in through the compartments.
+  useLayoutEffect(() => {
+    const parent = host.current;
+    const c = compartments.current;
+    if (parent === null || c === null) return undefined;
+    const initial = latest.current;
+    const doc = initial.value;
+    const selection =
+      initial.initialSelection === undefined
+        ? undefined
+        : EditorSelection.single(
+            ...clampRange(
+              EditorState.create({ doc }),
+              initial.initialSelection,
+            ),
+          );
+    const startSlots = slotsRef.current;
+    const slotExtensions = SLOT_NAMES.map((name) => {
+      applied.current[name] = startSlots[name].signature;
+      return c[name].of(startSlots[name].build());
+    });
+    const view = new EditorView({
+      parent,
+      state: EditorState.create({
+        doc,
+        ...(selection !== undefined ? { selection } : {}),
+        extensions: [
+          slotExtensions,
+          indentUnit.of('  '),
+          EditorState.tabSize.of(2),
+          history(),
+          highlightSpecialChars(),
+          highlightActiveLine(),
+          bracketMatching(),
+          closeBrackets(),
+          indentOnInput(),
+          memberObjects,
+          codeHighlighting,
+          codeEditorTheme,
+          keymap.of([
+            ...closeBracketsKeymap,
+            ...defaultKeymap,
+            ...historyKeymap,
+          ]),
+          EditorView.updateListener.of((update) => {
+            const changed = update.transactions.some(
+              (tr) => tr.docChanged && tr.annotation(external) !== true,
+            );
+            if (changed) latest.current.onChange?.(update.state.doc.toString());
+            if (update.focusChanged) {
+              if (update.view.hasFocus) latest.current.onFocus?.();
+              else latest.current.onBlur?.();
+            }
+          }),
+          EditorView.domEventObservers({
+            compositionend: () => {
+              // CodeMirror finishes the composition after this event; apply
+              // a value the host sent meanwhile once it has.
+              setTimeout(() => {
+                const pending = pendingValue.current;
+                const current = viewRef.current;
+                if (
+                  pending === null ||
+                  current === null ||
+                  current.compositionStarted
+                ) {
+                  return;
+                }
+                pendingValue.current = null;
+                applyValue(current, pending);
+              }, 0);
+            },
+          }),
+        ],
+      }),
+    });
+    viewRef.current = view;
+    latest.current.onView({
+      view,
+      focus(range, part) {
+        view.focus();
+        const target = range ?? locatePart(view, latest.current.language, part);
+        if (target === undefined) return;
+        const [from, to] = clampRange(view.state, target);
+        view.dispatch({
+          selection: EditorSelection.single(from, to),
+          effects: EditorView.scrollIntoView(from, { y: 'center' }),
+          userEvent: 'select',
+        });
+      },
+      getSelection() {
+        const main = view.state.selection.main;
+        return [main.from, main.to];
+      },
+      openCompletion() {
+        view.focus();
+        startCompletion(view);
+      },
+      nextDiagnostic() {
+        view.focus();
+      },
+    });
+    return () => {
+      latest.current.onView(null);
+      view.destroy();
+      viewRef.current = null;
+    };
+  }, []);
+
+  // Reconfigure the parts whose props changed.
+  useEffect(() => {
+    const view = viewRef.current;
+    const c = compartments.current;
+    if (view === null || c === null) return;
+    const effects = SLOT_NAMES.filter(
+      (name) => applied.current[name] !== slots[name].signature,
+    ).map((name) => {
+      applied.current[name] = slots[name].signature;
+      return c[name].reconfigure(slots[name].build());
+    });
+    if (effects.length > 0) view.dispatch({ effects });
+  });
+
+  // The value prop: applied as the smallest change, never echoed.
+  useEffect(() => {
+    const view = viewRef.current;
+    if (view === null) return;
+    // Mid-composition (IME), a change would break the reader's input.
+    if (view.compositionStarted) {
+      pendingValue.current = props.value;
+      return;
+    }
+    applyValue(view, props.value);
+  }, [props.value]);
+
+  return (
+    <>
+      <EditorIconSprite />
+      <div
+        ref={host}
+        className={fillHeight ? 'h-full min-h-0' : undefined}
+        data-code-editor-view=""
+      />
+    </>
+  );
+}
+
+/** Where the part of a JSON or YAML value a request names sits in the text. */
+function locatePart(
+  view: EditorView,
+  language: CodeEditorProps['language'],
+  part: IssueFocusPart | undefined,
+): IssueFocusRange | undefined {
+  if (part === undefined) return undefined;
+  const text = view.state.doc.toString();
+  const options = part.range === undefined ? {} : { range: part.range };
+  const found =
+    language === 'json'
+      ? locateJsonPointer(text, part.rest, options)
+      : language === 'yaml'
+        ? locateYamlPointer(text, part.rest, options)
+        : null;
+  return found === null ? undefined : [found.from, found.to];
+}
+
+function hasReason(reason: unknown): boolean {
+  if (reason === undefined || reason === null || typeof reason === 'boolean') {
+    return false;
+  }
+  return typeof reason !== 'string' || reason.trim() !== '';
+}
+
+function applyValue(view: EditorView, value: string): void {
+  const current = view.state.doc.toString();
+  if (current === value) return;
+  view.dispatch({
+    changes: minimalChange(current, value),
+    annotations: [external.of(true), Transaction.addToHistory.of(false)],
+  });
+}
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
new file mode 100644
index 0000000000..df5dbfb443
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -0,0 +1,700 @@
+import '@testing-library/jest-dom/vitest';
+import { EditorView } from '@codemirror/view';
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { useRef, useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { page, userEvent } from 'vitest/browser';
+
+import { act, render, screen, waitFor } from '@/tests/utils/render';
+
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogTitle,
+} from '../../overlays/responsive-dialog';
+import { Field } from '../field';
+import {
+  IssueFocusProvider,
+  useRequestIssueFocus,
+  type IssueFocusRange,
+} from '../issue-focus';
+import {
+  CodeEditor,
+  preloadCodeEditor,
+  type CodeEditorHandle,
+  type CodeEditorProps,
+} from './code-editor';
+
+import '../../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  vi.restoreAllMocks();
+});
+
+/** The editable text of the editor the test rendered. */
+async function content(name?: string | RegExp): Promise<HTMLElement> {
+  return screen.findByRole('textbox', name === undefined ? {} : { name }, {
+    timeout: 10_000,
+  });
+}
+
+/** A controlled editor with its value on screen, like a host form. */
+function Controlled(
+  props: Partial<CodeEditorProps> & {
+    initial?: string;
+    reformat?: (value: string) => string;
+    onValue?: (value: string) => void;
+  },
+) {
+  const { initial = '', reformat, onValue, ...rest } = props;
+  const [value, setValue] = useState(initial);
+  return (
+    <>
+      <CodeEditor
+        aria-label="Code"
+        language="javascript"
+        {...rest}
+        value={value}
+        onChange={(next) => {
+          const shown = reformat ? reformat(next) : next;
+          onValue?.(shown);
+          setValue(shown);
+        }}
+      />
+      <output data-testid="value">{value}</output>
+      <button type="button">After</button>
+    </>
+  );
+}
+
+function viewOf(element: HTMLElement): EditorView {
+  const view = EditorView.findFromDOM(element);
+  if (view === null) throw new Error('no editor view');
+  return view;
+}
+
+function selection(element: HTMLElement): [number, number] {
+  const { from, to } = viewOf(element).state.selection.main;
+  return [from, to];
+}
+
+describe('CodeEditor typing', () => {
+  it('round-trips a controlled value', async () => {
+    render(<Controlled initial="return 1;" />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End} // ok');
+    expect(screen.getByTestId('value')).toHaveTextContent('return 1; // ok');
+    expect(box).toHaveTextContent('return 1; // ok');
+  });
+
+  // REGRESSION (the JSON caret jump): a host that rewrites the text on every
+  // keystroke must not move the caret off what the reader typed.
+  it('keeps the caret when the host rewrites the value', async () => {
+    render(
+      <Controlled
+        language="json"
+        initial='{"a":1}'
+        reformat={(value) => value.replace(/\s+$/, '').replace('"a":', '"a": ')}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}{ArrowLeft}');
+    await userEvent.keyboard('2');
+    // "a": now holds 12, the host added the space, the caret is after the 2.
+    expect(screen.getByTestId('value')).toHaveTextContent('{"a": 12}');
+    const [from, to] = selection(box);
+    expect(from).toBe(to);
+    expect(box.textContent?.slice(0, from)).toBe('{"a": 12');
+  });
+
+  it('applies an outside change without echoing it to onChange', async () => {
+    const onChange = vi.fn();
+    const { rerender } = render(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value="hello"
+        onChange={onChange}
+      />,
+    );
+    await content('Code');
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value="hello world"
+        onChange={onChange}
+      />,
+    );
+    await waitFor(async () =>
+      expect(await content('Code')).toHaveTextContent('hello world'),
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('waits for an input method to finish before applying an outside change', async () => {
+    const { rerender } = render(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value="abc"
+        onChange={() => {}}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    box.dispatchEvent(new CompositionEvent('compositionstart', { data: '' }));
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value="abc def"
+        onChange={() => {}}
+      />,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(box).toHaveTextContent(/^abc$/);
+    box.dispatchEvent(new CompositionEvent('compositionend', { data: '' }));
+    await waitFor(() => expect(box).toHaveTextContent('abc def'));
+  });
+});
+
+const MOD = navigator.platform.toLowerCase().includes('mac')
+  ? 'Meta'
+  : 'Control';
+
+function announced(element: HTMLElement): string {
+  return (
+    element.closest('.cm-editor')?.querySelector('.cm-announced')
+      ?.textContent ?? ''
+  );
+}
+
+describe('CodeEditor keyboard', () => {
+  it('indents with Tab, then leaves with Esc and Tab', async () => {
+    render(<Controlled initial="a" />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}{Enter}{Tab}b');
+    expect(screen.getByTestId('value').textContent).toBe('a\n  b');
+    await userEvent.keyboard('{Escape}');
+    expect(announced(box)).toBe('Press Tab to move on.');
+    await userEvent.keyboard('{Tab}');
+    expect(screen.getByRole('button', { name: 'After' })).toHaveFocus();
+    expect(screen.getByTestId('value').textContent).toBe('a\n  b');
+  });
+
+  it('describes the way out to assistive technology', async () => {
+    render(<Controlled initial="a" />);
+    const box = await content('Code');
+    const ids = (box.getAttribute('aria-describedby') ?? '').split(' ');
+    const hint = ids
+      .map((id) => document.getElementById(id)?.textContent)
+      .join(' ');
+    expect(hint).toContain('To leave the editor, press Esc, then Tab.');
+  });
+
+  it('never takes Tab in one line and submits on Enter', async () => {
+    const onSubmit = vi.fn();
+    render(
+      <Controlled
+        singleLine
+        language="expression"
+        initial="a > 1"
+        onSubmit={onSubmit}
+        submitLabel="Run"
+      />,
+    );
+    const box = await content('Code');
+    expect(box).toHaveAttribute('aria-multiline', 'false');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Enter}');
+    expect(onSubmit).toHaveBeenCalledWith('a > 1');
+    expect(screen.getByTestId('value').textContent).toBe('a > 1');
+    await userEvent.keyboard('{Tab}');
+    expect(screen.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  it('turns pasted line breaks into spaces in one line', async () => {
+    render(<Controlled singleLine language="template" initial="" />);
+    const box = await content('Code');
+    act(() => {
+      viewOf(box).dispatch({
+        changes: { from: 0, insert: 'one\ntwo\nthree' },
+        userEvent: 'input.paste',
+      });
+    });
+    expect(screen.getByTestId('value').textContent).toBe('one two three');
+  });
+
+  it('submits with Mod-Enter from several lines', async () => {
+    const onSubmit = vi.fn();
+    render(
+      <Controlled
+        language="json"
+        initial={'{\n  "a": 1\n}'}
+        onSubmit={onSubmit}
+        submitLabel="Run"
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard(`{${MOD}>}{Enter}{/${MOD}}`);
+    expect(onSubmit).toHaveBeenCalledWith('{\n  "a": 1\n}');
+    expect(screen.getByTestId('value').textContent).toBe('{\n  "a": 1\n}');
+  });
+
+  it('shows the shortcut legend after keyboard focus only', async () => {
+    render(
+      <>
+        <button type="button">Before</button>
+        <Controlled initial="a" onSubmit={() => {}} submitLabel="Run" />
+      </>,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    expect(
+      document.querySelector('[data-code-editor-legend]'),
+    ).not.toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Before' }));
+    await userEvent.keyboard('{Tab}');
+    expect(box).toHaveFocus();
+    const legend = document.querySelector('[data-code-editor-legend]');
+    expect(legend).toBeInTheDocument();
+    expect(legend).toHaveAttribute('aria-hidden', 'true');
+    expect(legend?.textContent).toContain('Esc, then Tab to leave');
+    expect(legend?.textContent).toContain('Run');
+  });
+});
+
+describe('CodeEditor in a sheet', () => {
+  function SheetHost() {
+    const [open, setOpen] = useState(true);
+    const [value, setValue] = useState('const a = 1;');
+    return (
+      <>
+        <p>{open ? 'sheet open' : 'sheet closed'}</p>
+        <ResponsiveDialog open={open} onOpenChange={setOpen}>
+          <ResponsiveDialogContent>
+            <ResponsiveDialogTitle>Edit node</ResponsiveDialogTitle>
+            <CodeEditor
+              aria-label="Code"
+              language="javascript"
+              value={value}
+              onChange={setValue}
+            />
+          </ResponsiveDialogContent>
+        </ResponsiveDialog>
+      </>
+    );
+  }
+
+  // Escape is the editor's while it needs it: the first arms leave and the
+  // sheet stays; once armed, the next closes the sheet.
+  it('keeps the sheet open until leave is armed, at phone width', async () => {
+    await page.viewport(375, 800);
+    try {
+      render(<SheetHost />);
+      const box = await content('Code');
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      await userEvent.click(box);
+      await userEvent.keyboard('{Escape}');
+      expect(screen.getByText('sheet open')).toBeInTheDocument();
+      expect(announced(box)).toBe('Press Tab to move on.');
+      await userEvent.keyboard('{Escape}');
+      await waitFor(() =>
+        expect(screen.getByText('sheet closed')).toBeInTheDocument(),
+      );
+    } finally {
+      await page.viewport(1280, 800);
+    }
+  });
+
+  it('never lets a text selection drag the sheet', async () => {
+    await page.viewport(375, 800);
+    try {
+      render(<SheetHost />);
+      const box = await content('Code');
+      const frame = box.closest('[data-code-editor]');
+      expect(frame).toHaveAttribute('data-vaul-no-drag');
+      const sheet = box.closest('[role="dialog"]') as HTMLElement;
+      // Let the sheet finish sliding in.
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      const before = sheet.getBoundingClientRect().top;
+      const { left, top } = box.getBoundingClientRect();
+      const at = (y: number) => ({
+        bubbles: true,
+        pointerId: 1,
+        pointerType: 'touch',
+        clientX: left + 10,
+        clientY: y,
+      });
+      box.dispatchEvent(new PointerEvent('pointerdown', at(top + 5)));
+      for (const step of [30, 60, 120]) {
+        box.dispatchEvent(new PointerEvent('pointermove', at(top + step)));
+      }
+      box.dispatchEvent(new PointerEvent('pointerup', at(top + 120)));
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      expect(screen.getByText('sheet open')).toBeInTheDocument();
+      expect(sheet.getBoundingClientRect().top).toBe(before);
+    } finally {
+      await page.viewport(1280, 800);
+    }
+  });
+});
+
+describe('CodeEditor in a field', () => {
+  type Request = (anchor: string, range?: IssueFocusRange) => void;
+  const requester: { current: Request } = { current: () => {} };
+  function Requester() {
+    const request = useRequestIssueFocus();
+    requester.current = request;
+    return null;
+  }
+
+  function FieldHost({ value }: { value: string }) {
+    return (
+      <IssueFocusProvider>
+        <Requester />
+        <Field
+          label="Input"
+          htmlFor="node-input"
+          issues={[
+            { id: 'to', severity: 'error', message: 'Reads a missing field.' },
+          ]}
+        >
+          <CodeEditor
+            id="node-input"
+            language="json"
+            templates
+            value={value}
+            onChange={() => {}}
+            issueAnchor="/nodes/0/input"
+            describeDiagnostics={false}
+          />
+        </Field>
+      </IssueFocusProvider>
+    );
+  }
+
+  it('is named by its label and described by its problems', async () => {
+    render(<FieldHost value='{"to": "ada"}' />);
+    const box = await content('Input');
+    expect(box).toHaveAttribute('aria-invalid', 'true');
+    const described = (box.getAttribute('aria-describedby') ?? '')
+      .split(' ')
+      .map((id) => document.getElementById(id)?.textContent ?? '')
+      .join(' ');
+    expect(described).toContain('Reads a missing field.');
+    expect(box.closest('[data-code-editor]')?.className).toContain(
+      'border-destructive',
+    );
+  });
+
+  it('takes focus from a click on its label', async () => {
+    render(<FieldHost value='{"to": "ada"}' />);
+    const box = await content('Input');
+    await userEvent.click(screen.getByText('Input'));
+    expect(box).toHaveFocus();
+  });
+
+  it('selects the range a problem names', async () => {
+    render(<FieldHost value='{"to": "ada"}' />);
+    const box = await content('Input');
+    act(() => requester.current('/nodes/0/input', [1, 5]));
+    expect(box).toHaveFocus();
+    expect(selection(box)).toEqual([1, 5]);
+  });
+
+  // A problem with a key inside the JSON value lands on that key's text.
+  it('finds the part of the value a deeper problem names', async () => {
+    render(<FieldHost value='{"to": "ada", "cc": "bob"}' />);
+    const box = await content('Input');
+    act(() => requester.current('/nodes/0/input/cc', [0, 3]));
+    expect(box).toHaveFocus();
+    const [from, to] = selection(box);
+    expect(box.textContent?.slice(from, to)).toBe('bob');
+  });
+});
+
+describe('CodeEditor states', () => {
+  it('reads but never edits when read-only', async () => {
+    render(<Controlled readOnly initial="return 1;" />);
+    const box = await content('Code');
+    expect(box).toHaveAttribute('aria-readonly', 'true');
+    await userEvent.click(screen.getByRole('button', { name: 'After' }));
+    await userEvent.keyboard('{Shift>}{Tab}{/Shift}');
+    expect(box).toHaveFocus();
+    await userEvent.keyboard('{End}x');
+    expect(screen.getByTestId('value').textContent).toBe('return 1;');
+  });
+
+  it('says why it is disabled, on focus', async () => {
+    render(
+      <Controlled
+        disabled
+        disabledReason="Only an author can change this."
+        initial="return 1;"
+      />,
+    );
+    const box = await content('Code');
+    expect(box).toHaveAttribute('aria-disabled', 'true');
+    await userEvent.click(screen.getByRole('button', { name: 'After' }));
+    await userEvent.keyboard('{Shift>}{Tab}{/Shift}');
+    expect(box).toHaveFocus();
+    expect(
+      await screen.findAllByText('Only an author can change this.'),
+    ).not.toHaveLength(0);
+  });
+
+  it('grows with its text up to maxRows, then scrolls', async () => {
+    const lines = (n: number) =>
+      Array.from({ length: n }, (_, i) => `line ${i}`).join('\n');
+    const { rerender } = render(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value={lines(1)}
+        minRows={2}
+        maxRows={5}
+      />,
+    );
+    const box = await content('Code');
+    const scroller = box.closest('.cm-scroller') as HTMLElement;
+    const height = () => scroller.getBoundingClientRect().height;
+    const small = height();
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value={lines(4)}
+        minRows={2}
+        maxRows={5}
+      />,
+    );
+    await waitFor(() => expect(height()).toBeGreaterThan(small));
+    const grown = height();
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value={lines(20)}
+        minRows={2}
+        maxRows={5}
+      />,
+    );
+    await waitFor(() =>
+      expect(scroller.scrollHeight).toBeGreaterThan(scroller.clientHeight),
+    );
+    expect(height()).toBeGreaterThan(grown);
+    const capped = height();
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value={lines(40)}
+        minRows={2}
+        maxRows={5}
+      />,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(height()).toBe(capped);
+  });
+
+  it('shows the placeholder in the muted colour', async () => {
+    render(
+      <CodeEditor
+        aria-label="Code"
+        language="text"
+        value=""
+        placeholder="Write a prompt"
+      />,
+    );
+    await content('Code');
+    const placeholder = document.querySelector('.cm-placeholder');
+    expect(placeholder).toHaveTextContent('Write a prompt');
+  });
+});
+
+describe('CodeEditor templates', () => {
+  it('turns {{ into a pair with the caret inside', async () => {
+    render(<Controlled language="markdown" templates initial="Hi " />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}{{{{');
+    expect(screen.getByTestId('value').textContent).toBe('Hi {{  }}');
+    await userEvent.keyboard('name');
+    expect(screen.getByTestId('value').textContent).toBe('Hi {{ name }}');
+    await userEvent.keyboard('}}!');
+    expect(screen.getByTestId('value').textContent).toBe('Hi {{ name }}!');
+  });
+
+  it('removes an empty pair with one Backspace', async () => {
+    render(<Controlled language="template" initial="a " />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}{{{{');
+    expect(screen.getByTestId('value').textContent).toBe('a {{  }}');
+    await userEvent.keyboard('{Backspace}');
+    expect(screen.getByTestId('value').textContent).toBe('a ');
+  });
+
+  it('draws each template as one chip, in JSON strings too', async () => {
+    render(
+      <CodeEditor
+        aria-label="Code"
+        language="json"
+        templates
+        value={'{"to": "{{ input.email }}", "n": 1}'}
+      />,
+    );
+    await content('Code');
+    const chips = [...document.querySelectorAll('.cm-template')];
+    expect(chips.map((chip) => chip.textContent)).toEqual([
+      '{{ input.email }}',
+    ]);
+  });
+});
+
+describe('CodeEditor colours', () => {
+  it('reads the keyword colour from the palette in dark mode', async () => {
+    document.documentElement.classList.add('dark');
+    render(
+      <div className="bg-background p-4">
+        <CodeEditor
+          aria-label="Code"
+          language="javascript"
+          value="const a = 1;"
+        />
+      </div>,
+    );
+    const box = await content('Code');
+    const keyword = [...box.querySelectorAll('span')].find(
+      (span) => span.textContent === 'const',
+    );
+    expect(keyword).toBeDefined();
+    expect(getComputedStyle(keyword as HTMLElement).color).toBe(
+      'rgb(249, 117, 131)',
+    );
+  });
+
+  it.each(['light', 'dark'])(
+    'keeps every language readable on each surface (%s)',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      const samples: Array<Partial<CodeEditorProps> & { value: string }> = [
+        {
+          language: 'javascript',
+          value: 'const a = nodes.b.output; // why\nreturn { a, n: 1 };',
+        },
+        { language: 'expression', value: 'input.n > 2 && input.ok === true' },
+        {
+          language: 'json',
+          templates: true,
+          value: '{"to": "{{ input.email }}", "n": 1}',
+        },
+        {
+          language: 'yaml',
+          templates: true,
+          value: 'name: x\nprompt: Rate {{ item.title }}\n',
+        },
+        {
+          language: 'markdown',
+          templates: true,
+          value: '# Title\n\n**Bold** {{ nodes.a.output }} and `code`',
+        },
+        { language: 'template', value: 'Hi {{ "}}" }} and {{ open' },
+      ];
+      const { container } = render(
+        <div className="flex flex-col gap-4">
+          {['bg-background', 'bg-card', 'bg-bg-elevated'].map((surface) => (
+            <div key={surface} className={`${surface} flex flex-col gap-2 p-4`}>
+              {samples.map(({ value, ...sample }) => (
+                <CodeEditor
+                  key={`${surface}-${sample.language}`}
+                  aria-label={`${sample.language} on ${surface}`}
+                  language="text"
+                  {...sample}
+                  value={value}
+                />
+              ))}
+            </div>
+          ))}
+        </div>,
+      );
+      await screen.findAllByRole('textbox', {}, { timeout: 10_000 });
+      await waitFor(() =>
+        expect(
+          container.querySelectorAll('[data-code-editor-view] .cm-editor'),
+        ).toHaveLength(18),
+      );
+      const result = await axe.run(container, {
+        runOnly: [
+          'color-contrast',
+          'aria-allowed-attr',
+          'aria-valid-attr-value',
+          'aria-roledescription',
+          'label',
+        ],
+      });
+      expect(result.violations).toEqual([]);
+      expect(result.passes.some((rule) => rule.id === 'color-contrast')).toBe(
+        true,
+      );
+    },
+  );
+
+  it('keeps a steady caret under reduced motion', async () => {
+    const original = window.matchMedia.bind(window);
+    vi.spyOn(window, 'matchMedia').mockImplementation((query: string) => {
+      const list = original(query);
+      if (query === '(prefers-reduced-motion: reduce)') {
+        Object.defineProperty(list, 'matches', { value: true });
+      }
+      return list;
+    });
+    render(<Controlled initial="a" />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    const layer = box
+      .closest('.cm-editor')
+      ?.querySelector<HTMLElement>('.cm-cursorLayer');
+    expect(layer?.style.animationDuration).toBe('0ms');
+  });
+});
+
+it('exposes a handle that focuses, selects and reports the selection', async () => {
+  function WithHandle() {
+    const ref = useRef<CodeEditorHandle>(null);
+    return (
+      <>
+        <CodeEditor
+          ref={ref}
+          aria-label="Code"
+          language="text"
+          value="abcdef"
+        />
+        <button type="button" onClick={() => ref.current?.focus([2, 4])}>
+          Select
+        </button>
+        <output data-testid="selection">
+          {JSON.stringify(ref.current?.getSelection() ?? null)}
+        </output>
+      </>
+    );
+  }
+  render(<WithHandle />);
+  const box = await content('Code');
+  await userEvent.click(screen.getByRole('button', { name: 'Select' }));
+  expect(box).toHaveFocus();
+  expect(selection(box)).toEqual([2, 4]);
+});
+
+it('preloads without rendering', async () => {
+  expect(() => preloadCodeEditor()).not.toThrow();
+});
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.loading.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.loading.browser.test.tsx
new file mode 100644
index 0000000000..6ed068dc8a
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor.loading.browser.test.tsx
@@ -0,0 +1,98 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, expect, it } from 'vitest';
+
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import {
+  IssueFocusProvider,
+  useRequestIssueFocus,
+  type IssueFocusRange,
+} from '../issue-focus';
+import { CodeEditor } from './code-editor';
+
+import '../../../globals.css';
+
+/**
+ * What happens before the editor's implementation has loaded. Each browser
+ * test file runs in a fresh page, so the lazy chunk is cold here exactly
+ * once: everything that needs it cold is one test.
+ */
+
+afterEach(cleanup);
+
+const lines = (count: number) =>
+  Array.from({ length: count }, (_, i) => `line ${i + 1}`).join('\n');
+
+function Requests({
+  anchor,
+  range,
+}: {
+  anchor: string;
+  range: IssueFocusRange;
+}) {
+  const request = useRequestIssueFocus();
+  useEffect(() => {
+    request(anchor, range);
+  }, [anchor, range, request]);
+  return null;
+}
+
+it('keeps its size while loading, and applies a go-to asked for meanwhile', async () => {
+  const sizes = [
+    { name: 'short', value: lines(1), minRows: 3, maxRows: 14 },
+    { name: 'grown', value: lines(6), minRows: 3, maxRows: 14 },
+    { name: 'capped', value: lines(30), minRows: 3, maxRows: 8 },
+    { name: 'numbered', value: lines(4), minRows: 3, maxRows: 14 },
+  ];
+  render(
+    <IssueFocusProvider>
+      <div style={{ width: 480 }} className="flex flex-col gap-4">
+        {sizes.map(({ name, value, minRows, maxRows }) => (
+          <CodeEditor
+            key={name}
+            aria-label={name}
+            language="text"
+            value={value}
+            minRows={minRows}
+            maxRows={maxRows}
+            lineNumbers={name === 'numbered'}
+          />
+        ))}
+        <CodeEditor
+          aria-label="Prompt"
+          language="markdown"
+          templates
+          font="prose"
+          value="Summarise {{ nodes.nope.output }} today"
+          issueAnchor="/nodes/0/prompt"
+        />
+      </div>
+      <Requests anchor="/nodes/0/prompt" range={[10, 33]} />
+    </IssueFocusProvider>,
+  );
+
+  const frames = [
+    ...document.querySelectorAll<HTMLElement>('[data-code-editor]'),
+  ];
+  expect(frames).toHaveLength(5);
+  // Still the placeholder: the implementation has not arrived yet.
+  expect(document.querySelector('[data-code-editor-loading]')).not.toBeNull();
+  expect(frames[0]).toHaveAttribute('aria-busy', 'true');
+  const loading = frames.map((frame) => frame.getBoundingClientRect().height);
+
+  await waitFor(
+    () => expect(document.querySelectorAll('.cm-editor')).toHaveLength(5),
+    { timeout: 10_000 },
+  );
+  const loaded = frames.map((frame) => frame.getBoundingClientRect().height);
+  expect(loaded).toEqual(loading);
+  expect(frames[0]).not.toHaveAttribute('aria-busy');
+
+  // The go-to asked for before the editor existed selected its range.
+  const prompt = screen.getByRole('textbox', { name: 'Prompt' });
+  await waitFor(() => expect(prompt).toHaveFocus());
+  const selected = window.getSelection()?.toString();
+  expect(selected).toBe('{{ nodes.nope.output }}');
+});
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.tsx b/packages/ui/src/components/forms/code-editor/code-editor.tsx
new file mode 100644
index 0000000000..51e55c9eec
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor.tsx
@@ -0,0 +1,369 @@
+'use client';
+
+/**
+ * `@tale/ui/code-editor` — the one control for code, JSON, YAML, prompts and
+ * `{{ js }}` templates: highlighting in the shared AA palette, the keyboard
+ * model that never traps (Esc, then Tab leaves), and a place for a host's
+ * completion, hover and problems.
+ *
+ * This module is light: types, the frame, a same-size placeholder while the
+ * CodeMirror implementation (`code-editor-view.tsx`) loads, the Field and
+ * issue-focus wiring. Nothing here imports CodeMirror, so a page that
+ * renders no code field never downloads it.
+ */
+
+import {
+  forwardRef,
+  lazy,
+  Suspense,
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ForwardRefExoticComponent,
+  type RefAttributes,
+} from 'react';
+
+import { useIsMac } from '../../../hooks/use-is-mac';
+import { useMediaQuery } from '../../../hooks/use-media-query';
+import { useT } from '../../../i18n/client';
+import { cn } from '../../../lib/cn';
+import {
+  DisabledReasonTooltip,
+  hasDisabledReason,
+} from '../../overlays/disabled-reason';
+import { FIELD_FOCUS_WITHIN, FIELD_INVALID_WITHIN } from '../field-focus';
+import {
+  useIssueFocusTarget,
+  type IssueFocusPart,
+  type IssueFocusRange,
+} from '../issue-focus';
+import type { CodeEditorViewHandle } from './code-editor-view';
+import type { CodeEditorHandle, CodeEditorProps } from './types';
+
+export type {
+  CodeEditorDiagnostic,
+  CodeEditorDiagnosticsStatus,
+  CodeEditorHandle,
+  CodeEditorProps,
+} from './types';
+export type { CodeLanguage } from '../../../lib/code-roles';
+
+const loadView = () => import('./code-editor-view');
+const CodeEditorView = lazy(loadView);
+
+/**
+ * Starts loading the editor's implementation, so the first code field a
+ * reader opens is ready. Idempotent and fire-and-forget; call it when a
+ * surface that is likely to show code mounts, or on hover of what opens it.
+ */
+export function preloadCodeEditor(): void {
+  loadView().catch((error: unknown) => {
+    console.warn('[code-editor] preload failed', error);
+  });
+}
+
+/* Whether the reader is using the keyboard, for the shortcut legend: it
+   shows after a keyboard focus or a key press, never after a click. */
+let lastInput: 'keyboard' | 'pointer' = 'pointer';
+let modalityListeners = false;
+function trackModality(): void {
+  if (modalityListeners || typeof document === 'undefined') return;
+  modalityListeners = true;
+  document.addEventListener(
+    'keydown',
+    (event) => {
+      if (!event.metaKey && !event.ctrlKey) lastInput = 'keyboard';
+    },
+    true,
+  );
+  document.addEventListener(
+    'pointerdown',
+    () => {
+      lastInput = 'pointer';
+    },
+    true,
+  );
+}
+
+const SIZE_CLASS = {
+  sm: 'text-base md:text-xs',
+  md: 'text-base md:text-sm',
+} as const;
+
+const CODE_LANGUAGES = new Set(['javascript', 'expression', 'json', 'yaml']);
+
+interface PendingFocus {
+  range: IssueFocusRange | undefined;
+  part: IssueFocusPart | undefined;
+}
+
+const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
+  function CodeEditor(props, ref) {
+    const {
+      value,
+      language,
+      readOnly = false,
+      disabled = false,
+      disabledReason,
+      placeholder,
+      singleLine = false,
+      minRows = singleLine ? 1 : 3,
+      maxRows = singleLine ? 4 : 14,
+      fillHeight = false,
+      wrap,
+      font = 'mono',
+      size = 'sm',
+      lineNumbers = false,
+      onSubmit,
+      submitLabel,
+      issueAnchor = null,
+      issueReveal,
+      className,
+    } = props;
+    const { t } = useT('codeEditor');
+    const isMac = useIsMac();
+    const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+    const baseId = useId();
+    const keyboardHintId = `${baseId}-keyboard`;
+    const submitHintId = `${baseId}-submit`;
+    const softDisabled = disabled && hasDisabledReason(disabledReason);
+    const editable = !readOnly && !disabled;
+    const capturesTab = editable && !singleLine;
+    const shortcut = isMac ? '⌘↵' : 'Ctrl+Enter';
+    const canSubmit = onSubmit !== undefined && submitLabel !== undefined;
+    const invalid = props['aria-invalid'] === true;
+
+    const describedBy =
+      [
+        props['aria-describedby'],
+        capturesTab ? keyboardHintId : undefined,
+        canSubmit ? submitHintId : undefined,
+      ]
+        .filter(Boolean)
+        .join(' ') || undefined;
+
+    const viewHandle = useRef<CodeEditorViewHandle | null>(null);
+    const pending = useRef<PendingFocus | null>(null);
+    const [loaded, setLoaded] = useState(false);
+
+    const onView = useCallback((handle: CodeEditorViewHandle | null) => {
+      viewHandle.current = handle;
+      setLoaded(handle !== null);
+      if (handle === null) return;
+      const request = pending.current;
+      pending.current = null;
+      if (request !== null) handle.focus(request.range, request.part);
+    }, []);
+
+    const focus = useCallback(
+      (range?: IssueFocusRange, part?: IssueFocusPart) => {
+        const handle = viewHandle.current;
+        if (handle !== null) handle.focus(range, part);
+        else pending.current = { range, part };
+      },
+      [],
+    );
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: (range) => focus(range),
+        getSelection: () => viewHandle.current?.getSelection() ?? null,
+        openCompletion: () => viewHandle.current?.openCompletion(),
+        nextDiagnostic: (direction = 1) =>
+          viewHandle.current?.nextDiagnostic(direction),
+        get view() {
+          return viewHandle.current?.view ?? null;
+        },
+      }),
+      [focus],
+    );
+
+    // Go-to from a problems list: the range is offsets into `value`; a part
+    // of a JSON or YAML value is found in the text by the view.
+    useIssueFocusTarget(
+      issueAnchor,
+      { focus },
+      issueReveal === undefined ? undefined : { reveal: issueReveal },
+    );
+
+    // The shortcut legend follows keyboard use inside the frame.
+    const frameRef = useRef<HTMLDivElement>(null);
+    const [keyboardFocus, setKeyboardFocus] = useState(false);
+    useEffect(() => {
+      trackModality();
+      const frame = frameRef.current;
+      if (frame === null) return undefined;
+      const onFocusIn = () => {
+        if (lastInput === 'keyboard') setKeyboardFocus(true);
+      };
+      const onKeyDown = () => setKeyboardFocus(true);
+      const onFocusOut = (event: FocusEvent) => {
+        const next = event.relatedTarget;
+        if (!(next instanceof Node) || !frame.contains(next)) {
+          setKeyboardFocus(false);
+        }
+      };
+      frame.addEventListener('focusin', onFocusIn);
+      frame.addEventListener('keydown', onKeyDown);
+      frame.addEventListener('focusout', onFocusOut);
+      return () => {
+        frame.removeEventListener('focusin', onFocusIn);
+        frame.removeEventListener('keydown', onKeyDown);
+        frame.removeEventListener('focusout', onFocusOut);
+      };
+    }, []);
+
+    const frameStyle = {
+      '--ce-min-rows': String(minRows),
+      '--ce-max-rows': String(maxRows),
+    } as CSSProperties;
+
+    const isCode = CODE_LANGUAGES.has(language);
+    const wraps = wrap ?? (singleLine || !isCode);
+
+    const frame = (
+      <div
+        data-code-editor=""
+        data-vaul-no-drag=""
+        aria-busy={loaded ? undefined : true}
+        style={frameStyle}
+        ref={frameRef}
+        className={cn(
+          'group/code-editor bg-background @container relative w-full min-w-0 rounded-md border border-(--color-border-input) transition-[border-color,box-shadow] duration-150 motion-reduce:transition-none',
+          SIZE_CLASS[size],
+          !readOnly && !disabled && FIELD_FOCUS_WITHIN,
+          readOnly && 'border-border-base bg-bg-elevated',
+          readOnly && FIELD_FOCUS_WITHIN,
+          disabled &&
+            'cursor-not-allowed bg-[color:var(--color-bg-elevated)] text-[color:var(--color-fg-subtle)] [&_.cm-content]:opacity-70',
+          invalid && FIELD_INVALID_WITHIN,
+          fillHeight && 'flex h-full min-h-0 flex-1 flex-col',
+          className,
+        )}
+      >
+        <Suspense
+          fallback={
+            <LoadingText
+              value={value}
+              placeholder={placeholder}
+              wraps={wraps}
+              font={font}
+              lineNumbers={lineNumbers}
+              minRows={minRows}
+              maxRows={maxRows}
+              fillHeight={fillHeight}
+              loadingLabel={t('loading')}
+            />
+          }
+        >
+          <CodeEditorView
+            {...props}
+            describedBy={describedBy}
+            reducedMotion={reducedMotion}
+            onView={onView}
+          />
+        </Suspense>
+        {capturesTab ? (
+          <span id={keyboardHintId} hidden>
+            {t('keyboardHint')}
+          </span>
+        ) : null}
+        {canSubmit ? (
+          <span id={submitHintId} hidden>
+            {t('submitHint', { shortcut, action: submitLabel })}
+          </span>
+        ) : null}
+        {capturesTab && keyboardFocus ? (
+          <span
+            aria-hidden="true"
+            data-code-editor-legend=""
+            className="bg-background text-muted-foreground border-border motion-safe:animate-in motion-safe:fade-in pointer-events-none absolute right-2 -bottom-2.5 hidden h-5 items-center gap-2 rounded-sm border px-1.5 text-xs whitespace-nowrap motion-safe:duration-[var(--duration-short)] @min-[16rem]:inline-flex"
+          >
+            {canSubmit ? (
+              <span>
+                {t('legend.submit', { shortcut, action: submitLabel })}
+              </span>
+            ) : null}
+            <span>{t('legend.leave')}</span>
+          </span>
+        ) : null}
+      </div>
+    );
+
+    return (
+      <DisabledReasonTooltip reason={disabledReason} active={softDisabled}>
+        {frame}
+      </DisabledReasonTooltip>
+    );
+  },
+);
+
+/**
+ * What shows while the editor's implementation loads: the value in the
+ * editor's own metrics, so nothing moves when the editor replaces it.
+ */
+function LoadingText({
+  value,
+  placeholder,
+  wraps,
+  font,
+  lineNumbers,
+  minRows,
+  maxRows,
+  fillHeight,
+  loadingLabel,
+}: {
+  value: string;
+  placeholder: string | undefined;
+  wraps: boolean;
+  font: 'mono' | 'prose';
+  lineNumbers: boolean;
+  minRows: number;
+  maxRows: number;
+  fillHeight: boolean;
+  loadingLabel: string;
+}) {
+  const shown = value === '' ? (placeholder ?? '') : value;
+  return (
+    <>
+      <pre
+        aria-hidden="true"
+        data-code-editor-loading=""
+        className={cn(
+          'm-0 box-border overflow-auto py-2 pr-3 leading-[1.6]',
+          lineNumbers ? 'pl-[3.25rem]' : 'pl-3',
+          font === 'prose' ? 'font-sans' : 'font-mono',
+          wraps ? 'break-words whitespace-pre-wrap' : 'whitespace-pre',
+          value === '' && 'text-muted-foreground',
+          fillHeight && 'h-full min-h-0',
+        )}
+        style={{
+          minHeight: `calc(${minRows} * 1.6em + 1rem)`,
+          ...(fillHeight
+            ? {}
+            : { maxHeight: `calc(${maxRows} * 1.6em + 1rem)` }),
+        }}
+      >
+        {/* A trailing line break opens an empty last line in the editor. */}
+        {shown.endsWith('\n') ? `${shown} ` : shown}
+      </pre>
+      <span className="sr-only">{loadingLabel}</span>
+    </>
+  );
+}
+
+/**
+ * Edit code, JSON, YAML, Markdown prompts and `{{ js }}` templates. Put it
+ * in a `Field`: the label names it (`aria-labelledby`), the field's problems
+ * describe it.
+ */
+export const CodeEditor: ForwardRefExoticComponent<
+  CodeEditorProps & RefAttributes<CodeEditorHandle>
+> & { fieldLabelling: 'labelledby' } = Object.assign(CodeEditorBase, {
+  fieldLabelling: 'labelledby' as const,
+});
diff --git a/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts b/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
new file mode 100644
index 0000000000..fc24985a90
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
@@ -0,0 +1,250 @@
+import { highlightTree } from '@lezer/highlight';
+import { describe, expect, it } from 'vitest';
+
+import {
+  codeRoleOfColor,
+  type CodeLanguage,
+  type CodeRole,
+} from '../../../lib/code-roles';
+import { highlightCode, shikiLanguageFor } from '../../../markdown/shiki';
+import { codeRoleHighlighter } from './extensions/highlight';
+import { codeLanguage, templatesOn } from './extensions/languages';
+import { memberObjectRanges } from './extensions/member-objects';
+
+/**
+ * The editor and the read-only blocks must colour the same text the same
+ * way: a value should not change colour when a reader switches from the
+ * Source view to the field that edits it. This test highlights fixtures with
+ * both — CodeMirror's Lezer grammars through the editor's role table, Shiki's
+ * TextMate grammars through the css-variables theme — and compares the role
+ * of every visible character.
+ *
+ * The grammars differ in granularity in a few known places; each is listed
+ * in `ALLOWED` with the reason. The list may only shrink: a new difference
+ * fails here, and is fixed in the role table or the editor's style tags
+ * (`extensions/language-styles.ts`) unless it is one more instance of a
+ * listed grammar gap.
+ */
+
+interface Fixture {
+  name: string;
+  language: CodeLanguage;
+  templates?: boolean;
+  text: string;
+}
+
+const FIXTURES: Fixture[] = [
+  {
+    name: 'a transform body',
+    language: 'javascript',
+    text: [
+      '// Count the open issues per label.',
+      'const counts = {};',
+      'for (const issue of input.issues) {',
+      '  const label = issue.labels[0] ?? "none";',
+      '  counts[label] = (counts[label] ?? 0) + 1;',
+      '}',
+      'const top = input.items.filter((item) => item.score > 5).length;',
+      'return { counts, total: nodes.score.output.total, ok: true };',
+    ].join('\n'),
+  },
+  {
+    name: 'a condition',
+    language: 'expression',
+    text: 'nodes.score.output.total > 1000 && input.mode === "fast"',
+  },
+  {
+    name: 'a connector input with templates',
+    language: 'json',
+    templates: true,
+    text: [
+      '{',
+      '  "to": "{{ input.email }}",',
+      '  "subject": "Report for {{ nodes.triage.output.name }}",',
+      '  "limit": 25,',
+      '  "draft": false',
+      '}',
+    ].join('\n'),
+  },
+  {
+    name: 'an automation in YAML',
+    language: 'yaml',
+    templates: true,
+    text: [
+      'name: Triage GitHub issues',
+      'nodes:',
+      '  - id: open_issues',
+      '    type: transform',
+      '    forEach: "{{ nodes.issues.output.issues }}"',
+      '    prompt: Score {{ item.title }} for urgency',
+      '    code: |',
+      '      return input.items.length;',
+    ].join('\n'),
+  },
+  {
+    name: 'a prompt in Markdown with templates',
+    language: 'markdown',
+    templates: true,
+    text: [
+      '# Daily report',
+      '',
+      'Summarise **{{ nodes.report.output.count }}** issues for',
+      '{{ input.owner }}. Keep it *short*.',
+    ].join('\n'),
+  },
+  {
+    name: 'a template holding the closer in a string',
+    language: 'template',
+    text: 'Reply {{ "}}" }} to them',
+  },
+  {
+    name: 'a template holding an object literal',
+    language: 'template',
+    text: 'Pass {{ ({ a: { b: 1 } }) }} on',
+  },
+];
+
+/**
+ * Known differences: a fixture, the exact text of the token, and the two
+ * roles. Every entry names its reason.
+ */
+const ALLOWED: ReadonlyArray<{
+  token: string;
+  editor: CodeRole;
+  readOnly: CodeRole;
+  reason: string;
+}> = [
+  {
+    token: 'length',
+    editor: 'foreground',
+    readOnly: 'constant',
+    reason:
+      "TextMate knows JavaScript's built-in properties (`support.variable.property`); Lezer sees a property name like any other",
+  },
+  {
+    token: '.',
+    editor: 'foreground',
+    readOnly: 'function',
+    reason:
+      'TextMate scopes the whole callee of a method call as `meta.function-call`, the dots of `input.items.filter(` included',
+  },
+];
+
+type RoleRun = Array<CodeRole | null>;
+
+/** The editor's role of every character (`null` for whitespace). */
+function editorRoles(fixture: Fixture): RoleRun {
+  const language = codeLanguage(
+    fixture.language,
+    templatesOn(fixture.language, fixture.templates ?? false),
+  );
+  // One entry per UTF-16 unit, the offsets the syntax tree uses.
+  const roles: RoleRun = fixture.text
+    .split('')
+    .map((c) => (/\s/.test(c) ? null : 'foreground'));
+  if (language === null) return roles;
+  const tree = language.parser.parse(fixture.text);
+  highlightTree(tree, codeRoleHighlighter, (from, to, classes) => {
+    const role = classes.split(' ').at(-1)?.replace('role-', '') as CodeRole;
+    for (let i = from; i < to; i++) {
+      if (roles[i] !== null) roles[i] = role;
+    }
+  });
+  // The editor marks the object of each dot access from the tree.
+  for (const [from, to] of memberObjectRanges(tree)) {
+    for (let i = from; i < to; i++) roles[i] = 'constant';
+  }
+  return roles;
+}
+
+/** Shiki's role of every character, read from its HTML. */
+async function readOnlyRoles(fixture: Fixture): Promise<RoleRun> {
+  const result = await highlightCode(
+    fixture.text,
+    shikiLanguageFor(fixture.language, fixture.templates ?? false),
+  );
+  if (result === null) throw new Error(`no highlight for ${fixture.name}`);
+  const doc = new DOMParser().parseFromString(result.html, 'text/html');
+  const roles: RoleRun = [];
+  const lines = doc.querySelectorAll('.line');
+  lines.forEach((line, index) => {
+    if (index > 0) roles.push(null);
+    for (const span of line.querySelectorAll<HTMLElement>(':scope > span')) {
+      const role = codeRoleOfColor(span.style.color) ?? 'foreground';
+      for (const c of span.textContent ?? '') {
+        roles.push(/\s/.test(c) ? null : role);
+      }
+    }
+  });
+  return roles;
+}
+
+interface Difference {
+  token: string;
+  editor: CodeRole;
+  readOnly: CodeRole;
+}
+
+/** Runs of differing characters, as the token text they cover. */
+function differences(
+  text: string,
+  editor: RoleRun,
+  readOnly: RoleRun,
+): Difference[] {
+  const out: Difference[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const a = editor[i];
+    const b = readOnly[i];
+    if (a === null || b === null || a === b) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < text.length && editor[j] === a && readOnly[j] === b) j++;
+    out.push({ token: text.slice(i, j), editor: a, readOnly: b });
+    i = j;
+  }
+  return out;
+}
+
+describe('editor and read-only colours agree', () => {
+  it.each(FIXTURES)('$name', async (fixture) => {
+    const editor = editorRoles(fixture);
+    const readOnly = await readOnlyRoles(fixture);
+    expect(readOnly).toHaveLength(fixture.text.length);
+    const unexplained = differences(fixture.text, editor, readOnly).filter(
+      (difference) =>
+        !ALLOWED.some(
+          (allowed) =>
+            allowed.token === difference.token &&
+            allowed.editor === difference.editor &&
+            allowed.readOnly === difference.readOnly,
+        ),
+    );
+    expect(unexplained).toEqual([]);
+  });
+
+  it('lists no difference that no fixture shows any more', async () => {
+    const seen: Difference[] = [];
+    for (const fixture of FIXTURES) {
+      seen.push(
+        ...differences(
+          fixture.text,
+          editorRoles(fixture),
+          await readOnlyRoles(fixture),
+        ),
+      );
+    }
+    const stale = ALLOWED.filter(
+      (allowed) =>
+        !seen.some(
+          (difference) =>
+            difference.token === allowed.token &&
+            difference.editor === allowed.editor &&
+            difference.readOnly === allowed.readOnly,
+        ),
+    );
+    expect(stale.map((allowed) => allowed.token)).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/deps.test.ts b/packages/ui/src/components/forms/code-editor/deps.test.ts
new file mode 100644
index 0000000000..4b3e7bd39c
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/deps.test.ts
@@ -0,0 +1,62 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The code editor shares CodeMirror with Milkdown (the message editor), so
+ * the lockfile must hold one copy of `@codemirror/state` and
+ * `@codemirror/view`: a second copy breaks the editor at runtime
+ * ("Unrecognized extension value in extension set"). And the package must
+ * not reach for the CodeMirror bundles that pull in what it does not need:
+ * the `codemirror` meta package (a basic setup), `@codemirror/language-data`
+ * (every language CodeMirror knows) and `@codemirror/lang-markdown` (whose
+ * module imports the HTML and CSS languages; Markdown is built from
+ * `@lezer/markdown` instead).
+ */
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..', '..');
+const LOCKFILE = join(PACKAGE_ROOT, '..', '..', 'bun.lock');
+
+const FORBIDDEN = [
+  'codemirror',
+  '@codemirror/language-data',
+  '@codemirror/lang-markdown',
+];
+
+function sources(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) sources(full, out);
+    else if (/\.(ts|tsx)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+describe('CodeMirror dependencies', () => {
+  it.each(['@codemirror/state', '@codemirror/view'])(
+    'the lockfile resolves one copy of %s',
+    (name) => {
+      const lock = readFileSync(LOCKFILE, 'utf8');
+      const escaped = name.replace('/', '\\/');
+      const copies = lock.match(
+        new RegExp(`^\\s*"(?:[^"]*/)?${escaped}": \\["${escaped}@`, 'gm'),
+      );
+      expect(copies).toHaveLength(1);
+    },
+  );
+
+  it('never imports a CodeMirror bundle the editor does not need', () => {
+    const offenders: string[] = [];
+    for (const file of sources(join(PACKAGE_ROOT, 'src'))) {
+      if (file === __filename) continue;
+      const text = readFileSync(file, 'utf8');
+      for (const name of FORBIDDEN) {
+        if (new RegExp(`from '${name}'|import\\('${name}'\\)`).test(text)) {
+          offenders.push(`${relative(PACKAGE_ROOT, file)} imports ${name}`);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/extensions/highlight.ts b/packages/ui/src/components/forms/code-editor/extensions/highlight.ts
new file mode 100644
index 0000000000..f087e4a3b4
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/highlight.ts
@@ -0,0 +1,69 @@
+import { HighlightStyle, syntaxHighlighting } from '@codemirror/language';
+import type { Extension } from '@codemirror/state';
+import { tagHighlighter, type Highlighter, type Tag } from '@lezer/highlight';
+
+import {
+  CODE_FONT_TAGS,
+  CODE_ROLE_TAGS,
+  CODE_ROLES,
+  codeRoleColor,
+} from '../../../../lib/code-roles';
+
+interface TagStyle {
+  color?: string;
+  fontWeight?: string;
+  fontStyle?: string;
+  textDecoration?: string;
+}
+
+/**
+ * One style per tag, colour and type style merged: a highlighter keeps only
+ * the last spec that names a tag, so a link's colour and its underline must
+ * travel together.
+ */
+function tagStyles(): Map<Tag, TagStyle> {
+  const styles = new Map<Tag, TagStyle>();
+  const merge = (tag: Tag, style: TagStyle) => {
+    styles.set(tag, { ...styles.get(tag), ...style });
+  };
+  for (const role of CODE_ROLES) {
+    for (const tag of CODE_ROLE_TAGS[role] ?? []) {
+      merge(tag, { color: codeRoleColor(role) });
+    }
+  }
+  for (const tag of CODE_FONT_TAGS.bold) merge(tag, { fontWeight: '600' });
+  for (const tag of CODE_FONT_TAGS.italic) merge(tag, { fontStyle: 'italic' });
+  for (const tag of CODE_FONT_TAGS.underline) {
+    merge(tag, { textDecoration: 'underline' });
+  }
+  for (const tag of CODE_FONT_TAGS.strikethrough) {
+    merge(tag, { textDecoration: 'line-through' });
+  }
+  // Invalid text is underlined as well as coloured, so it never reads by
+  // colour alone.
+  for (const tag of CODE_ROLE_TAGS.invalid ?? []) {
+    merge(tag, { textDecoration: 'underline dotted' });
+  }
+  return styles;
+}
+
+/** The editor's colours: the `--code-*` palette Shiki reads too. */
+const codeHighlightStyle = HighlightStyle.define(
+  Array.from(tagStyles(), ([tag, style]) => Object.assign({ tag }, style)),
+);
+
+export const codeHighlighting: Extension =
+  syntaxHighlighting(codeHighlightStyle);
+
+/**
+ * The role each tag takes, as `role-<name>` classes — the parity test reads
+ * a highlighted tree through this to compare roles with Shiki's.
+ */
+export const codeRoleHighlighter: Highlighter = tagHighlighter(
+  CODE_ROLES.flatMap((role) => {
+    const tags = CODE_ROLE_TAGS[role];
+    return tags === undefined
+      ? []
+      : [{ tag: [...tags], class: `role-${role}` }];
+  }),
+);
diff --git a/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts b/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
new file mode 100644
index 0000000000..721cef4126
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
@@ -0,0 +1,298 @@
+import { closeCompletion, completionStatus } from '@codemirror/autocomplete';
+import { indentWithTab } from '@codemirror/commands';
+import { closeSearchPanel, searchPanelOpen } from '@codemirror/search';
+import {
+  EditorState,
+  Facet,
+  Prec,
+  Transaction,
+  type Extension,
+  type TransactionSpec,
+} from '@codemirror/state';
+import {
+  EditorView,
+  keymap,
+  ViewPlugin,
+  type PluginValue,
+  type ViewUpdate,
+} from '@codemirror/view';
+
+import { CLAIMS_ESCAPE_ATTRIBUTE } from '../../../overlays/claims-escape';
+
+/**
+ * The editor's keyboard model, so a code field never traps a keyboard user:
+ *
+ * - Tab indents in a multi-line editor; a one-line editor never takes Tab.
+ * - Escape closes what is open (the completion list, a tooltip, the search
+ *   panel); with nothing open it arms "leave" for two seconds and says so —
+ *   Tab then moves focus out (CodeMirror's tab-focus window).
+ * - Mod-Enter submits (and Enter, in a one-line editor).
+ * - Ctrl-M (Shift-Alt-M on a Mac) toggles Tab between indenting and moving
+ *   focus for good, and says which.
+ *
+ * Escape is claimed: while the editor needs it, its root carries
+ * `data-claims-escape` (see `overlays/claims-escape.ts`). A dialog or sheet
+ * hears Escape first — Radix listens on the document in the capture phase —
+ * so the editor takes a claimed Escape earlier still, on the window, and
+ * cancels it: the layer then stays open. The first Escape in a sheet closes
+ * the completion list, the next arms leave, and the third (unclaimed) closes
+ * the sheet.
+ */
+
+export interface KeyboardWords {
+  leaveArmed: string;
+  tabFocusOn: string;
+  tabFocusOff: string;
+}
+
+export interface EscapeClosable {
+  /** Closes the popup if one is open; true when it closed something. */
+  close(view: EditorView): boolean;
+  isOpen(view: EditorView): boolean;
+}
+
+/**
+ * Popups the editor's other extensions open (the problem tooltip, the type
+ * tooltip) register here so Escape closes them and the claim covers them.
+ */
+const escapeClosables = Facet.define<EscapeClosable>();
+
+const NO_WORDS: KeyboardWords = {
+  leaveArmed: '',
+  tabFocusOn: '',
+  tabFocusOff: '',
+};
+
+/** The announcements, read at the moment they are made (the language may change). */
+const keyboardWords = Facet.define<() => KeyboardWords, () => KeyboardWords>({
+  combine: (values) => values[0] ?? (() => NO_WORDS),
+});
+
+const LEAVE_MS = 2000;
+
+const builtInClosables: EscapeClosable[] = [
+  {
+    isOpen: (view) => completionStatus(view.state) !== null,
+    close: (view) => closeCompletion(view),
+  },
+  {
+    isOpen: (view) => searchPanelOpen(view.state),
+    close: (view) => closeSearchPanel(view),
+  },
+];
+
+function closables(view: EditorView): readonly EscapeClosable[] {
+  return [...builtInClosables, ...view.state.facet(escapeClosables)];
+}
+
+class EscapeClaim implements PluginValue {
+  armedUntil = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly view: EditorView) {
+    listenForEscape();
+    this.sync();
+  }
+
+  update(update: ViewUpdate) {
+    if (update.focusChanged && !update.view.hasFocus) this.disarm();
+    this.sync();
+  }
+
+  /** Closes what is open, else arms leave; the event is cancelled either way. */
+  escape(event: KeyboardEvent) {
+    const view = this.view;
+    event.preventDefault();
+    for (const closable of closables(view)) {
+      if (closable.isOpen(view) && closable.close(view)) {
+        this.sync();
+        return;
+      }
+    }
+    view.setTabFocusMode(LEAVE_MS);
+    this.arm();
+    view.dispatch({
+      effects: EditorView.announce.of(
+        view.state.facet(keyboardWords)().leaveArmed,
+      ),
+    });
+  }
+
+  arm() {
+    this.armedUntil = Date.now() + LEAVE_MS;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.armedUntil = 0;
+      this.sync();
+    }, LEAVE_MS);
+    this.sync();
+  }
+
+  disarm() {
+    this.armedUntil = 0;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  get armed(): boolean {
+    return this.armedUntil > Date.now();
+  }
+
+  /** The claim: a popup is open, or the editor has focus and is not leaving. */
+  sync() {
+    const open = closables(this.view).some((c) => c.isOpen(this.view));
+    const claims = open || (this.view.hasFocus && !this.armed);
+    if (claims) this.view.dom.setAttribute(CLAIMS_ESCAPE_ATTRIBUTE, '');
+    else this.view.dom.removeAttribute(CLAIMS_ESCAPE_ATTRIBUTE);
+  }
+
+  destroy() {
+    if (this.timer !== null) clearTimeout(this.timer);
+  }
+}
+
+const escapeClaim = ViewPlugin.fromClass(EscapeClaim);
+
+let escapeListener = false;
+
+/**
+ * One window listener for every editor on the page, in the capture phase so
+ * it runs before any overlay's document listener: an Escape inside an editor
+ * that claims it is the editor's.
+ */
+function listenForEscape(): void {
+  if (escapeListener || typeof window === 'undefined') return;
+  escapeListener = true;
+  window.addEventListener(
+    'keydown',
+    (event) => {
+      if (
+        event.key !== 'Escape' ||
+        event.isComposing ||
+        event.defaultPrevented
+      ) {
+        return;
+      }
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      const root = target.closest<HTMLElement>('.cm-editor');
+      if (root === null || !root.hasAttribute(CLAIMS_ESCAPE_ATTRIBUTE)) return;
+      const view = EditorView.findFromDOM(root);
+      if (view === null || view.composing) return;
+      view.plugin(escapeClaim)?.escape(event);
+    },
+    true,
+  );
+}
+
+const MODIFIER_KEYS = new Set(['Shift', 'Control', 'Alt', 'Meta', 'CapsLock']);
+
+function escapeHandling(words: () => KeyboardWords): Extension {
+  return [
+    keyboardWords.of(words),
+    escapeClaim,
+    EditorView.domEventObservers({
+      keydown(event, view) {
+        // Any other key ends the leave window, as CodeMirror's own does.
+        if (
+          event.key === 'Escape' ||
+          event.key === 'Tab' ||
+          MODIFIER_KEYS.has(event.key)
+        ) {
+          return;
+        }
+        const claim = view.plugin(escapeClaim);
+        claim?.disarm();
+        claim?.sync();
+      },
+      focus(_event, view) {
+        view.plugin(escapeClaim)?.sync();
+      },
+      blur(_event, view) {
+        const claim = view.plugin(escapeClaim);
+        claim?.disarm();
+        claim?.sync();
+      },
+    }),
+  ];
+}
+
+/** Turns line breaks a one-line editor receives (a paste) into spaces. */
+const singleLineFilter = EditorState.transactionFilter.of((tr) => {
+  if (!tr.docChanged || tr.newDoc.lines === 1) return tr;
+  const changes: Array<{ from: number; to: number; insert: string }> = [];
+  tr.changes.iterChanges((fromA, toA, _fromB, _toB, inserted) => {
+    changes.push({
+      from: fromA,
+      to: toA,
+      // The document stores every line break as `\n`; a space keeps the
+      // length, so the selection the transaction set still fits.
+      insert: inserted.toString().replace(/\n/g, ' '),
+    });
+  });
+  const spec: TransactionSpec = {
+    changes,
+    selection: tr.selection,
+    effects: tr.effects,
+    scrollIntoView: tr.scrollIntoView,
+  };
+  const userEvent = tr.annotation(Transaction.userEvent);
+  if (userEvent !== undefined) spec.userEvent = userEvent;
+  return spec;
+});
+
+const permanentTabFocus = new WeakMap<EditorView, boolean>();
+
+export interface KeyboardOptions {
+  singleLine: boolean;
+  /** Reads the current submit handler; null when the field has none. */
+  submit: () => ((view: EditorView) => void) | null;
+  words: () => KeyboardWords;
+}
+
+export function keyboard({
+  singleLine,
+  submit,
+  words,
+}: KeyboardOptions): Extension {
+  const runSubmit = (view: EditorView): boolean => {
+    const handler = submit();
+    if (handler === null) return false;
+    handler(view);
+    return true;
+  };
+  const toggleTabFocus = (view: EditorView): boolean => {
+    const next = !(permanentTabFocus.get(view) ?? false);
+    permanentTabFocus.set(view, next);
+    view.setTabFocusMode(next);
+    view.dispatch({
+      effects: EditorView.announce.of(
+        next ? words().tabFocusOn : words().tabFocusOff,
+      ),
+    });
+    return true;
+  };
+  return [
+    escapeHandling(words),
+    Prec.highest(
+      keymap.of([
+        { key: 'Mod-Enter', run: runSubmit },
+        ...(singleLine
+          ? [
+              {
+                key: 'Enter',
+                run: (view: EditorView) => {
+                  if (completionStatus(view.state) === 'active') return false;
+                  runSubmit(view);
+                  return true;
+                },
+              },
+            ]
+          : []),
+        { key: 'Ctrl-m', mac: 'Shift-Alt-m', run: toggleTabFocus },
+      ]),
+    ),
+    singleLine ? singleLineFilter : keymap.of([indentWithTab]),
+  ];
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/language-styles.ts b/packages/ui/src/components/forms/code-editor/extensions/language-styles.ts
new file mode 100644
index 0000000000..28985d6005
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/language-styles.ts
@@ -0,0 +1,42 @@
+import { styleTags, tags as t } from '@lezer/highlight';
+
+import { codeTags } from '../../../../lib/code-roles';
+
+/**
+ * Style tags the editor adds to the stock grammars so a value takes the
+ * colour the read-only grammars (TextMate, through Shiki) give it. A rule
+ * added here replaces the stock rule for the same node.
+ */
+
+/**
+ * TextMate names a `const` binding `variable.other.constant`; Lezer cannot
+ * tell `const` from `let`, and most bindings in a transform body are `const`.
+ * A statement's `;` is plain text there, a `,` a separator; the `:` of an
+ * object literal and `...` are keywords.
+ */
+export const javascriptStyles = styleTags({
+  'VariableDeclaration/VariableDefinition ForOfSpec/VariableDefinition ForInSpec/VariableDefinition':
+    t.constant(t.variableName),
+  ';': t.punctuation,
+  ': Spread': t.keyword,
+});
+
+/** JSON keys are keywords in the read-only palette (`property-name.json`). */
+export const jsonStyles = styleTags({
+  PropertyName: codeTags.jsonKey,
+});
+
+/**
+ * YAML keys are keywords and so is the `:` after them; a plain or quoted
+ * value is a string expression and a block scalar a string, as TextMate
+ * scopes them.
+ */
+export const yamlStyles = styleTags({
+  'Key/Literal Key/QuotedLiteral': codeTags.yamlKey,
+  Literal: codeTags.yamlValue,
+  QuotedLiteral: codeTags.yamlValue,
+  BlockLiteralContent: codeTags.yamlBlock,
+  BlockLiteralHeader: t.keyword,
+  ':': t.keyword,
+  '-': t.punctuation,
+});
diff --git a/packages/ui/src/components/forms/code-editor/extensions/languages.ts b/packages/ui/src/components/forms/code-editor/extensions/languages.ts
new file mode 100644
index 0000000000..2c4d0f42c8
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/languages.ts
@@ -0,0 +1,233 @@
+import { javascriptLanguage } from '@codemirror/lang-javascript';
+import { jsonLanguage } from '@codemirror/lang-json';
+import { yamlLanguage } from '@codemirror/lang-yaml';
+import {
+  defineLanguageFacet,
+  Language,
+  languageDataProp,
+} from '@codemirror/language';
+import type { Extension } from '@codemirror/state';
+import {
+  parseMixed,
+  type Input,
+  type NestedParse,
+  type SyntaxNodeRef,
+} from '@lezer/common';
+import {
+  GFM,
+  parser as markdownParser,
+  type MarkdownConfig,
+} from '@lezer/markdown';
+
+import { codeTags, type CodeLanguage } from '../../../../lib/code-roles';
+import { scanTemplates } from '../template-scan';
+import { javascriptStyles, jsonStyles, yamlStyles } from './language-styles';
+import {
+  expressionParser,
+  templateLanguage,
+  templateOverlay,
+  type TemplateScanner,
+} from './template/parser';
+
+/**
+ * The language a code field is parsed as, for highlighting, bracket
+ * matching, completion and syntax marks:
+ *
+ * - `javascript` — a script (a transform's body; a top-level `return` parses);
+ * - `expression` — one expression (a condition);
+ * - `json`, `yaml` — with `templates`, the `{{ js }}` inside string values
+ *   are parsed as JavaScript; keys never hold templates;
+ * - `markdown` — GitHub-flavoured Markdown, highlighting only; with
+ *   `templates`, a template is one inline element (so `{{ a * b }}` is never
+ *   emphasis) and templates in code spans and fenced code count too, as the
+ *   engine interpolates there;
+ * - `template` — text with templates; `text` — plain text, or text with
+ *   templates when `templates` is on.
+ */
+
+const javascript = javascriptLanguage.configure({ props: [javascriptStyles] });
+
+const expression = javascriptLanguage.configure(
+  { top: 'SingleExpression', props: [javascriptStyles] },
+  'expression',
+);
+
+function jsonWith(scanner: TemplateScanner | null): Language {
+  if (scanner === null) return jsonLanguage.configure({ props: [jsonStyles] });
+  return jsonLanguage.configure({
+    props: [jsonStyles],
+    wrap: parseMixed((node: SyntaxNodeRef, input: Input) =>
+      node.name === 'String'
+        ? templateOverlay(input, node.from + 1, node.to - 1, scanner)
+        : null,
+    ),
+  });
+}
+
+function yamlWith(scanner: TemplateScanner | null): Language {
+  if (scanner === null) return yamlLanguage.configure({ props: [yamlStyles] });
+  return yamlLanguage.configure({
+    props: [yamlStyles],
+    wrap: parseMixed(
+      (node: SyntaxNodeRef, input: Input): NestedParse | null => {
+        if (node.name === 'Literal' || node.name === 'QuotedLiteral') {
+          if (node.node.parent?.name === 'Key') return null;
+          return node.name === 'QuotedLiteral'
+            ? templateOverlay(input, node.from + 1, node.to - 1, scanner)
+            : templateOverlay(input, node.from, node.to, scanner);
+        }
+        if (node.name === 'BlockLiteralContent') {
+          return templateOverlay(input, node.from, node.to, scanner);
+        }
+        return null;
+      },
+    ),
+  });
+}
+
+/** Prose: only `{` auto-closes (for `{{`); `<!-- -->` comments a line. */
+const markdownData = defineLanguageFacet({
+  closeBrackets: { brackets: ['{'] },
+  commentTokens: { block: { open: '<!--', close: '-->' } },
+});
+
+/** A `{{ … }}` is one inline element, parsed before emphasis. */
+function templateInline(scanner: TemplateScanner): MarkdownConfig {
+  return {
+    defineNodes: [
+      { name: 'Template' },
+      { name: 'TemplateBrace', style: codeTags.templateBrace },
+      { name: 'TemplateBody' },
+      { name: 'TemplateUnterminated', style: codeTags.templateUnterminated },
+    ],
+    parseInline: [
+      {
+        name: 'Template',
+        before: 'Emphasis',
+        parse(cx, next, pos) {
+          if (next !== 123 || cx.char(pos + 1) !== 123) return -1;
+          const { spans, unterminated } = scanner(cx.slice(pos, cx.end));
+          const span = spans[0];
+          if (span !== undefined && span.open === 0) {
+            return cx.addElement(
+              cx.elt('Template', pos, pos + span.end, [
+                cx.elt('TemplateBrace', pos, pos + span.bodyFrom),
+                cx.elt('TemplateBody', pos + span.bodyFrom, pos + span.bodyTo),
+                cx.elt('TemplateBrace', pos + span.bodyTo, pos + span.end),
+              ]),
+            );
+          }
+          if (unterminated[0]?.[0] === 0) {
+            return cx.addElement(cx.elt('TemplateUnterminated', pos, pos + 2));
+          }
+          return -1;
+        },
+      },
+    ],
+  };
+}
+
+function markdownWith(scanner: TemplateScanner | null): Language {
+  const base = {
+    props: [languageDataProp.add({ Document: markdownData })],
+  };
+  if (scanner === null) {
+    return new Language(
+      markdownData,
+      markdownParser.configure([GFM, base]),
+      [],
+      'markdown',
+    );
+  }
+  return new Language(
+    markdownData,
+    markdownParser.configure([
+      GFM,
+      templateInline(scanner),
+      {
+        ...base,
+        wrap: parseMixed(
+          (node: SyntaxNodeRef, input: Input): NestedParse | null => {
+            if (node.name === 'TemplateBody')
+              return { parser: expressionParser };
+            if (node.name === 'CodeText') {
+              return templateOverlay(input, node.from, node.to, scanner);
+            }
+            return null;
+          },
+        ),
+      },
+    ]),
+    [],
+    'markdown',
+  );
+}
+
+const cache = new WeakMap<TemplateScanner, Map<string, Language | null>>();
+
+/**
+ * The parser for a field. `null` for plain text: no language, no tree.
+ * Built once per language, template mode and scanner.
+ */
+export function codeLanguage(
+  language: CodeLanguage,
+  templates: boolean,
+  scanner: TemplateScanner = scanTemplates,
+): Language | null {
+  let byKey = cache.get(scanner);
+  if (byKey === undefined) {
+    byKey = new Map();
+    cache.set(scanner, byKey);
+  }
+  const key = `${language}:${templates}`;
+  if (byKey.has(key)) return byKey.get(key) ?? null;
+  const withTemplates = templates ? scanner : null;
+  let built: Language | null;
+  switch (language) {
+    case 'javascript':
+      built = javascript;
+      break;
+    case 'expression':
+      built = expression;
+      break;
+    case 'json':
+      built = jsonWith(withTemplates);
+      break;
+    case 'yaml':
+      built = yamlWith(withTemplates);
+      break;
+    case 'markdown':
+      built = markdownWith(withTemplates);
+      break;
+    case 'template':
+      built = templateLanguage(scanner);
+      break;
+    case 'text':
+      built = templates ? templateLanguage(scanner) : null;
+      break;
+  }
+  byKey.set(key, built);
+  return built;
+}
+
+/** Whether `{{ }}` templates are live in a field. */
+export function templatesOn(
+  language: CodeLanguage,
+  templates: boolean,
+): boolean {
+  if (language === 'template') return true;
+  if (language === 'javascript' || language === 'expression') return false;
+  return templates;
+}
+
+/** The language extension, or nothing for plain text. */
+export function languageExtension(
+  language: CodeLanguage,
+  templates: boolean,
+  scanner?: TemplateScanner,
+): Extension {
+  return (
+    codeLanguage(language, templatesOn(language, templates), scanner)
+      ?.extension ?? []
+  );
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/member-objects.ts b/packages/ui/src/components/forms/code-editor/extensions/member-objects.ts
new file mode 100644
index 0000000000..dd9cb69aa4
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/member-objects.ts
@@ -0,0 +1,85 @@
+import { syntaxTree } from '@codemirror/language';
+import { RangeSetBuilder, type Extension } from '@codemirror/state';
+import {
+  Decoration,
+  ViewPlugin,
+  type DecorationSet,
+  type EditorView,
+  type ViewUpdate,
+} from '@codemirror/view';
+import type { SyntaxNode, Tree } from '@lezer/common';
+
+import { walkTree } from './tree-walk';
+
+/**
+ * The object of every dot access — the `nodes`, `score` and `output` of
+ * `nodes.score.output.total`, the `input` of `input?.items` — in document
+ * order. The read-only grammars (TextMate) colour these as constants
+ * (`variable.other.object`) and the last property as text; a style tag
+ * cannot tell a dot access from `counts[label]`, so the editor marks them
+ * here, from the tree.
+ */
+export function memberObjectRanges(
+  tree: Tree,
+  from = 0,
+  to = tree.length,
+): Array<[number, number]> {
+  const ranges: Array<[number, number]> = [];
+  walkTree(tree, from, to, (node, offset) => {
+    if (node.name !== 'MemberExpression') return;
+    const name = objectName(node);
+    if (name !== null) ranges.push([offset + name.from, offset + name.to]);
+  });
+  return ranges.sort((a, b) => a[0] - b[0]);
+}
+
+function objectName(node: SyntaxNode): SyntaxNode | null {
+  const object = node.firstChild;
+  const access = object?.nextSibling;
+  if (object === null || object === undefined) return null;
+  if (access?.name !== '.' && access?.name !== '?.') return null;
+  if (object.name === 'VariableName') return object;
+  if (object.name === 'MemberExpression') {
+    const last = object.lastChild;
+    if (last?.name === 'PropertyName') return last;
+  }
+  return null;
+}
+
+const objectMark = Decoration.mark({ class: 'cm-tale-object' });
+
+function build(view: EditorView): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  const tree = syntaxTree(view.state);
+  let last = -1;
+  for (const { from, to } of view.visibleRanges) {
+    for (const [start, end] of memberObjectRanges(tree, from, to)) {
+      if (start < last) continue;
+      builder.add(start, end, objectMark);
+      last = end;
+    }
+  }
+  return builder.finish();
+}
+
+/** Colours the object of each dot access as a constant. */
+export const memberObjects: Extension = ViewPlugin.fromClass(
+  class {
+    decorations: DecorationSet;
+
+    constructor(view: EditorView) {
+      this.decorations = build(view);
+    }
+
+    update(update: ViewUpdate) {
+      if (
+        update.docChanged ||
+        update.viewportChanged ||
+        syntaxTree(update.startState) !== syntaxTree(update.state)
+      ) {
+        this.decorations = build(update.view);
+      }
+    }
+  },
+  { decorations: (plugin) => plugin.decorations },
+);
diff --git a/packages/ui/src/components/forms/code-editor/extensions/phrases.ts b/packages/ui/src/components/forms/code-editor/extensions/phrases.ts
new file mode 100644
index 0000000000..fb3fc4dafa
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/phrases.ts
@@ -0,0 +1,40 @@
+import type { TFunction } from 'i18next';
+
+/**
+ * CodeMirror's own words (the completion list's name, the search panel,
+ * fold markers, screen-reader announcements) in the reader's language,
+ * keyed by the English phrase CodeMirror asks for. `$` stays: CodeMirror
+ * puts a number there. `phrases.test.ts` fails when an upgrade brings a
+ * phrase this list does not translate.
+ */
+export function editorPhrases(t: TFunction): Record<string, string> {
+  return {
+    'Control character': t('phrases.controlCharacter'),
+    close: t('phrases.close'),
+    'Selection deleted': t('phrases.selectionDeleted'),
+    'folded code': t('phrases.foldedCode'),
+    unfold: t('phrases.unfold'),
+    to: t('phrases.to'),
+    'Folded lines': t('phrases.foldedLines'),
+    'Unfolded lines': t('phrases.unfoldedLines'),
+    'Fold line': t('phrases.foldLine'),
+    'Unfold line': t('phrases.unfoldLine'),
+    Completions: t('phrases.completions'),
+    Find: t('phrases.find'),
+    Replace: t('phrases.replaceField'),
+    next: t('phrases.next'),
+    previous: t('phrases.previous'),
+    all: t('phrases.all'),
+    'match case': t('phrases.matchCase'),
+    regexp: t('phrases.regexp'),
+    'by word': t('phrases.byWord'),
+    replace: t('phrases.replace'),
+    'replace all': t('phrases.replaceAll'),
+    'Go to line': t('phrases.goToLine'),
+    go: t('phrases.go'),
+    'current match': t('phrases.currentMatch'),
+    'on line': t('phrases.onLine'),
+    'replaced $ matches': t('phrases.replacedMatches'),
+    'replaced match on line $': t('phrases.replacedMatchOnLine'),
+  };
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/template/chips.ts b/packages/ui/src/components/forms/code-editor/extensions/template/chips.ts
new file mode 100644
index 0000000000..2d8a802c56
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/template/chips.ts
@@ -0,0 +1,70 @@
+import { syntaxTree } from '@codemirror/language';
+import type { EditorState, Extension } from '@codemirror/state';
+import {
+  Decoration,
+  ViewPlugin,
+  type DecorationSet,
+  type EditorView,
+  type ViewUpdate,
+} from '@codemirror/view';
+
+import { walkTree } from '../tree-walk';
+
+/**
+ * Every `{{ … }}` template in `[from, to)`, as document ranges in order —
+ * top-level ones, the ones in a Markdown paragraph, and the ones overlaid on
+ * a JSON or YAML string.
+ */
+function templateRanges(
+  state: EditorState,
+  from = 0,
+  to = state.doc.length,
+): Array<[number, number]> {
+  const ranges: Array<[number, number]> = [];
+  walkTree(syntaxTree(state), from, to, (node, offset) => {
+    if (node.name === 'Template') {
+      ranges.push([offset + node.from, offset + node.to]);
+    }
+  });
+  return ranges.sort((a, b) => a[0] - b[0]);
+}
+
+const chip = Decoration.mark({ class: 'cm-template' });
+
+function build(view: EditorView): DecorationSet {
+  const marks = [];
+  let last = -1;
+  for (const { from, to } of view.visibleRanges) {
+    for (const [start, end] of templateRanges(view.state, from, to)) {
+      if (start < last || end <= start) continue;
+      marks.push(chip.range(start, end));
+      last = end;
+    }
+  }
+  return Decoration.set(marks, true);
+}
+
+/**
+ * Draws each template as one tinted chip, so an expression reads as a unit
+ * inside prose or a string.
+ */
+export const templateChips: Extension = ViewPlugin.fromClass(
+  class {
+    decorations: DecorationSet;
+
+    constructor(view: EditorView) {
+      this.decorations = build(view);
+    }
+
+    update(update: ViewUpdate) {
+      if (
+        update.docChanged ||
+        update.viewportChanged ||
+        syntaxTree(update.startState) !== syntaxTree(update.state)
+      ) {
+        this.decorations = build(update.view);
+      }
+    }
+  },
+  { decorations: (plugin) => plugin.decorations },
+);
diff --git a/packages/ui/src/components/forms/code-editor/extensions/template/input.ts b/packages/ui/src/components/forms/code-editor/extensions/template/input.ts
new file mode 100644
index 0000000000..69e4f83e58
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/template/input.ts
@@ -0,0 +1,135 @@
+import { startCompletion } from '@codemirror/autocomplete';
+import { syntaxTree } from '@codemirror/language';
+import {
+  EditorSelection,
+  Prec,
+  type EditorState,
+  type Extension,
+} from '@codemirror/state';
+import { EditorView, keymap } from '@codemirror/view';
+import type { SyntaxNode } from '@lezer/common';
+
+import type { CodeLanguage } from '../../../../../lib/code-roles';
+
+/**
+ * Typing a template: `{` after `{` becomes `{{ | }}` with the caret inside
+ * and completion open; `}` in front of the closing `}}` steps over it;
+ * Backspace in an empty `{{ | }}` removes the pair. Each is one undo step.
+ */
+
+/** Node names that hold text a template may sit in, per language. */
+const STRINGS: Partial<Record<CodeLanguage, ReadonlySet<string>>> = {
+  json: new Set(['String']),
+  yaml: new Set(['Literal', 'QuotedLiteral', 'BlockLiteralContent']),
+};
+
+const TEMPLATE_NODES = new Set(['Template', 'TemplateUnterminated']);
+
+/** Whether a template may start at `pos`: text, not code, not a key. */
+function canOpenAt(
+  state: EditorState,
+  pos: number,
+  language: CodeLanguage,
+): boolean {
+  const strings = STRINGS[language];
+  let inString = strings === undefined;
+  for (
+    let node: SyntaxNode | null = syntaxTree(state).resolveInner(pos, -1);
+    node !== null;
+    node = node.parent
+  ) {
+    if (node.name === 'TemplateBody') return false;
+    if (node.name === 'Key' || node.name === 'PropertyName') return false;
+    if (TEMPLATE_NODES.has(node.name)) inString = true;
+    if (strings?.has(node.name)) inString = true;
+  }
+  return inString;
+}
+
+function inTemplate(state: EditorState, pos: number): boolean {
+  for (
+    let node: SyntaxNode | null = syntaxTree(state).resolveInner(pos, -1);
+    node !== null;
+    node = node.parent
+  ) {
+    if (node.name === 'Template' || node.name === 'TemplateBody') return true;
+  }
+  return false;
+}
+
+function openTemplate(view: EditorView, at: number): boolean {
+  const { state } = view;
+  const doc = state.doc;
+  const closed = doc.sliceString(at, at + 1) === '}';
+  const replaceTo = closed ? at + 1 : at;
+  view.dispatch(
+    state.update({
+      changes: { from: at - 1, to: replaceTo, insert: '{{  }}' },
+      selection: EditorSelection.cursor(at - 1 + 3),
+      scrollIntoView: true,
+      userEvent: 'input.type',
+    }),
+  );
+  startCompletion(view);
+  return true;
+}
+
+export function templateInput(language: CodeLanguage): Extension {
+  return [
+    Prec.highest(
+      EditorView.inputHandler.of((view, from, to, text) => {
+        if (view.state.readOnly || from !== to) return false;
+        const doc = view.state.doc;
+        if (text === '{') {
+          if (doc.sliceString(from - 1, from) !== '{') return false;
+          if (doc.sliceString(from - 2, from - 1) === '{') return false;
+          if (!canOpenAt(view.state, from - 1, language)) return false;
+          return openTemplate(view, from);
+        }
+        if (text === '}' && inTemplate(view.state, from)) {
+          // In front of ` }}`, land between the braces; in front of the
+          // last `}`, step over it.
+          const skip =
+            doc.sliceString(from, from + 3) === ' }}'
+              ? 2
+              : doc.sliceString(from, from + 1) === '}'
+                ? 1
+                : 0;
+          if (skip === 0) return false;
+          view.dispatch({
+            selection: EditorSelection.cursor(from + skip),
+            scrollIntoView: true,
+            userEvent: 'select',
+          });
+          return true;
+        }
+        return false;
+      }),
+    ),
+    Prec.high(
+      keymap.of([
+        {
+          key: 'Backspace',
+          run: (view) => {
+            const range = view.state.selection.main;
+            if (!range.empty || view.state.readOnly) return false;
+            const pos = range.head;
+            const doc = view.state.doc;
+            const pair =
+              doc.sliceString(pos - 3, pos + 3) === '{{  }}'
+                ? 3
+                : doc.sliceString(pos - 2, pos + 2) === '{{}}'
+                  ? 2
+                  : 0;
+            if (pair === 0) return false;
+            view.dispatch({
+              changes: { from: pos - pair, to: pos + pair },
+              userEvent: 'delete.backward',
+            });
+            return true;
+          },
+        },
+      ]),
+    ),
+  ];
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/template/parser.ts b/packages/ui/src/components/forms/code-editor/extensions/template/parser.ts
new file mode 100644
index 0000000000..97c432152b
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/template/parser.ts
@@ -0,0 +1,229 @@
+import { javascriptLanguage } from '@codemirror/lang-javascript';
+import {
+  defineLanguageFacet,
+  Language,
+  languageDataProp,
+} from '@codemirror/language';
+import {
+  NodeSet,
+  NodeType,
+  parseMixed,
+  Parser,
+  Tree,
+  type Input,
+  type NestedParse,
+  type ParseWrapper,
+  type PartialParse,
+  type SyntaxNodeRef,
+  type TreeFragment,
+} from '@lezer/common';
+import { styleTags } from '@lezer/highlight';
+
+import { codeTags } from '../../../../../lib/code-roles';
+import { scanTemplates, type TemplateScan } from '../../template-scan';
+import { javascriptStyles } from '../language-styles';
+
+export type TemplateScanner = (text: string) => TemplateScan;
+
+/**
+ * Language data for text with templates: only `{` auto-closes, so the
+ * smart-brace input can turn `{{` into `{{ | }}` while prose quotes and
+ * parentheses type as written.
+ */
+const templateLanguageData = defineLanguageFacet({
+  closeBrackets: { brackets: ['{'] },
+});
+
+/** A template's body: one JavaScript expression (Lezer's `SingleExpression`). */
+export const expressionParser = javascriptLanguage.parser.configure({
+  top: 'SingleExpression',
+  props: [javascriptStyles],
+});
+
+const NODE_NAMES = [
+  'TemplateDocument',
+  'Template',
+  'TemplateBrace',
+  'TemplateBody',
+  'TemplateUnterminated',
+] as const;
+
+type NodeName = (typeof NODE_NAMES)[number];
+
+const nodeSet = new NodeSet(
+  NODE_NAMES.map((name, id) =>
+    NodeType.define({
+      id,
+      name,
+      top: id === 0,
+      props: id === 0 ? [[languageDataProp, templateLanguageData]] : [],
+    }),
+  ),
+).extend(
+  styleTags({
+    TemplateBrace: codeTags.templateBrace,
+    TemplateUnterminated: codeTags.templateUnterminated,
+  }),
+);
+
+function type(name: NodeName): NodeType {
+  return nodeSet.types[NODE_NAMES.indexOf(name)];
+}
+
+function leaf(name: NodeName, length: number): Tree {
+  return new Tree(type(name), [], [], length);
+}
+
+/** The JavaScript under every template's body. */
+const nestBodies: ParseWrapper = parseMixed(
+  (node: SyntaxNodeRef): NestedParse | null =>
+    node.name === 'TemplateBody' ? { parser: expressionParser } : null,
+);
+
+/**
+ * Reads the parsed ranges as one string, with whatever lies between two
+ * ranges blanked out: a template never starts in a gap, and offsets stay
+ * the document's minus the first range's start.
+ */
+function readRanges(
+  input: Input,
+  ranges: ReadonlyArray<{ from: number; to: number }>,
+): string {
+  const base = ranges[0].from;
+  let text = '';
+  for (const range of ranges) {
+    text += ' '.repeat(range.from - base - text.length);
+    text += input.read(range.from, range.to);
+  }
+  return text;
+}
+
+class TemplateParse implements PartialParse {
+  parsedPos: number;
+  stoppedAt: number | null = null;
+
+  constructor(
+    private readonly input: Input,
+    private readonly ranges: ReadonlyArray<{ from: number; to: number }>,
+    private readonly scanner: TemplateScanner,
+  ) {
+    this.parsedPos = ranges[0].from;
+  }
+
+  advance(): Tree {
+    const text = readRanges(this.input, this.ranges);
+    const { spans, unterminated } = this.scanner(text);
+    const nodes: Array<[number, Tree]> = [];
+    for (const span of spans) {
+      const body = span.bodyTo - span.bodyFrom;
+      nodes.push([
+        span.open,
+        new Tree(
+          type('Template'),
+          [
+            leaf('TemplateBrace', span.bodyFrom - span.open),
+            leaf('TemplateBody', body),
+            leaf('TemplateBrace', span.end - span.bodyTo),
+          ],
+          [0, span.bodyFrom - span.open, span.bodyTo - span.open],
+          span.end - span.open,
+        ),
+      ]);
+    }
+    for (const [from, to] of unterminated) {
+      nodes.push([from, leaf('TemplateUnterminated', to - from)]);
+    }
+    nodes.sort((a, b) => a[0] - b[0]);
+    this.parsedPos = this.ranges[this.ranges.length - 1].to;
+    return new Tree(
+      type('TemplateDocument'),
+      nodes.map(([, tree]) => tree),
+      nodes.map(([from]) => from),
+      text.length,
+    );
+  }
+
+  stopAt(pos: number): void {
+    this.stoppedAt = pos;
+  }
+}
+
+/** Text with `{{ js }}` templates in it. */
+class TemplateParser extends Parser {
+  constructor(private readonly scanner: TemplateScanner) {
+    super();
+  }
+
+  createParse(
+    input: Input,
+    fragments: readonly TreeFragment[],
+    ranges: readonly { from: number; to: number }[],
+  ): PartialParse {
+    return nestBodies(
+      new TemplateParse(input, ranges, this.scanner),
+      input,
+      fragments,
+      ranges,
+    );
+  }
+}
+
+const parsers = new WeakMap<TemplateScanner, TemplateParser>();
+
+/** One parser per scanner, so a language built twice shares its trees. */
+function templateParser(
+  scanner: TemplateScanner = scanTemplates,
+): TemplateParser {
+  let parser = parsers.get(scanner);
+  if (parser === undefined) {
+    parser = new TemplateParser(scanner);
+    parsers.set(scanner, parser);
+  }
+  return parser;
+}
+
+const languages = new WeakMap<TemplateScanner, Language>();
+
+/** The whole field is text with templates (`template`, `text` + templates). */
+export function templateLanguage(
+  scanner: TemplateScanner = scanTemplates,
+): Language {
+  let language = languages.get(scanner);
+  if (language === undefined) {
+    language = new Language(
+      templateLanguageData,
+      templateParser(scanner),
+      [],
+      'template',
+    );
+    languages.set(scanner, language);
+  }
+  return language;
+}
+
+/**
+ * The overlay that lays a field's templates over a string value in JSON,
+ * YAML or Markdown code: only the `{{ … }}` spans themselves (and any
+ * unclosed `{{`), so the text around them keeps its string colour. `null`
+ * when the content holds no `{{`.
+ */
+export function templateOverlay(
+  input: Input,
+  from: number,
+  to: number,
+  scanner: TemplateScanner,
+): NestedParse | null {
+  if (to <= from) return null;
+  const text = input.read(from, to);
+  if (!text.includes('{{')) return null;
+  const { spans, unterminated } = scanner(text);
+  const ranges = [
+    ...spans.map((span) => ({ from: from + span.open, to: from + span.end })),
+    ...unterminated.map(([start, end]) => ({
+      from: from + start,
+      to: from + end,
+    })),
+  ].sort((a, b) => a.from - b.from);
+  if (ranges.length === 0) return null;
+  return { parser: templateParser(scanner), overlay: ranges };
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/theme.ts b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
new file mode 100644
index 0000000000..5246718999
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
@@ -0,0 +1,174 @@
+import { EditorView } from '@codemirror/view';
+
+/**
+ * The editor's chrome, all through CSS variables (`--code-*` and the app's
+ * tokens), so one theme serves light and dark. Sizes come from the frame:
+ * the font size is inherited (`text-base md:text-xs` or `md:text-sm`), a
+ * line is 1.6 em like a read-only code block, and the frame sets
+ * `--ce-min-rows` / `--ce-max-rows`.
+ */
+export const codeEditorTheme = EditorView.theme({
+  '&': {
+    color: 'var(--code-foreground)',
+    backgroundColor: 'transparent',
+    fontSize: 'inherit',
+    borderRadius: 'inherit',
+  },
+  '&.cm-focused': { outline: 'none' },
+  '.cm-scroller': {
+    fontFamily: 'var(--font-mono)',
+    lineHeight: '1.6',
+    overflow: 'auto',
+    overscrollBehavior: 'contain',
+    maxHeight: 'calc(var(--ce-max-rows, 14) * 1.6em + 1rem)',
+    borderRadius: 'inherit',
+  },
+  '&.cm-fill': { height: '100%' },
+  '&.cm-fill .cm-scroller': { maxHeight: 'none', height: '100%' },
+  '&.cm-prose .cm-scroller': { fontFamily: 'var(--font-sans)' },
+  '.cm-content': {
+    padding: '0.5rem 0',
+    minHeight: 'calc(var(--ce-min-rows, 3) * 1.6em + 1rem)',
+    caretColor: 'var(--code-foreground)',
+  },
+  '.cm-line': { padding: '0 0.75rem' },
+  '.cm-placeholder': { color: 'hsl(var(--muted-foreground))' },
+  '.cm-cursor, .cm-dropCursor': { borderLeftColor: 'var(--code-foreground)' },
+  '&.cm-readonly .cm-cursor': { display: 'none' },
+  '.cm-selectionLayer .cm-selectionBackground': {
+    background: 'var(--code-selection-inactive)',
+  },
+  '&.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground': {
+    background: 'var(--code-selection)',
+  },
+  '.cm-activeLine': { backgroundColor: 'transparent' },
+  '&.cm-focused:not(.cm-readonly) .cm-activeLine': {
+    backgroundColor: 'var(--code-active-line)',
+  },
+  '.cm-gutters': {
+    backgroundColor: 'transparent',
+    border: 'none',
+    color: 'var(--code-line-number)',
+  },
+  '.cm-gutterElement': { userSelect: 'none' },
+  '.cm-lineNumbers .cm-gutterElement': {
+    minWidth: '1.75rem',
+    padding: '0 0 0 0.75rem',
+    textAlign: 'right',
+  },
+  '.cm-activeLineGutter': { backgroundColor: 'transparent' },
+  '&.cm-focused .cm-activeLineGutter': {
+    color: 'var(--code-line-number-active)',
+  },
+  '.cm-foldGutter .cm-gutterElement': {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: '0 0.125rem',
+    color: 'hsl(var(--muted-foreground))',
+  },
+  '.cm-foldGutter .cm-fold-open': { opacity: '0' },
+  '.cm-gutters:hover .cm-foldGutter .cm-fold-open, .cm-foldGutter .cm-fold-open:focus-visible':
+    { opacity: '1' },
+  '.cm-foldPlaceholder': {
+    backgroundColor: 'hsl(var(--muted))',
+    border: '1px solid hsl(var(--border))',
+    color: 'hsl(var(--muted-foreground))',
+    borderRadius: '0.25rem',
+    padding: '0 0.25rem',
+    margin: '0 0.125rem',
+  },
+  '&.cm-focused .cm-matchingBracket': {
+    backgroundColor: 'var(--code-match)',
+  },
+  '&.cm-focused .cm-nonmatchingBracket': {
+    backgroundColor: 'transparent',
+    textDecoration: 'underline wavy var(--code-squiggle-error) 1.5px',
+    textUnderlineOffset: '3px',
+    textDecorationSkipInk: 'none',
+  },
+  '.cm-searchMatch': { backgroundColor: 'var(--code-match)' },
+  '.cm-searchMatch.cm-searchMatch-selected': {
+    backgroundColor: 'var(--code-selection)',
+    outline: '1px solid var(--code-squiggle-info)',
+  },
+  '.cm-selectionMatch': { backgroundColor: 'var(--code-match)' },
+  // A `{{ … }}` template reads as one chip; in prose it keeps the code font,
+  // a little smaller so it sits on the text's x-height.
+  '.cm-template': {
+    backgroundColor: 'var(--code-template-tint)',
+    borderRadius: '3px',
+    boxDecorationBreak: 'clone',
+    WebkitBoxDecorationBreak: 'clone',
+  },
+  '&.cm-prose .cm-template': {
+    fontFamily: 'var(--font-mono)',
+    fontSize: '0.92em',
+  },
+  '.cm-tale-object': { color: 'var(--code-token-constant)' },
+  // Search and go-to-line panels, in the app's control styles.
+  '.cm-panels': {
+    backgroundColor: 'hsl(var(--card))',
+    color: 'hsl(var(--card-foreground))',
+    fontFamily: 'var(--font-sans)',
+  },
+  '.cm-panels.cm-panels-top': { borderBottom: '1px solid hsl(var(--border))' },
+  '.cm-panels.cm-panels-bottom': { borderTop: '1px solid hsl(var(--border))' },
+  '.cm-panel.cm-search, .cm-panel.cm-gotoLine': {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: '0.25rem 0.5rem',
+    padding: '0.375rem 2rem 0.375rem 0.5rem',
+    fontSize: '0.75rem',
+  },
+  '.cm-panel.cm-search br': { flexBasis: '100%', height: '0' },
+  '.cm-panel .cm-textfield': {
+    height: '1.75rem',
+    margin: '0',
+    padding: '0 0.5rem',
+    border: '1px solid var(--color-border-input)',
+    borderRadius: '0.375rem',
+    backgroundColor: 'hsl(var(--background))',
+    color: 'hsl(var(--foreground))',
+    fontSize: '0.75rem',
+  },
+  '.cm-panel .cm-textfield:focus-visible': {
+    outline:
+      '2px solid color-mix(in srgb, var(--color-accent-base) 30%, transparent)',
+    borderColor: 'var(--color-accent-base)',
+  },
+  '.cm-panel .cm-button': {
+    height: '1.75rem',
+    margin: '0',
+    padding: '0 0.5rem',
+    border: '1px solid hsl(var(--border))',
+    borderRadius: '0.375rem',
+    backgroundImage: 'none',
+    backgroundColor: 'hsl(var(--background))',
+    color: 'hsl(var(--foreground))',
+    fontSize: '0.75rem',
+    cursor: 'pointer',
+  },
+  '.cm-panel .cm-button:hover': { backgroundColor: 'hsl(var(--muted))' },
+  '.cm-panel label': {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '0.25rem',
+    fontSize: '0.75rem',
+    color: 'hsl(var(--foreground))',
+  },
+  '.cm-panel button[name=close]': {
+    top: '0.375rem',
+    right: '0.375rem',
+    width: '1.5rem',
+    height: '1.5rem',
+    borderRadius: '0.375rem',
+    color: 'hsl(var(--muted-foreground))',
+    fontSize: '1rem',
+  },
+  '.cm-panel button[name=close]:hover': {
+    backgroundColor: 'hsl(var(--muted))',
+    color: 'hsl(var(--foreground))',
+  },
+});
diff --git a/packages/ui/src/components/forms/code-editor/extensions/tree-walk.ts b/packages/ui/src/components/forms/code-editor/extensions/tree-walk.ts
new file mode 100644
index 0000000000..65c20ba1ef
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/tree-walk.ts
@@ -0,0 +1,33 @@
+import { NodeProp, type SyntaxNode, type Tree } from '@lezer/common';
+
+/**
+ * Visits every node of `tree` that touches `[from, to)`, entering the
+ * overlays mounted on it — a template inside a JSON or YAML string is an
+ * overlay, which a plain `tree.iterate` does not enter. `node` positions are
+ * relative to its own tree; `offset` turns them into document positions.
+ */
+export function walkTree(
+  tree: Tree,
+  from: number,
+  to: number,
+  enter: (node: SyntaxNode, offset: number) => void,
+  offset = 0,
+): void {
+  tree.iterate({
+    from: from - offset,
+    to: to - offset,
+    enter(ref) {
+      const mounted = ref.tree?.prop(NodeProp.mounted);
+      if (mounted?.overlay) {
+        walkTree(
+          mounted.tree,
+          from,
+          to,
+          enter,
+          offset + ref.from + mounted.overlay[0].from,
+        );
+      }
+      enter(ref.node, offset);
+    },
+  });
+}
diff --git a/packages/ui/src/components/forms/code-editor/icon-sprite.tsx b/packages/ui/src/components/forms/code-editor/icon-sprite.tsx
new file mode 100644
index 0000000000..287cc6d9dd
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/icon-sprite.tsx
@@ -0,0 +1,126 @@
+'use client';
+
+import {
+  Ban,
+  Braces,
+  Brackets,
+  ChevronDown,
+  ChevronRight,
+  CircleDashed,
+  CircleX,
+  CodeXml,
+  Hash,
+  Info,
+  KeyRound,
+  LogIn,
+  Pi,
+  SquareFunction,
+  ToggleLeft,
+  TriangleAlert,
+  Type,
+  Workflow,
+  type LucideIcon,
+} from 'lucide-react';
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * The Lucide icons the editor draws inside DOM that CodeMirror owns (gutter
+ * marks, completion rows), where React cannot render: one hidden sprite of
+ * `<symbol>`s in the document, referenced with `<use href="#…">`. Every
+ * editor on the page shares the first mounted sprite; the next takes over
+ * when it unmounts.
+ */
+const ICONS = {
+  'chevron-down': ChevronDown,
+  'chevron-right': ChevronRight,
+  'circle-x': CircleX,
+  'triangle-alert': TriangleAlert,
+  info: Info,
+  workflow: Workflow,
+  'log-in': LogIn,
+  'square-function': SquareFunction,
+  'key-round': KeyRound,
+  pi: Pi,
+  'code-xml': CodeXml,
+  type: Type,
+  hash: Hash,
+  'toggle-left': ToggleLeft,
+  braces: Braces,
+  brackets: Brackets,
+  ban: Ban,
+  'circle-dashed': CircleDashed,
+} satisfies Record<string, LucideIcon>;
+
+export type EditorIconName = keyof typeof ICONS;
+
+const ID_PREFIX = 'tale-code-editor-icon-';
+
+/**
+ * An icon element for CodeMirror DOM: `size-3.5` by default, decorative,
+ * coloured by `currentColor`, in an inline-flex box.
+ */
+export function editorIcon(
+  name: EditorIconName,
+  className = 'size-3.5',
+): HTMLSpanElement {
+  const ns = 'http://www.w3.org/2000/svg';
+  const box = document.createElement('span');
+  box.className = 'inline-flex shrink-0 items-center justify-center';
+  box.setAttribute('aria-hidden', 'true');
+  const svg = document.createElementNS(ns, 'svg');
+  svg.setAttribute('class', className);
+  svg.setAttribute('focusable', 'false');
+  const use = document.createElementNS(ns, 'use');
+  use.setAttribute('href', `#${ID_PREFIX}${name}`);
+  svg.appendChild(use);
+  box.appendChild(svg);
+  return box;
+}
+
+const claims: symbol[] = [];
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function owner(): symbol | null {
+  return claims[0] ?? null;
+}
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Renders the sprite once per document, from whichever editor came first. */
+export function EditorIconSprite() {
+  const [me] = useState(() => Symbol('code-editor-sprite'));
+  const current = useSyncExternalStore(subscribe, owner, () => null);
+  useEffect(() => {
+    claims.push(me);
+    notify();
+    return () => {
+      const index = claims.indexOf(me);
+      if (index !== -1) claims.splice(index, 1);
+      notify();
+    };
+  }, [me]);
+  if (current !== me) return null;
+  return createPortal(
+    <svg
+      aria-hidden="true"
+      focusable="false"
+      data-code-editor-sprite=""
+      style={{ position: 'absolute', width: 0, height: 0, overflow: 'hidden' }}
+    >
+      {Object.entries(ICONS).map(([name, Icon]) => (
+        <symbol key={name} id={`${ID_PREFIX}${name}`} viewBox="0 0 24 24">
+          <Icon width={24} height={24} />
+        </symbol>
+      ))}
+    </svg>,
+    document.body,
+  );
+}
diff --git a/packages/ui/src/components/forms/code-editor/locate.test.ts b/packages/ui/src/components/forms/code-editor/locate.test.ts
new file mode 100644
index 0000000000..4efc1b00d3
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/locate.test.ts
@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import { stringify } from 'yaml';
+
+import { locateJsonPointer, locateYamlPointer } from './locate';
+
+function slice(text: string, range: { from: number; to: number } | null) {
+  return range === null ? null : text.slice(range.from, range.to);
+}
+
+describe('locateJsonPointer', () => {
+  const text = JSON.stringify(
+    {
+      to: 'ada@example.com',
+      nested: { list: [1, { deep: true }] },
+      'a/b': 'slash',
+      'c~d': 'tilde',
+    },
+    null,
+    2,
+  );
+
+  it('finds a value by pointer, nested and in arrays', () => {
+    expect(slice(text, locateJsonPointer(text, '/to'))).toBe(
+      '"ada@example.com"',
+    );
+    expect(slice(text, locateJsonPointer(text, '/nested/list/1/deep'))).toBe(
+      'true',
+    );
+    expect(slice(text, locateJsonPointer(text, ''))).toBe(text);
+  });
+
+  it('decodes ~1 and ~0 in pointer segments', () => {
+    expect(slice(text, locateJsonPointer(text, '/a~1b'))).toBe('"slash"');
+    expect(slice(text, locateJsonPointer(text, '/c~0d'))).toBe('"tilde"');
+  });
+
+  it('marks a key or, for a missing member, the key of its object', () => {
+    expect(
+      slice(text, locateJsonPointer(text, '/to', { subject: 'key' })),
+    ).toBe('"to"');
+    expect(
+      slice(
+        text,
+        locateJsonPointer(text, '/nested/nope', { subject: 'missing' }),
+      ),
+    ).toBe('"nested"');
+    expect(
+      slice(text, locateJsonPointer(text, '/nope', { subject: 'missing' })),
+    ).toBe('{');
+  });
+
+  it('maps a range in the decoded string onto the raw text', () => {
+    const raw = '{"a": "x\\"y\\n\\u00e9z\\ud83d\\ude00!"}';
+    const decoded = JSON.parse(raw).a as string;
+    expect(decoded).toBe('x"y\néz😀!');
+    // "éz" in the decoded value
+    const start = decoded.indexOf('é');
+    expect(
+      slice(raw, locateJsonPointer(raw, '/a', { range: [start, start + 2] })),
+    ).toBe('\\u00e9z');
+    // the emoji: two UTF-16 units, two escapes
+    const emoji = decoded.indexOf('😀');
+    expect(
+      slice(raw, locateJsonPointer(raw, '/a', { range: [emoji, emoji + 2] })),
+    ).toBe('\\ud83d\\ude00');
+  });
+
+  it('answers null for text that does not parse or a pointer to nothing', () => {
+    expect(locateJsonPointer('{"a": ', '/a')).toBeNull();
+    expect(locateJsonPointer(text, '/nope')).toBeNull();
+    expect(locateJsonPointer(text, 'no-slash')).toBeNull();
+  });
+
+  // Whatever a value holds, the raw text at the mapped range decodes back
+  // to exactly the decoded substring that was asked for.
+  it('round-trips ranges through JSON.stringify', () => {
+    const samples = [
+      'plain text',
+      'quote " and backslash \\ inside',
+      'tab\tnew\nline',
+      'ümlaut é 😀 emoji',
+      '{{ nodes.a.output }} and {{ "}}" }}',
+      '\u0001 control',
+    ];
+    for (const value of samples) {
+      const raw = JSON.stringify({ v: value });
+      for (let from = 0; from < value.length; from++) {
+        for (let to = from + 1; to <= value.length; to++) {
+          // Never split a surrogate pair.
+          if (/[\ud800-\udbff]/.test(value[to - 1] ?? '')) continue;
+          if (/[\udc00-\udfff]/.test(value[from] ?? '')) continue;
+          const found = locateJsonPointer(raw, '/v', { range: [from, to] });
+          expect(found).not.toBeNull();
+          const piece = raw.slice(found?.from, found?.to);
+          expect(JSON.parse(`"${piece}"`)).toBe(value.slice(from, to));
+        }
+      }
+    }
+  });
+});
+
+describe('locateYamlPointer', () => {
+  const text = [
+    'name: Triage',
+    'nodes:',
+    '  - id: score',
+    '    prompt: Rate {{ item.title }} now',
+    "    single: 'it''s {{ x }}'",
+    '    double: "say {{ y }}"',
+    '    escaped: "tab\\there {{ z }}"',
+    '    code: |',
+    '      const a = 1;',
+    '      return {{ w }};',
+    '    folded: >',
+    '      one',
+    '      two {{ v }}',
+    '    flow: { a: 1, b: "{{ u }}" }',
+  ].join('\n');
+
+  it('finds a value by pointer', () => {
+    expect(slice(text, locateYamlPointer(text, '/name'))).toBe('Triage');
+    expect(slice(text, locateYamlPointer(text, '/nodes/0/id'))).toBe('score');
+    expect(slice(text, locateYamlPointer(text, '/nodes/0/flow/b'))).toBe(
+      '"{{ u }}"',
+    );
+  });
+
+  it('marks a key, and the key of the object a missing member belongs to', () => {
+    expect(
+      slice(text, locateYamlPointer(text, '/nodes/0/id', { subject: 'key' })),
+    ).toBe('id');
+    // An item has no key of its own: its first key stands in.
+    expect(
+      slice(
+        text,
+        locateYamlPointer(text, '/nodes/0/missing', { subject: 'missing' }),
+      ),
+    ).toBe('id');
+    expect(locateYamlPointer(text, '/missing', { subject: 'missing' })).toBe(
+      null,
+    );
+    expect(
+      slice(text, locateYamlPointer(text, '/name/x', { subject: 'missing' })),
+    ).toBe('name');
+  });
+
+  it.each([
+    ['/nodes/0/prompt', 'Rate {{ item.title }} now', '{{ item.title }}'],
+    ['/nodes/0/single', "it's {{ x }}", '{{ x }}'],
+    ['/nodes/0/double', 'say {{ y }}', '{{ y }}'],
+    ['/nodes/0/code', 'const a = 1;\nreturn {{ w }};\n', '{{ w }}'],
+    ['/nodes/0/folded', 'one two {{ v }}\n', '{{ v }}'],
+  ])('maps a range inside %s exactly', (pointer, decoded, part) => {
+    const at = decoded.indexOf(part);
+    const found = locateYamlPointer(text, pointer, {
+      range: [at, at + part.length],
+    });
+    expect(slice(text, found)).toBe(part);
+  });
+
+  it('marks a whole escaped value rather than guess inside it', () => {
+    const found = locateYamlPointer(text, '/nodes/0/escaped', {
+      range: [9, 16],
+    });
+    expect(slice(text, found)).toBe('"tab\\there {{ z }}"');
+  });
+
+  it('answers null for YAML that does not parse', () => {
+    expect(locateYamlPointer('a: [1, 2', '/a')).toBeNull();
+  });
+
+  // Values written by `yaml.stringify` as plain or block scalars: the text
+  // at a mapped range is the decoded substring, give or take the
+  // indentation a block scalar adds to each line.
+  it('round-trips ranges through yaml.stringify', () => {
+    const samples = [
+      'plain value with {{ nodes.a.output }}',
+      'two\nlines {{ x }}\nthree',
+      "it's quoted: {{ y }}",
+    ];
+    for (const value of samples) {
+      const raw = stringify({ v: value }, { lineWidth: 0 });
+      for (let from = 0; from < value.length; from++) {
+        for (let to = from + 1; to <= value.length; to++) {
+          const found = locateYamlPointer(raw, '/v', { range: [from, to] });
+          expect(found, `${raw} [${from}, ${to})`).not.toBeNull();
+          if (found === null) continue;
+          const piece = raw
+            .slice(found.from, found.to)
+            .replace(/\n[ ]+/g, '\n')
+            .replace(/''/g, "'");
+          expect(piece).toBe(value.slice(from, to));
+        }
+      }
+    }
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/locate.ts b/packages/ui/src/components/forms/code-editor/locate.ts
new file mode 100644
index 0000000000..83e2bd9a95
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/locate.ts
@@ -0,0 +1,398 @@
+/**
+ * JSON Pointer → text offsets: where a problem a check reported by pointer
+ * (`/nodes/2/input/to`) sits in the JSON or YAML text a reader edits.
+ *
+ * A pointer names a value; `subject` picks what to mark:
+ *
+ * - `value` (default) — the value. With `range`, offsets into the DECODED
+ *   string value (what the check saw) are mapped onto the raw text, escapes
+ *   and block-scalar indentation included.
+ * - `key` — the member's key.
+ * - `missing` — the pointer names a member that is not there; mark the key
+ *   of the object that should hold it (or that object, at the top level).
+ *
+ * Both return `null` when the text does not parse or the pointer names
+ * nothing; the caller then marks the whole field.
+ */
+
+import {
+  isMap,
+  isNode,
+  isPair,
+  isScalar,
+  isSeq,
+  parseDocument,
+  type Node as YamlNode,
+  type Pair,
+  type Scalar,
+} from 'yaml';
+
+export type LocateSubject = 'value' | 'key' | 'missing';
+
+export interface LocateOptions {
+  /** `[from, to)` inside the decoded string value (subject `value` only). */
+  range?: readonly [number, number];
+  subject?: LocateSubject;
+}
+
+export interface LocatedRange {
+  from: number;
+  to: number;
+}
+
+/** `/a~1b/0` → `['a/b', '0']`; `''` → `[]` (the whole document). */
+export function parsePointer(pointer: string): string[] | null {
+  if (pointer === '') return [];
+  if (!pointer.startsWith('/')) return null;
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+
+/* ------------------------------------------------------------------ JSON */
+
+interface JsonString {
+  kind: 'string';
+  from: number;
+  to: number;
+  value: string;
+  /** Raw offset of each decoded UTF-16 unit, plus one past the last. */
+  map: number[];
+}
+
+interface JsonMember {
+  key: JsonString;
+  value: JsonValue;
+}
+
+type JsonValue =
+  | JsonString
+  | { kind: 'object'; from: number; to: number; members: JsonMember[] }
+  | { kind: 'array'; from: number; to: number; items: JsonValue[] }
+  | { kind: 'scalar'; from: number; to: number };
+
+class JsonReader {
+  private pos = 0;
+
+  constructor(private readonly text: string) {}
+
+  read(): JsonValue | null {
+    try {
+      const value = this.value();
+      this.space();
+      return this.pos === this.text.length ? value : null;
+    } catch (error) {
+      if (error instanceof SyntaxError) return null;
+      throw error;
+    }
+  }
+
+  private fail(): never {
+    throw new SyntaxError(`Unexpected JSON at ${this.pos}`);
+  }
+
+  private space(): void {
+    while (/[ \t\n\r]/.test(this.text[this.pos] ?? '')) this.pos++;
+  }
+
+  private value(): JsonValue {
+    this.space();
+    const c = this.text[this.pos];
+    if (c === '{') return this.object();
+    if (c === '[') return this.array();
+    if (c === '"') return this.string();
+    const literal =
+      /^(?:-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)/.exec(
+        this.text.slice(this.pos),
+      );
+    if (literal === null) this.fail();
+    const from = this.pos;
+    this.pos += literal[0].length;
+    return { kind: 'scalar', from, to: this.pos };
+  }
+
+  private object(): JsonValue {
+    const from = this.pos++;
+    const members: JsonMember[] = [];
+    this.space();
+    if (this.text[this.pos] === '}') {
+      this.pos++;
+      return { kind: 'object', from, to: this.pos, members };
+    }
+    for (;;) {
+      this.space();
+      if (this.text[this.pos] !== '"') this.fail();
+      const key = this.string();
+      this.space();
+      if (this.text[this.pos++] !== ':') this.fail();
+      members.push({ key, value: this.value() });
+      this.space();
+      const next = this.text[this.pos++];
+      if (next === '}') return { kind: 'object', from, to: this.pos, members };
+      if (next !== ',') this.fail();
+    }
+  }
+
+  private array(): JsonValue {
+    const from = this.pos++;
+    const items: JsonValue[] = [];
+    this.space();
+    if (this.text[this.pos] === ']') {
+      this.pos++;
+      return { kind: 'array', from, to: this.pos, items };
+    }
+    for (;;) {
+      items.push(this.value());
+      this.space();
+      const next = this.text[this.pos++];
+      if (next === ']') return { kind: 'array', from, to: this.pos, items };
+      if (next !== ',') this.fail();
+    }
+  }
+
+  private string(): JsonString {
+    const from = this.pos++;
+    let value = '';
+    const map: number[] = [];
+    for (;;) {
+      const at = this.pos;
+      const c = this.text[this.pos];
+      if (c === undefined || c === '\n') this.fail();
+      if (c === '"') {
+        this.pos++;
+        map.push(at);
+        return { kind: 'string', from, to: this.pos, value, map };
+      }
+      if (c !== '\\') {
+        value += c;
+        map.push(at);
+        this.pos++;
+        continue;
+      }
+      const escape = this.text[this.pos + 1];
+      if (escape === 'u') {
+        const hex = this.text.slice(this.pos + 2, this.pos + 6);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) this.fail();
+        value += String.fromCharCode(parseInt(hex, 16));
+        map.push(at);
+        this.pos += 6;
+        continue;
+      }
+      const decoded = SIMPLE_ESCAPES[escape ?? ''];
+      if (decoded === undefined) this.fail();
+      value += decoded;
+      map.push(at);
+      this.pos += 2;
+    }
+  }
+}
+
+const SIMPLE_ESCAPES: Readonly<Record<string, string>> = {
+  '"': '"',
+  '\\': '\\',
+  '/': '/',
+  b: '\b',
+  f: '\f',
+  n: '\n',
+  r: '\r',
+  t: '\t',
+};
+
+function jsonChild(
+  value: JsonValue,
+  segment: string,
+): JsonMember | JsonValue | null {
+  if (value.kind === 'object') {
+    // The last of duplicate keys wins, as in JSON.parse.
+    return (
+      value.members.findLast((member) => member.key.value === segment) ?? null
+    );
+  }
+  if (value.kind === 'array' && /^(?:0|[1-9]\d*)$/.test(segment)) {
+    return value.items[Number(segment)] ?? null;
+  }
+  return null;
+}
+
+function stringRange(
+  value: JsonString,
+  range: readonly [number, number] | undefined,
+): LocatedRange {
+  if (range === undefined) return { from: value.from, to: value.to };
+  const length = value.map.length - 1;
+  const start = Math.min(Math.max(range[0], 0), length);
+  const end = Math.min(Math.max(range[1], start), length);
+  if (start === end) return { from: value.map[start], to: value.map[start] };
+  // The end is the raw offset after the last decoded unit in the range.
+  return { from: value.map[start], to: value.map[end] };
+}
+
+export function locateJsonPointer(
+  text: string,
+  pointer: string,
+  options: LocateOptions = {},
+): LocatedRange | null {
+  const path = parsePointer(pointer);
+  if (path === null) return null;
+  const root = new JsonReader(text).read();
+  if (root === null) return null;
+  const subject = options.subject ?? 'value';
+  const target = subject === 'missing' ? path.slice(0, -1) : path;
+  let value: JsonValue = root;
+  let member: JsonMember | null = null;
+  for (const segment of target) {
+    const child = jsonChild(value, segment);
+    if (child === null) return null;
+    if ('key' in child) {
+      member = child;
+      value = child.value;
+    } else {
+      member = null;
+      value = child;
+    }
+  }
+  if (subject === 'missing') {
+    if (member !== null) return { from: member.key.from, to: member.key.to };
+    return { from: value.from, to: value.from + 1 };
+  }
+  if (subject === 'key') {
+    if (member === null) return null;
+    return { from: member.key.from, to: member.key.to };
+  }
+  if (value.kind === 'string') return stringRange(value, options.range);
+  return { from: value.from, to: value.to };
+}
+
+/* ------------------------------------------------------------------ YAML */
+
+function yamlKeyText(pair: Pair): string | null {
+  const key = pair.key;
+  if (isScalar(key)) return String(key.value);
+  return null;
+}
+
+/**
+ * The raw offset of each decoded character of a scalar's value, plus one
+ * past the last, by walking the source beside the value: indentation,
+ * folded line breaks and quotes are skipped. `null` when the two cannot be
+ * aligned (an escape sequence changed a character).
+ */
+function alignScalar(text: string, scalar: Scalar): number[] | null {
+  const value = scalar.value;
+  if (typeof value !== 'string' || !scalar.range) return null;
+  let [from] = scalar.range;
+  const end = scalar.range[1];
+  const type = scalar.type;
+  if (type === 'QUOTE_DOUBLE') {
+    if (text.slice(from, end).includes('\\')) return null;
+    from += 1;
+  } else if (type === 'QUOTE_SINGLE') {
+    from += 1;
+  } else if (type === 'BLOCK_LITERAL' || type === 'BLOCK_FOLDED') {
+    // Skip the header line (`|`, `>-`, `|2+` and a comment).
+    const newline = text.indexOf('\n', from);
+    if (newline === -1) return null;
+    from = newline + 1;
+  }
+  const map: number[] = [];
+  let j = from;
+  for (let i = 0; i < value.length; i++) {
+    const c = value[i];
+    while (j < end && text[j] !== c) {
+      const skip = text[j];
+      if (c === ' ' && skip === '\n') break; // a folded line break
+      if (skip !== ' ' && skip !== '\t' && skip !== '\n' && skip !== '\r') {
+        return null;
+      }
+      j++;
+    }
+    if (j >= end) return null;
+    map.push(j);
+    j++;
+    if (type === 'QUOTE_SINGLE' && c === "'" && text[j] === "'") j++;
+  }
+  map.push(Math.min(j, end));
+  return map;
+}
+
+function yamlValueRange(
+  text: string,
+  node: YamlNode,
+  range: readonly [number, number] | undefined,
+): LocatedRange | null {
+  if (node.range === undefined || node.range === null) return null;
+  const whole = { from: node.range[0], to: node.range[1] };
+  if (range === undefined || !isScalar(node)) return trimEnd(text, whole);
+  const map = alignScalar(text, node);
+  if (map === null) return trimEnd(text, whole);
+  const length = map.length - 1;
+  const start = Math.min(Math.max(range[0], 0), length);
+  const stop = Math.min(Math.max(range[1], start), length);
+  if (start === stop) return { from: map[start], to: map[start] };
+  return { from: map[start], to: map[stop - 1] + 1 };
+}
+
+/** A block value's range runs through its last line break; mark the text. */
+function trimEnd(text: string, range: LocatedRange): LocatedRange {
+  let to = range.to;
+  while (to > range.from && /\s/.test(text[to - 1] ?? '')) to--;
+  return { from: range.from, to };
+}
+
+export function locateYamlPointer(
+  text: string,
+  pointer: string,
+  options: LocateOptions = {},
+): LocatedRange | null {
+  const path = parsePointer(pointer);
+  if (path === null) return null;
+  let document;
+  try {
+    document = parseDocument(text, { keepSourceTokens: false });
+  } catch (error) {
+    if (error instanceof Error) return null;
+    throw error;
+  }
+  if (document.errors.length > 0 || document.contents === null) return null;
+  const subject = options.subject ?? 'value';
+  const target = subject === 'missing' ? path.slice(0, -1) : path;
+  let node: YamlNode = document.contents;
+  let pair: Pair | null = null;
+  for (const segment of target) {
+    if (isMap(node)) {
+      const found: Pair | undefined = node.items.findLast(
+        (item) => isPair(item) && yamlKeyText(item) === segment,
+      );
+      if (found === undefined || !isNode(found.value)) return null;
+      pair = found;
+      node = found.value;
+      continue;
+    }
+    if (isSeq(node) && /^(?:0|[1-9]\d*)$/.test(segment)) {
+      const item: unknown = node.items[Number(segment)];
+      if (!isNode(item)) return null;
+      pair = null;
+      node = item;
+      continue;
+    }
+    return null;
+  }
+  const keyRange = (): LocatedRange | null => {
+    const key = pair?.key;
+    if (key === null || key === undefined || !isScalar(key)) return null;
+    if (key.range === undefined || key.range === null) return null;
+    return { from: key.range[0], to: key.range[1] };
+  };
+  if (subject === 'missing') {
+    if (pair !== null) return keyRange();
+    // A sequence item has no key: its first key stands in. The document
+    // itself has none either, so the caller marks the whole field.
+    if (target.length === 0 || !isMap(node)) return null;
+    const first = node.items[0]?.key;
+    if (!isScalar(first) || !first.range) return null;
+    return { from: first.range[0], to: first.range[1] };
+  }
+  if (subject === 'key') return keyRange();
+  return yamlValueRange(text, node, options.range);
+}
diff --git a/packages/ui/src/components/forms/code-editor/phrases.test.ts b/packages/ui/src/components/forms/code-editor/phrases.test.ts
new file mode 100644
index 0000000000..0f2d6be771
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/phrases.test.ts
@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import type { TFunction } from 'i18next';
+import { describe, expect, it } from 'vitest';
+import { parse } from 'yaml';
+
+import { editorPhrases } from './extensions/phrases';
+
+/**
+ * CodeMirror asks for its user-facing words (the completion list's name,
+ * the search panel, announcements) by English phrase. A phrase without a
+ * translation shows in English to a German or French reader, so every
+ * phrase the editor's packages ask for must be in `editorPhrases`, and every
+ * key it uses in each package catalog. A CodeMirror upgrade that adds a
+ * phrase fails here.
+ */
+
+const require = createRequire(join(__dirname, 'phrases.test.ts'));
+
+/** The packages the editor imports that render or announce words. */
+const PACKAGES = [
+  '@codemirror/view',
+  '@codemirror/commands',
+  '@codemirror/language',
+  '@codemirror/autocomplete',
+  '@codemirror/search',
+];
+
+function phrasesIn(packageName: string): string[] {
+  const entry = require.resolve(packageName);
+  const source = readFileSync(entry, 'utf8');
+  const found = new Set<string>();
+  for (const call of source.matchAll(/phrase\(([^)]*)\)/g)) {
+    for (const literal of call[1].matchAll(/"((?:[^"\\]|\\.)*)"/g)) {
+      found.add(JSON.parse(`"${literal[1]}"`));
+    }
+  }
+  return [...found];
+}
+
+const keyOf = ((key: string) => key) as unknown as TFunction;
+const table = editorPhrases(keyOf);
+
+function catalog(locale: string): Record<string, unknown> {
+  const raw: unknown = parse(
+    readFileSync(
+      join(__dirname, '..', '..', '..', 'i18n', 'messages', `${locale}.yml`),
+      'utf8',
+    ),
+  );
+  return raw as Record<string, unknown>;
+}
+
+function lookup(tree: Record<string, unknown>, path: string): unknown {
+  return path
+    .split('.')
+    .reduce<unknown>(
+      (node, part) =>
+        node !== null && typeof node === 'object'
+          ? (node as Record<string, unknown>)[part]
+          : undefined,
+      tree,
+    );
+}
+
+describe('CodeMirror phrases', () => {
+  it.each(PACKAGES)(
+    '%s asks for no phrase the editor leaves untranslated',
+    (name) => {
+      const phrases = phrasesIn(name);
+      expect(phrases.length).toBeGreaterThan(0);
+      const missing = phrases.filter((phrase) => !(phrase in table));
+      expect(missing).toEqual([]);
+    },
+  );
+
+  it.each(['en', 'de', 'fr'])(
+    'the %s catalog has every phrase key',
+    (locale) => {
+      const messages = catalog(locale);
+      const missing = Object.values(table).filter(
+        (key) => typeof lookup(messages, `codeEditor.${key}`) !== 'string',
+      );
+      expect(missing).toEqual([]);
+    },
+  );
+});
diff --git a/packages/ui/src/components/forms/code-editor/providers.test.ts b/packages/ui/src/components/forms/code-editor/providers.test.ts
new file mode 100644
index 0000000000..4aad080013
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/providers.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  combineProviders,
+  type CodeCompletionContext,
+  type CodeHoverContext,
+} from './providers';
+
+const signal = new AbortController().signal;
+
+const completionContext: CodeCompletionContext = {
+  text: 'nodes.',
+  pos: 6,
+  language: 'javascript',
+  region: 'code',
+  path: ['nodes'],
+  prefix: '',
+  from: 6,
+  to: 6,
+  explicit: false,
+  signal,
+};
+
+const hoverContext: CodeHoverContext = {
+  text: 'nodes.a',
+  pos: 6,
+  language: 'javascript',
+  region: 'code',
+  path: ['nodes', 'a'],
+  word: 'a',
+  from: 6,
+  to: 7,
+  signal,
+};
+
+describe('combineProviders', () => {
+  it('concatenates completions with one item per label, the higher boost winning', async () => {
+    const combined = combineProviders(
+      {
+        completion: () => ({
+          items: [
+            { label: 'a', detail: 'from shapes' },
+            { label: 'b', boost: 2 },
+          ],
+          validFor: /^\w*$/,
+        }),
+      },
+      undefined,
+      {
+        completion: async () => ({
+          items: [
+            { label: 'a', detail: 'from types', boost: 1 },
+            { label: 'b', boost: 0 },
+            { label: 'c' },
+          ],
+        }),
+      },
+    );
+    const result = await combined.completion?.(completionContext);
+    expect(result?.items.map((item) => [item.label, item.detail])).toEqual([
+      ['a', 'from types'],
+      ['b', undefined],
+      ['c', undefined],
+    ]);
+    expect(result?.validFor).toEqual(/^\w*$/);
+  });
+
+  it('answers null when no provider completes', async () => {
+    const combined = combineProviders({ completion: () => null });
+    expect(await combined.completion?.(completionContext)).toBeNull();
+  });
+
+  it('takes the first hover answer', async () => {
+    const combined = combineProviders(
+      { hover: () => null },
+      { hover: async () => ({ type: 'string', title: 'nodes.a' }) },
+      { hover: () => ({ type: 'never' }) },
+    );
+    expect(await combined.hover?.(hoverContext)).toEqual({
+      type: 'string',
+      title: 'nodes.a',
+    });
+  });
+
+  it('concatenates problems with one per code and range', async () => {
+    const combined = combineProviders(
+      {
+        lint: () => [
+          {
+            id: '1',
+            severity: 'error',
+            message: 'A',
+            code: 'X',
+            range: [0, 1],
+          },
+        ],
+        lintDelay: 300,
+      },
+      {
+        lint: async () => [
+          {
+            id: '2',
+            severity: 'error',
+            message: 'A again',
+            code: 'X',
+            range: [0, 1],
+          },
+          {
+            id: '3',
+            severity: 'warning',
+            message: 'B',
+            code: 'X',
+            range: [2, 3],
+          },
+        ],
+        lintDelay: 100,
+      },
+    );
+    const found = await combined.lint?.({
+      text: 'abc',
+      language: 'javascript',
+      signal,
+    });
+    expect(found?.map((d) => d.id)).toEqual(['1', '3']);
+    expect(combined.lintDelay).toBe(100);
+  });
+
+  it('leaves out what no provider offers', () => {
+    expect(combineProviders(undefined, {})).toEqual({});
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/providers.ts b/packages/ui/src/components/forms/code-editor/providers.ts
new file mode 100644
index 0000000000..01393f288d
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/providers.ts
@@ -0,0 +1,226 @@
+/**
+ * What a host plugs into the code editor: completion, hover and local
+ * problems. Each provider is a plain function over a parsed context, with no
+ * editor types in it, so a host's knowledge (the shapes of an automation's
+ * data, later a TypeScript worker) stays out of the editor and any number of
+ * hosts can be combined.
+ */
+
+import type { CodeLanguage } from '../../../lib/code-roles';
+import type { CodeEditorDiagnostic } from './types';
+
+export type { CodeLanguage } from '../../../lib/code-roles';
+
+/**
+ * What the cursor sits in: JavaScript `code`, the JavaScript inside a
+ * `{{ }}` `template`, plain `text` (prose, Markdown), a JSON/YAML `string`
+ * value or `key`, or a `comment`.
+ */
+export type CodeRegion =
+  | 'code'
+  | 'template'
+  | 'text'
+  | 'string'
+  | 'key'
+  | 'comment';
+
+export type CodePathSegment = string | number;
+
+export interface CodeCompletionContext {
+  text: string;
+  pos: number;
+  language: CodeLanguage;
+  region: CodeRegion;
+  /**
+   * The member chain left of the cursor, in JavaScript (a script, an
+   * expression or a template's body): `nodes.score.output.it|` →
+   * `['nodes', 'score', 'output']` with prefix `it`; `nodes["a b"]?.x.` →
+   * `['nodes', 'a b', 'x']`; `items[0].` → `[…, 'items', 0]`; a bare
+   * identifier → `[]`; outside an expression → `null`.
+   */
+  path: readonly CodePathSegment[] | null;
+  /** The word being typed, `[from, to)`. */
+  prefix: string;
+  from: number;
+  to: number;
+  /** JSON/YAML: pointer of the object whose key or value holds the cursor. */
+  pointer?: string;
+  /** Asked for (Ctrl+Space) rather than opened by typing. */
+  explicit: boolean;
+  /** Aborted when the reader types on and the answer is no longer wanted. */
+  signal: AbortSignal;
+}
+
+export type CodeCompletionKind =
+  | 'node'
+  | 'input'
+  | 'variable'
+  | 'property'
+  | 'method'
+  | 'function'
+  | 'keyword'
+  | 'constant'
+  | 'snippet';
+
+export type CodeValueType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+  | 'unknown';
+
+export interface CodeCompletionItem {
+  /** The name. One that is not an identifier is inserted as `["name"]`. */
+  label: string;
+  /** Raw text to insert instead of the label (a snippet). */
+  apply?: string;
+  /** Short trailing text: `string`, `Transform`, `{ count: number }`. */
+  detail?: string;
+  kind?: CodeCompletionKind;
+  /** Picks the icon of a variable or property. */
+  valueType?: CodeValueType;
+  info?: { type?: string; description?: string; sample?: string };
+  /** Shows `?` after the label and "optional" in the info panel. */
+  optional?: boolean;
+  /** Group header: "Earlier nodes". */
+  section?: string;
+  boost?: number;
+}
+
+export type CodeCompletionResult = {
+  items: readonly CodeCompletionItem[];
+  /** Keep the answer while the typed word still matches. */
+  validFor?: RegExp;
+} | null;
+
+export interface CodeHoverContext {
+  text: string;
+  pos: number;
+  language: CodeLanguage;
+  region: CodeRegion;
+  /** The chain up to and including the hovered word. */
+  path: readonly CodePathSegment[] | null;
+  word: string;
+  from: number;
+  to: number;
+  signal: AbortSignal;
+}
+
+export interface CodeHoverInfo {
+  /** TypeScript-like, highlighted. */
+  type: string;
+  /** `nodes.score.output.total`. */
+  title?: string;
+  description?: string;
+  /** Last run's value, already redacted and shortened by the host. */
+  sample?: string;
+}
+
+export interface CodeLintContext {
+  text: string;
+  language: CodeLanguage;
+  signal: AbortSignal;
+}
+
+export interface CodeEditorProviders {
+  completion?: (
+    context: CodeCompletionContext,
+  ) => CodeCompletionResult | Promise<CodeCompletionResult>;
+  hover?: (
+    context: CodeHoverContext,
+  ) => CodeHoverInfo | null | Promise<CodeHoverInfo | null>;
+  /** Instant local problems (a host's own checker), debounced by `lintDelay`. */
+  lint?: (
+    context: CodeLintContext,
+  ) =>
+    | readonly CodeEditorDiagnostic[]
+    | Promise<readonly CodeEditorDiagnostic[]>;
+  /** Milliseconds after the last edit before `lint` runs; default 150. */
+  lintDelay?: number;
+}
+
+function sameRange(
+  a: CodeEditorDiagnostic['range'],
+  b: CodeEditorDiagnostic['range'],
+): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a[0] === b[0] && a[1] === b[1];
+}
+
+/**
+ * Merges providers (say, an automation's data shapes and a TypeScript
+ * worker): completions are concatenated with one item per label, the higher
+ * `boost` winning; the first hover answer wins; problems are concatenated
+ * with one per `code` and range.
+ */
+export function combineProviders(
+  ...providers: Array<CodeEditorProviders | undefined>
+): CodeEditorProviders {
+  const present = providers.filter(
+    (provider): provider is CodeEditorProviders => provider !== undefined,
+  );
+  const completers = present.flatMap((p) =>
+    p.completion ? [p.completion] : [],
+  );
+  const hovers = present.flatMap((p) => (p.hover ? [p.hover] : []));
+  const linters = present.flatMap((p) => (p.lint ? [p.lint] : []));
+  const combined: CodeEditorProviders = {};
+  if (completers.length > 0) {
+    combined.completion = async (context) => {
+      const answers = await Promise.all(
+        completers.map((c) => Promise.resolve(c(context))),
+      );
+      const byLabel = new Map<string, CodeCompletionItem>();
+      let validFor: RegExp | undefined;
+      let any = false;
+      for (const answer of answers) {
+        if (answer === null) continue;
+        any = true;
+        validFor ??= answer.validFor;
+        for (const item of answer.items) {
+          const known = byLabel.get(item.label);
+          if (known === undefined || (item.boost ?? 0) > (known.boost ?? 0)) {
+            byLabel.set(item.label, item);
+          }
+        }
+      }
+      if (!any) return null;
+      return { items: [...byLabel.values()], validFor };
+    };
+  }
+  if (hovers.length > 0) {
+    combined.hover = async (context) => {
+      for (const hover of hovers) {
+        const answer = await hover(context);
+        if (answer !== null) return answer;
+      }
+      return null;
+    };
+  }
+  if (linters.length > 0) {
+    combined.lint = async (context) => {
+      const answers = await Promise.all(
+        linters.map((lint) => Promise.resolve(lint(context))),
+      );
+      const out: CodeEditorDiagnostic[] = [];
+      for (const diagnostic of answers.flat()) {
+        const duplicate = out.some(
+          (known) =>
+            known.code !== undefined &&
+            known.code === diagnostic.code &&
+            sameRange(known.range, diagnostic.range),
+        );
+        if (!duplicate) out.push(diagnostic);
+      }
+      return out;
+    };
+    const delays = present.flatMap((p) =>
+      p.lint && p.lintDelay !== undefined ? [p.lintDelay] : [],
+    );
+    if (delays.length > 0) combined.lintDelay = Math.min(...delays);
+  }
+  return combined;
+}
diff --git a/packages/ui/src/components/forms/code-editor/template-scan.test.ts b/packages/ui/src/components/forms/code-editor/template-scan.test.ts
new file mode 100644
index 0000000000..1b4513b18f
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/template-scan.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+
+import { scanTemplates } from './template-scan';
+
+/** The text of each template and whether it balanced. */
+function templates(text: string): Array<[string, boolean]> {
+  return scanTemplates(text).spans.map((span) => [
+    text.slice(span.open, span.end),
+    span.balanced,
+  ]);
+}
+
+describe('scanTemplates', () => {
+  it('finds each template with its body', () => {
+    const text = 'Hi {{ input.name }}, see {{nodes.a.output}}.';
+    const { spans, unterminated } = scanTemplates(text);
+    expect(unterminated).toEqual([]);
+    expect(spans).toHaveLength(2);
+    const [first, second] = spans;
+    expect(text.slice(first.bodyFrom, first.bodyTo)).toBe(' input.name ');
+    expect(text.slice(second.bodyFrom, second.bodyTo)).toBe('nodes.a.output');
+    expect(text.slice(second.end)).toBe('.');
+  });
+
+  // The engine's own cases (P1 `tokenizeTemplate`): a template ends at the
+  // `}}` that closes its expression.
+  it.each([
+    ['{{ xs.map(x => ({ y: x })) }}', '{{ xs.map(x => ({ y: x })) }}'],
+    ['{{ ({ a: { b: 1 } }) }} tail', '{{ ({ a: { b: 1 } }) }}'],
+    ['{{ "}}" }} tail', '{{ "}}" }}'],
+    ["{{ '}}' + `}}` }}", "{{ '}}' + `}}` }}"],
+    ['{{ `${a}}` }}', '{{ `${a}}` }}'],
+    ['{{ x // }} }}', '{{ x // }}'],
+    ['{{ a }}}', '{{ a }}'],
+  ])('%s', (text, expected) => {
+    expect(templates(text)[0]).toEqual([expected, true]);
+  });
+
+  it('keeps the first closer when nothing balanced fits, and says so', () => {
+    expect(templates('{{ a) }} b')).toEqual([['{{ a) }}', false]]);
+    expect(templates('{{ }} b')).toEqual([['{{ }}', false]]);
+  });
+
+  it('lists a {{ with no closer after it as unterminated', () => {
+    const text = 'a {{ b }} c {{ d';
+    const { spans, unterminated } = scanTemplates(text);
+    expect(spans.map((span) => text.slice(span.open, span.end))).toEqual([
+      '{{ b }}',
+    ]);
+    expect(unterminated).toEqual([[12, 14]]);
+  });
+
+  it('leaves an empty {{}} as quiet text', () => {
+    expect(scanTemplates('a {{}} b')).toEqual({ spans: [], unterminated: [] });
+  });
+
+  // Generated identifier and member templates always round-trip: one span
+  // per template, covering it exactly.
+  it('round-trips generated member templates', () => {
+    const names = ['nodes', 'input', 'item', 'a_b', '$x', 'output'];
+    let seed = 7;
+    const next = () => {
+      seed = (seed * 1103515245 + 12345) % 2147483648;
+      return seed;
+    };
+    for (let run = 0; run < 200; run++) {
+      const parts: string[] = [];
+      const expected: string[] = [];
+      for (let i = 0; i < 1 + (next() % 4); i++) {
+        const chain = Array.from(
+          { length: 1 + (next() % 4) },
+          () => names[next() % names.length],
+        ).join(next() % 2 === 0 ? '.' : '?.');
+        const template = `{{ ${chain} }}`;
+        expected.push(template);
+        parts.push(`text ${i} `, template);
+      }
+      const text = parts.join('');
+      expect(templates(text).map(([found]) => found)).toEqual(expected);
+    }
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/template-scan.ts b/packages/ui/src/components/forms/code-editor/template-scan.ts
new file mode 100644
index 0000000000..0ecee6c56c
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/template-scan.ts
@@ -0,0 +1,195 @@
+/**
+ * Where each `{{ <expression> }}` of a text begins and ends — the rule a
+ * runtime that evaluates templates applies, without a JavaScript parser.
+ *
+ * A template ends at the `}}` that closes its expression, not at the first
+ * `}}` in the text, so an object literal, a string holding `}}` or a nested
+ * arrow body survive: `{{ xs.map(x => ({ y: x })) }}` is one template.
+ *
+ * 1. The first `}}` at least one character after the `{{` is the candidate
+ *    closer. When the text between is balanced — every string, comment and
+ *    bracket that opens in it also closes — that span is the template.
+ * 2. Otherwise the scan continues from the `{{` until every bracket and
+ *    string has closed, and the first `}}` from there closes the template.
+ * 3. When that fails too, the first `}}` stays the closer and the span is
+ *    marked `balanced: false` (the host reports the syntax error).
+ *
+ * A `{{` with no `}}` anywhere after it is text, listed in `unterminated`;
+ * `{{}}` is an empty pair and stays quiet text.
+ *
+ * "Balanced" stands in for "parses": a host with a real parser (Tale's
+ * engine) passes its own tokenizer to the code editor as `templateScanner`,
+ * and the two agree on everything but exotic input (a regular expression
+ * literal holding `}}`).
+ */
+
+export interface TemplateSpan {
+  /** Offset of `{{`. */
+  open: number;
+  /** The expression between the braces, untrimmed: `[bodyFrom, bodyTo)`. */
+  bodyFrom: number;
+  bodyTo: number;
+  /** Offset just after the closing `}}`. */
+  end: number;
+  /** False when no balanced expression fits the braces (rule 3). */
+  balanced: boolean;
+}
+
+export interface TemplateScan {
+  spans: TemplateSpan[];
+  /** `[from, to)` of every `{{` with no `}}` after it. */
+  unterminated: Array<[number, number]>;
+}
+
+const OPENERS: Readonly<Record<string, string>> = {
+  '(': ')',
+  '[': ']',
+  '{': '}',
+};
+
+interface ScanState {
+  /** Closers still expected, innermost last; `` ` `` marks a template literal. */
+  stack: string[];
+  /** Inside a string or block comment that has not closed. */
+  open: boolean;
+}
+
+/**
+ * Scans JavaScript-ish text from `from`, calling `atTopLevel(pos)` at every
+ * position where nothing is open (no bracket, string or comment); a `true`
+ * answer stops the scan there. Returns the state at the end of the scan.
+ */
+function scan(
+  text: string,
+  from: number,
+  to: number,
+  atTopLevel?: (pos: number) => boolean,
+): ScanState {
+  const stack: string[] = [];
+  let i = from;
+  while (i < to) {
+    const top = stack.at(-1);
+    if (top === '`') {
+      // Inside a template literal: text until `${` or the closing backtick.
+      const c = text[i];
+      if (c === '\\') {
+        i += 2;
+        continue;
+      }
+      if (c === '`') {
+        stack.pop();
+        i++;
+        continue;
+      }
+      if (c === '$' && text[i + 1] === '{') {
+        stack.push('}');
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (stack.length === 0 && atTopLevel?.(i)) return { stack, open: false };
+    const c = text[i];
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      while (j < to && text[j] !== c && text[j] !== '\n') {
+        j += text[j] === '\\' ? 2 : 1;
+      }
+      if (j >= to || text[j] !== c) return { stack, open: true };
+      i = j + 1;
+      continue;
+    }
+    if (c === '/' && text[i + 1] === '/') {
+      const newline = text.indexOf('\n', i);
+      // A line comment the range ends inside closes with the range.
+      if (newline === -1 || newline >= to) return { stack, open: false };
+      i = newline + 1;
+      continue;
+    }
+    if (c === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close === -1 || close + 2 > to) return { stack, open: true };
+      i = close + 2;
+      continue;
+    }
+    if (c === '`') {
+      stack.push('`');
+      i++;
+      continue;
+    }
+    const closer = OPENERS[c];
+    if (closer !== undefined) {
+      stack.push(closer);
+      i++;
+      continue;
+    }
+    if (c === ')' || c === ']' || c === '}') {
+      if (stack.at(-1) !== c) return { stack: [c], open: false };
+      stack.pop();
+      i++;
+      continue;
+    }
+    i++;
+  }
+  if (stack.length === 0) atTopLevel?.(to);
+  return { stack, open: false };
+}
+
+function balanced(text: string, from: number, to: number): boolean {
+  if (text.slice(from, to).trim() === '') return false;
+  const state = scan(text, from, to);
+  return !state.open && state.stack.length === 0;
+}
+
+/** The first `}}` after the expression that starts at `from` closes. */
+function closerAfterExpression(text: string, from: number): number {
+  let found = -1;
+  scan(text, from, text.length, (pos) => {
+    if (text.startsWith('}}', pos)) {
+      found = pos;
+      return true;
+    }
+    return false;
+  });
+  return found;
+}
+
+function span(open: number, close: number, isBalanced: boolean): TemplateSpan {
+  return {
+    open,
+    bodyFrom: open + 2,
+    bodyTo: close,
+    end: close + 2,
+    balanced: isBalanced,
+  };
+}
+
+export function scanTemplates(text: string): TemplateScan {
+  const spans: TemplateSpan[] = [];
+  const unterminated: Array<[number, number]> = [];
+  let open = text.indexOf('{{');
+  while (open !== -1) {
+    const close = text.indexOf('}}', open + 3);
+    if (close === -1) {
+      if (text.indexOf('}}', open + 2) === -1) {
+        unterminated.push([open, open + 2]);
+      }
+      open = text.indexOf('{{', open + 2);
+      continue;
+    }
+    let found: TemplateSpan;
+    if (balanced(text, open + 2, close)) {
+      found = span(open, close, true);
+    } else {
+      const later = closerAfterExpression(text, open + 2);
+      found =
+        later > close && balanced(text, open + 2, later)
+          ? span(open, later, true)
+          : span(open, close, false);
+    }
+    spans.push(found);
+    open = text.indexOf('{{', found.end);
+  }
+  return { spans, unterminated };
+}
diff --git a/packages/ui/src/components/forms/code-editor/types.ts b/packages/ui/src/components/forms/code-editor/types.ts
new file mode 100644
index 0000000000..85846695cc
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/types.ts
@@ -0,0 +1,119 @@
+import type { ReactNode } from 'react';
+
+import type { CodeLanguage } from '../../../lib/code-roles';
+import type { CodeEditorProviders } from './providers';
+import type { TemplateScan } from './template-scan';
+
+/** A problem with the text, at a range or for the whole field. */
+export interface CodeEditorDiagnostic {
+  /** Stable across checks (a check's issue id). */
+  id: string;
+  severity: 'error' | 'warning' | 'info';
+  /** One translated sentence: the tooltip line, the summary, the announcement. */
+  message: string;
+  /**
+   * UTF-16 `[from, to)` into `diagnosticsFor` (default: `value`). Absent:
+   * the whole field is meant — no underline, a gutter mark on line 1, listed
+   * in the summary. An empty range widens to one character.
+   */
+  range?: readonly [number, number];
+  /** Stable machine code, small and monospaced in the tooltip. */
+  code?: string;
+  /** Rich tooltip body, e.g. `<IssueDetail issue={item} density="compact" />`. */
+  detail?: ReactNode;
+  /** One-click repairs. Offsets into `diagnosticsFor`, mapped like `range`. */
+  fixes?: ReadonlyArray<{
+    label: string;
+    changes: ReadonlyArray<{
+      range: readonly [number, number];
+      insert: string;
+    }>;
+  }>;
+}
+
+export type CodeEditorDiagnosticsStatus =
+  | 'ready'
+  | 'checking'
+  | 'stale'
+  | 'failed';
+
+export interface CodeEditorProps {
+  value: string;
+  onChange?: (value: string) => void;
+  language: CodeLanguage;
+  /** `{{ js }}` inside json, yaml, markdown or text; implied by `template`. */
+  templates?: boolean;
+  /** Replaces the built-in template scanner (a host's runtime rule). Pure. */
+  templateScanner?: (text: string) => TemplateScan;
+
+  /** Focusable and selectable but not editable; code-block chrome. */
+  readOnly?: boolean;
+  disabled?: boolean;
+  /** Why it is disabled: keeps it focusable and shows this as a tooltip. */
+  disabledReason?: ReactNode;
+  placeholder?: string;
+
+  /** One line: Enter never inserts a newline and Tab moves focus. */
+  singleLine?: boolean;
+  /** Default 1 (singleLine) or 3. */
+  minRows?: number;
+  /** Default 4 (singleLine, soft-wrapped) or 14; ignored with `fillHeight`. */
+  maxRows?: number;
+  /** Fill the flex parent and scroll inside. */
+  fillHeight?: boolean;
+  /** Soft-wrap long lines. Default: on for markdown, template, text and singleLine. */
+  wrap?: boolean;
+  /** `prose` sets the text in the reading font (prompts); templates stay mono. */
+  font?: 'mono' | 'prose';
+  /** `sm` 12 px (inspector) or `md` 14 px; 16 px below md, so iOS never zooms. */
+  size?: 'sm' | 'md';
+  lineNumbers?: boolean;
+  /** Fold markers in the gutter. Default: `lineNumbers`. */
+  fold?: boolean;
+  /** Find and replace on Mod-F. Default off: Mod-F stays the browser's. */
+  search?: boolean;
+  /** An "Expand editor" button that opens the same field in a large dialog. */
+  expandable?: boolean | { title: string };
+
+  /** Set on the focusable text area, for `<label for>` and focus requests. */
+  id?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  'aria-invalid'?: boolean;
+  required?: boolean;
+
+  diagnostics?: readonly CodeEditorDiagnostic[];
+  /** The text `diagnostics` ranges index into; edits since are mapped. */
+  diagnosticsFor?: string;
+  diagnosticsStatus?: CodeEditorDiagnosticsStatus;
+  /** An sr-only summary of the problems; false where a Field lists them. */
+  describeDiagnostics?: boolean;
+  /** Local syntax marks (JSON/YAML, unclosed `{{`, JavaScript). Default on. */
+  syntaxDiagnostics?: boolean;
+
+  providers?: CodeEditorProviders;
+  /** Mod-Enter, and Enter when `singleLine`. */
+  onSubmit?: (value: string) => void;
+  /** The host button's label, for the shortcut hint ("Run"). */
+  submitLabel?: string;
+  onFocus?: () => void;
+  onBlur?: () => void;
+
+  /** Registers with the nearest IssueFocusProvider (inert without one). */
+  issueAnchor?: string | null;
+  issueReveal?: () => void;
+  initialSelection?: readonly [number, number];
+  /** Classes for the frame. */
+  className?: string;
+}
+
+export interface CodeEditorHandle {
+  /** Focuses (and selects `range`); waits for the editor to load. */
+  focus(range?: readonly [number, number]): void;
+  getSelection(): readonly [number, number] | null;
+  openCompletion(): void;
+  nextDiagnostic(direction?: 1 | -1): void;
+  /** The CodeMirror view, for host tests; untyped on purpose. */
+  readonly view: unknown;
+}
diff --git a/packages/ui/src/i18n/messages/de-CH.yml b/packages/ui/src/i18n/messages/de-CH.yml
index fc94dbcbe2..a462758f09 100644
--- a/packages/ui/src/i18n/messages/de-CH.yml
+++ b/packages/ui/src/i18n/messages/de-CH.yml
@@ -13,3 +13,7 @@ common:
     close: Schliessen
 envEditor:
   projectSecretBadKey: «{key}» muss mit einem Grossbuchstaben beginnen und darf nur Grossbuchstaben, Ziffern oder Unterstriche enthalten (maximal 64 Zeichen).
+codeEditor:
+  phrases:
+    close: Schliessen
+    matchCase: Gross-/Kleinschreibung
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index 325160cc68..146bd030e9 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -434,3 +434,43 @@ issues:
   technicalDetails: Technische Details
   learnMore: Mehr erfahren
   goTo: Zur Stelle
+
+codeEditor:
+  roleDescription: Code-Editor
+  loading: Editor wird geladen…
+  keyboardHint: Tab rückt ein. Um den Editor zu verlassen, drücke Esc und dann Tab.
+  submitHint: 'Tastenkürzel {shortcut}: {action}.'
+  legend:
+    leave: Esc, dann Tab zum Verlassen
+    submit: '{shortcut}: {action}'
+  leaveArmed: Drücke Tab, um weiterzugehen.
+  tabFocusOn: Tab wechselt jetzt den Fokus.
+  tabFocusOff: Tab rückt jetzt ein.
+  phrases:
+    controlCharacter: Steuerzeichen
+    close: Schließen
+    selectionDeleted: Auswahl gelöscht
+    foldedCode: eingeklappter Code
+    unfold: ausklappen
+    to: bis
+    foldedLines: Eingeklappte Zeilen
+    unfoldedLines: Ausgeklappte Zeilen
+    foldLine: Zeile einklappen
+    unfoldLine: Zeile ausklappen
+    completions: Vorschläge
+    find: Suchen
+    replaceField: Ersetzen
+    next: Weiter
+    previous: Zurück
+    all: Alle
+    matchCase: Groß-/Kleinschreibung
+    regexp: Regex
+    byWord: Ganzes Wort
+    replace: Ersetzen
+    replaceAll: Alle ersetzen
+    goToLine: Zu Zeile springen
+    go: Los
+    currentMatch: aktueller Treffer
+    onLine: in Zeile
+    replacedMatches: $ Treffer ersetzt
+    replacedMatchOnLine: Treffer in Zeile $ ersetzt
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index 02a49ad005..1c983911f0 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -434,3 +434,43 @@ issues:
   technicalDetails: Technical details
   learnMore: Learn more
   goTo: Go to
+
+codeEditor:
+  roleDescription: code editor
+  loading: Loading the editor…
+  keyboardHint: Tab indents. To leave the editor, press Esc, then Tab.
+  submitHint: 'Shortcut {shortcut}: {action}.'
+  legend:
+    leave: Esc, then Tab to leave
+    submit: '{shortcut}: {action}'
+  leaveArmed: Press Tab to move on.
+  tabFocusOn: Tab now moves focus.
+  tabFocusOff: Tab now indents.
+  phrases:
+    controlCharacter: Control character
+    close: Close
+    selectionDeleted: Selection deleted
+    foldedCode: folded code
+    unfold: unfold
+    to: to
+    foldedLines: Folded lines
+    unfoldedLines: Unfolded lines
+    foldLine: Fold line
+    unfoldLine: Unfold line
+    completions: Completions
+    find: Find
+    replaceField: Replace
+    next: Next
+    previous: Previous
+    all: All
+    matchCase: Match case
+    regexp: Regex
+    byWord: Whole word
+    replace: Replace
+    replaceAll: Replace all
+    goToLine: Go to line
+    go: Go
+    currentMatch: current match
+    onLine: on line
+    replacedMatches: Replaced $ matches
+    replacedMatchOnLine: Replaced a match on line $
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 4d8cb5e6dc..3dba856318 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -434,3 +434,43 @@ issues:
   technicalDetails: Détails techniques
   learnMore: En savoir plus
   goTo: Y aller
+
+codeEditor:
+  roleDescription: éditeur de code
+  loading: Chargement de l'éditeur…
+  keyboardHint: Tab indente. Pour quitter l'éditeur, appuie sur Échap, puis sur Tab.
+  submitHint: 'Raccourci {shortcut} : {action}.'
+  legend:
+    leave: Échap, puis Tab pour quitter
+    submit: '{shortcut} : {action}'
+  leaveArmed: Appuie sur Tab pour continuer.
+  tabFocusOn: Tab déplace maintenant le focus.
+  tabFocusOff: Tab indente maintenant.
+  phrases:
+    controlCharacter: Caractère de contrôle
+    close: Fermer
+    selectionDeleted: Sélection supprimée
+    foldedCode: code replié
+    unfold: déplier
+    to: à
+    foldedLines: Lignes repliées
+    unfoldedLines: Lignes dépliées
+    foldLine: Replier la ligne
+    unfoldLine: Déplier la ligne
+    completions: Suggestions
+    find: Rechercher
+    replaceField: Remplacer
+    next: Suivant
+    previous: Précédent
+    all: Tout
+    matchCase: Respecter la casse
+    regexp: Regex
+    byWord: Mot entier
+    replace: Remplacer
+    replaceAll: Tout remplacer
+    goToLine: Aller à la ligne
+    go: Aller
+    currentMatch: correspondance actuelle
+    onLine: à la ligne
+    replacedMatches: $ correspondances remplacées
+    replacedMatchOnLine: Correspondance remplacée à la ligne $
diff --git a/packages/ui/src/lib/code-roles.ts b/packages/ui/src/lib/code-roles.ts
index 653ef5a9e8..ea56cab685 100644
--- a/packages/ui/src/lib/code-roles.ts
+++ b/packages/ui/src/lib/code-roles.ts
@@ -1,3 +1,5 @@
+import { Tag, tags as t } from '@lezer/highlight';
+
 /**
  * The colour roles of highlighted code — the one vocabulary the read-only
  * renderer (Shiki) and the code editor (CodeMirror) share.
@@ -65,6 +67,11 @@ function codeRoleVariable(role: CodeRole): string {
   return `--code-token-${role}`;
 }
 
+/** A role's colour as a CSS value, `var(--code-…)`. */
+export function codeRoleColor(role: CodeRole): string {
+  return `var(${codeRoleVariable(role)})`;
+}
+
 const ROLE_BY_VARIABLE = new Map<string, CodeRole>(
   CODE_ROLES.map((role) => [codeRoleVariable(role), role]),
 );
@@ -80,3 +87,107 @@ export function codeRoleOfColor(color: string | undefined): CodeRole | null {
   if (match === null) return null;
   return ROLE_BY_VARIABLE.get(match[1].toLowerCase()) ?? null;
 }
+
+/* ---------------------------------------------------------- the editor */
+
+/**
+ * Tags the editor's languages attach where Lezer's standard tags do not
+ * say enough to match the read-only colours: JSON and YAML keys, YAML plain
+ * values, block scalars, and the braces of a `{{ }}` template. (The object
+ * of a dot access, TextMate's `variable.other.object`, depends on the token
+ * after it, which a tag cannot see: the editor marks it separately.)
+ */
+export const codeTags = {
+  jsonKey: Tag.define(t.propertyName),
+  yamlKey: Tag.define(t.propertyName),
+  yamlValue: Tag.define(t.string),
+  yamlBlock: Tag.define(t.string),
+  templateBrace: Tag.define(t.brace),
+  templateUnterminated: Tag.define(t.invalid),
+};
+
+/**
+ * Which syntax tags take which colour role in the editor. The roles mirror
+ * the read-only grammars' scopes (`code-roles.parity.test.ts` compares the
+ * two per character); a more specific tag listed under one role wins over
+ * its parent listed under another (`null` is a keyword in Lezer, a
+ * constant here).
+ */
+export const CODE_ROLE_TAGS: Readonly<
+  Partial<Record<CodeRole, readonly Tag[]>>
+> = {
+  keyword: [
+    t.keyword,
+    t.controlKeyword,
+    t.definitionKeyword,
+    t.moduleKeyword,
+    t.operatorKeyword,
+    t.modifier,
+    t.operator,
+    t.compareOperator,
+    t.arithmeticOperator,
+    t.logicOperator,
+    t.bitwiseOperator,
+    t.updateOperator,
+    t.definitionOperator,
+    t.typeOperator,
+    t.controlOperator,
+    t.function(t.punctuation),
+    codeTags.jsonKey,
+    codeTags.yamlKey,
+    codeTags.templateBrace,
+  ],
+  'string-expression': [
+    t.string,
+    t.special(t.string),
+    t.regexp,
+    codeTags.yamlValue,
+  ],
+  string: [t.monospace, codeTags.yamlBlock],
+  constant: [
+    t.number,
+    t.bool,
+    t.null,
+    t.atom,
+    t.self,
+    t.constant(t.variableName),
+  ],
+  function: [
+    t.function(t.variableName),
+    t.function(t.propertyName),
+    t.function(t.definition(t.variableName)),
+    t.typeName,
+    t.className,
+    t.definition(t.className),
+    t.attributeName,
+  ],
+  comment: [t.comment, t.lineComment, t.blockComment, t.docComment],
+  punctuation: [t.separator],
+  // Names stay unstyled (the editor's text colour), so the mark that
+  // colours the object of a dot access shows through them.
+  foreground: [
+    t.derefOperator,
+    t.bracket,
+    t.paren,
+    t.brace,
+    t.squareBracket,
+    t.angleBracket,
+    t.special(t.brace),
+    t.escape,
+    t.content,
+    t.heading,
+    t.processingInstruction,
+    t.labelName,
+    t.meta,
+  ],
+  link: [t.url, t.link],
+  invalid: [t.invalid, codeTags.templateUnterminated],
+};
+
+/** Type styles that ride on top of a role colour. */
+export const CODE_FONT_TAGS = {
+  bold: [t.heading, t.strong] as readonly Tag[],
+  italic: [t.emphasis] as readonly Tag[],
+  strikethrough: [t.strikethrough] as readonly Tag[],
+  underline: [t.link, t.url] as readonly Tag[],
+};

From bdee0e083891645007cd1ad16eb49a37b28113d3 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 09:15:04 +0200
Subject: [PATCH 09/78] feat(ui): show problems, completion and types in the
 CodeEditor

- Problems: the host's (a check's results, placed on the text it saw
  and mapped through later edits), a host's instant lint provider, and the
  editor's own syntax marks (JSON or YAML that does not parse, an unclosed
  {{, unreadable JavaScript), merged in one state field. Underlines say the
  severity by style, the gutter by glyph; the tooltip shows the message,
  the host's detail, the code and fix buttons. F8 / Shift-F8 walk them and
  read each aloud; Mod-. applies a fix; a summary describes the field
  unless a Field already lists its problems.
- Completion from the host's provider with the member chain, a JSON or
  YAML pointer and the region the cursor is in; names that are not
  identifiers go in as ["a b"]; Tab or Enter accepts; the list keeps
  inside a sheet and Escape closes it before the sheet.
- Hover types after 200 ms, and on Mod-K Mod-I, read aloud.
- Expand opens the field in a large dialog and brings the caret back.
- Every new string in en, de, fr and de-CH.
---
 .../forms/code-editor/code-editor-view.tsx    | 175 ++++-
 .../code-editor/code-editor.browser.test.tsx  | 692 ++++++++++++++++-
 .../forms/code-editor/code-editor.tsx         | 170 +++-
 .../code-editor/diagnostic-mapping.test.ts    | 179 +++++
 .../code-editor/extensions/completion.ts      | 262 +++++++
 .../code-editor/extensions/diagnostics.ts     | 728 ++++++++++++++++++
 .../forms/code-editor/extensions/highlight.ts |  37 +-
 .../forms/code-editor/extensions/hover.ts     | 135 ++++
 .../forms/code-editor/extensions/keyboard.ts  |   6 +-
 .../code-editor/extensions/template/input.ts  |   9 +-
 .../forms/code-editor/extensions/theme.ts     |  91 +++
 .../forms/code-editor/extensions/tooltips.ts  |  95 +++
 .../forms/code-editor/member-path.test.ts     | 130 ++++
 .../forms/code-editor/member-path.ts          | 295 +++++++
 .../components/forms/code-editor/providers.ts |   5 +-
 .../forms/code-editor/tooltip-bodies.tsx      | 143 ++++
 packages/ui/src/i18n/messages/de-CH.yml       |   3 +
 packages/ui/src/i18n/messages/de.yml          |  23 +
 packages/ui/src/i18n/messages/en.yml          |  23 +
 packages/ui/src/i18n/messages/fr.yml          |  23 +
 20 files changed, 3205 insertions(+), 19 deletions(-)
 create mode 100644 packages/ui/src/components/forms/code-editor/diagnostic-mapping.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/completion.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/hover.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/extensions/tooltips.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/member-path.test.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/member-path.ts
 create mode 100644 packages/ui/src/components/forms/code-editor/tooltip-bodies.tsx

diff --git a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
index 26f6e8d6bb..8df876cdff 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
@@ -45,11 +45,28 @@ import {
   lineNumbers,
   placeholder as placeholderExtension,
 } from '@codemirror/view';
-import { useEffect, useLayoutEffect, useRef } from 'react';
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { createPortal } from 'react-dom';
 
 import { useT } from '../../../i18n/client';
 import type { IssueFocusPart, IssueFocusRange } from '../issue-focus';
+import { completionExtension } from './extensions/completion';
+import {
+  applyFix,
+  diagnosticsExtension,
+  goToDiagnostic,
+  placeDiagnostics,
+  setDiagnostics,
+  type DiagnosticWords,
+} from './extensions/diagnostics';
 import { codeHighlighting } from './extensions/highlight';
+import { hoverExtension } from './extensions/hover';
 import { keyboard, type KeyboardWords } from './extensions/keyboard';
 import { languageExtension, templatesOn } from './extensions/languages';
 import { memberObjects } from './extensions/member-objects';
@@ -57,8 +74,15 @@ import { editorPhrases } from './extensions/phrases';
 import { templateChips } from './extensions/template/chips';
 import { templateInput } from './extensions/template/input';
 import { codeEditorTheme } from './extensions/theme';
+import {
+  createTooltipPortals,
+  tooltipPlacement,
+  tooltipPortals,
+  type TooltipPortals,
+} from './extensions/tooltips';
 import { editorIcon, EditorIconSprite } from './icon-sprite';
 import { locateJsonPointer, locateYamlPointer } from './locate';
+import { DiagnosticTooltipBody, TypeTooltipBody } from './tooltip-bodies';
 import type { CodeEditorProps } from './types';
 
 /** What the light wrapper drives once the view exists. */
@@ -143,7 +167,10 @@ type SlotName =
   | 'search'
   | 'templates'
   | 'phrases'
-  | 'selection';
+  | 'selection'
+  | 'diagnostics'
+  | 'completion'
+  | 'hover';
 
 const SLOT_NAMES: readonly SlotName[] = [
   'language',
@@ -157,6 +184,9 @@ const SLOT_NAMES: readonly SlotName[] = [
   'templates',
   'phrases',
   'selection',
+  'diagnostics',
+  'completion',
+  'hover',
 ];
 
 /** One reconfigurable part: rebuilt only when its signature changes. */
@@ -184,6 +214,9 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     templates: new Compartment(),
     phrases: new Compartment(),
     selection: new Compartment(),
+    diagnostics: new Compartment(),
+    completion: new Compartment(),
+    hover: new Compartment(),
   };
   const applied = useRef<Partial<Record<SlotName, string>>>({});
 
@@ -201,6 +234,35 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     wordsRef.current = words;
   });
 
+  const diagnosticWords: DiagnosticWords = {
+    severity: {
+      error: t('diagnostics.severity.error'),
+      warning: t('diagnostics.severity.warning'),
+      info: t('diagnostics.severity.info'),
+    },
+    atCursor: (values) => t('diagnostics.atCursor', values),
+    fixAvailable: (shortcut) => t('diagnostics.fixAvailable', { shortcut }),
+    fixApplied: (label) => t('diagnostics.fixApplied', { label }),
+    syntax: {
+      json: t('syntax.json'),
+      yaml: t('syntax.yaml'),
+      javascript: t('syntax.javascript'),
+      unterminatedTemplate: t('syntax.unterminatedTemplate'),
+    },
+  };
+  const completionWords = {
+    type: t('typeInfo.label'),
+    optional: t('typeInfo.optional'),
+    sample: (value: string) => t('typeInfo.sample', { value }),
+  };
+  const textWords = useRef({ diagnosticWords, completionWords, t });
+  useLayoutEffect(() => {
+    textWords.current = { diagnosticWords, completionWords, t };
+  });
+
+  // Tooltip bodies are React, portalled into the DOM CodeMirror positions.
+  const [portals] = useState<TooltipPortals>(createTooltipPortals);
+
   const {
     language,
     templates = false,
@@ -220,7 +282,16 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     required,
     describedBy,
     reducedMotion,
+    diagnosticsStatus,
+    syntaxDiagnostics = true,
+    providers,
   } = props;
+  const pending =
+    diagnosticsStatus === 'checking' || diagnosticsStatus === 'stale';
+  const showGutter =
+    showLineNumbers ||
+    props.diagnostics !== undefined ||
+    providers?.lint !== undefined;
   const softDisabled = disabled && hasReason(disabledReason);
   const editable = !disabled && !readOnly;
   const live = templatesOn(language, templates);
@@ -247,11 +318,13 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     autocorrect: font === 'prose' ? 'on' : 'off',
     autocapitalize: 'off',
     ...(isCode ? { translate: 'no', dir: 'ltr' } : {}),
+    ...(pending ? { 'aria-busy': 'true' } : {}),
   };
   const rootClass = [
     font === 'prose' ? 'cm-prose' : '',
     fillHeight ? 'cm-fill' : '',
     readOnly || disabled ? 'cm-readonly' : '',
+    pending ? 'cm-diagnostics-pending' : '',
   ]
     .filter(Boolean)
     .join(' ');
@@ -342,6 +415,49 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       signature: String(reducedMotion),
       build: () => drawSelection({ cursorBlinkRate: reducedMotion ? 0 : 1200 }),
     },
+    diagnostics: {
+      signature: `${language}|${syntaxDiagnostics}|${showGutter}`,
+      build: () =>
+        diagnosticsExtension({
+          language,
+          syntax: syntaxDiagnostics,
+          gutter: showGutter,
+          words: () => textWords.current.diagnosticWords,
+          providers: () => latest.current.providers,
+          render: (view, items, focusFix) => (
+            <DiagnosticTooltipBody
+              items={items}
+              focusFix={focusFix}
+              onFix={(fix) => applyFix(view, fix)}
+            />
+          ),
+        }),
+    },
+    completion: {
+      signature: `${language}|${editable}|${providers?.completion !== undefined}`,
+      build: () =>
+        editable && providers?.completion !== undefined
+          ? completionExtension({
+              language,
+              providers: () => latest.current.providers,
+              words: () => textWords.current.completionWords,
+            })
+          : [],
+    },
+    hover: {
+      signature: language,
+      build: () =>
+        hoverExtension({
+          language,
+          providers: () => latest.current.providers,
+          render: (info) => <TypeTooltipBody info={info} />,
+          announce: (info) =>
+            textWords.current.t('typeInfo.announce', {
+              title: info.title ?? '',
+              type: info.type,
+            }),
+        }),
+    },
   };
   const slotsRef = useRef(slots);
   useLayoutEffect(() => {
@@ -387,6 +503,8 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
           memberObjects,
           codeHighlighting,
           codeEditorTheme,
+          tooltipPortals.of(portals),
+          tooltipPlacement,
           keymap.of([
             ...closeBracketsKeymap,
             ...defaultKeymap,
@@ -407,17 +525,17 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
               // CodeMirror finishes the composition after this event; apply
               // a value the host sent meanwhile once it has.
               setTimeout(() => {
-                const pending = pendingValue.current;
+                const waiting = pendingValue.current;
                 const current = viewRef.current;
                 if (
-                  pending === null ||
+                  waiting === null ||
                   current === null ||
                   current.compositionStarted
                 ) {
                   return;
                 }
                 pendingValue.current = null;
-                applyValue(current, pending);
+                applyValue(current, waiting);
               }, 0);
             },
           }),
@@ -446,8 +564,9 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
         view.focus();
         startCompletion(view);
       },
-      nextDiagnostic() {
+      nextDiagnostic(direction) {
         view.focus();
+        goToDiagnostic(view, direction);
       },
     });
     return () => {
@@ -455,7 +574,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       view.destroy();
       viewRef.current = null;
     };
-  }, []);
+  }, [portals]);
 
   // Reconfigure the parts whose props changed.
   useEffect(() => {
@@ -471,6 +590,23 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     if (effects.length > 0) view.dispatch({ effects });
   });
 
+  // The host's problems, placed on the text they were found in.
+  useEffect(() => {
+    const view = viewRef.current;
+    if (view === null) return;
+    view.dispatch({
+      effects: setDiagnostics.of({
+        source: 'host',
+        items: placeDiagnostics(
+          'host',
+          props.diagnostics ?? [],
+          view.state.doc,
+          props.diagnosticsFor,
+        ),
+      }),
+    });
+  }, [props.diagnostics, props.diagnosticsFor]);
+
   // The value prop: applied as the smallest change, never echoed.
   useEffect(() => {
     const view = viewRef.current;
@@ -486,6 +622,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
   return (
     <>
       <EditorIconSprite />
+      <TooltipPortalsHost portals={portals} viewRef={viewRef} />
       <div
         ref={host}
         className={fillHeight ? 'h-full min-h-0' : undefined}
@@ -513,6 +650,30 @@ function locatePart(
   return found === null ? undefined : [found.from, found.to];
 }
 
+/**
+ * Renders each open tooltip's React body into its CodeMirror element, then
+ * asks CodeMirror to measure again: the body arrives after the element.
+ */
+function TooltipPortalsHost({
+  portals,
+  viewRef,
+}: {
+  portals: TooltipPortals;
+  viewRef: { current: EditorView | null };
+}) {
+  const open = useSyncExternalStore(
+    portals.subscribe,
+    portals.snapshot,
+    portals.snapshot,
+  );
+  useLayoutEffect(() => {
+    viewRef.current?.requestMeasure();
+  }, [open, viewRef]);
+  return [...open].map(([dom, node], index) =>
+    createPortal(node, dom, `tooltip-${index}`),
+  );
+}
+
 function hasReason(reason: unknown): boolean {
   if (reason === undefined || reason === null || typeof reason === 'boolean') {
     return false;
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
index df5dbfb443..3db5e35784 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -2,11 +2,13 @@ import '@testing-library/jest-dom/vitest';
 import { EditorView } from '@codemirror/view';
 import { cleanup } from '@testing-library/react';
 import axe from 'axe-core';
-import { useRef, useState } from 'react';
+import type { i18n as I18n } from 'i18next';
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { page, userEvent } from 'vitest/browser';
+import { cdp, page, userEvent } from 'vitest/browser';
 
-import { act, render, screen, waitFor } from '@/tests/utils/render';
+import { act, render, screen, waitFor, within } from '@/tests/utils/render';
 
 import {
   ResponsiveDialog,
@@ -22,9 +24,11 @@ import {
 import {
   CodeEditor,
   preloadCodeEditor,
+  type CodeEditorDiagnostic,
   type CodeEditorHandle,
   type CodeEditorProps,
 } from './code-editor';
+import type { CodeEditorProviders } from './providers';
 
 import '../../../globals.css';
 
@@ -698,3 +702,685 @@ it('exposes a handle that focuses, selects and reports the selection', async ()
 it('preloads without rendering', async () => {
   expect(() => preloadCodeEditor()).not.toThrow();
 });
+
+/** A host that knows two nodes and their outputs, for completion and hover. */
+const SHAPES: CodeEditorProviders = {
+  completion: ({ path }) => {
+    if (path === null) return null;
+    if (path.length === 0) {
+      return {
+        items: [
+          { label: 'nodes', kind: 'variable', valueType: 'object' },
+          { label: 'input', kind: 'input', valueType: 'object' },
+        ],
+      };
+    }
+    if (path.length === 1 && path[0] === 'nodes') {
+      return {
+        items: [
+          {
+            label: 'score',
+            kind: 'node',
+            detail: 'Language model',
+            section: 'Earlier nodes',
+          },
+          {
+            label: 'open issues',
+            kind: 'node',
+            detail: 'Transform',
+            section: 'Earlier nodes',
+          },
+        ],
+      };
+    }
+    if (path.length === 2 && path[0] === 'nodes') {
+      return {
+        items: [
+          {
+            label: 'output',
+            kind: 'property',
+            valueType: 'object',
+            info: {
+              type: '{ total: number }',
+              description: 'What the node returns.',
+            },
+          },
+        ],
+      };
+    }
+    return { items: [] };
+  },
+  hover: ({ path }) =>
+    path !== null && path.join('.') === 'nodes.score'
+      ? { title: 'nodes.score', type: '{ output: { total: number } }' }
+      : null,
+};
+
+/**
+ * The open completion list, once it takes keys: CodeMirror ignores keys for
+ * its first 75 ms, so a list that opens under fast typing is not chosen from
+ * by accident.
+ */
+async function listbox(): Promise<HTMLElement> {
+  const list = await screen.findByRole('listbox', {}, { timeout: 5000 });
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  return list;
+}
+
+describe('CodeEditor completion', () => {
+  it('lists what can come after a dot, by keyboard', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial=""
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('nodes.');
+    const list = await listbox();
+    expect(box).toHaveAttribute('aria-autocomplete', 'list');
+    const options = [...list.querySelectorAll('[role="option"]')];
+    expect(
+      options.map(
+        (option) => option.querySelector('.cm-completionLabel')?.textContent,
+      ),
+    ).toEqual(['score', 'open issues']);
+    expect(box.getAttribute('aria-activedescendant')).toBe(options[0].id);
+    await userEvent.keyboard('{ArrowDown}');
+    expect(box.getAttribute('aria-activedescendant')).toBe(options[1].id);
+    await userEvent.keyboard('{ArrowUp}{Enter}');
+    expect(screen.getByTestId('value').textContent).toBe('nodes.score');
+  });
+
+  it('accepts with Tab, and quotes a name that is not an identifier', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial=""
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('nodes.');
+    await listbox();
+    await userEvent.keyboard('{ArrowDown}{Tab}');
+    expect(screen.getByTestId('value').textContent).toBe(
+      'nodes["open issues"]',
+    );
+  });
+
+  it('shows the type of an option in its info panel', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial="nodes.score"
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}.');
+    await listbox();
+    const info = await screen.findByText('What the node returns.');
+    expect(info.closest('.cm-completionInfo')?.textContent).toContain('total');
+  });
+
+  it('opens on Ctrl-Space where it would not open by itself', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial=""
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Control>} {/Control}');
+    const list = await listbox();
+    expect(list.textContent).toContain('nodes');
+  });
+
+  it('opens with the template roots after {{ in a prompt', async () => {
+    render(
+      <Controlled
+        language="markdown"
+        templates
+        providers={SHAPES}
+        initial="Hi "
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}{{{{');
+    const list = await listbox();
+    expect(list.textContent).toContain('input');
+  });
+
+  // Escape closes the list first; the sheet stays open.
+  it('closes the list before the sheet, at phone width', async () => {
+    await page.viewport(375, 800);
+    try {
+      function Host() {
+        const [open, setOpen] = useState(true);
+        const [value, setValue] = useState('');
+        return (
+          <>
+            <p>{open ? 'sheet open' : 'sheet closed'}</p>
+            <ResponsiveDialog open={open} onOpenChange={setOpen}>
+              <ResponsiveDialogContent>
+                <ResponsiveDialogTitle>Edit node</ResponsiveDialogTitle>
+                <div style={{ height: 120 }} />
+                <CodeEditor
+                  aria-label="Code"
+                  language="expression"
+                  singleLine
+                  value={value}
+                  onChange={setValue}
+                  providers={SHAPES}
+                />
+                <div style={{ height: 320 }} />
+              </ResponsiveDialogContent>
+            </ResponsiveDialog>
+          </>
+        );
+      }
+      render(<Host />);
+      const box = await content('Code');
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      await userEvent.click(box);
+      await userEvent.keyboard('nodes.');
+      const list = await listbox();
+      // The list sits inside the sheet.
+      const sheet = box.closest('[role="dialog"]') as HTMLElement;
+      const listBox = list.getBoundingClientRect();
+      const sheetBox = sheet.getBoundingClientRect();
+      expect(listBox.top).toBeGreaterThanOrEqual(sheetBox.top);
+      expect(listBox.bottom).toBeLessThanOrEqual(sheetBox.bottom + 1);
+      await userEvent.keyboard('{Escape}');
+      await waitFor(() => expect(screen.queryByRole('listbox')).toBeNull());
+      expect(screen.getByText('sheet open')).toBeInTheDocument();
+      await userEvent.keyboard('{Escape}');
+      expect(screen.getByText('sheet open')).toBeInTheDocument();
+      expect(announced(box)).toBe('Press Tab to move on.');
+      await userEvent.keyboard('{Escape}');
+      await waitFor(() =>
+        expect(screen.getByText('sheet closed')).toBeInTheDocument(),
+      );
+    } finally {
+      await page.viewport(1280, 800);
+    }
+  });
+});
+
+describe('CodeEditor completion in German', () => {
+  const shared: { i18n?: I18n } = {};
+  function CaptureI18n() {
+    const { i18n } = useTranslation();
+    useEffect(() => {
+      shared.i18n = i18n;
+    }, [i18n]);
+    return null;
+  }
+  afterEach(async () => {
+    cleanup();
+    localStorage.removeItem('user-locale');
+    await shared.i18n?.changeLanguage('en-US');
+  });
+
+  it("names the list in the reader's language", async () => {
+    localStorage.setItem('user-locale', 'de');
+    render(
+      <>
+        <CaptureI18n />
+        <Controlled
+          language="expression"
+          singleLine
+          providers={SHAPES}
+          initial=""
+        />
+      </>,
+    );
+    const box = await content();
+    await userEvent.click(box);
+    await userEvent.keyboard('nodes.');
+    const list = await listbox();
+    expect(list).toHaveAttribute('aria-label', 'Vorschläge');
+  });
+});
+
+describe('CodeEditor problems', () => {
+  const unknown: CodeEditorDiagnostic = {
+    id: 'ref',
+    severity: 'error',
+    message: 'Reads "nope", and there is no node with that id.',
+    code: 'REF_UNKNOWN_NODE',
+    range: [6, 10],
+    fixes: [
+      { label: 'Read "score"', changes: [{ range: [6, 10], insert: 'score' }] },
+    ],
+  };
+  const note: CodeEditorDiagnostic = {
+    id: 'note',
+    severity: 'warning',
+    message: 'May be empty.',
+    range: [11, 17],
+  };
+
+  it('underlines each problem by severity and marks its line', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope.output"
+        diagnostics={[unknown, note]}
+      />,
+    );
+    const box = await content('Code');
+    const error = box.querySelector('.cm-diagnostic-error');
+    const warning = box.querySelector('.cm-diagnostic-warning');
+    expect(error?.textContent).toBe('nope');
+    expect(warning?.textContent).toBe('output');
+    expect(getComputedStyle(error as HTMLElement).textDecorationStyle).toBe(
+      'wavy',
+    );
+    const gutter = box
+      .closest('.cm-editor')
+      ?.querySelector('.cm-diagnostic-gutter .cm-gutterElement svg');
+    expect(gutter).not.toBeNull();
+  });
+
+  it('shows the problem, its code and its fix on hover', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope.output"
+        diagnostics={[unknown]}
+      />,
+    );
+    const box = await content('Code');
+    const error = box.querySelector('.cm-diagnostic-error') as HTMLElement;
+    await userEvent.hover(error);
+    expect(
+      await screen.findByText(unknown.message, {}, { timeout: 3000 }),
+    ).toBeInTheDocument();
+    expect(screen.getByText('REF_UNKNOWN_NODE')).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: 'Read "score"' }),
+    ).toBeInTheDocument();
+  });
+
+  it('walks the problems with F8 and reads each aloud', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope.output"
+        diagnostics={[unknown, note]}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Home}{F8}');
+    expect(selection(box)).toEqual([6, 10]);
+    expect(announced(box)).toBe(
+      'Error on line 1: Reads "nope", and there is no node with that id. Fix available: press ' +
+        (MOD === 'Meta' ? '⌘.' : 'Ctrl+.') +
+        '.',
+    );
+    await userEvent.keyboard('{F8}');
+    expect(selection(box)).toEqual([11, 17]);
+    expect(announced(box)).toBe('Warning on line 1: May be empty.');
+    await userEvent.keyboard('{Shift>}{F8}{/Shift}');
+    expect(selection(box)).toEqual([6, 10]);
+  });
+
+  it('applies the one fix with Mod-. and says so', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope.output"
+        diagnostics={[unknown]}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Home}{F8}');
+    await userEvent.keyboard(`{${MOD}>}.{/${MOD}}`);
+    expect(screen.getByTestId('value').textContent).toBe('nodes.score.output');
+    expect(announced(box)).toBe('Applied: Read "score"');
+  });
+
+  it('describes its problems, and only when asked to', async () => {
+    const { rerender } = render(
+      <CodeEditor
+        aria-label="Code"
+        language="expression"
+        value="nodes.nope.output"
+        diagnostics={[unknown]}
+      />,
+    );
+    const box = await content('Code');
+    const described = () =>
+      (box.getAttribute('aria-describedby') ?? '')
+        .split(' ')
+        .map((id) => document.getElementById(id)?.textContent ?? '')
+        .join(' ');
+    expect(described()).toContain('1 error.');
+    expect(described()).toContain('Line 1: Reads "nope"');
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="expression"
+        value="nodes.nope.output"
+        diagnostics={[unknown]}
+        describeDiagnostics={false}
+      />,
+    );
+    await waitFor(() => expect(described()).not.toContain('1 error.'));
+  });
+
+  // The host's own announcer says a check's result once; new problems
+  // arriving as a prop must not make the editor speak.
+  it('announces nothing when new problems arrive', async () => {
+    const { rerender } = render(
+      <CodeEditor aria-label="Code" language="expression" value="nodes.nope" />,
+    );
+    const box = await content('Code');
+    rerender(
+      <CodeEditor
+        aria-label="Code"
+        language="expression"
+        value="nodes.nope"
+        diagnostics={[unknown]}
+      />,
+    );
+    await waitFor(() =>
+      expect(box.querySelector('.cm-diagnostic-error')).not.toBeNull(),
+    );
+    expect(announced(box)).toBe('');
+  });
+
+  it('keeps a problem in place while the reader types before it', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope"
+        diagnostics={[{ ...unknown, fixes: [] }]}
+        diagnosticsFor="nodes.nope"
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Home}x');
+    expect(box.querySelector('.cm-diagnostic-error')?.textContent).toBe('nope');
+  });
+
+  it('marks text that does not parse, after a pause and away from the cursor', async () => {
+    render(<Controlled language="json" initial={'{"a": 1,, "b": 2}'} />);
+    const box = await content('Code');
+    await waitFor(
+      () => expect(box.querySelector('.cm-diagnostic-error')).not.toBeNull(),
+      { timeout: 3000 },
+    );
+    const mark = box.querySelector('.cm-diagnostic-error') as HTMLElement;
+    await userEvent.hover(mark);
+    expect(
+      await screen.findByText(
+        "This isn't valid JSON here.",
+        {},
+        { timeout: 3000 },
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it('marks a {{ that never closes', async () => {
+    render(<Controlled language="template" initial="Hi {{ name" />);
+    const box = await content('Code');
+    await waitFor(
+      () =>
+        expect(box.querySelector('.cm-diagnostic-error')?.textContent).toBe(
+          '{{',
+        ),
+      { timeout: 3000 },
+    );
+  });
+
+  it('fades its underlines while a check runs', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope"
+        diagnostics={[unknown]}
+        diagnosticsStatus="checking"
+      />,
+    );
+    const box = await content('Code');
+    expect(box.closest('.cm-editor')).toHaveClass('cm-diagnostics-pending');
+    expect(box).toHaveAttribute('aria-busy', 'true');
+  });
+});
+
+describe('CodeEditor types', () => {
+  it('shows the type under the pointer', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial="nodes.score.output"
+      />,
+    );
+    const box = await content('Code');
+    const word = [...box.querySelectorAll('span')].find(
+      (span) => span.textContent === 'score',
+    );
+    await userEvent.hover(word as HTMLElement);
+    const title = await screen.findByText('nodes.score', {}, { timeout: 3000 });
+    expect(title.closest('.cm-tooltip')?.textContent).toContain('total');
+  });
+
+  it('reads the type at the cursor aloud on Mod-K Mod-I', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial="nodes.score.output"
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    act(() => {
+      viewOf(box).dispatch({ selection: { anchor: 8 } });
+    });
+    await userEvent.keyboard(`{${MOD}>}k{/${MOD}}{${MOD}>}i{/${MOD}}`);
+    await waitFor(() =>
+      expect(announced(box)).toBe('nodes.score: { output: { total: number } }'),
+    );
+    await userEvent.keyboard('{Escape}');
+    await waitFor(() =>
+      expect(document.querySelector('.cm-tooltip')).toBeNull(),
+    );
+  });
+});
+
+describe('CodeEditor expand', () => {
+  it('edits in a large dialog and brings the caret back', async () => {
+    render(
+      <Controlled
+        language="javascript"
+        expandable
+        initial={'const a = 1;\nreturn a;'}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.click(
+      screen.getByRole('button', { name: 'Expand editor' }),
+    );
+    const dialog = await screen.findByRole('dialog');
+    const big = await within(dialog).findByRole(
+      'textbox',
+      {},
+      { timeout: 5000 },
+    );
+    await waitFor(() => expect(big).toHaveFocus());
+    await userEvent.keyboard('{End} // more');
+    expect(screen.getByTestId('value').textContent).toBe(
+      'const a = 1;\nreturn a; // more',
+    );
+    const caret = selection(big);
+    await userEvent.click(
+      within(dialog).getByRole('button', { name: 'Back to the field' }),
+    );
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+    await waitFor(() => expect(box).toHaveFocus());
+    expect(box.textContent).toContain('return a; // more');
+    expect(selection(box)).toEqual(caret);
+  });
+});
+
+describe('CodeEditor problem tooltips by keyboard', () => {
+  const two: CodeEditorDiagnostic = {
+    id: 'two',
+    severity: 'error',
+    message: 'Reads a node that does not exist.',
+    range: [6, 10],
+    fixes: [
+      { label: 'Read "score"', changes: [{ range: [6, 10], insert: 'score' }] },
+      {
+        label: 'Read "report"',
+        changes: [{ range: [6, 10], insert: 'report' }],
+      },
+    ],
+  };
+
+  it('offers several fixes as buttons, chosen with the arrows', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope"
+        diagnostics={[two]}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Home}{F8}');
+    await userEvent.keyboard(`{${MOD}>}.{/${MOD}}`);
+    const first = await screen.findByRole('button', { name: 'Read "score"' });
+    await waitFor(() => expect(first).toHaveFocus());
+    await userEvent.keyboard('{ArrowDown}');
+    expect(screen.getByRole('button', { name: 'Read "report"' })).toHaveFocus();
+    await userEvent.keyboard('{Enter}');
+    expect(screen.getByTestId('value').textContent).toBe('nodes.report');
+    expect(box).toHaveFocus();
+  });
+
+  it('closes the tooltip with Escape before arming leave', async () => {
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        initial="nodes.nope"
+        diagnostics={[two]}
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('{Home}{F8}');
+    expect(await screen.findByText(two.message)).toBeInTheDocument();
+    await userEvent.keyboard('{Escape}');
+    await waitFor(() => expect(screen.queryByText(two.message)).toBeNull());
+    expect(announced(box)).not.toBe('Press Tab to move on.');
+    await userEvent.keyboard('{Escape}');
+    expect(announced(box)).toBe('Press Tab to move on.');
+  });
+});
+
+describe.each(['light', 'dark'])('CodeEditor popups (%s)', (theme) => {
+  it('keeps the open list and a problem tooltip accessible', async () => {
+    document.documentElement.classList.toggle('dark', theme === 'dark');
+    const problem: CodeEditorDiagnostic = {
+      id: 'p',
+      severity: 'warning',
+      message: 'May be empty.',
+      code: 'MAYBE_NULL',
+      range: [0, 5],
+    };
+    render(
+      <div className="bg-background p-4">
+        <Controlled
+          language="expression"
+          singleLine
+          providers={SHAPES}
+          initial="nodes"
+          diagnostics={[problem]}
+        />
+      </div>,
+    );
+    const box = await content('Code');
+    await userEvent.hover(
+      box.querySelector('.cm-diagnostic-warning') as HTMLElement,
+    );
+    await screen.findByText('MAYBE_NULL', {}, { timeout: 3000 });
+    await userEvent.click(box);
+    await userEvent.keyboard('{End}.');
+    await listbox();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    const result = await axe.run(document.body, {
+      runOnly: [
+        'color-contrast',
+        'aria-allowed-attr',
+        'aria-valid-attr-value',
+        'aria-required-children',
+        'aria-required-parent',
+        'button-name',
+      ],
+    });
+    expect(result.violations).toEqual([]);
+  });
+});
+
+describe('CodeEditor under reduced motion', () => {
+  afterEach(async () => {
+    await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+  });
+
+  it('opens the list without animation and keeps the caret steady', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    render(
+      <Controlled
+        language="expression"
+        singleLine
+        providers={SHAPES}
+        initial=""
+      />,
+    );
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard('nodes.');
+    await listbox();
+    const tooltip = document.querySelector(
+      '.cm-tooltip-autocomplete',
+    ) as HTMLElement;
+    expect(getComputedStyle(tooltip).animationName).toBe('none');
+    const layer = box
+      .closest('.cm-editor')
+      ?.querySelector<HTMLElement>('.cm-cursorLayer');
+    expect(layer?.style.animationDuration).toBe('0ms');
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.tsx b/packages/ui/src/components/forms/code-editor/code-editor.tsx
index 51e55c9eec..bbd3c50be0 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.tsx
@@ -12,6 +12,7 @@
  * renders no code field never downloads it.
  */
 
+import { Maximize2 } from 'lucide-react';
 import {
   forwardRef,
   lazy,
@@ -20,6 +21,7 @@ import {
   useEffect,
   useId,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
   type CSSProperties,
@@ -35,6 +37,13 @@ import {
   DisabledReasonTooltip,
   hasDisabledReason,
 } from '../../overlays/disabled-reason';
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogTitle,
+} from '../../overlays/responsive-dialog';
+import { Button } from '../../primitives/button';
+import { IconButton } from '../../primitives/icon-button';
 import { FIELD_FOCUS_WITHIN, FIELD_INVALID_WITHIN } from '../field-focus';
 import {
   useIssueFocusTarget,
@@ -42,7 +51,11 @@ import {
   type IssueFocusRange,
 } from '../issue-focus';
 import type { CodeEditorViewHandle } from './code-editor-view';
-import type { CodeEditorHandle, CodeEditorProps } from './types';
+import type {
+  CodeEditorDiagnostic,
+  CodeEditorHandle,
+  CodeEditorProps,
+} from './types';
 
 export type {
   CodeEditorDiagnostic,
@@ -96,6 +109,53 @@ const SIZE_CLASS = {
 
 const CODE_LANGUAGES = new Set(['javascript', 'expression', 'json', 'yaml']);
 
+/** The line `offset` is on, 1-based. */
+function lineOf(text: string, offset: number): number {
+  let line = 1;
+  for (let i = 0; i < Math.min(offset, text.length); i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+/**
+ * The words a screen reader hears for a field's problems: the count, then
+ * the first three with their lines.
+ */
+function useProblemSummary(
+  diagnostics: readonly CodeEditorDiagnostic[] | undefined,
+  text: string,
+  ready: boolean,
+): string {
+  const { t } = useT('codeEditor');
+  const { t: tIssues } = useT('issues');
+  const settled = useRef('');
+  return useMemo(() => {
+    if (!ready) return settled.current;
+    const list = diagnostics ?? [];
+    if (list.length === 0) {
+      settled.current = '';
+      return '';
+    }
+    const errors = list.filter((d) => d.severity === 'error').length;
+    const warnings = list.filter((d) => d.severity === 'warning').length;
+    const parts = [
+      `${tIssues('summary', { errors, warnings })}.`,
+      ...list.slice(0, 3).map((d) =>
+        t('diagnostics.lineItem', {
+          line: lineOf(text, d.range?.[0] ?? 0),
+          message: d.message,
+        }),
+      ),
+    ];
+    if (list.length > 3) {
+      parts.push(`${t('diagnostics.more', { count: list.length - 3 })}.`);
+    }
+    settled.current = parts.join(' ');
+    return settled.current;
+  }, [diagnostics, text, ready, t, tIssues]);
+}
+
 interface PendingFocus {
   range: IssueFocusRange | undefined;
   part: IssueFocusPart | undefined;
@@ -122,6 +182,8 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
       submitLabel,
       issueAnchor = null,
       issueReveal,
+      expandable = false,
+      describeDiagnostics = true,
       className,
     } = props;
     const { t } = useT('codeEditor');
@@ -130,16 +192,24 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
     const baseId = useId();
     const keyboardHintId = `${baseId}-keyboard`;
     const submitHintId = `${baseId}-submit`;
+    const summaryId = `${baseId}-summary`;
     const softDisabled = disabled && hasDisabledReason(disabledReason);
     const editable = !readOnly && !disabled;
     const capturesTab = editable && !singleLine;
     const shortcut = isMac ? '⌘↵' : 'Ctrl+Enter';
     const canSubmit = onSubmit !== undefined && submitLabel !== undefined;
     const invalid = props['aria-invalid'] === true;
+    const summary = useProblemSummary(
+      props.diagnostics,
+      props.diagnosticsFor ?? value,
+      (props.diagnosticsStatus ?? 'ready') === 'ready',
+    );
+    const summarize = describeDiagnostics && summary !== '';
 
     const describedBy =
       [
         props['aria-describedby'],
+        summarize ? summaryId : undefined,
         capturesTab ? keyboardHintId : undefined,
         canSubmit ? submitHintId : undefined,
       ]
@@ -191,6 +261,35 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
       issueReveal === undefined ? undefined : { reveal: issueReveal },
     );
 
+    // Expand: the same field in a large dialog, the caret carried both ways.
+    const [expanded, setExpanded] = useState(false);
+    const [expandSelection, setExpandSelection] = useState<
+      readonly [number, number] | undefined
+    >(undefined);
+    const expandedEditor = useRef<CodeEditorHandle>(null);
+    const expandTitle =
+      typeof expandable === 'object'
+        ? expandable.title
+        : (props['aria-label'] ?? t('expand'));
+    const openExpanded = () => {
+      setExpandSelection(viewHandle.current?.getSelection() ?? undefined);
+      setExpanded(true);
+    };
+    useEffect(() => {
+      if (!expanded) return undefined;
+      // Into the large editor, at the caret the field had.
+      const frame = requestAnimationFrame(() =>
+        expandedEditor.current?.focus(expandSelection),
+      );
+      return () => cancelAnimationFrame(frame);
+    }, [expanded, expandSelection]);
+    const closeExpanded = () => {
+      const selection = expandedEditor.current?.getSelection() ?? undefined;
+      setExpanded(false);
+      // Back in the field, with the caret where the dialog left it.
+      requestAnimationFrame(() => focus(selection));
+    };
+
     // The shortcut legend follows keyboard use inside the frame.
     const frameRef = useRef<HTMLDivElement>(null);
     const [keyboardFocus, setKeyboardFocus] = useState(false);
@@ -243,6 +342,7 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
             'cursor-not-allowed bg-[color:var(--color-bg-elevated)] text-[color:var(--color-fg-subtle)] [&_.cm-content]:opacity-70',
           invalid && FIELD_INVALID_WITHIN,
           fillHeight && 'flex h-full min-h-0 flex-1 flex-col',
+          expandable !== false && '[&_.cm-content]:pr-7',
           className,
         )}
       >
@@ -268,6 +368,21 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
             onView={onView}
           />
         </Suspense>
+        {expandable !== false ? (
+          <IconButton
+            icon={Maximize2}
+            iconSize={3}
+            size="sm"
+            aria-label={t('expand')}
+            onClick={openExpanded}
+            className="absolute top-1 right-1 z-10 size-6 opacity-0 transition-opacity duration-[var(--duration-short)] group-focus-within/code-editor:opacity-100 group-hover/code-editor:opacity-100 focus-visible:opacity-100 motion-reduce:transition-none pointer-coarse:opacity-100 pointer-coarse:after:absolute pointer-coarse:after:-inset-2.5 pointer-coarse:after:content-['']"
+          />
+        ) : null}
+        {summarize ? (
+          <span id={summaryId} hidden>
+            {summary}
+          </span>
+        ) : null}
         {capturesTab ? (
           <span id={keyboardHintId} hidden>
             {t('keyboardHint')}
@@ -296,9 +411,56 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
     );
 
     return (
-      <DisabledReasonTooltip reason={disabledReason} active={softDisabled}>
-        {frame}
-      </DisabledReasonTooltip>
+      <>
+        <DisabledReasonTooltip reason={disabledReason} active={softDisabled}>
+          {frame}
+        </DisabledReasonTooltip>
+        {expandable !== false ? (
+          <ResponsiveDialog
+            open={expanded}
+            onOpenChange={(open) => {
+              if (open) setExpanded(true);
+              else closeExpanded();
+            }}
+          >
+            <ResponsiveDialogContent
+              preventCloseAutoFocus
+              onOpenAutoFocus={(event) => event.preventDefault()}
+              className="flex h-[85dvh] flex-col gap-3 md:h-[80dvh] md:max-w-4xl"
+            >
+              <ResponsiveDialogTitle>{expandTitle}</ResponsiveDialogTitle>
+              {expanded ? (
+                <div className="flex min-h-0 flex-1 flex-col">
+                  <CodeEditorBase
+                    {...props}
+                    ref={expandedEditor}
+                    id={undefined}
+                    issueAnchor={null}
+                    expandable={false}
+                    className={undefined}
+                    aria-label={expandTitle}
+                    aria-labelledby={undefined}
+                    size="md"
+                    lineNumbers
+                    fold
+                    fillHeight
+                    initialSelection={expandSelection}
+                  />
+                </div>
+              ) : null}
+              <div className="flex justify-end">
+                <Button
+                  type="button"
+                  variant="secondary"
+                  onClick={closeExpanded}
+                >
+                  {t('collapse')}
+                </Button>
+              </div>
+            </ResponsiveDialogContent>
+          </ResponsiveDialog>
+        ) : null}
+      </>
     );
   },
 );
diff --git a/packages/ui/src/components/forms/code-editor/diagnostic-mapping.test.ts b/packages/ui/src/components/forms/code-editor/diagnostic-mapping.test.ts
new file mode 100644
index 0000000000..8dc411cc0a
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/diagnostic-mapping.test.ts
@@ -0,0 +1,179 @@
+import { EditorState, Text } from '@codemirror/state';
+import { describe, expect, it } from 'vitest';
+
+import {
+  diagnosticState,
+  placeDiagnostics,
+  setDiagnostics,
+  shownDiagnostics,
+} from './extensions/diagnostics';
+import type { CodeEditorDiagnostic } from './types';
+
+function problem(
+  id: string,
+  range: readonly [number, number] | undefined,
+  extra: Partial<CodeEditorDiagnostic> = {},
+): CodeEditorDiagnostic {
+  return {
+    id,
+    severity: 'error',
+    message: `problem ${id}`,
+    ...(range === undefined ? {} : { range }),
+    ...extra,
+  };
+}
+
+function spans(items: ReturnType<typeof placeDiagnostics>) {
+  return items.map((item) =>
+    item.whole
+      ? [item.diagnostic.id, 'whole']
+      : [item.diagnostic.id, item.from, item.to],
+  );
+}
+
+describe('placeDiagnostics', () => {
+  const doc = Text.of(['const a = nodes.nope;', 'return a;']);
+
+  it('keeps ranges into the text shown, widening an empty one', () => {
+    expect(
+      spans(
+        placeDiagnostics(
+          'host',
+          [
+            problem('a', [10, 20]),
+            problem('b', [6, 6]),
+            problem('c', undefined),
+          ],
+          doc,
+        ),
+      ),
+    ).toEqual([
+      ['a', 10, 20],
+      ['b', 6, 7],
+      ['c', 'whole'],
+    ]);
+  });
+
+  // The host checked an older text; the reader typed since.
+  it('maps ranges from the checked text and hides those the edit touched', () => {
+    const checked = 'const a = nodes.nope;\nreturn a;';
+    const now = Text.of(['const abc = nodes.nope;', 'return a;']);
+    expect(
+      spans(
+        placeDiagnostics(
+          'host',
+          [
+            problem('before', [0, 5]),
+            problem('inside', [6, 7]),
+            problem('after', [10, 20]),
+          ],
+          now,
+          checked,
+        ),
+      ),
+    ).toEqual([
+      ['before', 0, 5],
+      ['after', 12, 22],
+    ]);
+  });
+
+  it('drops a fix whose text was edited, keeps one that was not', () => {
+    const checked = 'a b';
+    const now = Text.of(['a bc']);
+    const [placed] = placeDiagnostics(
+      'host',
+      [
+        problem('x', [0, 1], {
+          fixes: [
+            { label: 'keep', changes: [{ range: [0, 1], insert: 'A' }] },
+            { label: 'lose', changes: [{ range: [2, 3], insert: 'B' }] },
+          ],
+        }),
+      ],
+      now,
+      checked,
+    );
+    expect(placed.fixes.map((fix) => fix.label)).toEqual(['keep']);
+  });
+});
+
+describe('the diagnostics state', () => {
+  function state(doc: string) {
+    return EditorState.create({ doc, extensions: [diagnosticState] });
+  }
+
+  it('shows a lint problem unless the host reports the same code there', () => {
+    let current = state('nodes.nope + nodes.other');
+    current = current.update({
+      effects: [
+        setDiagnostics.of({
+          source: 'host',
+          items: placeDiagnostics(
+            'host',
+            [problem('h', [0, 10], { code: 'REF' })],
+            current.doc,
+          ),
+        }),
+        setDiagnostics.of({
+          source: 'lint',
+          items: placeDiagnostics(
+            'lint',
+            [
+              problem('same', [6, 10], { code: 'REF' }),
+              problem('other', [13, 24], { code: 'REF' }),
+            ],
+            current.doc,
+          ),
+        }),
+      ],
+    }).state;
+    expect(shownDiagnostics(current).map((d) => d.diagnostic.id)).toEqual([
+      'h',
+      'other',
+    ]);
+  });
+
+  it('hides a syntax mark that another problem covers', () => {
+    let current = state('{"a": }');
+    current = current.update({
+      effects: [
+        setDiagnostics.of({
+          source: 'host',
+          items: placeDiagnostics('host', [problem('h', [5, 7])], current.doc),
+        }),
+        setDiagnostics.of({
+          source: 'syntax',
+          items: placeDiagnostics(
+            'syntax',
+            [problem('s1', [6, 7]), problem('s2', [0, 1])],
+            current.doc,
+          ),
+        }),
+      ],
+    }).state;
+    expect(shownDiagnostics(current).map((d) => d.diagnostic.id)).toEqual([
+      's2',
+      'h',
+    ]);
+  });
+
+  it('maps problems through an edit and hides the one the edit touches', () => {
+    let current = state('aaa bbb ccc');
+    current = current.update({
+      effects: setDiagnostics.of({
+        source: 'host',
+        items: placeDiagnostics(
+          'host',
+          [problem('a', [0, 3]), problem('b', [4, 7]), problem('c', [8, 11])],
+          current.doc,
+        ),
+      }),
+    }).state;
+    current = current.update({ changes: { from: 5, insert: 'XX' } }).state;
+    expect(spans([...shownDiagnostics(current)])).toEqual([
+      ['a', 0, 3],
+      ['c', 10, 13],
+    ]);
+    expect(current.field(diagnosticState).host).toHaveLength(2);
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/extensions/completion.ts b/packages/ui/src/components/forms/code-editor/extensions/completion.ts
new file mode 100644
index 0000000000..24dff616a5
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/completion.ts
@@ -0,0 +1,262 @@
+import {
+  acceptCompletion,
+  autocompletion,
+  insertCompletionText,
+  type Completion,
+  type CompletionContext,
+  type CompletionResult,
+} from '@codemirror/autocomplete';
+import { Prec, type Extension } from '@codemirror/state';
+import { keymap, type EditorView } from '@codemirror/view';
+
+import type { CodeLanguage } from '../../../../lib/code-roles';
+import { editorIcon, type EditorIconName } from '../icon-sprite';
+import { cursorContext, type CursorContext } from '../member-path';
+import type {
+  CodeCompletionItem,
+  CodeCompletionKind,
+  CodeEditorProviders,
+  CodeValueType,
+} from '../providers';
+import { highlightType } from './highlight';
+
+/**
+ * Completion from the host's provider: the editor works out where the
+ * cursor is (the member chain, a JSON or YAML key) and asks; the host says
+ * what can come next. A name that is not an identifier goes in as
+ * `["a b"]`, a number as `[0]`. The list opens as the reader types a name,
+ * a `.` or a `[` in code, a key in JSON or YAML, or on Ctrl-Space anywhere.
+ */
+
+export interface CompletionWords {
+  type: string;
+  optional: string;
+  sample: (value: string) => string;
+}
+
+export interface CompletionConfig {
+  language: CodeLanguage;
+  providers: () => CodeEditorProviders | undefined;
+  words: () => CompletionWords;
+}
+
+interface TaleCompletion extends Completion {
+  item: CodeCompletionItem;
+  /** The provider's order, kept among equally good matches. */
+  order: number;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const INDEX = /^(?:0|[1-9]\d*)$/;
+
+const KIND_ICON: Record<CodeCompletionKind, EditorIconName | null> = {
+  node: 'workflow',
+  input: 'log-in',
+  method: 'square-function',
+  function: 'square-function',
+  keyword: 'key-round',
+  constant: 'pi',
+  snippet: 'code-xml',
+  variable: null,
+  property: null,
+};
+
+const VALUE_ICON: Record<CodeValueType, EditorIconName> = {
+  string: 'type',
+  number: 'hash',
+  integer: 'hash',
+  boolean: 'toggle-left',
+  object: 'braces',
+  array: 'brackets',
+  null: 'ban',
+  unknown: 'circle-dashed',
+};
+
+function iconFor(item: CodeCompletionItem): EditorIconName {
+  const kind = item.kind === undefined ? null : KIND_ICON[item.kind];
+  return kind ?? VALUE_ICON[item.valueType ?? 'unknown'];
+}
+
+function shorten(text: string, max = 40): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+/** How a chosen name is written at the cursor. */
+function applyFor(
+  item: CodeCompletionItem,
+  cursor: CursorContext,
+): Completion['apply'] {
+  if (item.apply !== undefined) return item.apply;
+  const label = item.label;
+  const plain = IDENTIFIER.test(label);
+  if (cursor.trigger === 'bracket') {
+    return INDEX.test(label) ? `${label}]` : `${JSON.stringify(label)}]`;
+  }
+  if (plain) return label;
+  if (cursor.trigger !== 'dot') return label;
+  const subscript = INDEX.test(label)
+    ? `[${label}]`
+    : `[${JSON.stringify(label)}]`;
+  return (
+    view: EditorView,
+    _completion: Completion,
+    from: number,
+    to: number,
+  ) => {
+    // Replace the `.` (or keep `?.`) before the name with the subscript.
+    const optional = view.state.doc.sliceString(from - 2, from) === '?.';
+    const start = optional ? from : from - 1;
+    view.dispatch(insertCompletionText(view.state, subscript, start, to));
+  };
+}
+
+function infoFor(
+  item: CodeCompletionItem,
+  words: CompletionWords,
+): Completion['info'] {
+  const info = item.info;
+  if (info === undefined && !item.optional) return undefined;
+  return () => {
+    const dom = document.createElement('div');
+    dom.className = 'flex max-w-80 flex-col gap-1 p-2 text-xs';
+    if (info?.type !== undefined) {
+      const type = document.createElement('code');
+      type.className = 'font-mono break-words whitespace-pre-wrap';
+      type.setAttribute('aria-label', `${words.type}: ${info.type}`);
+      for (const run of highlightType(info.type)) {
+        const span = document.createElement('span');
+        span.textContent = run.text;
+        if (run.className !== '') span.className = run.className;
+        type.appendChild(span);
+      }
+      dom.appendChild(type);
+    }
+    if (info?.description !== undefined) {
+      const description = document.createElement('p');
+      description.className = 'text-foreground';
+      description.textContent = info.description;
+      dom.appendChild(description);
+    }
+    if (info?.sample !== undefined) {
+      const sample = document.createElement('p');
+      sample.className = 'text-muted-foreground font-mono break-all';
+      sample.textContent = words.sample(info.sample);
+      dom.appendChild(sample);
+    }
+    if (item.optional) {
+      const optional = document.createElement('p');
+      optional.className = 'text-muted-foreground';
+      optional.textContent = words.optional;
+      dom.appendChild(optional);
+    }
+    return dom;
+  };
+}
+
+function toCompletion(
+  item: CodeCompletionItem,
+  order: number,
+  cursor: CursorContext,
+  words: CompletionWords,
+): TaleCompletion {
+  return {
+    item,
+    order,
+    label: item.label,
+    ...(item.optional ? { displayLabel: `${item.label}?` } : {}),
+    ...(item.detail !== undefined ? { detail: shorten(item.detail) } : {}),
+    ...(item.section !== undefined ? { section: item.section } : {}),
+    ...(item.boost !== undefined ? { boost: item.boost } : {}),
+    type: item.kind ?? 'property',
+    apply: applyFor(item, cursor),
+    info: infoFor(item, words),
+  };
+}
+
+/** Whether the cursor invites a list without Ctrl-Space. */
+function opensByItself(cursor: CursorContext): boolean {
+  if (cursor.region === 'code' || cursor.region === 'template') {
+    return cursor.trigger !== 'none';
+  }
+  if (cursor.region === 'key') return cursor.word !== '';
+  return false;
+}
+
+function completionSource(config: CompletionConfig) {
+  return async (
+    context: CompletionContext,
+  ): Promise<CompletionResult | null> => {
+    const provider = config.providers()?.completion;
+    if (provider === undefined) return null;
+    const cursor = cursorContext(context.state, context.pos);
+    if (!context.explicit && !opensByItself(cursor)) return null;
+    const controller = new AbortController();
+    context.addEventListener('abort', () => controller.abort(), {
+      onDocChange: true,
+    });
+    const answer = await provider({
+      text: context.state.doc.toString(),
+      pos: context.pos,
+      language: config.language,
+      region: cursor.region,
+      path: cursor.path,
+      prefix: cursor.word,
+      from: cursor.from,
+      to: cursor.to,
+      ...(cursor.pointer !== undefined ? { pointer: cursor.pointer } : {}),
+      explicit: context.explicit,
+      signal: controller.signal,
+    });
+    if (answer === null || controller.signal.aborted) return null;
+    const words = config.words();
+    return {
+      from: cursor.from,
+      to: cursor.to,
+      options: answer.items.map((item, order) =>
+        toCompletion(item, order, cursor, words),
+      ),
+      validFor: answer.validFor ?? /^[\w$]*$/,
+    };
+  };
+}
+
+function isTaleCompletion(
+  completion: Completion,
+): completion is TaleCompletion {
+  return 'item' in completion;
+}
+
+export function completionExtension(config: CompletionConfig): Extension {
+  return [
+    autocompletion({
+      override: [completionSource(config)],
+      activateOnTyping: true,
+      selectOnOpen: true,
+      closeOnBlur: true,
+      maxRenderedOptions: 60,
+      icons: false,
+      // Equally good matches keep the host's order (earlier nodes first).
+      compareCompletions: (a, b) =>
+        isTaleCompletion(a) && isTaleCompletion(b)
+          ? a.order - b.order
+          : a.label.localeCompare(b.label),
+      optionClass: () => 'pointer-coarse:min-h-9',
+      tooltipClass: () =>
+        'cm-tale-completion motion-safe:animate-in motion-safe:fade-in-0 motion-safe:zoom-in-95 motion-safe:duration-[var(--duration-micro)] motion-safe:ease-[var(--ease-out-quint)]',
+      addToOptions: [
+        {
+          position: 20,
+          render: (option) =>
+            isTaleCompletion(option)
+              ? editorIcon(
+                  iconFor(option.item),
+                  'size-3.5 text-muted-foreground',
+                )
+              : null,
+        },
+      ],
+    }),
+    // Tab accepts while the list is open; otherwise it indents or moves on.
+    Prec.highest(keymap.of([{ key: 'Tab', run: acceptCompletion }])),
+  ];
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts b/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
new file mode 100644
index 0000000000..970ca4986f
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
@@ -0,0 +1,728 @@
+import { syntaxTree } from '@codemirror/language';
+import {
+  EditorSelection,
+  Facet,
+  RangeSet,
+  RangeSetBuilder,
+  StateEffect,
+  StateField,
+  type EditorState,
+  type Extension,
+  type Text,
+  type Transaction,
+} from '@codemirror/state';
+import {
+  Decoration,
+  EditorView,
+  gutter,
+  GutterMarker,
+  hoverTooltip,
+  keymap,
+  showTooltip,
+  ViewPlugin,
+  type PluginValue,
+  type Tooltip,
+  type ViewUpdate,
+} from '@codemirror/view';
+import type { SyntaxNode } from '@lezer/common';
+import type { ReactNode } from 'react';
+
+import type { CodeLanguage } from '../../../../lib/code-roles';
+import { ISSUE_SEVERITY_ICON_CLASS } from '../../../feedback/issue-severity';
+import { editorIcon } from '../icon-sprite';
+import type { CodeEditorProviders } from '../providers';
+import type { CodeEditorDiagnostic } from '../types';
+import { escapeClosables } from './keyboard';
+import { reactTooltip } from './tooltips';
+import { walkTree } from './tree-walk';
+
+/**
+ * Problems in the text: the host's (a check's results, authoritative), a
+ * host's local `lint` provider (instant), and the editor's own syntax marks
+ * (JSON or YAML that does not parse, an unclosed `{{`, JavaScript that
+ * cannot be read). All three live in one state field, mapped through every
+ * edit; a problem whose text the reader edits hides until the next result.
+ *
+ * A problem shows as an underline whose style says its severity (wavy for
+ * an error and a warning, dotted for a note), a glyph in the gutter, and a
+ * tooltip on hover. F8 / Shift-F8 walk the problems and read each aloud;
+ * Mod-. applies a fix.
+ */
+
+export type DiagnosticSource = 'host' | 'lint' | 'syntax';
+
+export interface PlacedFix {
+  label: string;
+  changes: Array<{ from: number; to: number; insert: string }>;
+}
+
+/** A problem in document positions. `whole`: the field as a whole. */
+export interface PlacedDiagnostic {
+  key: string;
+  source: DiagnosticSource;
+  diagnostic: CodeEditorDiagnostic;
+  from: number;
+  to: number;
+  whole: boolean;
+  fixes: PlacedFix[];
+}
+
+export interface DiagnosticWords {
+  severity: Record<CodeEditorDiagnostic['severity'], string>;
+  atCursor: (values: {
+    severity: string;
+    line: number;
+    message: string;
+  }) => string;
+  fixAvailable: (shortcut: string) => string;
+  fixApplied: (label: string) => string;
+  syntax: Record<
+    'json' | 'yaml' | 'javascript' | 'unterminatedTemplate',
+    string
+  >;
+}
+
+export interface DiagnosticsConfig {
+  language: CodeLanguage;
+  words: () => DiagnosticWords;
+  /** The tooltip body (React). `focusFix` focuses its first fix button. */
+  render: (
+    view: EditorView,
+    items: readonly PlacedDiagnostic[],
+    focusFix: boolean,
+  ) => ReactNode;
+  providers: () => CodeEditorProviders | undefined;
+  syntax: boolean;
+  gutter: boolean;
+}
+
+const SEVERITY_RANK: Record<CodeEditorDiagnostic['severity'], number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+};
+
+/* --------------------------------------------------------------- placing */
+
+/** One character at least: an empty range widens forward, or back at a line end. */
+function widen(doc: Text, from: number, to: number): [number, number] {
+  const start = Math.min(Math.max(from, 0), doc.length);
+  const end = Math.min(Math.max(to, start), doc.length);
+  if (end > start) return [start, end];
+  if (start < doc.length && doc.sliceString(start, start + 1) !== '\n') {
+    return [start, start + 1];
+  }
+  if (start > 0) return [start - 1, start];
+  return [start, start];
+}
+
+/**
+ * How text the host checked maps onto the text now shown: the common
+ * prefix and suffix stay; a range inside what changed is gone.
+ */
+function mapperFrom(
+  checked: string | undefined,
+  doc: Text,
+): (from: number, to: number) => [number, number] | null {
+  const now = doc.toString();
+  if (checked === undefined || checked === now) return (from, to) => [from, to];
+  const max = Math.min(checked.length, now.length);
+  let prefix = 0;
+  while (prefix < max && checked[prefix] === now[prefix]) prefix++;
+  let suffix = 0;
+  while (
+    suffix < max - prefix &&
+    checked[checked.length - 1 - suffix] === now[now.length - 1 - suffix]
+  ) {
+    suffix++;
+  }
+  const changedEnd = checked.length - suffix;
+  const delta = now.length - checked.length;
+  // Text next to an edit counts as edited, as CodeMirror's own mapping
+  // treats it: a problem on `a` is stale once `a` became `abc`.
+  return (from, to) => {
+    if (to < prefix) return [from, to];
+    if (from > changedEnd) return [from + delta, to + delta];
+    return null;
+  };
+}
+
+export function placeDiagnostics(
+  source: DiagnosticSource,
+  diagnostics: readonly CodeEditorDiagnostic[],
+  doc: Text,
+  checked?: string,
+): PlacedDiagnostic[] {
+  const map = mapperFrom(checked, doc);
+  const out: PlacedDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    const fixes: PlacedFix[] = [];
+    for (const fix of diagnostic.fixes ?? []) {
+      const changes: PlacedFix['changes'] = [];
+      let lost = false;
+      for (const change of fix.changes) {
+        const mapped = map(change.range[0], change.range[1]);
+        if (mapped === null) lost = true;
+        else
+          changes.push({
+            from: mapped[0],
+            to: mapped[1],
+            insert: change.insert,
+          });
+      }
+      if (!lost) fixes.push({ label: fix.label, changes });
+    }
+    const key = `${source}:${diagnostic.id}`;
+    if (diagnostic.range === undefined) {
+      out.push({ key, source, diagnostic, from: 0, to: 0, whole: true, fixes });
+      continue;
+    }
+    const mapped = map(diagnostic.range[0], diagnostic.range[1]);
+    if (mapped === null) continue;
+    const [from, to] = widen(doc, mapped[0], mapped[1]);
+    out.push({ key, source, diagnostic, from, to, whole: false, fixes });
+  }
+  return out;
+}
+
+function overlaps(a: PlacedDiagnostic, b: PlacedDiagnostic): boolean {
+  if (a.whole || b.whole) return false;
+  return a.from < b.to && b.from < a.to;
+}
+
+/**
+ * The problems to show: every host problem; a lint problem unless the host
+ * reports the same code there; a syntax mark unless any other problem
+ * covers its text.
+ */
+function merge(
+  host: readonly PlacedDiagnostic[],
+  lint: readonly PlacedDiagnostic[],
+  syntax: readonly PlacedDiagnostic[],
+): PlacedDiagnostic[] {
+  const shown = [...host];
+  for (const item of lint) {
+    const duplicate = host.some(
+      (known) =>
+        known.diagnostic.code !== undefined &&
+        known.diagnostic.code === item.diagnostic.code &&
+        overlaps(known, item),
+    );
+    if (!duplicate) shown.push(item);
+  }
+  const reported = [...shown];
+  for (const item of syntax) {
+    if (!reported.some((known) => overlaps(known, item))) shown.push(item);
+  }
+  return shown.sort(
+    (a, b) =>
+      (a.whole ? -1 : a.from) - (b.whole ? -1 : b.from) ||
+      SEVERITY_RANK[a.diagnostic.severity] -
+        SEVERITY_RANK[b.diagnostic.severity],
+  );
+}
+
+/* ----------------------------------------------------------------- state */
+
+export const setDiagnostics = StateEffect.define<{
+  source: DiagnosticSource;
+  items: PlacedDiagnostic[];
+}>();
+
+/** The problem tooltip opened from the keyboard (F8, Mod-.). */
+const pinTooltip = StateEffect.define<{
+  keys: string[];
+  pos: number;
+  focusFix: boolean;
+} | null>();
+
+interface DiagnosticState {
+  host: PlacedDiagnostic[];
+  lint: PlacedDiagnostic[];
+  syntax: PlacedDiagnostic[];
+  shown: PlacedDiagnostic[];
+  pinned: { keys: string[]; pos: number; focusFix: boolean } | null;
+}
+
+function mapThrough(
+  items: readonly PlacedDiagnostic[],
+  tr: Transaction,
+): PlacedDiagnostic[] {
+  if (!tr.docChanged) return [...items];
+  const out: PlacedDiagnostic[] = [];
+  for (const item of items) {
+    if (item.whole) {
+      out.push(item);
+      continue;
+    }
+    if (tr.changes.touchesRange(item.from, item.to)) continue;
+    const fixes = item.fixes.flatMap((fix) =>
+      fix.changes.some((change) =>
+        tr.changes.touchesRange(change.from, change.to),
+      )
+        ? []
+        : [
+            {
+              label: fix.label,
+              changes: fix.changes.map((change) => ({
+                from: tr.changes.mapPos(change.from, 1),
+                to: tr.changes.mapPos(change.to, -1),
+                insert: change.insert,
+              })),
+            },
+          ],
+    );
+    out.push({
+      ...item,
+      from: tr.changes.mapPos(item.from, 1),
+      to: tr.changes.mapPos(item.to, -1),
+      fixes,
+    });
+  }
+  return out;
+}
+
+export const diagnosticState = StateField.define<DiagnosticState>({
+  create: () => ({ host: [], lint: [], syntax: [], shown: [], pinned: null }),
+  update(value, tr) {
+    let { host, lint, syntax, pinned } = value;
+    host = mapThrough(host, tr);
+    lint = mapThrough(lint, tr);
+    syntax = mapThrough(syntax, tr);
+    if (tr.docChanged) pinned = null;
+    for (const effect of tr.effects) {
+      if (effect.is(setDiagnostics)) {
+        if (effect.value.source === 'host') host = effect.value.items;
+        else if (effect.value.source === 'lint') lint = effect.value.items;
+        else syntax = effect.value.items;
+      } else if (effect.is(pinTooltip)) {
+        pinned = effect.value;
+      }
+    }
+    return { host, lint, syntax, shown: merge(host, lint, syntax), pinned };
+  },
+});
+
+/** The problems shown now (for tests and the summary). */
+export function shownDiagnostics(
+  state: EditorState,
+): readonly PlacedDiagnostic[] {
+  return state.field(diagnosticState, false)?.shown ?? [];
+}
+
+/* ---------------------------------------------------------- decorations */
+
+const marks = {
+  error: Decoration.mark({ class: 'cm-diagnostic cm-diagnostic-error' }),
+  warning: Decoration.mark({ class: 'cm-diagnostic cm-diagnostic-warning' }),
+  info: Decoration.mark({ class: 'cm-diagnostic cm-diagnostic-info' }),
+};
+
+const underlines = EditorView.decorations.compute(
+  [diagnosticState],
+  (state) => {
+    const items = state
+      .field(diagnosticState)
+      .shown.filter((item) => !item.whole);
+    return Decoration.set(
+      items
+        .filter((item) => item.to > item.from)
+        .map((item) =>
+          marks[item.diagnostic.severity].range(item.from, item.to),
+        ),
+      true,
+    );
+  },
+);
+
+const GUTTER_ICON = {
+  error: 'circle-x',
+  warning: 'triangle-alert',
+  info: 'info',
+} as const;
+
+class SeverityMarker extends GutterMarker {
+  constructor(readonly severity: CodeEditorDiagnostic['severity']) {
+    super();
+  }
+
+  eq(other: SeverityMarker) {
+    return other.severity === this.severity;
+  }
+
+  toDOM() {
+    const icon = editorIcon(GUTTER_ICON[this.severity]);
+    icon.classList.add(...ISSUE_SEVERITY_ICON_CLASS[this.severity].split(' '));
+    return icon;
+  }
+}
+
+const gutterMarkers = {
+  error: new SeverityMarker('error'),
+  warning: new SeverityMarker('warning'),
+  info: new SeverityMarker('info'),
+};
+
+function lineMarkers(state: EditorState): RangeSet<GutterMarker> {
+  const worst = new Map<number, CodeEditorDiagnostic['severity']>();
+  for (const item of state.field(diagnosticState).shown) {
+    const line = item.whole ? 1 : state.doc.lineAt(item.from).number;
+    const known = worst.get(line);
+    if (
+      known === undefined ||
+      SEVERITY_RANK[item.diagnostic.severity] < SEVERITY_RANK[known]
+    ) {
+      worst.set(line, item.diagnostic.severity);
+    }
+  }
+  const builder = new RangeSetBuilder<GutterMarker>();
+  for (const line of [...worst.keys()].sort((a, b) => a - b)) {
+    const severity = worst.get(line);
+    if (severity === undefined) continue;
+    const start = state.doc.line(line).from;
+    builder.add(start, start, gutterMarkers[severity]);
+  }
+  return builder.finish();
+}
+
+const diagnosticGutter = gutter({
+  class: 'cm-diagnostic-gutter',
+  markers: (view) => lineMarkers(view.state),
+  initialSpacer: () => gutterMarkers.info,
+});
+
+/* -------------------------------------------------------------- tooltips */
+
+const diagnosticsConfig = Facet.define<
+  DiagnosticsConfig,
+  DiagnosticsConfig | null
+>({
+  combine: (values) => values[0] ?? null,
+});
+
+const TOOLTIP_CLASS =
+  'cm-tale-tooltip motion-safe:animate-in motion-safe:fade-in-0 motion-safe:duration-[var(--duration-short)]';
+
+function itemsAt(
+  state: EditorState,
+  pos: number,
+  side: -1 | 1,
+): PlacedDiagnostic[] {
+  return state
+    .field(diagnosticState)
+    .shown.filter(
+      (item) =>
+        !item.whole &&
+        item.from <= pos &&
+        item.to >= pos &&
+        (item.from < pos || side > 0) &&
+        (item.to > pos || side < 0),
+    );
+}
+
+function tooltipFor(
+  items: readonly PlacedDiagnostic[],
+  focusFix: boolean,
+  pos?: number,
+): Tooltip {
+  const from = pos ?? Math.min(...items.map((item) => item.from));
+  return {
+    pos: from,
+    end:
+      pos === undefined ? Math.max(...items.map((item) => item.to)) : undefined,
+    above: false,
+    create: (view) => {
+      const config = view.state.facet(diagnosticsConfig);
+      return reactTooltip(
+        view,
+        config?.render(view, items, focusFix) ?? null,
+        TOOLTIP_CLASS,
+      );
+    },
+  };
+}
+
+const hoverProblems = hoverTooltip(
+  (view, pos, side) => {
+    const items = itemsAt(view.state, pos, side);
+    return items.length === 0 ? null : tooltipFor(items, false);
+  },
+  { hoverTime: 200 },
+);
+
+const pinnedTooltip = showTooltip.compute([diagnosticState], (state) => {
+  const pinned = state.field(diagnosticState).pinned;
+  if (pinned === null) return null;
+  const items = state
+    .field(diagnosticState)
+    .shown.filter((item) => pinned.keys.includes(item.key));
+  if (items.length === 0) return null;
+  return tooltipFor(items, pinned.focusFix, pinned.pos);
+});
+
+/* -------------------------------------------------------------- keyboard */
+
+function announce(view: EditorView, text: string): void {
+  view.dispatch({ effects: EditorView.announce.of(text) });
+}
+
+const FIX_SHORTCUT =
+  typeof navigator !== 'undefined' && /mac/i.test(navigator.platform)
+    ? '⌘.'
+    : 'Ctrl+.';
+
+function describe(view: EditorView, item: PlacedDiagnostic): string {
+  const config = view.state.facet(diagnosticsConfig);
+  if (config === null) return item.diagnostic.message;
+  const words = config.words();
+  const line = item.whole ? 1 : view.state.doc.lineAt(item.from).number;
+  const text = words.atCursor({
+    severity: words.severity[item.diagnostic.severity],
+    line,
+    message: item.diagnostic.message,
+  });
+  return item.fixes.length > 0
+    ? `${text} ${words.fixAvailable(FIX_SHORTCUT)}`
+    : text;
+}
+
+/**
+ * Moves to the next (or previous) problem after the cursor, selects it,
+ * opens its tooltip and reads it aloud. Wraps around.
+ */
+export function goToDiagnostic(view: EditorView, direction: 1 | -1): boolean {
+  const items = shownDiagnostics(view.state);
+  if (items.length === 0) return false;
+  // Forward from the end of the selection, back from its start: a problem
+  // F8 selected is never found again.
+  const { from: start, to: end } = view.state.selection.main;
+  const placed = items.map((item) => ({
+    item,
+    at: item.whole ? 0 : item.from,
+  }));
+  const next =
+    direction > 0
+      ? (placed.find(({ at }) => at > end) ??
+        placed.find(({ at }) => at >= end) ??
+        placed[0])
+      : (placed.findLast(({ at }) => at < start) ?? placed[placed.length - 1]);
+  const { item } = next;
+  const from = item.whole ? 0 : item.from;
+  const to = item.whole ? 0 : item.to;
+  view.dispatch({
+    selection: EditorSelection.single(from, to),
+    effects: [
+      EditorView.scrollIntoView(from, { y: 'center' }),
+      ...(item.whole
+        ? []
+        : [pinTooltip.of({ keys: [item.key], pos: from, focusFix: false })]),
+    ],
+    userEvent: 'select',
+  });
+  announce(view, describe(view, item));
+  return true;
+}
+
+export function applyFix(view: EditorView, fix: PlacedFix): void {
+  view.dispatch({
+    changes: fix.changes,
+    effects: pinTooltip.of(null),
+    userEvent: 'input.fix',
+  });
+  view.focus();
+  const config = view.state.facet(diagnosticsConfig);
+  if (config !== null) announce(view, config.words().fixApplied(fix.label));
+}
+
+function quickFix(view: EditorView): boolean {
+  const head = view.state.selection.main.head;
+  const items = [
+    ...itemsAt(view.state, head, -1),
+    ...itemsAt(view.state, head, 1),
+  ];
+  const withFixes = items.filter((item) => item.fixes.length > 0);
+  if (withFixes.length === 0) return false;
+  const fixes = withFixes.flatMap((item) => item.fixes);
+  if (fixes.length === 1) {
+    applyFix(view, fixes[0]);
+    return true;
+  }
+  view.dispatch({
+    effects: pinTooltip.of({
+      keys: withFixes.map((item) => item.key),
+      pos: withFixes[0].from,
+      focusFix: true,
+    }),
+  });
+  return true;
+}
+
+/* ---------------------------------------------------------- syntax marks */
+
+const SYNTAX_DELAY = 500;
+
+function syntaxProblems(
+  state: EditorState,
+  language: CodeLanguage,
+  words: DiagnosticWords,
+): CodeEditorDiagnostic[] {
+  const found: CodeEditorDiagnostic[] = [];
+  const head = state.selection.main.head;
+  const seen = new Set<number>();
+  walkTree(syntaxTree(state), 0, state.doc.length, (node, offset) => {
+    const isUnclosed = node.name === 'TemplateUnterminated';
+    if (!node.type.isError && !isUnclosed) return;
+    const [from, to] = widen(state.doc, offset + node.from, offset + node.to);
+    if (seen.has(from)) return;
+    seen.add(from);
+    // Never under what the reader is still typing.
+    if (from <= head && head <= to) return;
+    const kind: keyof DiagnosticWords['syntax'] = isUnclosed
+      ? 'unterminatedTemplate'
+      : insideTemplate(node)
+        ? 'javascript'
+        : language === 'json' || language === 'yaml'
+          ? language
+          : 'javascript';
+    found.push({
+      id: `syntax-${from}`,
+      severity: 'error',
+      message: words.syntax[kind],
+      range: [from, to],
+    });
+  });
+  return found;
+}
+
+/** Inside a `{{ }}` template: the JavaScript of its body. */
+function insideTemplate(node: SyntaxNode): boolean {
+  for (let at: SyntaxNode | null = node; at !== null; at = at.parent) {
+    if (at.name === 'TemplateBody' || at.name === 'Template') return true;
+  }
+  return false;
+}
+
+class SyntaxMarks implements PluginValue {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly view: EditorView) {
+    this.schedule();
+  }
+
+  update(update: ViewUpdate) {
+    if (
+      update.docChanged ||
+      syntaxTree(update.startState) !== syntaxTree(update.state)
+    ) {
+      this.schedule();
+    }
+  }
+
+  schedule() {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      const config = this.view.state.facet(diagnosticsConfig);
+      if (config === null || !config.syntax) return;
+      const problems = syntaxProblems(
+        this.view.state,
+        config.language,
+        config.words(),
+      );
+      this.view.dispatch({
+        effects: setDiagnostics.of({
+          source: 'syntax',
+          items: placeDiagnostics('syntax', problems, this.view.state.doc),
+        }),
+      });
+    }, SYNTAX_DELAY);
+  }
+
+  destroy() {
+    if (this.timer !== null) clearTimeout(this.timer);
+  }
+}
+
+/* ------------------------------------------------------------ local lint */
+
+class LocalLint implements PluginValue {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private running: AbortController | null = null;
+
+  constructor(private readonly view: EditorView) {
+    this.schedule();
+  }
+
+  update(update: ViewUpdate) {
+    if (update.docChanged) this.schedule();
+  }
+
+  schedule() {
+    const config = this.view.state.facet(diagnosticsConfig);
+    const lint = config?.providers()?.lint;
+    if (config === null || lint === undefined) return;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.running?.abort();
+    const delay = config.providers()?.lintDelay ?? 150;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      const controller = new AbortController();
+      this.running = controller;
+      const doc = this.view.state.doc;
+      Promise.resolve(
+        lint({
+          text: doc.toString(),
+          language: config.language,
+          signal: controller.signal,
+        }),
+      ).then(
+        (problems) => {
+          if (controller.signal.aborted || this.view.state.doc !== doc) return;
+          this.view.dispatch({
+            effects: setDiagnostics.of({
+              source: 'lint',
+              items: placeDiagnostics('lint', problems, doc),
+            }),
+          });
+        },
+        (error: unknown) => {
+          if (controller.signal.aborted) return;
+          console.warn('[code-editor] the lint provider failed', error);
+        },
+      );
+    }, delay);
+  }
+
+  destroy() {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.running?.abort();
+  }
+}
+
+/* ------------------------------------------------------------- assembly */
+
+export function diagnosticsExtension(config: DiagnosticsConfig): Extension {
+  return [
+    diagnosticsConfig.of(config),
+    diagnosticState,
+    underlines,
+    hoverProblems,
+    pinnedTooltip,
+    config.gutter ? diagnosticGutter : [],
+    ViewPlugin.fromClass(SyntaxMarks),
+    ViewPlugin.fromClass(LocalLint),
+    escapeClosables.of({
+      isOpen: (view) => view.state.field(diagnosticState).pinned !== null,
+      close: (view) => {
+        view.dispatch({ effects: pinTooltip.of(null) });
+        view.focus();
+        return true;
+      },
+    }),
+    keymap.of([
+      { key: 'F8', run: (view) => goToDiagnostic(view, 1) },
+      { key: 'Shift-F8', run: (view) => goToDiagnostic(view, -1) },
+      { key: 'Mod-.', run: quickFix },
+    ]),
+  ];
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/highlight.ts b/packages/ui/src/components/forms/code-editor/extensions/highlight.ts
index f087e4a3b4..7d37971ac3 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/highlight.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/highlight.ts
@@ -1,6 +1,12 @@
+import { typescriptLanguage } from '@codemirror/lang-javascript';
 import { HighlightStyle, syntaxHighlighting } from '@codemirror/language';
 import type { Extension } from '@codemirror/state';
-import { tagHighlighter, type Highlighter, type Tag } from '@lezer/highlight';
+import {
+  highlightCode,
+  tagHighlighter,
+  type Highlighter,
+  type Tag,
+} from '@lezer/highlight';
 
 import {
   CODE_FONT_TAGS,
@@ -67,3 +73,32 @@ export const codeRoleHighlighter: Highlighter = tagHighlighter(
       : [{ tag: [...tags], class: `role-${role}` }];
   }),
 );
+
+/** A run of text and the classes that colour it. */
+export interface HighlightedRun {
+  text: string;
+  className: string;
+}
+
+const TYPE_PREFIX = 'type _ = ';
+
+/**
+ * A TypeScript type (`{ count: number }`) as coloured runs, in the editor's
+ * palette: the type info of a completion or a hover. Parsed as the right
+ * side of a type alias, so any type reads as TypeScript does.
+ */
+export function highlightType(type: string): HighlightedRun[] {
+  const source = `${TYPE_PREFIX}${type}`;
+  const tree = typescriptLanguage.parser.parse(source);
+  const runs: HighlightedRun[] = [];
+  highlightCode(
+    source,
+    tree,
+    codeHighlightStyle,
+    (text, className) => runs.push({ text, className }),
+    () => runs.push({ text: '\n', className: '' }),
+    TYPE_PREFIX.length,
+    source.length,
+  );
+  return runs;
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/hover.ts b/packages/ui/src/components/forms/code-editor/extensions/hover.ts
new file mode 100644
index 0000000000..8d1287ffa5
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/hover.ts
@@ -0,0 +1,135 @@
+import { StateEffect, StateField, type Extension } from '@codemirror/state';
+import {
+  EditorView,
+  hoverTooltip,
+  keymap,
+  showTooltip,
+  type Tooltip,
+} from '@codemirror/view';
+import type { ReactNode } from 'react';
+
+import type { CodeLanguage } from '../../../../lib/code-roles';
+import { hoverContext } from '../member-path';
+import type { CodeEditorProviders, CodeHoverInfo } from '../providers';
+import { escapeClosables } from './keyboard';
+import { reactTooltip } from './tooltips';
+
+/**
+ * The type of what is under the pointer, from the host's hover provider:
+ * after 200 ms on a name, or on Mod-K Mod-I at the cursor, which also reads
+ * the type aloud. Escape closes it.
+ */
+
+export interface HoverConfig {
+  language: CodeLanguage;
+  providers: () => CodeEditorProviders | undefined;
+  render: (info: CodeHoverInfo) => ReactNode;
+  announce: (info: CodeHoverInfo) => string;
+}
+
+const TOOLTIP_CLASS =
+  'cm-tale-tooltip motion-safe:animate-in motion-safe:fade-in-0 motion-safe:duration-[var(--duration-short)]';
+
+async function infoAt(
+  view: EditorView,
+  config: HoverConfig,
+  pos: number,
+  side: -1 | 1,
+  signal: AbortSignal,
+): Promise<{ info: CodeHoverInfo; from: number; to: number } | null> {
+  const provider = config.providers()?.hover;
+  if (provider === undefined) return null;
+  const context = hoverContext(view.state, pos, side);
+  if (context === null) return null;
+  const info = await provider({
+    text: view.state.doc.toString(),
+    pos,
+    language: config.language,
+    region: context.region,
+    path: context.path,
+    word: context.word,
+    from: context.from,
+    to: context.to,
+    signal,
+  });
+  return info === null ? null : { info, from: context.from, to: context.to };
+}
+
+function tooltip(
+  config: HoverConfig,
+  info: CodeHoverInfo,
+  from: number,
+  to: number,
+): Tooltip {
+  return {
+    pos: from,
+    end: to,
+    above: true,
+    create: (view) => reactTooltip(view, config.render(info), TOOLTIP_CLASS),
+  };
+}
+
+const showType = StateEffect.define<Tooltip | null>();
+
+const typeTooltip = StateField.define<Tooltip | null>({
+  create: () => null,
+  update(value, tr) {
+    let next = tr.docChanged || tr.selection ? null : value;
+    for (const effect of tr.effects) {
+      if (effect.is(showType)) next = effect.value;
+    }
+    return next;
+  },
+  provide: (field) => showTooltip.from(field),
+});
+
+export function hoverExtension(config: HoverConfig): Extension {
+  return [
+    hoverTooltip(
+      async (view, pos, side) => {
+        const controller = new AbortController();
+        const found = await infoAt(view, config, pos, side, controller.signal);
+        return found === null
+          ? null
+          : tooltip(config, found.info, found.from, found.to);
+      },
+      { hoverTime: 200 },
+    ),
+    typeTooltip,
+    escapeClosables.of({
+      isOpen: (view) => view.state.field(typeTooltip) !== null,
+      close: (view) => {
+        view.dispatch({ effects: showType.of(null) });
+        return true;
+      },
+    }),
+    keymap.of([
+      {
+        key: 'Mod-k Mod-i',
+        run: (view) => {
+          const head = view.state.selection.main.head;
+          const controller = new AbortController();
+          void infoAt(view, config, head, -1, controller.signal).then(
+            (found) => {
+              if (found === null || view.state.selection.main.head !== head) {
+                return;
+              }
+              view.dispatch({
+                effects: [
+                  showType.of(
+                    tooltip(config, found.info, found.from, found.to),
+                  ),
+                  EditorView.announce.of(config.announce(found.info)),
+                ],
+              });
+            },
+            (error: unknown) => {
+              console.warn('[code-editor] the hover provider failed', error);
+            },
+          );
+          return true;
+        },
+      },
+    ]),
+  ];
+}
diff --git a/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts b/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
index 721cef4126..9af0d1c134 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/keyboard.ts
@@ -55,7 +55,7 @@ export interface EscapeClosable {
  * Popups the editor's other extensions open (the problem tooltip, the type
  * tooltip) register here so Escape closes them and the claim covers them.
  */
-const escapeClosables = Facet.define<EscapeClosable>();
+export const escapeClosables = Facet.define<EscapeClosable>();
 
 const NO_WORDS: KeyboardWords = {
   leaveArmed: '',
@@ -72,7 +72,8 @@ const LEAVE_MS = 2000;
 
 const builtInClosables: EscapeClosable[] = [
   {
-    isOpen: (view) => completionStatus(view.state) !== null,
+    // A list on screen; a request still pending is dropped quietly below.
+    isOpen: (view) => completionStatus(view.state) === 'active',
     close: (view) => closeCompletion(view),
   },
   {
@@ -109,6 +110,7 @@ class EscapeClaim implements PluginValue {
         return;
       }
     }
+    if (completionStatus(view.state) === 'pending') closeCompletion(view);
     view.setTabFocusMode(LEAVE_MS);
     this.arm();
     view.dispatch({
diff --git a/packages/ui/src/components/forms/code-editor/extensions/template/input.ts b/packages/ui/src/components/forms/code-editor/extensions/template/input.ts
index 69e4f83e58..ab77849379 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/template/input.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/template/input.ts
@@ -38,7 +38,14 @@ function canOpenAt(
     node !== null;
     node = node.parent
   ) {
-    if (node.name === 'TemplateBody') return false;
+    // Inside a template's JavaScript (whose tree hangs below `Template`).
+    if (
+      node.name === 'TemplateBody' ||
+      node.name === 'SingleExpression' ||
+      node.name === 'Script'
+    ) {
+      return false;
+    }
     if (node.name === 'Key' || node.name === 'PropertyName') return false;
     if (TEMPLATE_NODES.has(node.name)) inString = true;
     if (strings?.has(node.name)) inString = true;
diff --git a/packages/ui/src/components/forms/code-editor/extensions/theme.ts b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
index 5246718999..cefe263f3f 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/theme.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
@@ -106,6 +106,97 @@ export const codeEditorTheme = EditorView.theme({
     fontSize: '0.92em',
   },
   '.cm-tale-object': { color: 'var(--code-token-constant)' },
+  // Problems: the underline's style says the severity (wavy for an error or
+  // a warning, dotted for a note), so it never reads by colour alone.
+  '.cm-diagnostic': {
+    textUnderlineOffset: '3px',
+    textDecorationSkipInk: 'none',
+  },
+  '.cm-diagnostic-error': {
+    textDecoration: 'underline wavy var(--code-squiggle-error) 1.5px',
+  },
+  '.cm-diagnostic-warning': {
+    textDecoration: 'underline wavy var(--code-squiggle-warning) 1px',
+  },
+  '.cm-diagnostic-info': {
+    textDecoration: 'underline dotted var(--code-squiggle-info) 1px',
+  },
+  // While a check runs, the last answer's underlines fade to 60 %.
+  '&.cm-diagnostics-pending .cm-diagnostic-error': {
+    textDecorationColor:
+      'color-mix(in srgb, var(--code-squiggle-error) 60%, transparent)',
+  },
+  '&.cm-diagnostics-pending .cm-diagnostic-warning': {
+    textDecorationColor:
+      'color-mix(in srgb, var(--code-squiggle-warning) 60%, transparent)',
+  },
+  '&.cm-diagnostics-pending .cm-diagnostic-info': {
+    textDecorationColor:
+      'color-mix(in srgb, var(--code-squiggle-info) 60%, transparent)',
+  },
+  '.cm-diagnostic-gutter .cm-gutterElement': {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: '1.25rem',
+    paddingLeft: '0.25rem',
+  },
+  // Tooltips and the completion list look like the app's popovers.
+  '.cm-tooltip': {
+    backgroundColor: 'hsl(var(--popover))',
+    color: 'hsl(var(--popover-foreground))',
+    border: '1px solid hsl(var(--border))',
+    borderRadius: '0.5rem',
+    boxShadow: 'var(--shadow-overlay)',
+    fontFamily: 'var(--font-sans)',
+    fontSize: '0.75rem',
+    lineHeight: '1.4',
+  },
+  '.dark & .cm-tooltip': { backgroundColor: 'hsl(var(--muted))' },
+  '.cm-tooltip.cm-tooltip-autocomplete': {
+    padding: '0.25rem 0',
+    minWidth: '14rem',
+    maxWidth: '24rem',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul': {
+    fontFamily: 'var(--font-mono)',
+    maxHeight: 'calc(8 * 1.75rem + 2rem)',
+    maxWidth: '24rem',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > li': {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '0.5rem',
+    minHeight: '1.75rem',
+    padding: '0 0.5rem',
+    lineHeight: '1.75rem',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected]': {
+    backgroundColor: 'hsl(var(--accent))',
+    color: 'hsl(var(--accent-foreground))',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > completion-section': {
+    display: 'block',
+    padding: '0.5rem 0.5rem 0.25rem',
+    fontFamily: 'var(--font-sans)',
+    fontSize: '0.75rem',
+    fontWeight: '500',
+    color: 'hsl(var(--muted-foreground))',
+    borderBottom: 'none',
+    opacity: '1',
+  },
+  '.cm-completionLabel': { color: 'hsl(var(--foreground))' },
+  '.cm-completionMatchedText': { textDecoration: 'none', fontWeight: '600' },
+  '.cm-completionDetail': {
+    marginLeft: 'auto',
+    paddingLeft: '0.75rem',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    fontStyle: 'normal',
+    color: 'hsl(var(--muted-foreground))',
+  },
+  '.cm-tooltip.cm-completionInfo': { padding: '0', maxWidth: '20rem' },
   // Search and go-to-line panels, in the app's control styles.
   '.cm-panels': {
     backgroundColor: 'hsl(var(--card))',
diff --git a/packages/ui/src/components/forms/code-editor/extensions/tooltips.ts b/packages/ui/src/components/forms/code-editor/extensions/tooltips.ts
new file mode 100644
index 0000000000..9a047140ab
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/extensions/tooltips.ts
@@ -0,0 +1,95 @@
+import { Facet, type Extension } from '@codemirror/state';
+import { tooltips, type EditorView, type TooltipView } from '@codemirror/view';
+import type { ReactNode } from 'react';
+
+/**
+ * Tooltip bodies the editor draws with React (a problem's detail and its
+ * fix buttons, a type with its description) inside the DOM CodeMirror
+ * positions. CodeMirror creates the element; the view component renders the
+ * React node into it through a portal, so the node keeps the app's context
+ * (language, theme).
+ */
+export interface TooltipPortals {
+  set: (dom: HTMLElement, node: ReactNode) => void;
+  remove: (dom: HTMLElement) => void;
+  subscribe: (listener: () => void) => () => void;
+  snapshot: () => ReadonlyMap<HTMLElement, ReactNode>;
+}
+
+export function createTooltipPortals(): TooltipPortals {
+  let current = new Map<HTMLElement, ReactNode>();
+  const listeners = new Set<() => void>();
+  const publish = (next: Map<HTMLElement, ReactNode>) => {
+    current = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    set: (dom, node) => {
+      publish(new Map(current).set(dom, node));
+    },
+    remove: (dom) => {
+      if (!current.has(dom)) return;
+      const next = new Map(current);
+      next.delete(dom);
+      publish(next);
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    snapshot: () => current,
+  };
+}
+
+export const tooltipPortals = Facet.define<
+  TooltipPortals,
+  TooltipPortals | null
+>({
+  combine: (values) => values[0] ?? null,
+});
+
+/** A tooltip whose body is a React node. */
+export function reactTooltip(
+  view: EditorView,
+  node: ReactNode,
+  className: string,
+): TooltipView {
+  const dom = document.createElement('div');
+  dom.className = className;
+  const portals = view.state.facet(tooltipPortals);
+  portals?.set(dom, node);
+  return {
+    dom,
+    destroy() {
+      portals?.remove(dom);
+    },
+  };
+}
+
+/**
+ * Tooltips are fixed-positioned, so an inspector that clips its overflow
+ * cannot cut them off, and they never run below the dialog or sheet the
+ * editor sits in: a completion list flips up rather than run under its
+ * bottom edge. (They may rise above a short sheet: confined to it, a list
+ * in a sheet of a few lines would have no room at all.)
+ */
+export const tooltipPlacement: Extension = tooltips({
+  position: 'fixed',
+  tooltipSpace: (view) => {
+    const viewport = {
+      top: 0,
+      left: 0,
+      right: window.innerWidth,
+      bottom: window.innerHeight,
+    };
+    const dialog = view.dom.closest('[role="dialog"]');
+    if (dialog === null) return viewport;
+    const box = dialog.getBoundingClientRect();
+    return {
+      top: viewport.top,
+      left: Math.max(viewport.left, box.left),
+      right: Math.min(viewport.right, box.right),
+      bottom: Math.min(viewport.bottom, box.bottom),
+    };
+  },
+});
diff --git a/packages/ui/src/components/forms/code-editor/member-path.test.ts b/packages/ui/src/components/forms/code-editor/member-path.test.ts
new file mode 100644
index 0000000000..508b19a403
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/member-path.test.ts
@@ -0,0 +1,130 @@
+import { EditorState } from '@codemirror/state';
+import { describe, expect, it } from 'vitest';
+
+import type { CodeLanguage } from '../../../lib/code-roles';
+import { languageExtension } from './extensions/languages';
+import { cursorContext, hoverContext } from './member-path';
+
+/** A state for `text`, with `|` marking the cursor. */
+function at(text: string, language: CodeLanguage, templates = false) {
+  const pos = text.indexOf('|');
+  const doc = text.replace('|', '');
+  const state = EditorState.create({
+    doc,
+    extensions: [languageExtension(language, templates)],
+  });
+  return { state, pos };
+}
+
+function context(text: string, language: CodeLanguage, templates = false) {
+  const { state, pos } = at(text, language, templates);
+  return cursorContext(state, pos);
+}
+
+describe('cursorContext in code', () => {
+  it('reads the chain before a word being typed after a dot', () => {
+    const found = context('return nodes.score.output.it|', 'javascript');
+    expect(found).toMatchObject({
+      region: 'code',
+      path: ['nodes', 'score', 'output'],
+      word: 'it',
+      trigger: 'dot',
+    });
+  });
+
+  it('reads quoted keys, optional chaining and indexes', () => {
+    expect(context('nodes["a b"]?.x.|', 'expression').path).toEqual([
+      'nodes',
+      'a b',
+      'x',
+    ]);
+    expect(context('input.items[0].|', 'expression').path).toEqual([
+      'input',
+      'items',
+      0,
+    ]);
+    expect(context('nodes?.["a b"].|', 'expression').path).toEqual([
+      'nodes',
+      'a b',
+    ]);
+  });
+
+  it('answers an empty chain for a bare name', () => {
+    expect(context('inp|', 'expression')).toMatchObject({
+      path: [],
+      word: 'inp',
+      trigger: 'name',
+    });
+  });
+
+  it('reads the chain before a bracket', () => {
+    expect(context('nodes[|', 'expression')).toMatchObject({
+      path: ['nodes'],
+      trigger: 'bracket',
+    });
+  });
+
+  it('gives no chain in a comment or a string', () => {
+    expect(context('// nodes.|', 'javascript')).toMatchObject({
+      region: 'comment',
+      path: null,
+    });
+    expect(context('const a = "nodes.|";', 'javascript')).toMatchObject({
+      region: 'string',
+      path: null,
+    });
+  });
+
+  it('reads the JavaScript inside a template', () => {
+    expect(context('Hi {{ input.na| }}', 'template')).toMatchObject({
+      region: 'template',
+      path: ['input'],
+      word: 'na',
+    });
+    expect(context('{"to": "{{ nodes.a.| }}"}', 'json', true)).toMatchObject({
+      region: 'template',
+      path: ['nodes', 'a'],
+    });
+  });
+
+  it('gives no chain in the text around a template', () => {
+    expect(context('Hi th|ere {{ a }}', 'template')).toMatchObject({
+      region: 'text',
+      path: null,
+    });
+  });
+});
+
+describe('cursorContext in JSON and YAML', () => {
+  it('names a key and the pointer of the object it belongs to', () => {
+    expect(context('{"a": {"b|": 1}}', 'json')).toMatchObject({
+      region: 'key',
+      pointer: '/a',
+    });
+  });
+
+  it('names a value and its own pointer', () => {
+    expect(context('{"a": [1, {"to": "x|"}]}', 'json')).toMatchObject({
+      region: 'string',
+      pointer: '/a/1/to',
+    });
+    expect(
+      context('nodes:\n  - id: a\n    prompt: Hi th|ere', 'yaml'),
+    ).toMatchObject({ region: 'string', pointer: '/nodes/0/prompt' });
+  });
+});
+
+describe('hoverContext', () => {
+  it('reads the whole word and the chain up to it', () => {
+    const { state, pos } = at('nodes.sc|ore.output', 'expression');
+    expect(hoverContext(state, pos, 1)).toMatchObject({
+      word: 'score',
+      path: ['nodes', 'score'],
+    });
+  });
+
+  it('answers nothing outside a name', () => {
+    const { state, pos } = at('1 +| 2', 'expression');
+    expect(hoverContext(state, pos, 1)).toBeNull();
+  });
+});
diff --git a/packages/ui/src/components/forms/code-editor/member-path.ts b/packages/ui/src/components/forms/code-editor/member-path.ts
new file mode 100644
index 0000000000..564737f436
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/member-path.ts
@@ -0,0 +1,295 @@
+import { syntaxTree } from '@codemirror/language';
+import type { EditorState } from '@codemirror/state';
+import type { SyntaxNode } from '@lezer/common';
+
+import type { CodePathSegment, CodeRegion } from './providers';
+
+/**
+ * Where the cursor is, in the terms a completion or hover provider needs:
+ * what kind of text it sits in, the member chain left of the word under it
+ * (`nodes["a b"]?.x.it|` → `['nodes', 'a b', 'x']`, word `it`), and for
+ * JSON or YAML the pointer of the object around it. Read from the syntax
+ * tree, the JavaScript inside a `{{ }}` template included.
+ */
+export interface CursorContext {
+  region: CodeRegion;
+  /** The chain before the word; `[]` for a bare name; `null` outside code. */
+  path: CodePathSegment[] | null;
+  /** The word at the cursor, `[from, to)`; for completion it ends at the cursor. */
+  from: number;
+  to: number;
+  word: string;
+  /** What opened completion: a name, a `.`/`?.` or a `[`. */
+  trigger: 'name' | 'dot' | 'bracket' | 'none';
+  /**
+   * JSON/YAML: in a key, the pointer of the object the key belongs to; in a
+   * value, the pointer of that value.
+   */
+  pointer?: string;
+}
+
+const JS_TOPS = new Set(['Script', 'SingleExpression']);
+const JS_STRINGS = new Set(['String', 'TemplateString', 'RegExp']);
+const JS_COMMENTS = new Set(['LineComment', 'BlockComment']);
+const NAME = /[\w$]/;
+
+function ancestors(node: SyntaxNode): SyntaxNode[] {
+  const out: SyntaxNode[] = [];
+  for (let at: SyntaxNode | null = node; at !== null; at = at.parent)
+    out.push(at);
+  return out;
+}
+
+function text(state: EditorState, node: SyntaxNode): string {
+  return state.doc.sliceString(node.from, node.to);
+}
+
+/** A JSON or JavaScript string literal's value, or null. */
+function stringValue(raw: string): string | null {
+  const quoted = raw.startsWith("'")
+    ? `"${raw.slice(1, -1).replaceAll('"', '\\"')}"`
+    : raw;
+  try {
+    const value: unknown = JSON.parse(quoted);
+    return typeof value === 'string' ? value : null;
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+/** The member chain a node spells, or null when it is not a plain chain. */
+function chainOf(
+  state: EditorState,
+  node: SyntaxNode,
+): CodePathSegment[] | null {
+  if (node.name === 'VariableName') return [text(state, node)];
+  if (node.name === 'ParenthesizedExpression') {
+    const inner = node.firstChild?.nextSibling;
+    return inner ? chainOf(state, inner) : null;
+  }
+  if (node.name !== 'MemberExpression') return null;
+  const object = node.firstChild;
+  if (object === null) return null;
+  const base = chainOf(state, object);
+  if (base === null) return null;
+  let access = object.nextSibling;
+  // `a?.["x"]`: the optional marker, then the bracket.
+  if (access?.name === '?.' && access.nextSibling?.name === '[') {
+    access = access.nextSibling;
+  }
+  const key = access?.nextSibling;
+  if (
+    access === null ||
+    access === undefined ||
+    key === null ||
+    key === undefined
+  ) {
+    return null;
+  }
+  if (access.name === '.' || access.name === '?.') {
+    return key.name === 'PropertyName' ? [...base, text(state, key)] : null;
+  }
+  if (access.name === '[') {
+    if (key.name === 'Number') return [...base, Number(text(state, key))];
+    if (key.name === 'String') {
+      const value = stringValue(text(state, key));
+      return value === null ? null : [...base, value];
+    }
+  }
+  return null;
+}
+
+/** The outermost chain node that ends exactly at `end`. */
+function chainEndingAt(node: SyntaxNode, end: number): SyntaxNode {
+  let at = node;
+  while (
+    at.parent !== null &&
+    at.parent.to === end &&
+    (at.parent.name === 'MemberExpression' ||
+      at.parent.name === 'ParenthesizedExpression')
+  ) {
+    at = at.parent;
+  }
+  return at;
+}
+
+function toPointer(segments: readonly string[]): string {
+  return segments
+    .map((segment) => `/${segment.replaceAll('~', '~0').replaceAll('/', '~1')}`)
+    .join('');
+}
+
+function jsonPointer(state: EditorState, node: SyntaxNode): string {
+  const segments: string[] = [];
+  let child: SyntaxNode = node;
+  for (let at = node.parent; at !== null; child = at, at = at.parent) {
+    if (at.name === 'Property' && child.name !== 'PropertyName') {
+      const name = at.getChild('PropertyName');
+      const key = name === null ? null : stringValue(text(state, name));
+      if (key !== null) segments.unshift(key);
+    } else if (at.name === 'Array') {
+      let index = 0;
+      for (
+        let item = at.firstChild;
+        item !== null && item.from < child.from;
+        item = item.nextSibling
+      ) {
+        if (!['[', ']', ','].includes(item.name)) index++;
+      }
+      segments.unshift(String(index));
+    }
+  }
+  return toPointer(segments);
+}
+
+function yamlPointer(state: EditorState, node: SyntaxNode): string {
+  const segments: string[] = [];
+  let child: SyntaxNode = node;
+  for (let at = node.parent; at !== null; child = at, at = at.parent) {
+    if (at.name === 'Pair' && child.name !== 'Key') {
+      const key = at.getChild('Key');
+      if (key !== null)
+        segments.unshift(text(state, key).replace(/^["']|["']$/g, ''));
+    } else if (at.name === 'Item') {
+      const list = at.parent;
+      if (list === null) continue;
+      let index = 0;
+      for (
+        let item = list.firstChild;
+        item !== null && item.from < at.from;
+        item = item.nextSibling
+      ) {
+        if (item.name === 'Item') index++;
+      }
+      segments.unshift(String(index));
+    }
+  }
+  return toPointer(segments);
+}
+
+/** The context at `pos`, for completion: the word runs up to the cursor. */
+export function cursorContext(state: EditorState, pos: number): CursorContext {
+  const doc = state.doc;
+  let from = pos;
+  while (from > 0 && NAME.test(doc.sliceString(from - 1, from))) from--;
+  const word = doc.sliceString(from, pos);
+  const node = syntaxTree(state).resolveInner(pos, -1);
+  const chain = ancestors(node);
+  const names = new Set(chain.map((at) => at.name));
+  const base = { from, to: pos, word };
+
+  // The JavaScript part of the chain: up to its top (a script, or the
+  // expression of a template's body), not the JSON or YAML around it.
+  const jsTop = chain.findIndex((at) => JS_TOPS.has(at.name));
+  if (jsTop !== -1) {
+    const inJs = chain.slice(0, jsTop + 1);
+    if (inJs.some((at) => JS_COMMENTS.has(at.name))) {
+      return { ...base, region: 'comment', path: null, trigger: 'none' };
+    }
+    const inString = inJs.find((at) => JS_STRINGS.has(at.name));
+    if (inString !== undefined && inString.from < pos && inString.to > pos) {
+      return { ...base, region: 'string', path: null, trigger: 'none' };
+    }
+    const region: CodeRegion =
+      names.has('TemplateBody') || names.has('Template') ? 'template' : 'code';
+    const before = doc.sliceString(Math.max(0, from - 2), from);
+    if (before.endsWith('.')) {
+      const objectEnd = before.endsWith('?.') ? from - 2 : from - 1;
+      const object = chainEndingAt(
+        syntaxTree(state).resolveInner(objectEnd, -1),
+        objectEnd,
+      );
+      return { ...base, region, path: chainOf(state, object), trigger: 'dot' };
+    }
+    if (before.endsWith('[')) {
+      const objectEnd = from - 1;
+      const object = chainEndingAt(
+        syntaxTree(state).resolveInner(objectEnd, -1),
+        objectEnd,
+      );
+      return {
+        ...base,
+        region,
+        path: chainOf(state, object),
+        trigger: 'bracket',
+      };
+    }
+    return {
+      ...base,
+      region,
+      path: [],
+      trigger: word === '' ? 'none' : 'name',
+    };
+  }
+
+  if (names.has('JsonText')) {
+    const pointer = jsonPointer(state, node);
+    if (names.has('PropertyName'))
+      return { ...base, region: 'key', path: null, trigger: 'name', pointer };
+    if (names.has('String'))
+      return {
+        ...base,
+        region: 'string',
+        path: null,
+        trigger: 'none',
+        pointer,
+      };
+    return { ...base, region: 'key', path: null, trigger: 'none', pointer };
+  }
+
+  if (names.has('Stream')) {
+    if (names.has('Key')) {
+      return {
+        ...base,
+        region: 'key',
+        path: null,
+        trigger: 'name',
+        pointer: yamlPointer(state, node),
+      };
+    }
+    if (
+      names.has('Literal') ||
+      names.has('QuotedLiteral') ||
+      names.has('BlockLiteralContent')
+    ) {
+      return {
+        ...base,
+        region: 'string',
+        path: null,
+        trigger: 'none',
+        pointer: yamlPointer(state, node),
+      };
+    }
+  }
+
+  return { ...base, region: 'text', path: null, trigger: 'none' };
+}
+
+/**
+ * The context of the word under `pos`, for hover: the whole word, and the
+ * chain up to and including it (`nodes.score.output` on `output`).
+ */
+export function hoverContext(
+  state: EditorState,
+  pos: number,
+  side: -1 | 1,
+): CursorContext | null {
+  const node = syntaxTree(state).resolveInner(pos, side);
+  if (node.name !== 'VariableName' && node.name !== 'PropertyName') return null;
+  const context = cursorContext(state, node.to);
+  if (context.region !== 'code' && context.region !== 'template') return null;
+  const parent = node.parent;
+  const owner =
+    node.name === 'PropertyName' && parent?.name === 'MemberExpression'
+      ? parent
+      : node;
+  return {
+    ...context,
+    from: node.from,
+    to: node.to,
+    word: text(state, node),
+    path: chainOf(state, owner),
+    trigger: 'none',
+  };
+}
diff --git a/packages/ui/src/components/forms/code-editor/providers.ts b/packages/ui/src/components/forms/code-editor/providers.ts
index 01393f288d..19a3ac74fd 100644
--- a/packages/ui/src/components/forms/code-editor/providers.ts
+++ b/packages/ui/src/components/forms/code-editor/providers.ts
@@ -43,7 +43,10 @@ export interface CodeCompletionContext {
   prefix: string;
   from: number;
   to: number;
-  /** JSON/YAML: pointer of the object whose key or value holds the cursor. */
+  /**
+   * JSON/YAML: in a key, the pointer of the object the key belongs to; in a
+   * value, the pointer of that value.
+   */
   pointer?: string;
   /** Asked for (Ctrl+Space) rather than opened by typing. */
   explicit: boolean;
diff --git a/packages/ui/src/components/forms/code-editor/tooltip-bodies.tsx b/packages/ui/src/components/forms/code-editor/tooltip-bodies.tsx
new file mode 100644
index 0000000000..978d3e9a07
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/tooltip-bodies.tsx
@@ -0,0 +1,143 @@
+'use client';
+
+import { Wrench } from 'lucide-react';
+import { useEffect, useRef, type KeyboardEvent } from 'react';
+
+import { useT } from '../../../i18n/client';
+import { IssueSeverityIcon } from '../../feedback/issue-severity';
+import { Button } from '../../primitives/button';
+import type { PlacedDiagnostic, PlacedFix } from './extensions/diagnostics';
+import { highlightType } from './extensions/highlight';
+import type { CodeHoverInfo } from './providers';
+
+/**
+ * The React bodies of the editor's tooltips, rendered into the DOM
+ * CodeMirror positions (see `extensions/tooltips.ts`).
+ */
+
+/** Arrow keys move between a tooltip's fix buttons. */
+function moveBetweenButtons(event: KeyboardEvent<HTMLDivElement>): void {
+  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+  const buttons = [
+    ...event.currentTarget.querySelectorAll<HTMLButtonElement>('button'),
+  ];
+  const at = buttons.findIndex((button) => button === document.activeElement);
+  if (at === -1) return;
+  event.preventDefault();
+  const next =
+    (at + (event.key === 'ArrowDown' ? 1 : -1) + buttons.length) %
+    buttons.length;
+  buttons[next]?.focus();
+}
+
+export function DiagnosticTooltipBody({
+  items,
+  focusFix,
+  onFix,
+}: {
+  items: readonly PlacedDiagnostic[];
+  focusFix: boolean;
+  onFix: (fix: PlacedFix) => void;
+}) {
+  const { t } = useT('codeEditor');
+  const firstFix = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (focusFix) firstFix.current?.focus();
+  }, [focusFix]);
+  const severity = {
+    error: t('diagnostics.severity.error'),
+    warning: t('diagnostics.severity.warning'),
+    info: t('diagnostics.severity.info'),
+  };
+  const fixes = items.flatMap((item) => item.fixes);
+  return (
+    <div className="flex max-w-80 flex-col gap-2 p-2">
+      {items.map((item) => (
+        <div key={item.key} className="flex gap-2">
+          <IssueSeverityIcon
+            severity={item.diagnostic.severity}
+            className="mt-0.5 size-4 shrink-0"
+          />
+          <div className="min-w-0 space-y-1">
+            <p className="text-foreground text-sm break-words">
+              <span className="sr-only">
+                {severity[item.diagnostic.severity]}:{' '}
+              </span>
+              {item.diagnostic.message}
+            </p>
+            {item.diagnostic.detail}
+            {item.diagnostic.code !== undefined ? (
+              <p className="text-muted-foreground font-mono text-xs">
+                {item.diagnostic.code}
+              </p>
+            ) : null}
+          </div>
+        </div>
+      ))}
+      {fixes.length > 0 ? (
+        <div
+          role="toolbar"
+          tabIndex={-1}
+          aria-orientation="vertical"
+          aria-label={t('diagnostics.fixMenu')}
+          className="border-border flex flex-col items-start gap-1 border-t pt-2"
+          onKeyDown={moveBetweenButtons}
+        >
+          {fixes.map((fix, index) => (
+            <Button
+              key={`${fix.label}-${index}`}
+              ref={index === 0 ? firstFix : undefined}
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => onFix(fix)}
+            >
+              <Wrench className="size-3.5" aria-hidden="true" />
+              {fix.label}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** A TypeScript type in the editor's colours. */
+function TypeText({ type }: { type: string }) {
+  return (
+    <code className="font-mono text-xs break-words whitespace-pre-wrap">
+      {highlightType(type).map((run, index) => (
+        <span key={index} className={run.className || undefined}>
+          {run.text}
+        </span>
+      ))}
+    </code>
+  );
+}
+
+export function TypeTooltipBody({ info }: { info: CodeHoverInfo }) {
+  const { t } = useT('codeEditor');
+  return (
+    <div className="flex max-w-80 flex-col gap-1 p-2 text-xs">
+      {info.title !== undefined ? (
+        <p className="text-foreground font-mono font-medium break-all">
+          {info.title}
+        </p>
+      ) : null}
+      <p className="flex gap-1">
+        <span className="text-muted-foreground shrink-0">
+          {t('typeInfo.label')}
+        </span>
+        <TypeText type={info.type} />
+      </p>
+      {info.description !== undefined ? (
+        <p className="text-foreground">{info.description}</p>
+      ) : null}
+      {info.sample !== undefined ? (
+        <p className="text-muted-foreground font-mono break-all">
+          {t('typeInfo.sample', { value: info.sample })}
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/i18n/messages/de-CH.yml b/packages/ui/src/i18n/messages/de-CH.yml
index a462758f09..f2f33bb8f0 100644
--- a/packages/ui/src/i18n/messages/de-CH.yml
+++ b/packages/ui/src/i18n/messages/de-CH.yml
@@ -14,6 +14,9 @@ common:
 envEditor:
   projectSecretBadKey: «{key}» muss mit einem Grossbuchstaben beginnen und darf nur Grossbuchstaben, Ziffern oder Unterstriche enthalten (maximal 64 Zeichen).
 codeEditor:
+  expand: Editor vergrössern
+  syntax:
+    unterminatedTemplate: "Zu diesem '{{' fehlt das schliessende '}}'."
   phrases:
     close: Schliessen
     matchCase: Gross-/Kleinschreibung
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index 146bd030e9..97dcabf10a 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -446,6 +446,29 @@ codeEditor:
   leaveArmed: Drücke Tab, um weiterzugehen.
   tabFocusOn: Tab wechselt jetzt den Fokus.
   tabFocusOff: Tab rückt jetzt ein.
+  expand: Editor vergrößern
+  collapse: Zurück zum Feld
+  diagnostics:
+    atCursor: '{severity} in Zeile {line}: {message}'
+    severity:
+      error: Fehler
+      warning: Warnung
+      info: Hinweis
+    fixAvailable: 'Korrektur verfügbar: Drücke {shortcut}.'
+    fixApplied: 'Angewendet: {label}'
+    fixMenu: Korrekturen
+    lineItem: 'Zeile {line}: {message}'
+    more: '{count, plural, one {und # weiteres Problem} other {und # weitere Probleme}}'
+  syntax:
+    json: Hier ist das kein gültiges JSON.
+    yaml: Hier ist das kein gültiges YAML.
+    javascript: Das lässt sich hier nicht als JavaScript lesen. Prüfe, ob eine Klammer, ein Anführungszeichen oder ein Komma fehlt.
+    unterminatedTemplate: "Zu diesem '{{' fehlt das schließende '}}'."
+  typeInfo:
+    label: Typ
+    announce: '{title}: {type}'
+    optional: optional
+    sample: 'Letzter Lauf: {value}'
   phrases:
     controlCharacter: Steuerzeichen
     close: Schließen
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index 1c983911f0..6e4688da76 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -446,6 +446,29 @@ codeEditor:
   leaveArmed: Press Tab to move on.
   tabFocusOn: Tab now moves focus.
   tabFocusOff: Tab now indents.
+  expand: Expand editor
+  collapse: Back to the field
+  diagnostics:
+    atCursor: '{severity} on line {line}: {message}'
+    severity:
+      error: Error
+      warning: Warning
+      info: Note
+    fixAvailable: 'Fix available: press {shortcut}.'
+    fixApplied: 'Applied: {label}'
+    fixMenu: Fixes
+    lineItem: 'Line {line}: {message}'
+    more: '{count, plural, one {and # more problem} other {and # more problems}}'
+  syntax:
+    json: This isn't valid JSON here.
+    yaml: This isn't valid YAML here.
+    javascript: This can't be read as JavaScript here. Look for a missing bracket, quote or comma.
+    unterminatedTemplate: "This '{{' has no closing '}}'."
+  typeInfo:
+    label: Type
+    announce: '{title}: {type}'
+    optional: optional
+    sample: 'Last run: {value}'
   phrases:
     controlCharacter: Control character
     close: Close
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 3dba856318..3b12746dc9 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -446,6 +446,29 @@ codeEditor:
   leaveArmed: Appuie sur Tab pour continuer.
   tabFocusOn: Tab déplace maintenant le focus.
   tabFocusOff: Tab indente maintenant.
+  expand: Agrandir l'éditeur
+  collapse: Revenir au champ
+  diagnostics:
+    atCursor: '{severity} à la ligne {line} : {message}'
+    severity:
+      error: Erreur
+      warning: Avertissement
+      info: Remarque
+    fixAvailable: 'Correction disponible : appuie sur {shortcut}.'
+    fixApplied: 'Appliqué : {label}'
+    fixMenu: Corrections
+    lineItem: 'Ligne {line} : {message}'
+    more: '{count, plural, one {et # autre problème} many {et # autres problèmes} other {et # autres problèmes}}'
+  syntax:
+    json: Ce n'est pas du JSON valide ici.
+    yaml: Ce n'est pas du YAML valide ici.
+    javascript: Impossible de lire ceci comme du JavaScript. Vérifie s'il manque une parenthèse, un guillemet ou une virgule.
+    unterminatedTemplate: "Ce '{{' n'a pas de '}}' fermant."
+  typeInfo:
+    label: Type
+    announce: '{title} : {type}'
+    optional: facultatif
+    sample: 'Dernière exécution : {value}'
   phrases:
     controlCharacter: Caractère de contrôle
     close: Fermer

From a1902d4f4e475874257308f7be99ff15210b2bf4 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 09:19:39 +0200
Subject: [PATCH 10/78] feat(ui): add SchemaTree and move VendorIcon into the
 package
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SchemaTree lists the fields a value has the way a form reads: each
field's name, its kind in words (text, a number, list of objects, one of
“open” or “closed”), whether it is required, a host's tag (from the
trigger) and whether it may be empty; compact for a summary, comfortable
with nested fields and descriptions, and the same shape as TypeScript
behind a disclosure. schemaKindLabel gives the kind alone. French carries
the preposition in the plural kinds, so a list of objects elides.

VendorIcon moves unchanged from the platform's credential settings to
@tale/ui/vendor-icon, so automation nodes can show a connector's icon.
---
 packages/ui/package.json                      |   2 +
 .../data-display/schema-tree.browser.test.tsx |  78 ++++
 .../data-display/schema-tree.test.tsx         | 176 +++++++++
 .../components/data-display/schema-tree.tsx   | 351 ++++++++++++++++++
 .../data-display/vendor-icon.test.tsx         |  37 ++
 .../components/data-display}/vendor-icon.tsx  |   7 +-
 packages/ui/src/i18n/messages/de.yml          |  26 ++
 packages/ui/src/i18n/messages/en.yml          |  26 ++
 packages/ui/src/i18n/messages/fr.yml          |  26 ++
 .../settings/credentials/credential-table.tsx |   2 +-
 .../credentials/vendor-picker-pane.tsx        |   2 +-
 11 files changed, 728 insertions(+), 5 deletions(-)
 create mode 100644 packages/ui/src/components/data-display/schema-tree.browser.test.tsx
 create mode 100644 packages/ui/src/components/data-display/schema-tree.test.tsx
 create mode 100644 packages/ui/src/components/data-display/schema-tree.tsx
 create mode 100644 packages/ui/src/components/data-display/vendor-icon.test.tsx
 rename {services/platform/app/features/settings/credentials => packages/ui/src/components/data-display}/vendor-icon.tsx (81%)

diff --git a/packages/ui/package.json b/packages/ui/package.json
index f2a132fbf9..418925e970 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -284,6 +284,7 @@
     "./responsive-dialog": "./src/components/overlays/responsive-dialog.tsx",
     "./route-progress-bar": "./src/components/layout/route-progress-bar.tsx",
     "./schedule-occurrence-list": "./src/components/data-display/schedule-occurrence-list.tsx",
+    "./schema-tree": "./src/components/data-display/schema-tree.tsx",
     "./scroll-wheel-chain": "./src/lib/scroll-wheel-chain.ts",
     "./search": "./src/components/search/index.ts",
     "./search-input": "./src/components/forms/search-input.tsx",
@@ -410,6 +411,7 @@
     "./use-viewport-visibility": "./src/hooks/use-viewport-visibility.ts",
     "./use-zoom-pan": "./src/hooks/use-zoom-pan.ts",
     "./validation-check-item": "./src/components/feedback/validation-check-item.tsx",
+    "./vendor-icon": "./src/components/data-display/vendor-icon.tsx",
     "./vite/message-topics": "./src/vite/message-topics.ts",
     "./vite/yaml": "./src/vite/yaml.ts",
     "./wizard/use-wizard": "./src/components/wizard/use-wizard.ts",
diff --git a/packages/ui/src/components/data-display/schema-tree.browser.test.tsx b/packages/ui/src/components/data-display/schema-tree.browser.test.tsx
new file mode 100644
index 0000000000..4f8f4c632c
--- /dev/null
+++ b/packages/ui/src/components/data-display/schema-tree.browser.test.tsx
@@ -0,0 +1,78 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { afterEach, describe, expect, it } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+import { render, screen } from '@/tests/utils/render';
+
+import { SchemaTree, type SchemaTreeSchema } from './schema-tree';
+
+import '../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+});
+
+const SHAPE: SchemaTreeSchema = {
+  type: 'object',
+  required: ['reviewed'],
+  properties: {
+    reviewed: { type: 'integer', description: 'How many issues were read.' },
+    actionable: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { title: { type: 'string' }, score: { type: 'number' } },
+      },
+    },
+  },
+};
+
+describe.each(['light', 'dark'])('SchemaTree (%s)', (theme) => {
+  it.each(['bg-background', 'bg-card', 'bg-bg-elevated'])(
+    'reads at AA on %s',
+    async (surface) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      const { container } = render(
+        <div className={`${surface} p-4`}>
+          <SchemaTree
+            schema={SHAPE}
+            tagOf={(path) =>
+              path[0] === 'reviewed' ? 'from Report' : undefined
+            }
+            maybeEmpty={(path) => path[0] === 'actionable'}
+            typeScript="{ reviewed: number; actionable: { title: string }[] }"
+          />
+        </div>,
+      );
+      const result = await axe.run(container, {
+        runOnly: ['color-contrast', 'list', 'listitem', 'aria-allowed-attr'],
+      });
+      expect(result.violations).toEqual([]);
+      expect(result.passes.some((rule) => rule.id === 'color-contrast')).toBe(
+        true,
+      );
+    },
+  );
+});
+
+it('opens the TypeScript shape from the keyboard', async () => {
+  render(
+    <>
+      <button type="button">Before</button>
+      <SchemaTree schema={SHAPE} typeScript="{ reviewed: number }" />
+    </>,
+  );
+  await userEvent.click(screen.getByRole('button', { name: 'Before' }));
+  await userEvent.keyboard('{Tab}');
+  const summary = screen.getByText('Show as TypeScript');
+  expect(summary).toHaveFocus();
+  await userEvent.keyboard('{Enter}');
+  const details = summary.closest('details') as HTMLDetailsElement;
+  expect(details).toHaveAttribute('open');
+  const code = details.querySelector('code');
+  expect(code).toBeVisible();
+  expect(code?.textContent).toContain('reviewed: number');
+});
diff --git a/packages/ui/src/components/data-display/schema-tree.test.tsx b/packages/ui/src/components/data-display/schema-tree.test.tsx
new file mode 100644
index 0000000000..d2570bd8de
--- /dev/null
+++ b/packages/ui/src/components/data-display/schema-tree.test.tsx
@@ -0,0 +1,176 @@
+import type { TFunction } from 'i18next';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
+
+import { initServiceI18n } from '../../i18n/init-service';
+import { uiMessages } from '../../i18n/messages';
+import {
+  SchemaTree,
+  schemaKindLabel,
+  type SchemaTreeSchema,
+} from './schema-tree';
+
+let i18n: ReturnType<typeof initServiceI18n>;
+beforeAll(() => {
+  i18n = initServiceI18n({
+    bundles: { en: {}, de: {}, fr: {} },
+    regional: {},
+    packages: [uiMessages],
+  });
+});
+
+function tFor(locale: string): TFunction {
+  return i18n.getFixedT(locale, 'schemaTree');
+}
+
+const ISSUES: SchemaTreeSchema = {
+  type: 'object',
+  required: ['owner', 'repo'],
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'The account that owns the repository.',
+    },
+    repo: { type: 'string' },
+    limit: { type: 'integer' },
+    state: { enum: ['open', 'closed'] },
+    labels: { type: 'array', items: { type: 'string' } },
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title'],
+        properties: {
+          title: { type: 'string' },
+          score: { type: ['number', 'null'] },
+        },
+      },
+    },
+  },
+};
+
+describe('schemaKindLabel', () => {
+  it.each([
+    ['en', { type: 'string' }, 'text'],
+    ['en', { type: 'integer' }, 'a whole number'],
+    ['en', { type: 'array', items: { type: 'object' } }, 'list of objects'],
+    ['en', { type: 'array', items: { type: 'array' } }, 'list of lists'],
+    ['en', { type: 'array' }, 'list of values'],
+    ['en', { type: ['string', 'null'] }, 'text or empty'],
+    [
+      'en',
+      { anyOf: [{ type: 'number' }, { type: 'boolean' }] },
+      'a number or true or false',
+    ],
+    ['en', { properties: { a: {} } }, 'an object'],
+    ['en', {}, 'anything'],
+    ['de', { type: 'array', items: { type: 'string' } }, 'Liste von Texten'],
+    ['de', { type: 'boolean' }, 'wahr oder falsch'],
+    // French carries the preposition in the plural, so "objets" elides.
+    ['fr', { type: 'array', items: { type: 'object' } }, "liste d'objets"],
+    ['fr', { type: 'array', items: { type: 'number' } }, 'liste de nombres'],
+  ] as const)('%s: %j reads "%s"', (locale, schema, expected) => {
+    expect(schemaKindLabel(tFor(locale), schema, locale)).toBe(expected);
+  });
+
+  it('quotes the values of an enum the way each language does', () => {
+    const schema = { enum: ['draft', 'sent'] };
+    expect(schemaKindLabel(tFor('en'), schema, 'en')).toBe(
+      'one of “draft” or “sent”',
+    );
+    expect(schemaKindLabel(tFor('de'), schema, 'de')).toBe(
+      'eines von „draft“ oder „sent“',
+    );
+    expect(schemaKindLabel(tFor('fr'), schema, 'fr')).toBe(
+      "l'un de «\u00a0draft\u00a0» ou «\u00a0sent\u00a0»",
+    );
+    expect(schemaKindLabel(tFor('de'), schema, 'de-CH')).toBe(
+      'eines von «draft» oder «sent»',
+    );
+  });
+});
+
+describe('SchemaTree', () => {
+  it('lists the top-level fields with their kind, compactly', () => {
+    render(<SchemaTree schema={ISSUES} density="compact" />);
+    const list = screen.getByRole('list', { name: 'Fields' });
+    const rows = [...list.querySelectorAll(':scope > li')].map(
+      (row) => row.textContent,
+    );
+    expect(rows).toEqual([
+      'owner text · required',
+      'repo text · required',
+      'limit a whole number',
+      'state one of “open” or “closed”',
+      'labels list of texts',
+      'issues list of objects',
+    ]);
+    expect(
+      screen.queryByText('The account that owns the repository.'),
+    ).toBeNull();
+  });
+
+  it('stops at maxRows and says how many fields are left', () => {
+    render(<SchemaTree schema={ISSUES} density="compact" maxRows={2} />);
+    expect(screen.getAllByRole('listitem')).toHaveLength(3);
+    expect(screen.getByText('4 more fields')).toBeInTheDocument();
+  });
+
+  it('nests the fields of objects and of list items, with descriptions', () => {
+    render(<SchemaTree schema={ISSUES} />);
+    expect(
+      screen.getByText('The account that owns the repository.'),
+    ).toBeInTheDocument();
+    const issues = screen.getByText('issues').closest('li') as HTMLElement;
+    const nested = [...issues.querySelectorAll('ul > li')].map(
+      (row) => row.textContent,
+    );
+    expect(nested).toEqual([
+      'title text · required',
+      'score a number or empty · optional',
+    ]);
+    // Optional only says so where the object names what is required.
+    expect(screen.getByText('limit').nextElementSibling?.textContent).toBe(
+      'a whole number · optional',
+    );
+  });
+
+  it('tags fields and says which may be empty', () => {
+    render(
+      <SchemaTree
+        schema={ISSUES}
+        density="compact"
+        tagOf={(path) => (path[0] === 'owner' ? 'from the trigger' : undefined)}
+        maybeEmpty={(path) => path[0] === 'limit'}
+      />,
+    );
+    expect(screen.getByText('owner').nextElementSibling?.textContent).toBe(
+      'text · required · from the trigger',
+    );
+    expect(screen.getByText('limit').nextElementSibling?.textContent).toBe(
+      'a whole number · may be empty',
+    );
+  });
+
+  it('says the kind of a value that has no fields', () => {
+    render(
+      <SchemaTree schema={{ type: 'array', items: { type: 'number' } }} />,
+    );
+    expect(screen.getByText('list of numbers')).toBeInTheDocument();
+    expect(screen.queryByRole('list')).toBeNull();
+  });
+
+  it('offers the shape as TypeScript behind a disclosure', () => {
+    render(<SchemaTree schema={ISSUES} typeScript="{ owner: string }" />);
+    expect(screen.getByText('Show as TypeScript')).toBeInTheDocument();
+  });
+
+  it('passes axe audit', async () => {
+    const { container } = render(
+      <SchemaTree schema={ISSUES} typeScript="{ owner: string }" />,
+    );
+    await checkAccessibility(container);
+  });
+});
diff --git a/packages/ui/src/components/data-display/schema-tree.tsx b/packages/ui/src/components/data-display/schema-tree.tsx
new file mode 100644
index 0000000000..2a7725524a
--- /dev/null
+++ b/packages/ui/src/components/data-display/schema-tree.tsx
@@ -0,0 +1,351 @@
+'use client';
+
+import type { TFunction } from 'i18next';
+import { useTranslation } from 'react-i18next';
+
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import { HighlightedCode } from '../../markdown/highlighted-code';
+import { CollapsibleDetails } from '../navigation/collapsible-details';
+
+/**
+ * The fields a value has, as a reader reads a form: each field's name, what
+ * kind of value it holds in words ("text", "a number", "list of objects"),
+ * whether it is required, and where it comes from. For the input a run
+ * starts with, what a step receives and returns, a webhook's payload.
+ */
+
+/** A JSON Schema subset: what describes the fields of a value. */
+export interface SchemaTreeSchema {
+  type?:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'object'
+    | 'array'
+    | 'null'
+    | ReadonlyArray<string>;
+  properties?: Readonly<Record<string, SchemaTreeSchema>>;
+  required?: readonly string[];
+  items?: SchemaTreeSchema;
+  enum?: readonly unknown[];
+  anyOf?: readonly SchemaTreeSchema[];
+  /** Written by the author; shown as is (document content, not translated). */
+  description?: string;
+}
+
+export interface SchemaTreeProps {
+  schema: SchemaTreeSchema;
+  /**
+   * `compact`: the top-level fields, one line each (a node's face, a
+   * summary). `comfortable`: nested fields and descriptions too.
+   */
+  density?: 'compact' | 'comfortable';
+  /** Top-level fields shown before "+n more fields". */
+  maxRows?: number;
+  /** A tag after the kind: "from the trigger", "from Triage". */
+  tagOf?: (path: readonly string[]) => string | undefined;
+  /** Adds "may be empty" to a field. */
+  maybeEmpty?: (path: readonly string[]) => boolean;
+  /** The same shape as TypeScript, behind "Show as TypeScript". */
+  typeScript?: string;
+  'aria-label'?: string;
+  className?: string;
+}
+
+type PluralKind =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'any';
+
+function typesOf(schema: SchemaTreeSchema): string[] {
+  if (schema.type === undefined) return [];
+  return typeof schema.type === 'string' ? [schema.type] : [...schema.type];
+}
+
+function singular(t: TFunction, kind: string): string {
+  switch (kind) {
+    case 'string':
+      return t('kinds.string');
+    case 'number':
+      return t('kinds.number');
+    case 'integer':
+      return t('kinds.integer');
+    case 'boolean':
+      return t('kinds.boolean');
+    case 'object':
+      return t('kinds.object');
+    case 'null':
+      return t('kinds.null');
+    default:
+      return t('kinds.any');
+  }
+}
+
+function plural(t: TFunction, kind: PluralKind): string {
+  switch (kind) {
+    case 'string':
+      return t('kindsPlural.string');
+    case 'number':
+      return t('kindsPlural.number');
+    case 'integer':
+      return t('kindsPlural.integer');
+    case 'boolean':
+      return t('kindsPlural.boolean');
+    case 'object':
+      return t('kindsPlural.object');
+    case 'array':
+      return t('kindsPlural.array');
+    default:
+      return t('kindsPlural.any');
+  }
+}
+
+/** The kind a list's items have, in the plural ("texts", "objects"). */
+function itemsKind(schema: SchemaTreeSchema | undefined): PluralKind {
+  const [first] = schema === undefined ? [] : typesOf(schema);
+  if (
+    first === 'string' ||
+    first === 'number' ||
+    first === 'integer' ||
+    first === 'boolean' ||
+    first === 'object' ||
+    first === 'array'
+  ) {
+    return first;
+  }
+  if (schema?.properties !== undefined) return 'object';
+  return 'any';
+}
+
+/** Quotation marks of the reader's language around a literal value. */
+function quoted(locale: string, value: unknown): string {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  if (locale.startsWith('de-CH')) return `«${text}»`;
+  if (locale.startsWith('de')) return `„${text}“`;
+  if (locale.startsWith('fr')) return `« ${text} »`;
+  return `“${text}”`;
+}
+
+function either(locale: string, parts: string[]): string {
+  return new Intl.ListFormat(locale, {
+    style: 'long',
+    type: 'disjunction',
+  }).format(parts);
+}
+
+/**
+ * A schema's kind in words: "text", "a number", "list of objects",
+ * "one of “draft” or “sent”", "text or empty".
+ */
+export function schemaKindLabel(
+  t: TFunction,
+  schema: SchemaTreeSchema,
+  locale = 'en',
+): string {
+  if (schema.enum !== undefined && schema.enum.length > 0) {
+    return t('oneOf', {
+      values: either(
+        locale,
+        schema.enum.map((value) => quoted(locale, value)),
+      ),
+    });
+  }
+  if (schema.anyOf !== undefined && schema.anyOf.length > 0) {
+    return either(
+      locale,
+      schema.anyOf.map((option) => schemaKindLabel(t, option, locale)),
+    );
+  }
+  const types = typesOf(schema);
+  if (types.length === 0) {
+    return schema.properties !== undefined ? t('kinds.object') : t('kinds.any');
+  }
+  return either(
+    locale,
+    types.map((type) =>
+      type === 'array'
+        ? t('kinds.array', { item: plural(t, itemsKind(schema.items)) })
+        : singular(t, type),
+    ),
+  );
+}
+
+/** The fields to list under a schema: its own, or those of its items. */
+function fieldsOf(schema: SchemaTreeSchema): {
+  properties: Readonly<Record<string, SchemaTreeSchema>>;
+  required: readonly string[];
+} | null {
+  if (schema.properties !== undefined) {
+    return { properties: schema.properties, required: schema.required ?? [] };
+  }
+  if (schema.items?.properties !== undefined) {
+    return {
+      properties: schema.items.properties,
+      required: schema.items.required ?? [],
+    };
+  }
+  return null;
+}
+
+interface RowsProps {
+  schema: SchemaTreeSchema;
+  path: readonly string[];
+  density: 'compact' | 'comfortable';
+  maxRows: number | undefined;
+  tagOf: SchemaTreeProps['tagOf'];
+  maybeEmpty: SchemaTreeProps['maybeEmpty'];
+  t: TFunction;
+  locale: string;
+  label?: string;
+  nested?: boolean;
+}
+
+function Rows({
+  schema,
+  path,
+  density,
+  maxRows,
+  tagOf,
+  maybeEmpty,
+  t,
+  locale,
+  label,
+  nested = false,
+}: RowsProps) {
+  const fields = fieldsOf(schema);
+  if (fields === null) return null;
+  const names = Object.keys(fields.properties);
+  const shown = maxRows === undefined ? names : names.slice(0, maxRows);
+  const hidden = names.length - shown.length;
+  const comfortable = density === 'comfortable';
+  return (
+    <ul
+      aria-label={label}
+      className={cn(
+        'flex flex-col',
+        nested && 'border-border mt-1 ml-1 border-l pl-4',
+      )}
+    >
+      {shown.map((name) => {
+        const field = fields.properties[name] ?? {};
+        const fieldPath = [...path, name];
+        const isRequired = fields.required.includes(name);
+        const tag = tagOf?.(fieldPath);
+        const empty = maybeEmpty?.(fieldPath) ?? false;
+        const notes = [
+          schemaKindLabel(t, field, locale),
+          ...(isRequired
+            ? [t('required')]
+            : comfortable && fields.required.length > 0
+              ? [t('optional')]
+              : []),
+          ...(tag !== undefined ? [tag] : []),
+          ...(empty ? [t('maybeEmpty')] : []),
+        ];
+        return (
+          <li
+            key={name}
+            className={cn(
+              'flex flex-col justify-center',
+              comfortable ? 'min-h-8 py-1' : 'min-h-6',
+            )}
+          >
+            <span className="flex min-w-0 flex-wrap items-baseline gap-x-1.5">
+              <span className="text-foreground font-mono text-xs break-all">
+                {name}
+              </span>{' '}
+              <span className="text-muted-foreground text-xs">
+                {notes.join(' · ')}
+              </span>
+            </span>
+            {comfortable && field.description !== undefined ? (
+              <span className="text-muted-foreground text-xs">
+                {field.description}
+              </span>
+            ) : null}
+            {comfortable ? (
+              <Rows
+                schema={field}
+                path={fieldPath}
+                density={density}
+                maxRows={undefined}
+                tagOf={tagOf}
+                maybeEmpty={maybeEmpty}
+                t={t}
+                locale={locale}
+                nested
+              />
+            ) : null}
+          </li>
+        );
+      })}
+      {hidden > 0 ? (
+        <li
+          className={cn(
+            'text-muted-foreground flex items-center text-xs',
+            comfortable ? 'min-h-8' : 'min-h-6',
+          )}
+        >
+          {t('more', { count: hidden })}
+        </li>
+      ) : null}
+    </ul>
+  );
+}
+
+export function SchemaTree({
+  schema,
+  density = 'comfortable',
+  maxRows,
+  tagOf,
+  maybeEmpty,
+  typeScript,
+  'aria-label': ariaLabel,
+  className,
+}: SchemaTreeProps) {
+  const { t } = useT('schemaTree');
+  // The UI language decides the quotes and the "or" of a list of kinds.
+  const { i18n } = useTranslation();
+  const locale = i18n?.resolvedLanguage ?? i18n?.language ?? 'en';
+  const hasFields = fieldsOf(schema) !== null;
+  return (
+    <div
+      data-slot="schema-tree"
+      className={cn('flex flex-col gap-2', className)}
+    >
+      {hasFields ? (
+        <Rows
+          schema={schema}
+          path={[]}
+          density={density}
+          maxRows={maxRows}
+          tagOf={tagOf}
+          maybeEmpty={maybeEmpty}
+          t={t}
+          locale={locale}
+          label={ariaLabel ?? t('label')}
+        />
+      ) : (
+        <p className="text-muted-foreground text-xs">
+          {schemaKindLabel(t, schema, locale)}
+        </p>
+      )}
+      {typeScript !== undefined ? (
+        <CollapsibleDetails variant="compact" summary={t('asTypeScript')}>
+          <HighlightedCode
+            code={typeScript}
+            language="typescript"
+            showLineNumbers={false}
+            className="bg-bg-elevated border-border-base mt-2 rounded-md border text-xs [&_pre]:text-xs"
+          />
+        </CollapsibleDetails>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/data-display/vendor-icon.test.tsx b/packages/ui/src/components/data-display/vendor-icon.test.tsx
new file mode 100644
index 0000000000..794f73491a
--- /dev/null
+++ b/packages/ui/src/components/data-display/vendor-icon.test.tsx
@@ -0,0 +1,37 @@
+import { fireEvent } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { render } from '@/tests/utils/render';
+
+import { VendorIcon } from './vendor-icon';
+
+describe('VendorIcon', () => {
+  it("shows the vendor's icon as decoration", () => {
+    const { container } = render(<VendorIcon iconUrl="/icons/github.svg" />);
+    const image = container.querySelector('img');
+    expect(image).toHaveAttribute('src', '/icons/github.svg');
+    expect(image).toHaveAttribute('alt', '');
+  });
+
+  it('falls back to the plug glyph without an icon or when it fails to load', () => {
+    const { container, rerender } = render(<VendorIcon />);
+    expect(container.querySelector('img')).toBeNull();
+    expect(container.querySelector('svg')).toHaveAttribute(
+      'aria-hidden',
+      'true',
+    );
+
+    rerender(<VendorIcon iconUrl="/icons/broken.svg" />);
+    const image = container.querySelector('img') as HTMLImageElement;
+    fireEvent.error(image);
+    expect(container.querySelector('img')).toBeNull();
+    expect(container.querySelector('svg')).not.toBeNull();
+
+    // Another vendor's icon gets its own attempt.
+    rerender(<VendorIcon iconUrl="/icons/slack.svg" />);
+    expect(container.querySelector('img')).toHaveAttribute(
+      'src',
+      '/icons/slack.svg',
+    );
+  });
+});
diff --git a/services/platform/app/features/settings/credentials/vendor-icon.tsx b/packages/ui/src/components/data-display/vendor-icon.tsx
similarity index 81%
rename from services/platform/app/features/settings/credentials/vendor-icon.tsx
rename to packages/ui/src/components/data-display/vendor-icon.tsx
index 73c04c99ce..506d23ae6a 100644
--- a/services/platform/app/features/settings/credentials/vendor-icon.tsx
+++ b/packages/ui/src/components/data-display/vendor-icon.tsx
@@ -1,12 +1,13 @@
 'use client';
 
-import { cn } from '@tale/ui/cn';
 import { Plug } from 'lucide-react';
 import { useState } from 'react';
 
+import { cn } from '../../lib/cn';
+
 /**
- * A vendor's shipped icon — a connector's or an AI provider's — falling back to
- * the generic plug glyph. Not every vendor ships an `icon.svg` (WebDAV
+ * `@tale/ui/vendor-icon` — a vendor's shipped icon (a connector's, an AI
+ * provider's), falling back to the generic plug glyph. Not every vendor ships an `icon.svg` (WebDAV
  * doesn't), and a served icon can still fail to load. Decorative either way:
  * the vendor's name sits right next to it, so the image carries an empty alt
  * instead of doubling the heading for screen readers.
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index 97dcabf10a..23a37c8206 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -497,3 +497,29 @@ codeEditor:
     onLine: in Zeile
     replacedMatches: $ Treffer ersetzt
     replacedMatchOnLine: Treffer in Zeile $ ersetzt
+
+schemaTree:
+  label: Felder
+  kinds:
+    string: Text
+    number: eine Zahl
+    integer: eine ganze Zahl
+    boolean: wahr oder falsch
+    object: ein Objekt
+    'null': leer
+    any: beliebig
+    array: Liste von {item}
+  kindsPlural:
+    string: Texten
+    number: Zahlen
+    integer: ganzen Zahlen
+    boolean: Wahrheitswerten
+    object: Objekten
+    array: Listen
+    any: Werten
+  oneOf: eines von {values}
+  required: Pflicht
+  optional: optional
+  maybeEmpty: kann leer sein
+  more: '{count, plural, one {# weiteres Feld} other {# weitere Felder}}'
+  asTypeScript: Als TypeScript zeigen
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index 6e4688da76..cd745a45f4 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -497,3 +497,29 @@ codeEditor:
     onLine: on line
     replacedMatches: Replaced $ matches
     replacedMatchOnLine: Replaced a match on line $
+
+schemaTree:
+  label: Fields
+  kinds:
+    string: text
+    number: a number
+    integer: a whole number
+    boolean: true or false
+    object: an object
+    'null': empty
+    any: anything
+    array: list of {item}
+  kindsPlural:
+    string: texts
+    number: numbers
+    integer: whole numbers
+    boolean: true/false values
+    object: objects
+    array: lists
+    any: values
+  oneOf: one of {values}
+  required: required
+  optional: optional
+  maybeEmpty: may be empty
+  more: '{count, plural, one {# more field} other {# more fields}}'
+  asTypeScript: Show as TypeScript
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 3b12746dc9..7f69f43a2a 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -497,3 +497,29 @@ codeEditor:
     onLine: à la ligne
     replacedMatches: $ correspondances remplacées
     replacedMatchOnLine: Correspondance remplacée à la ligne $
+
+schemaTree:
+  label: Champs
+  kinds:
+    string: texte
+    number: un nombre
+    integer: un nombre entier
+    boolean: vrai ou faux
+    object: un objet
+    'null': vide
+    any: quelconque
+    array: liste {item}
+  kindsPlural:
+    string: de textes
+    number: de nombres
+    integer: de nombres entiers
+    boolean: de valeurs vrai/faux
+    object: d'objets
+    array: de listes
+    any: de valeurs
+  oneOf: l'un de {values}
+  required: obligatoire
+  optional: facultatif
+  maybeEmpty: peut être vide
+  more: '{count, plural, one {# autre champ} many {# autres champs} other {# autres champs}}'
+  asTypeScript: Afficher en TypeScript
diff --git a/services/platform/app/features/settings/credentials/credential-table.tsx b/services/platform/app/features/settings/credentials/credential-table.tsx
index 4c7c0c4511..491a014257 100644
--- a/services/platform/app/features/settings/credentials/credential-table.tsx
+++ b/services/platform/app/features/settings/credentials/credential-table.tsx
@@ -12,6 +12,7 @@ import {
 import { HStack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { DEFAULT_LIST_PAGE_SIZE, useListPage } from '@tale/ui/use-list-page';
+import { VendorIcon } from '@tale/ui/vendor-icon';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Plus, type LucideIcon } from 'lucide-react';
 import { useMemo, useState } from 'react';
@@ -25,7 +26,6 @@ import {
 } from './adapter';
 import { CredentialAddDialog } from './credential-add-dialog';
 import { CredentialRowActions } from './credential-row-actions';
-import { VendorIcon } from './vendor-icon';
 
 /** The per-surface copy the shared table cannot name for itself. */
 export interface CredentialTableLabels {
diff --git a/services/platform/app/features/settings/credentials/vendor-picker-pane.tsx b/services/platform/app/features/settings/credentials/vendor-picker-pane.tsx
index 98bdb9ec10..3a36ce1d44 100644
--- a/services/platform/app/features/settings/credentials/vendor-picker-pane.tsx
+++ b/services/platform/app/features/settings/credentials/vendor-picker-pane.tsx
@@ -7,6 +7,7 @@ import { SearchInput } from '@tale/ui/search-input';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
+import { VendorIcon } from '@tale/ui/vendor-icon';
 import { ChevronRight, Plus } from 'lucide-react';
 import { useMemo, useState } from 'react';
 
@@ -17,7 +18,6 @@ import {
   type CredentialLike,
   type CredentialVendor,
 } from './adapter';
-import { VendorIcon } from './vendor-icon';
 
 /**
  * Step one of adding a credential: the whole shipped catalog, as a list.

From 00376e6e0c26e7a442b38883399c56d76e6759cb Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:26:25 +0200
Subject: [PATCH 11/78] test(ui): warm Shiki's grammars before checking a
 highlight

Shiki stops tokenizing a line after 500 ms and leaves the rest of it
plain. The first highlight in a language compiles its grammar, which on
a loaded machine took that long, so the palette test saw a comment as
plain text and failed. Both highlight tests now pay for the grammars on
other snippets first.
---
 .../forms/code-editor/code-roles.parity.test.ts   | 15 ++++++++++++++-
 packages/ui/src/markdown/shiki.test.ts            |  9 ++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts b/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
index fc24985a90..9aa54eba9a 100644
--- a/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
+++ b/packages/ui/src/components/forms/code-editor/code-roles.parity.test.ts
@@ -1,5 +1,5 @@
 import { highlightTree } from '@lezer/highlight';
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 
 import {
   codeRoleOfColor,
@@ -209,6 +209,19 @@ function differences(
 }
 
 describe('editor and read-only colours agree', () => {
+  // Shiki stops tokenizing a line after 500 ms and leaves its rest plain.
+  // The first highlight in a language compiles its grammar's patterns, which
+  // on a loaded machine can take that long, so each grammar is warmed on a
+  // copy of its fixture (another cache key) before the fixtures are compared.
+  beforeAll(async () => {
+    for (const fixture of FIXTURES) {
+      await highlightCode(
+        `${fixture.text}\n`,
+        shikiLanguageFor(fixture.language, fixture.templates ?? false),
+      );
+    }
+  }, 120_000);
+
   it.each(FIXTURES)('$name', async (fixture) => {
     const editor = editorRoles(fixture);
     const readOnly = await readOnlyRoles(fixture);
diff --git a/packages/ui/src/markdown/shiki.test.ts b/packages/ui/src/markdown/shiki.test.ts
index 36fc6c4f1b..59d4b8576b 100644
--- a/packages/ui/src/markdown/shiki.test.ts
+++ b/packages/ui/src/markdown/shiki.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 
 import { CODE_LANGUAGES, codeRoleOfColor } from '../lib/code-roles';
 import {
@@ -43,6 +43,13 @@ describe('resolveShikiTheme', () => {
 });
 
 describe('highlightCode palette', () => {
+  // Shiki stops tokenizing a line after 500 ms and leaves its rest plain.
+  // The first TypeScript highlight compiles the grammar's patterns, which on
+  // a loaded machine can take that long, so a different snippet pays for it.
+  beforeAll(async () => {
+    await highlightCode('let warm = 0; // warm up\nreturn "w";', 'ts');
+  }, 60_000);
+
   // The read-only blocks failed AA with min-light/min-dark (comments 1.69:1).
   // They now colour through the `--code-*` variables, the editor's palette.
   it('colours tokens through the --code-* variables, never a hex value', async () => {

From 0b20aace57d1cedea2ed64f889d8fd82f298a160 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:26:33 +0200
Subject: [PATCH 12/78] test(ui): keep CodeMirror out of the code editor's
 light modules

A page that shows no code field, or only imports locate, template-scan
or providers, must never download CodeMirror. The guard walks the
static imports from each public code-editor module through the
package's own files and refuses any CodeMirror or Lezer module, or the
editor view itself, which loads only through a dynamic import. A walk
from the view proves that it would catch one.
---
 .../forms/code-editor/light.test.ts           | 117 ++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 packages/ui/src/components/forms/code-editor/light.test.ts

diff --git a/packages/ui/src/components/forms/code-editor/light.test.ts b/packages/ui/src/components/forms/code-editor/light.test.ts
new file mode 100644
index 0000000000..0fff95c1a3
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/light.test.ts
@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The public code-editor modules are light: a page that renders no code
+ * field, or only imports a helper (`locate`, `template-scan`, `providers`),
+ * never downloads CodeMirror. Only `code-editor-view.tsx`, loaded through a
+ * dynamic `import()`, may reach it. This walks the static imports from each
+ * public entry through the package's own files and refuses a CodeMirror or
+ * Lezer module, or the view itself, anywhere in that closure.
+ *
+ * Only `import type` and `export type … from` are left out of the walk. The
+ * package compiles with `verbatimModuleSyntax`, so an inline
+ * `import { type X } from '…'` stays in the output as an import of that
+ * module, and counts here.
+ */
+
+const HERE = __dirname;
+const SRC = resolve(HERE, '..', '..', '..');
+
+const ENTRIES = [
+  'code-editor.tsx',
+  'providers.ts',
+  'template-scan.ts',
+  'locate.ts',
+].map((name) => join(HERE, name));
+
+const HEAVY = /^(?:@codemirror\/|@lezer\/|codemirror$|style-mod$|w3c-keyname$)/;
+const VIEW = join(HERE, 'code-editor-view.tsx');
+
+/**
+ * `import … from '…'`, `export … from '…'` and `import '…'` at the start of a
+ * statement; a dynamic `import('…')` does not match. Group 1 is `type ` on a
+ * type-only statement, group 2 the specifier.
+ */
+const STATIC_IMPORT =
+  /(?:^|[;}\n])\s*(?:import|export)\s+(type\s+)?(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]/g;
+
+function withoutComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+function resolveRelative(from: string, specifier: string): string | null {
+  const base = resolve(dirname(from), specifier);
+  for (const candidate of [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+  ]) {
+    if (/\.tsx?$/.test(candidate) && existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Every bare specifier and package file the entries load statically. */
+function staticClosure(entries: readonly string[]): {
+  files: Set<string>;
+  packages: Map<string, string>;
+} {
+  const files = new Set<string>();
+  const packages = new Map<string, string>();
+  const queue = [...entries];
+  while (queue.length > 0) {
+    const file = queue.pop();
+    if (file === undefined || files.has(file)) continue;
+    files.add(file);
+    const source = withoutComments(readFileSync(file, 'utf8'));
+    for (const match of source.matchAll(STATIC_IMPORT)) {
+      if (match[1] !== undefined) continue;
+      const specifier = match[2];
+      if (specifier.startsWith('.')) {
+        const target = resolveRelative(file, specifier);
+        // A relative import of a non-script file (CSS, YAML) holds no code.
+        if (target !== null) queue.push(target);
+      } else if (!packages.has(specifier)) {
+        packages.set(specifier, relative(SRC, file));
+      }
+    }
+  }
+  return { files, packages };
+}
+
+describe('the light code-editor modules', () => {
+  const { files, packages } = staticClosure(ENTRIES);
+
+  it('walks the entries and what they import', () => {
+    // A walk that found nothing would pass every check below.
+    expect(files.size).toBeGreaterThan(ENTRIES.length);
+    expect(packages.has('react')).toBe(true);
+  });
+
+  it('would catch CodeMirror, as the view itself shows', () => {
+    const view = staticClosure([VIEW]).packages;
+    expect(view.has('@codemirror/view')).toBe(true);
+    expect([...view.keys()].some((specifier) => HEAVY.test(specifier))).toBe(
+      true,
+    );
+  });
+
+  it('never load CodeMirror or Lezer statically', () => {
+    const heavy = [...packages]
+      .filter(([specifier]) => HEAVY.test(specifier))
+      .map(([specifier, file]) => `${file} imports ${specifier}`);
+    expect(heavy).toEqual([]);
+  });
+
+  it('reach the editor view only through a dynamic import', () => {
+    expect(files.has(VIEW)).toBe(false);
+    expect(readFileSync(join(HERE, 'code-editor.tsx'), 'utf8')).toContain(
+      "import('./code-editor-view')",
+    );
+  });
+});

From 6a9b46afff0fac76fc12ab8ab2246e37ae123248 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:26:42 +0200
Subject: [PATCH 13/78] fix(platform): highlight file previews once for both
 themes

Read-only code now colours through the --code-* variables, so one
highlight serves light and dark. The document and skill asset previews
still asked again for the min-* theme on every switch, blanked to plain
text until the answer came back, and their tests expected the old
min-* class. They now highlight without a theme and keep it across a
switch; the tests check the one palette in both themes.
---
 .../document-preview-text.browser.test.tsx    | 24 ++++++++-----------
 .../components/document-preview-text.tsx      |  9 ++++---
 .../skill-asset-viewer.browser.test.tsx       | 24 ++++++++-----------
 .../skills/components/skill-asset-viewer.tsx  |  9 ++++---
 4 files changed, 28 insertions(+), 38 deletions(-)

diff --git a/services/platform/app/features/documents/components/document-preview-text.browser.test.tsx b/services/platform/app/features/documents/components/document-preview-text.browser.test.tsx
index 0c64e3f57d..0d70977b96 100644
--- a/services/platform/app/features/documents/components/document-preview-text.browser.test.tsx
+++ b/services/platform/app/features/documents/components/document-preview-text.browser.test.tsx
@@ -47,11 +47,11 @@ const THEMES = {
   dark: { theme: 'dark', resolvedTheme: 'dark', setTheme: () => {} },
 } as const;
 
-// The first highlight loads Shiki's engine, both themes and every eager
+// The first highlight loads Shiki's engine, its theme and every eager
 // grammar: seconds on a busy runner, past `waitFor`'s budget. Pay it here,
 // through the unmocked singleton, so every test starts warm.
 beforeAll(async () => {
-  await shikiHighlight('x', 'ts', 'min-light');
+  await shikiHighlight('x', 'ts');
 }, 30_000);
 
 afterEach(() => {
@@ -202,22 +202,18 @@ describe('DocumentPreviewText typography', () => {
     },
   );
 
-  it.each([
-    ['light', 'min-light'],
-    ['dark', 'min-dark'],
-  ] as const)(
-    'asks the highlighter for the %s theme by its own name',
-    async (theme, shikiTheme) => {
+  it.each(['light', 'dark'] as const)(
+    'colours the %s canvas through the one code palette',
+    async (theme) => {
       preview.text = '{"answer": 42}';
       const container = renderPreview('answer.json', theme);
       await highlightedRows(container);
 
-      expect(highlightCode).toHaveBeenCalledWith(
-        preview.text,
-        'json',
-        shikiTheme,
-      );
-      expect(container.querySelector('pre.shiki')).toHaveClass(shikiTheme);
+      expect(highlightCode).toHaveBeenCalledWith(preview.text, 'json');
+      expect(container.querySelector('pre.shiki')).toHaveClass('tale-code');
+      expect(
+        container.querySelector('pre.shiki span[style*="var(--code-token-"]'),
+      ).not.toBeNull();
     },
   );
 });
diff --git a/services/platform/app/features/documents/components/document-preview-text.tsx b/services/platform/app/features/documents/components/document-preview-text.tsx
index 3d4a1d90f6..16cc15e701 100644
--- a/services/platform/app/features/documents/components/document-preview-text.tsx
+++ b/services/platform/app/features/documents/components/document-preview-text.tsx
@@ -2,7 +2,6 @@
 
 import { cn } from '@tale/ui/cn';
 import { Text } from '@tale/ui/text';
-import { useTheme } from '@tale/ui/theme';
 import { useCallback, useEffect, useState } from 'react';
 
 import { useT } from '@/lib/i18n/client';
@@ -38,7 +37,6 @@ export function DocumentPreviewText({
   fileName,
 }: DocumentPreviewTextProps) {
   const { t } = useT('documents');
-  const { resolvedTheme } = useTheme();
   const { data, isLoading, error } = useTextPreview(url);
   const content = data?.text;
   const truncated = data?.truncated ?? false;
@@ -51,7 +49,6 @@ export function DocumentPreviewText({
     category === 'markup' ||
     category === 'config' ||
     category === 'data';
-  const shikiTheme = resolvedTheme === 'dark' ? 'min-dark' : 'min-light';
   // Until its highlight lands, a code file under both caps is laid out the
   // way the highlight will lay it out: unwrapped, in the numbered column.
   const willHighlight =
@@ -67,13 +64,15 @@ export function DocumentPreviewText({
 
     let cancelled = false;
     const lang = resolveLanguage(ext);
-    void highlightCode(content, lang, shikiTheme).then((result) => {
+    // One highlight serves both themes: it colours through the `--code-*`
+    // variables, so a theme switch keeps it.
+    void highlightCode(content, lang).then((result) => {
       if (!cancelled) setHighlightedHtml(result?.html ?? null);
     });
     return () => {
       cancelled = true;
     };
-  }, [content, ext, willHighlight, shikiTheme]);
+  }, [content, ext, willHighlight]);
 
   const highlightRef = useCallback(
     (el: HTMLDivElement | null) => {
diff --git a/services/platform/app/features/skills/components/skill-asset-viewer.browser.test.tsx b/services/platform/app/features/skills/components/skill-asset-viewer.browser.test.tsx
index da6e5eae51..c2b7c8ec19 100644
--- a/services/platform/app/features/skills/components/skill-asset-viewer.browser.test.tsx
+++ b/services/platform/app/features/skills/components/skill-asset-viewer.browser.test.tsx
@@ -60,11 +60,11 @@ const THEMES = {
   dark: { theme: 'dark', resolvedTheme: 'dark', setTheme: () => {} },
 } as const;
 
-// The first highlight loads Shiki's engine, both themes and every eager
+// The first highlight loads Shiki's engine, its theme and every eager
 // grammar: seconds on a busy runner, past `waitFor`'s budget. Pay it here,
 // through the unmocked singleton, so every test starts warm.
 beforeAll(async () => {
-  await shikiHighlight('x', 'ts', 'min-light');
+  await shikiHighlight('x', 'ts');
 }, 30_000);
 
 afterEach(() => {
@@ -298,22 +298,18 @@ describe('SkillAssetViewer typography', () => {
     },
   );
 
-  it.each([
-    ['light', 'min-light'],
-    ['dark', 'min-dark'],
-  ] as const)(
-    'asks the highlighter for the %s theme by its own name',
-    async (theme, shikiTheme) => {
+  it.each(['light', 'dark'] as const)(
+    'colours the %s canvas through the one code palette',
+    async (theme) => {
       asset.text = 'name: demo';
       const { container } = renderViewer('config.yaml', theme);
       await highlightedRows(container);
 
-      expect(highlightCode).toHaveBeenCalledWith(
-        asset.text,
-        'yaml',
-        shikiTheme,
-      );
-      expect(container.querySelector('pre.shiki')).toHaveClass(shikiTheme);
+      expect(highlightCode).toHaveBeenCalledWith(asset.text, 'yaml');
+      expect(container.querySelector('pre.shiki')).toHaveClass('tale-code');
+      expect(
+        container.querySelector('pre.shiki span[style*="var(--code-token-"]'),
+      ).not.toBeNull();
     },
   );
 });
diff --git a/services/platform/app/features/skills/components/skill-asset-viewer.tsx b/services/platform/app/features/skills/components/skill-asset-viewer.tsx
index 2cb6b49ad8..04c5cb97b0 100644
--- a/services/platform/app/features/skills/components/skill-asset-viewer.tsx
+++ b/services/platform/app/features/skills/components/skill-asset-viewer.tsx
@@ -8,7 +8,6 @@ import { HStack, Stack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
-import { useTheme } from '@tale/ui/theme';
 import { useRetryFocus } from '@tale/ui/use-retry-focus';
 import { Check, Copy, WrapText } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
@@ -89,8 +88,6 @@ export function SkillAssetViewer({
   const { t } = useT('skills');
   const { locale } = useLocale();
   const { t: tCommon } = useT('common');
-  const { resolvedTheme } = useTheme();
-  const shikiTheme = resolvedTheme === 'dark' ? 'min-dark' : 'min-light';
 
   const ext = getFileExtensionLower(assetPath);
   const isImage = IMAGE_EXTS.has(ext);
@@ -153,13 +150,15 @@ export function SkillAssetViewer({
     if (!useShiki || !content || oversize) return undefined;
     let cancelled = false;
     const lang = resolveLanguage(ext);
-    void highlightCode(content, lang, shikiTheme).then((result) => {
+    // One highlight serves both themes: it colours through the `--code-*`
+    // variables, so a theme switch keeps it.
+    void highlightCode(content, lang).then((result) => {
       if (!cancelled) setHighlightedHtml(result?.html ?? null);
     });
     return () => {
       cancelled = true;
     };
-  }, [content, ext, useShiki, oversize, shikiTheme]);
+  }, [content, ext, useShiki, oversize]);
 
   const highlightRef = useCallback(
     (el: HTMLDivElement | null) => {

From 28ac5a5398663a99789583e75a5061daf75c7716 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:26:54 +0200
Subject: [PATCH 14/78] docs(ui): guide the code editor, the schema tree and
 vendor icons

ui.tale.dev gains a Code editor guide (fields, languages, templates,
problems, completion and types, the keyboard, read-only code, go-to and
every prop) with six live demos, and a Schema tree guide with one. The
Dialog guide says how a widget claims Escape, Colors lists the --code-*
roles and the contrast they keep, and Icons shows VendorIcon with its
fallback. Stories cover the three components; the package README lists
them.
---
 packages/ui/README.md                         |   4 +-
 .../data-display/schema-tree.stories.tsx      |  59 +++
 .../data-display/vendor-icon.stories.tsx      |  30 ++
 .../forms/code-editor/code-editor.stories.tsx | 369 ++++++++++++++++++
 services/ui-docs/app/content/frontmatter.json |  14 +
 .../ui-docs/app/demos/code-editor/basic.tsx   |  35 ++
 .../app/demos/code-editor/completion.tsx      | 131 +++++++
 .../app/demos/code-editor/diagnostics.tsx     |  98 +++++
 .../app/demos/code-editor/languages.tsx       |  71 ++++
 .../app/demos/code-editor/read-only.tsx       |  30 ++
 .../app/demos/code-editor/templates.tsx       |  49 +++
 .../app/demos/foundations/vendor-icon.tsx     |  26 ++
 .../ui-docs/app/demos/schema-tree/basic.tsx   |  62 +++
 .../ui-docs/content/components/code-editor.md | 136 +++++++
 services/ui-docs/content/components/dialog.md |   6 +
 .../ui-docs/content/components/schema-tree.md |  39 ++
 .../ui-docs/content/foundations/colors.md     |   6 +
 services/ui-docs/content/foundations/icons.md |   6 +
 services/ui-docs/content/nav.json             |   2 +
 services/ui-docs/content/published.json       |   2 +
 20 files changed, 1173 insertions(+), 2 deletions(-)
 create mode 100644 packages/ui/src/components/data-display/schema-tree.stories.tsx
 create mode 100644 packages/ui/src/components/data-display/vendor-icon.stories.tsx
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor.stories.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/basic.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/completion.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/diagnostics.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/languages.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/read-only.tsx
 create mode 100644 services/ui-docs/app/demos/code-editor/templates.tsx
 create mode 100644 services/ui-docs/app/demos/foundations/vendor-icon.tsx
 create mode 100644 services/ui-docs/app/demos/schema-tree/basic.tsx
 create mode 100644 services/ui-docs/content/components/code-editor.md
 create mode 100644 services/ui-docs/content/components/schema-tree.md

diff --git a/packages/ui/README.md b/packages/ui/README.md
index 6b2a61354e..165a4063dd 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -14,8 +14,8 @@ and stories live together under `src/components/<family>/`.
 
 | Need | Example imports |
 | --- | --- |
-| Controls and forms | `button`, `icon-button`, `input`, `select`, `checkbox`, `use-form`, `field-shell` |
-| Tables and values | `data-table/data-table`, `data-table/column-builders`, `copyable-field`, `json-viewer` |
+| Controls and forms | `button`, `icon-button`, `input`, `select`, `checkbox`, `use-form`, `field-shell`, `code-editor` |
+| Tables and values | `data-table/data-table`, `data-table/column-builders`, `copyable-field`, `json-viewer`, `schema-tree`, `vendor-icon` |
 | Layout and navigation | `page-layout`, `adaptive-header`, `sub-panel`, `header-breadcrumbs`, `tab-navigation` |
 | Dialogs and feedback | `dialog/form-dialog`, `dialog/delete-dialog`, `toaster`, `use-toast`, `use-retry-focus` |
 | Problems a check found | `issue-list`, `issue-summary`, `issue-severity`, `field-issue-messages`, `issue-focus`, `flow/node-issue-marker` |
diff --git a/packages/ui/src/components/data-display/schema-tree.stories.tsx b/packages/ui/src/components/data-display/schema-tree.stories.tsx
new file mode 100644
index 0000000000..93b1a77082
--- /dev/null
+++ b/packages/ui/src/components/data-display/schema-tree.stories.tsx
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SchemaTree, type SchemaTreeSchema } from './schema-tree';
+
+const meta: Meta<typeof SchemaTree> = {
+  title: 'DataDisplay/SchemaTree',
+  component: SchemaTree,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'The fields of a value as a form reads them: name, kind in words, required, tags. See the guide on ui.tale.dev.',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SchemaTree>;
+
+const INPUT: SchemaTreeSchema = {
+  type: 'object',
+  required: ['owner', 'repo'],
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'The account that owns the repository.',
+    },
+    repo: { type: 'string' },
+    limit: { type: 'integer' },
+    state: { enum: ['open', 'closed'] },
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { title: { type: 'string' }, score: { type: 'number' } },
+      },
+    },
+  },
+};
+
+export const Compact: Story = {
+  args: { schema: INPUT, density: 'compact', maxRows: 3 },
+};
+
+export const Comfortable: Story = {
+  args: {
+    schema: INPUT,
+    tagOf: (path) => (path[0] === 'owner' ? 'from the trigger' : undefined),
+    maybeEmpty: (path) => path[0] === 'issues',
+    typeScript: '{ owner: string; repo: string; limit?: number }',
+  },
+};
+
+export const NoFields: Story = {
+  args: { schema: { type: 'array', items: { type: 'number' } } },
+};
diff --git a/packages/ui/src/components/data-display/vendor-icon.stories.tsx b/packages/ui/src/components/data-display/vendor-icon.stories.tsx
new file mode 100644
index 0000000000..3ea673200d
--- /dev/null
+++ b/packages/ui/src/components/data-display/vendor-icon.stories.tsx
@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { VendorIcon } from './vendor-icon';
+
+const meta: Meta<typeof VendorIcon> = {
+  title: 'DataDisplay/VendorIcon',
+  component: VendorIcon,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A vendor's shipped icon, falling back to the plug glyph when there is none or it fails to load. Decorative: put the vendor's name beside it.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof VendorIcon>;
+
+export const WithoutIcon: Story = { args: {} };
+
+/** An image the browser cannot decode fails at once, without a request. */
+export const BrokenIcon: Story = {
+  args: { iconUrl: 'data:image/svg+xml,%3Csvg' },
+};
+
+export const Larger: Story = { args: { className: 'size-8' } };
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.stories.tsx b/packages/ui/src/components/forms/code-editor/code-editor.stories.tsx
new file mode 100644
index 0000000000..055ac1a3bf
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor.stories.tsx
@@ -0,0 +1,369 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogTitle,
+} from '../../overlays/responsive-dialog';
+import { TooltipProvider } from '../../overlays/tooltip';
+import { Button } from '../../primitives/button';
+import { Field } from '../field';
+import {
+  CodeEditor,
+  type CodeEditorDiagnostic,
+  type CodeEditorProps,
+} from './code-editor';
+import type { CodeEditorProviders } from './providers';
+
+const meta: Meta<typeof CodeEditor> = {
+  title: 'Forms/CodeEditor',
+  component: CodeEditor,
+  tags: ['autodocs'],
+  // A disabled reason shows in a tooltip, which needs a provider; the app
+  // gets one from `AppShell`.
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <Story />
+      </TooltipProvider>
+    ),
+  ],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+The one control for code, JSON, YAML, prompts and \`{{ js }}\` templates, on
+CodeMirror 6 behind a lazy chunk. Highlights in the shared \`--code-*\` palette,
+takes completion, hover and problems from the host, and never traps the
+keyboard: Esc, then Tab leaves. See the guide on ui.tale.dev.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof CodeEditor>;
+
+/** A controlled editor, as a host form keeps one. */
+function Controlled(props: Omit<CodeEditorProps, 'onChange'>) {
+  const [value, setValue] = useState(props.value);
+  return (
+    <div className="max-w-xl">
+      <CodeEditor {...props} value={value} onChange={setValue} />
+    </div>
+  );
+}
+
+const SAMPLES: Array<
+  Pick<CodeEditorProps, 'language' | 'templates' | 'value'>
+> = [
+  {
+    language: 'javascript',
+    value:
+      'const total = input.items.length;\nreturn { total, empty: total === 0 };',
+  },
+  { language: 'expression', value: 'nodes.score.output.total > 1000' },
+  {
+    language: 'json',
+    value: '{\n  "to": "ada@example.com",\n  "draft": false\n}',
+  },
+  {
+    language: 'yaml',
+    value: 'name: Triage GitHub issues\nnodes:\n  - id: score\n    type: llm',
+  },
+  {
+    language: 'markdown',
+    value: '# Daily report\n\nSummarise the **open** issues.',
+  },
+  { language: 'template', value: 'Hello {{ input.name }}!' },
+  { language: 'text', value: 'Plain text.' },
+];
+
+export const Languages: Story = {
+  render: () => (
+    <div className="flex max-w-xl flex-col gap-3">
+      {SAMPLES.map((sample) => (
+        <Controlled
+          key={sample.language}
+          aria-label={sample.language}
+          {...sample}
+          minRows={1}
+        />
+      ))}
+    </div>
+  ),
+};
+
+export const Templates: Story = {
+  render: () => (
+    <div className="flex max-w-xl flex-col gap-3">
+      <Controlled
+        aria-label="Text"
+        language="text"
+        templates
+        value="Reply to {{ nodes.triage.output.name }} today."
+      />
+      <Controlled
+        aria-label="JSON"
+        language="json"
+        templates
+        value={'{\n  "to": "{{ input.email }}",\n  "n": 1\n}'}
+      />
+      <Controlled
+        aria-label="YAML"
+        language="yaml"
+        templates
+        value={'prompt: Rate {{ item.title }}\nwhen: "{{ input.ok }}"'}
+      />
+      <Controlled
+        aria-label="Markdown"
+        language="markdown"
+        templates
+        font="prose"
+        value="Summarise **{{ nodes.report.output.count }}** issues."
+      />
+      <Controlled
+        aria-label="Unterminated"
+        language="template"
+        singleLine
+        value="{{ nodes.issues.output.items"
+      />
+    </div>
+  ),
+};
+
+const PROBLEMS: CodeEditorDiagnostic[] = [
+  {
+    id: 'ref',
+    severity: 'error',
+    message: 'Reads "triag", and there is no node with that id.',
+    code: 'REF_UNKNOWN_NODE',
+    range: [18, 23],
+    fixes: [
+      {
+        label: 'Read "triage"',
+        changes: [{ range: [18, 23], insert: 'triage' }],
+      },
+    ],
+  },
+  {
+    id: 'empty',
+    severity: 'warning',
+    message: 'A run started by hand may leave this empty.',
+    range: [43, 54],
+  },
+  { id: 'todo', severity: 'info', message: 'Left for later.', range: [59, 63] },
+];
+
+export const Diagnostics: Story = {
+  render: () => (
+    <div className="flex max-w-xl flex-col gap-3">
+      <Controlled
+        aria-label="Ready"
+        language="template"
+        value={
+          'Reply to {{ nodes.triag.output }} about {{ input.topic }}.\nTODO: sign off.'
+        }
+        diagnostics={PROBLEMS}
+      />
+      <Controlled
+        aria-label="Checking"
+        language="template"
+        value={
+          'Reply to {{ nodes.triag.output }} about {{ input.topic }}.\nTODO: sign off.'
+        }
+        diagnostics={PROBLEMS}
+        diagnosticsStatus="checking"
+      />
+    </div>
+  ),
+};
+
+const SHAPES: CodeEditorProviders = {
+  completion: ({ path }) => {
+    if (path === null) return null;
+    if (path.length === 0) {
+      return {
+        items: [
+          { label: 'nodes', kind: 'variable', valueType: 'object' },
+          { label: 'input', kind: 'input', valueType: 'object' },
+        ],
+      };
+    }
+    if (path[0] === 'nodes' && path.length === 1) {
+      return {
+        items: [
+          {
+            label: 'score',
+            kind: 'node',
+            detail: 'Language model',
+            section: 'Earlier nodes',
+          },
+          {
+            label: 'open issues',
+            kind: 'node',
+            detail: 'Transform',
+            section: 'Earlier nodes',
+          },
+        ],
+      };
+    }
+    return {
+      items: [
+        {
+          label: 'output',
+          valueType: 'object',
+          info: {
+            type: '{ total: number }',
+            description: 'What the node returns.',
+          },
+        },
+      ],
+    };
+  },
+  hover: ({ path }) =>
+    path === null ? null : { title: path.join('.'), type: '{ total: number }' },
+};
+
+export const Completion: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Condition"
+      language="expression"
+      singleLine
+      providers={SHAPES}
+      value="nodes."
+    />
+  ),
+};
+
+export const Hover: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Code"
+      language="javascript"
+      providers={SHAPES}
+      value="return nodes.score.output;"
+    />
+  ),
+};
+
+export const SingleLine: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Run when"
+      language="expression"
+      singleLine
+      value="input.priority === 'high'"
+      onSubmit={() => {}}
+      submitLabel="Run"
+    />
+  ),
+};
+
+export const AutoGrow: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Code"
+      language="javascript"
+      minRows={2}
+      maxRows={6}
+      value={'// Add lines: the field grows to six, then scrolls.\nreturn 1;'}
+    />
+  ),
+};
+
+export const ReadOnly: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Source"
+      language="yaml"
+      templates
+      readOnly
+      lineNumbers
+      size="md"
+      value={
+        'name: Triage\nnodes:\n  - id: score\n    prompt: Rate {{ item.title }}'
+      }
+    />
+  ),
+};
+
+export const DisabledWithReason: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Code"
+      language="javascript"
+      disabled
+      disabledReason="Only an author can change this."
+      value="return input;"
+    />
+  ),
+};
+
+export const Expand: Story = {
+  render: () => (
+    <Controlled
+      aria-label="Code"
+      language="javascript"
+      expandable
+      lineNumbers
+      value={'const a = 1;\nreturn a;'}
+    />
+  ),
+};
+
+export const InAFieldWithIssues: Story = {
+  render: () => (
+    <div className="max-w-xl">
+      <Field
+        label="Input"
+        htmlFor="story-field-input"
+        issues={[
+          { id: 'to', severity: 'error', message: 'Reads a missing field.' },
+        ]}
+      >
+        <CodeEditor
+          id="story-field-input"
+          language="json"
+          templates
+          value={'{"to": "{{ input.mail }}"}'}
+          describeDiagnostics={false}
+        />
+      </Field>
+    </div>
+  ),
+};
+
+function DialogStory() {
+  const [open, setOpen] = useState(false);
+  const [value, setValue] = useState('nodes.score.output.total > 10');
+  return (
+    <>
+      <Button type="button" onClick={() => setOpen(true)}>
+        Edit condition
+      </Button>
+      <ResponsiveDialog open={open} onOpenChange={setOpen}>
+        <ResponsiveDialogContent>
+          <ResponsiveDialogTitle>Edit condition</ResponsiveDialogTitle>
+          <CodeEditor
+            aria-label="Condition"
+            language="expression"
+            singleLine
+            providers={SHAPES}
+            value={value}
+            onChange={setValue}
+          />
+        </ResponsiveDialogContent>
+      </ResponsiveDialog>
+    </>
+  );
+}
+
+/** Escape closes the list, then arms leaving, then closes the dialog. */
+export const InAResponsiveDialog: Story = {
+  render: () => <DialogStory />,
+};
diff --git a/services/ui-docs/app/content/frontmatter.json b/services/ui-docs/app/content/frontmatter.json
index 7fa65654b0..ccf3024a38 100644
--- a/services/ui-docs/app/content/frontmatter.json
+++ b/services/ui-docs/app/content/frontmatter.json
@@ -13,6 +13,13 @@
       "description": "Choose an action style, name icon controls, and handle loading or unavailable actions without losing context."
     }
   },
+  "components/code-editor": {
+    "slug": "components/code-editor",
+    "frontmatter": {
+      "title": "Code editor",
+      "description": "Edit code, JSON, YAML and templates with highlighting, completion and inline problems, and leave the field with the keyboard."
+    }
+  },
   "components/data-table": {
     "slug": "components/data-table",
     "frontmatter": {
@@ -76,6 +83,13 @@
       "description": "Show the next times a schedule starts, in the schedule's time zone, with the reader's own time and any clock change spelled out."
     }
   },
+  "components/schema-tree": {
+    "slug": "components/schema-tree",
+    "frontmatter": {
+      "title": "Schema tree",
+      "description": "Show the fields a value has, with each kind in words, whether it is required, and where it comes from."
+    }
+  },
   "components/tabs-and-navigation": {
     "slug": "components/tabs-and-navigation",
     "frontmatter": {
diff --git a/services/ui-docs/app/demos/code-editor/basic.tsx b/services/ui-docs/app/demos/code-editor/basic.tsx
new file mode 100644
index 0000000000..cb2c930d1e
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/basic.tsx
@@ -0,0 +1,35 @@
+import { CodeEditor } from '@tale/ui/code-editor';
+import { Field } from '@tale/ui/field';
+import { useState } from 'react';
+
+const START = `// Count the open issues per label.
+const counts = {};
+for (const issue of input.issues) {
+  const label = issue.labels[0] ?? 'none';
+  counts[label] = (counts[label] ?? 0) + 1;
+}
+return counts;`;
+
+export default function CodeEditorBasic() {
+  const [code, setCode] = useState(START);
+  return (
+    <div className="w-full max-w-xl">
+      <Field
+        label="Code"
+        htmlFor="demo-code-editor-basic"
+        description="Runs once per run. What it returns is the node's output."
+      >
+        <CodeEditor
+          id="demo-code-editor-basic"
+          language="javascript"
+          value={code}
+          onChange={setCode}
+          lineNumbers
+          minRows={6}
+          maxRows={14}
+          expandable
+        />
+      </Field>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/code-editor/completion.tsx b/services/ui-docs/app/demos/code-editor/completion.tsx
new file mode 100644
index 0000000000..652c1a18e9
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/completion.tsx
@@ -0,0 +1,131 @@
+import { CodeEditor } from '@tale/ui/code-editor';
+import type {
+  CodeCompletionItem,
+  CodeEditorProviders,
+} from '@tale/ui/code-editor/providers';
+import { Field } from '@tale/ui/field';
+import { useState } from 'react';
+
+/** What each name holds, in the demo: a tiny made-up automation. */
+interface Shape {
+  type: string;
+  description?: string;
+  fields?: Record<string, Shape>;
+}
+
+const DATA: Record<string, Shape> = {
+  input: {
+    type: '{ owner: string; repo: string }',
+    description: 'What the run started with.',
+    fields: {
+      owner: {
+        type: 'string',
+        description: 'The account that owns the repository.',
+      },
+      repo: { type: 'string' },
+    },
+  },
+  nodes: {
+    type: '{ issues: …; score: … }',
+    fields: {
+      issues: {
+        type: '{ output: { items: object[] } }',
+        fields: {
+          output: {
+            type: '{ items: object[] }',
+            fields: {
+              items: {
+                type: 'object[]',
+                description: 'Open issues, newest first.',
+              },
+            },
+          },
+        },
+      },
+      score: {
+        type: '{ output: { total: number } }',
+        fields: {
+          output: {
+            type: '{ total: number }',
+            fields: {
+              total: {
+                type: 'number',
+                description: 'How urgent the issues are, 0 to 100.',
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+function at(
+  path: readonly (string | number)[],
+): Record<string, Shape> | undefined {
+  let level: Record<string, Shape> | undefined = DATA;
+  for (const segment of path) {
+    level = level?.[String(segment)]?.fields;
+  }
+  return level;
+}
+
+function valueType(type: string): CodeCompletionItem['valueType'] {
+  if (type === 'string') return 'string';
+  if (type === 'number') return 'number';
+  if (type.endsWith('[]')) return 'array';
+  return 'object';
+}
+
+const PROVIDERS: CodeEditorProviders = {
+  completion: ({ path }) => {
+    if (path === null) return null;
+    const fields = at(path);
+    if (fields === undefined) return null;
+    return {
+      items: Object.entries(fields).map(([label, shape]) => ({
+        label,
+        kind: path.length === 1 && path[0] === 'nodes' ? 'node' : 'property',
+        valueType: valueType(shape.type),
+        detail: shape.type,
+        info: { type: shape.type, description: shape.description },
+      })),
+    };
+  },
+  hover: ({ path }) => {
+    if (path === null || path.length === 0) return null;
+    const parent = at(path.slice(0, -1));
+    const shape = parent?.[String(path.at(-1))];
+    return shape === undefined
+      ? null
+      : {
+          title: path.join('.'),
+          type: shape.type,
+          description: shape.description,
+        };
+  },
+};
+
+export default function CodeEditorCompletion() {
+  const [code, setCode] = useState(
+    'const total = nodes.score.output.total;\nreturn { owner: input.owner, total };',
+  );
+  return (
+    <div className="w-full max-w-xl">
+      <Field
+        label="Code"
+        htmlFor="demo-completion-code"
+        description="Type nodes. or input. — or press Ctrl+Space."
+      >
+        <CodeEditor
+          id="demo-completion-code"
+          language="javascript"
+          value={code}
+          onChange={setCode}
+          providers={PROVIDERS}
+          minRows={4}
+        />
+      </Field>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/code-editor/diagnostics.tsx b/services/ui-docs/app/demos/code-editor/diagnostics.tsx
new file mode 100644
index 0000000000..4e36345c83
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/diagnostics.tsx
@@ -0,0 +1,98 @@
+import { CodeEditor, type CodeEditorDiagnostic } from '@tale/ui/code-editor';
+import { Field } from '@tale/ui/field';
+import { Switch } from '@tale/ui/switch';
+import { useMemo, useState } from 'react';
+
+const NODES = ['triage', 'score', 'report'];
+
+/** The nearest known node name, for a "did you mean" fix. */
+function closest(name: string): string | undefined {
+  return NODES.find((node) => node[0] === name[0]) ?? NODES[0];
+}
+
+/**
+ * The demo's own checker: a node that does not exist is an error with a
+ * fix, a run input may be empty, and a TODO is a note.
+ */
+function check(text: string): CodeEditorDiagnostic[] {
+  const found: CodeEditorDiagnostic[] = [];
+  for (const match of text.matchAll(/nodes\.(\w+)/g)) {
+    const name = match[1];
+    if (NODES.includes(name)) continue;
+    const from = (match.index ?? 0) + 'nodes.'.length;
+    const suggestion = closest(name);
+    found.push({
+      id: `node-${from}`,
+      severity: 'error',
+      message: `Reads "${name}", and there is no node with that id.`,
+      code: 'REF_UNKNOWN_NODE',
+      range: [from, from + name.length],
+      fixes:
+        suggestion === undefined
+          ? []
+          : [
+              {
+                label: `Read "${suggestion}"`,
+                changes: [
+                  { range: [from, from + name.length], insert: suggestion },
+                ],
+              },
+            ],
+    });
+  }
+  for (const match of text.matchAll(/input\.\w+/g)) {
+    const from = match.index ?? 0;
+    found.push({
+      id: `input-${from}`,
+      severity: 'warning',
+      message: 'A run started by hand may leave this empty.',
+      range: [from, from + match[0].length],
+    });
+  }
+  for (const match of text.matchAll(/TODO/g)) {
+    const from = match.index ?? 0;
+    found.push({
+      id: `todo-${from}`,
+      severity: 'info',
+      message: 'Left for later.',
+      range: [from, from + 4],
+    });
+  }
+  return found;
+}
+
+export default function CodeEditorDiagnostics() {
+  const [text, setText] = useState(
+    'Reply to {{ nodes.triag.output.name }} about {{ input.topic }}.\nTODO: sign off.',
+  );
+  const [checking, setChecking] = useState(false);
+  // A real host checks on a server and passes the text it checked.
+  const [checked, setChecked] = useState(text);
+  const diagnostics = useMemo(() => check(checked), [checked]);
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-3">
+      <Switch
+        label="Show the check as running"
+        checked={checking}
+        onCheckedChange={(next) => {
+          setChecking(next);
+          if (!next) setChecked(text);
+        }}
+      />
+      <Field label="Prompt" htmlFor="demo-diagnostics-prompt">
+        <CodeEditor
+          id="demo-diagnostics-prompt"
+          language="template"
+          value={text}
+          onChange={(next) => {
+            setText(next);
+            if (!checking) setChecked(next);
+          }}
+          diagnostics={diagnostics}
+          diagnosticsFor={checked}
+          diagnosticsStatus={checking ? 'checking' : 'ready'}
+        />
+      </Field>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/code-editor/languages.tsx b/services/ui-docs/app/demos/code-editor/languages.tsx
new file mode 100644
index 0000000000..d10a19f24a
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/languages.tsx
@@ -0,0 +1,71 @@
+import { CodeEditor, type CodeLanguage } from '@tale/ui/code-editor';
+import { Select } from '@tale/ui/select';
+import { useState } from 'react';
+
+const SAMPLES: Record<CodeLanguage, string> = {
+  javascript: `const total = input.items.length;
+return { total, empty: total === 0 };`,
+  expression: 'nodes.score.output.total > 1000',
+  json: `{
+  "to": "ada@example.com",
+  "subject": "Weekly report",
+  "draft": false
+}`,
+  yaml: `name: Triage GitHub issues
+nodes:
+  - id: open_issues
+    type: transform`,
+  markdown: `# Daily report
+
+Summarise the **open** issues in a short list.`,
+  template:
+    'Hello {{ input.name }}, you have {{ nodes.inbox.output.count }} new messages.',
+  text: 'Plain text, with no highlighting.',
+};
+
+const LABELS: Record<CodeLanguage, string> = {
+  javascript: 'JavaScript (a script)',
+  expression: 'Expression (a condition)',
+  json: 'JSON',
+  yaml: 'YAML',
+  markdown: 'Markdown',
+  template: 'Text with templates',
+  text: 'Plain text',
+};
+
+const ORDER: CodeLanguage[] = [
+  'javascript',
+  'expression',
+  'json',
+  'yaml',
+  'markdown',
+  'template',
+  'text',
+];
+
+export default function CodeEditorLanguages() {
+  const [language, setLanguage] = useState<CodeLanguage>('javascript');
+  const [texts, setTexts] = useState(SAMPLES);
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-3">
+      <Select
+        label="Language"
+        value={language}
+        onValueChange={(next) => {
+          const found = ORDER.find((option) => option === next);
+          if (found !== undefined) setLanguage(found);
+        }}
+        options={ORDER.map((value) => ({ value, label: LABELS[value] }))}
+      />
+      <CodeEditor
+        key={language}
+        aria-label={`${LABELS[language]} sample`}
+        language={language}
+        value={texts[language]}
+        onChange={(value) => setTexts({ ...texts, [language]: value })}
+        singleLine={language === 'expression'}
+        font={language === 'markdown' ? 'prose' : 'mono'}
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/code-editor/read-only.tsx b/services/ui-docs/app/demos/code-editor/read-only.tsx
new file mode 100644
index 0000000000..84b9bc6814
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/read-only.tsx
@@ -0,0 +1,30 @@
+import { CodeEditor } from '@tale/ui/code-editor';
+import { CodeBlock } from '@tale/ui/markdown/code-block';
+
+const SOURCE = `name: Triage GitHub issues
+nodes:
+  - id: score
+    type: llm
+    prompt: Rate {{ item.title }} from 0 to 100
+    when: "{{ nodes.issues.output.items.length > 0 }}"`;
+
+export default function CodeEditorReadOnly() {
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-4">
+      <CodeEditor
+        aria-label="Automation source"
+        language="yaml"
+        templates
+        readOnly
+        lineNumbers
+        size="md"
+        value={SOURCE}
+      />
+      <CodeBlock
+        code={SOURCE}
+        language="yaml-template"
+        filename="automation.yml"
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/code-editor/templates.tsx b/services/ui-docs/app/demos/code-editor/templates.tsx
new file mode 100644
index 0000000000..b2dfcd7dd7
--- /dev/null
+++ b/services/ui-docs/app/demos/code-editor/templates.tsx
@@ -0,0 +1,49 @@
+import { CodeEditor } from '@tale/ui/code-editor';
+import { Field } from '@tale/ui/field';
+import { useState } from 'react';
+
+export default function CodeEditorTemplates() {
+  const [prompt, setPrompt] = useState(
+    'Summarise the issues of {{ input.owner }}/{{ input.repo }}.\n\nRank them by **urgency** and keep {{ nodes.score.output.top }} at the top.',
+  );
+  const [body, setBody] = useState(
+    '{\n  "to": "{{ input.email }}",\n  "subject": "Report for {{ nodes.triage.output.name }}"\n}',
+  );
+  const [each, setEach] = useState('{{ nodes.issues.output.items');
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-4">
+      <Field label="Prompt" htmlFor="demo-templates-prompt">
+        <CodeEditor
+          id="demo-templates-prompt"
+          language="markdown"
+          templates
+          font="prose"
+          value={prompt}
+          onChange={setPrompt}
+        />
+      </Field>
+      <Field label="Input" htmlFor="demo-templates-input">
+        <CodeEditor
+          id="demo-templates-input"
+          language="json"
+          templates
+          value={body}
+          onChange={setBody}
+        />
+      </Field>
+      <Field
+        label="For each"
+        htmlFor="demo-templates-each"
+        description="Its {{ has no closing }} yet."
+      >
+        <CodeEditor
+          id="demo-templates-each"
+          language="template"
+          singleLine
+          value={each}
+          onChange={setEach}
+        />
+      </Field>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/foundations/vendor-icon.tsx b/services/ui-docs/app/demos/foundations/vendor-icon.tsx
new file mode 100644
index 0000000000..df5f20f5df
--- /dev/null
+++ b/services/ui-docs/app/demos/foundations/vendor-icon.tsx
@@ -0,0 +1,26 @@
+import { VendorIcon } from '@tale/ui/vendor-icon';
+
+/**
+ * An image the browser cannot decode: it fails at once, with no request and
+ * no 404 in the console, as a vendor icon that fails to load would.
+ */
+const BROKEN_ICON = 'data:image/svg+xml,%3Csvg';
+
+export default function FoundationsVendorIcon() {
+  return (
+    <ul className="flex flex-col gap-3 text-sm">
+      <li className="flex items-center gap-2">
+        <VendorIcon iconUrl="/favicon-light.png" />
+        <span>Tale (the vendor's own icon)</span>
+      </li>
+      <li className="flex items-center gap-2">
+        <VendorIcon />
+        <span>WebDAV (ships no icon)</span>
+      </li>
+      <li className="flex items-center gap-2">
+        <VendorIcon iconUrl={BROKEN_ICON} />
+        <span>Example API (its icon failed to load)</span>
+      </li>
+    </ul>
+  );
+}
diff --git a/services/ui-docs/app/demos/schema-tree/basic.tsx b/services/ui-docs/app/demos/schema-tree/basic.tsx
new file mode 100644
index 0000000000..4aaac19ed8
--- /dev/null
+++ b/services/ui-docs/app/demos/schema-tree/basic.tsx
@@ -0,0 +1,62 @@
+import { SchemaTree, type SchemaTreeSchema } from '@tale/ui/schema-tree';
+
+const INPUT: SchemaTreeSchema = {
+  type: 'object',
+  required: ['owner', 'repo'],
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'The account that owns the repository.',
+    },
+    repo: { type: 'string' },
+    limit: { type: 'integer', description: 'At most this many issues.' },
+    state: { enum: ['open', 'closed'] },
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title'],
+        properties: {
+          title: { type: 'string' },
+          score: { type: ['number', 'null'] },
+        },
+      },
+    },
+  },
+};
+
+const TYPESCRIPT = `{
+  owner: string;
+  repo: string;
+  limit?: number;
+  state?: "open" | "closed";
+  issues?: { title: string; score?: number | null }[];
+}`;
+
+export default function SchemaTreeBasic() {
+  return (
+    <div className="grid w-full max-w-2xl gap-6 md:grid-cols-2">
+      <div className="flex flex-col gap-2">
+        <p className="text-muted-foreground text-xs font-medium">Compact</p>
+        <SchemaTree
+          schema={INPUT}
+          density="compact"
+          maxRows={3}
+          tagOf={(path) =>
+            path[0] === 'owner' ? 'from the trigger' : undefined
+          }
+          aria-label="Run input"
+        />
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-muted-foreground text-xs font-medium">Comfortable</p>
+        <SchemaTree
+          schema={INPUT}
+          maybeEmpty={(path) => path[0] === 'issues'}
+          typeScript={TYPESCRIPT}
+          aria-label="Run input, in full"
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/services/ui-docs/content/components/code-editor.md b/services/ui-docs/content/components/code-editor.md
new file mode 100644
index 0000000000..4eb1db18b7
--- /dev/null
+++ b/services/ui-docs/content/components/code-editor.md
@@ -0,0 +1,136 @@
+---
+title: Code editor
+description: Edit code, JSON, YAML and templates with highlighting, completion and inline problems, and leave the field with the keyboard.
+---
+
+`CodeEditor` is the field for anything a reader writes as code: a transform's script, a condition, a connector's JSON input, a prompt with `{{ }}` templates, an automation in YAML. It highlights in the same colours as read-only code blocks, takes completion, hover and problems from your host, and never traps a keyboard user.
+
+```tsx
+import { CodeEditor, preloadCodeEditor } from '@tale/ui/code-editor';
+import { combineProviders } from '@tale/ui/code-editor/providers';
+import { scanTemplates } from '@tale/ui/code-editor/template-scan';
+import { locateJsonPointer, locateYamlPointer } from '@tale/ui/code-editor/locate';
+```
+
+## Edit code in a form
+
+<Demo name="code-editor/basic" />
+
+Put the editor in a `Field` and pass the field's `htmlFor` as the editor's `id`. The editor's text is not an `input`, so the field names it with `aria-labelledby`, and a click on the label still moves focus into it. `value` and `onChange` work as in any controlled field. The editor applies a new `value` as the smallest change, so a host that rewrites the text on every keystroke never moves the caret, and it never echoes a `value` you passed back to `onChange`.
+
+The implementation (CodeMirror 6) loads the first time an editor mounts. Until it arrives, the field shows its text in the editor's own metrics, so nothing moves when the editor replaces it, and a focus request made meanwhile waits for it. Call `preloadCodeEditor()` when a surface that is likely to show code mounts, or on hover over what opens it.
+
+`minRows` and `maxRows` set the height: the field grows with its text, then scrolls. `fillHeight` fills a flex parent instead. `lineNumbers` adds the gutter, with fold markers unless you pass `fold={false}`. `expandable` adds **Expand editor**, which opens the same field in a large dialog and carries the caret there and back.
+
+## Choose a language
+
+<Demo name="code-editor/languages" />
+
+| `language` | Use it for |
+| --- | --- |
+| `javascript` | A script: statements and a top-level `return`, such as a transform's body. |
+| `expression` | One expression, such as a condition. `{ a: 1 }` reads as an object. |
+| `json`, `yaml` | Structured values. With `templates`, the `{{ }}` inside string values are parsed as JavaScript. Keys never hold templates. |
+| `markdown` | Prompts and descriptions, highlighted only. |
+| `template` | Text with `{{ }}` templates. |
+| `text` | Plain text. `templates` turns templates on. |
+
+`font="prose"` sets the text in the reading font, for prompts; templates keep the code font. `singleLine` makes a one-line field: Enter submits instead of adding a line, Tab moves focus, and a pasted line break becomes a space.
+
+## Write templates
+
+<Demo name="code-editor/templates" />
+
+Each `{{ … }}` reads as one tinted chip, and the JavaScript inside it is highlighted and completed like code. Typing `{` after `{` gives `{{  }}` with the caret inside and opens completion. Typing `}` in front of the closing braces steps over them, and Backspace in an empty `{{ }}` removes the pair. A `{{` with no closing `}}` is marked as a problem.
+
+A template ends at the `}}` that closes its expression, not at the first `}}`, so `{{ xs.map(x => ({ y: x })) }}` and `{{ "}}" }}` are one template each. The editor's own rule is that every bracket and string inside has closed. If your runtime decides differently, pass its rule as `templateScanner` so the editor and the runtime agree exactly. `scanTemplates` from `@tale/ui/code-editor/template-scan` is the default.
+
+## Show problems
+
+<Demo name="code-editor/diagnostics" />
+
+Pass `diagnostics`, each with an `id`, a `severity` (`error`, `warning` or `info`), a translated `message`, and usually a `range` into the text. Without a range the whole field is meant. `code` shows small in the tooltip, `detail` takes any node (an `IssueDetail`, for example), and `fixes` offer one-click repairs.
+
+A check takes time, and the reader keeps typing. Pass the text you checked as `diagnosticsFor`: the editor maps each range onto the current text and hides a problem whose text was edited until your next result. While a check runs, set `diagnosticsStatus="checking"`: the underlines fade to 60 % and the text is marked busy.
+
+| Severity | Underline | Gutter |
+| --- | --- | --- |
+| `error` | Wavy, 1.5 px | Crossed circle |
+| `warning` | Wavy, 1 px | Triangle |
+| `info` | Dotted, 1 px | Circled i |
+
+The editor adds marks of its own: JSON or YAML that does not parse, JavaScript it cannot read, and an unclosed `{{`. They wait half a second after the last edit, never sit under the word being typed, and give way to any problem you report at the same place. `syntaxDiagnostics={false}` turns them off. A `lint` provider adds instant local problems of yours.
+
+Hover a problem to see its tooltip. F8 and Shift+F8 move to the next and previous problem, select it, open its tooltip and read it aloud. ⌘. (Ctrl+. elsewhere) applies a fix, or moves focus to the fix buttons when there are several; the arrow keys move between them. The editor describes its problems to assistive technology with a summary; inside a `Field` that already lists them, pass `describeDiagnostics={false}`. The editor never announces a new result by itself: announce a check's result once, with [`IssueAnnouncer`](/docs/components/issue-list#count-and-announce-the-result).
+
+## Complete names and show types
+
+<Demo name="code-editor/completion" />
+
+`providers.completion` receives where the cursor is: the `region` (code, the code inside a template, text, or a JSON or YAML key or value), the member `path` before the word being typed (`nodes["a b"]?.x.` gives `['nodes', 'a b', 'x']`), the `prefix`, and for JSON and YAML the `pointer` of the object a key belongs to or of the value. Return items with a `label`, and optionally a `detail`, a `kind` and `valueType` for the icon, a `section`, and `info` for the side panel. A name that is not an identifier goes in as `["a b"]`, an index as `[0]`.
+
+The list opens as the reader types a name, a `.` or a `[` in code, or a key in JSON or YAML, and Ctrl+Space opens it anywhere. Enter or Tab accepts. A provider may answer asynchronously: its `signal` aborts when the reader types on, and equally good matches keep your order.
+
+`providers.hover` answers for the name under the pointer after 200 ms, and for the name at the cursor on ⌘K ⌘I (Ctrl+K Ctrl+I), which also reads the type aloud. `combineProviders` merges several hosts, such as known data shapes and a type checker.
+
+## Keyboard
+
+| Key | Several lines | One line |
+| --- | --- | --- |
+| Tab, Shift+Tab | Indent, outdent | Next, previous control |
+| Esc | Closes the list, a tooltip or search; with nothing open, arms leaving for two seconds | The same |
+| Esc, then Tab | Leaves the editor | — |
+| Ctrl+M (Shift+Alt+M on a Mac) | Makes Tab move focus from now on, or indent again | — |
+| Enter | New line | `onSubmit` |
+| ⌘Enter (Ctrl+Enter) | `onSubmit` | `onSubmit` |
+| Ctrl+Space | Completion | Completion |
+| F8, Shift+F8 | Next, previous problem | The same |
+| ⌘. (Ctrl+.) | Apply a fix | The same |
+| ⌘K ⌘I (Ctrl+K Ctrl+I) | Show the type | The same |
+| ⌘F (Ctrl+F) | Find and replace, with `search` | — |
+
+After keyboard focus, a small legend on the field's bottom edge shows the way out, and the submit shortcut when you pass `onSubmit` and `submitLabel`. The same words describe the field to assistive technology. A pointer never shows the legend.
+
+Escape is claimed while the editor needs it, so the first Escape in a sheet closes the completion list and the next arms leaving; the sheet closes on the third. See [widgets that use Escape](/docs/components/dialog#widgets-that-use-escape).
+
+## Read-only code
+
+<Demo name="code-editor/read-only" />
+
+Use `readOnly` when read-only text needs the editor: problems on it, or a go-to that selects a range. It is focusable and selectable, says it is read-only, and takes the code-block surface. To only display code, use `CodeBlock` from `@tale/ui/markdown/code-block`. It highlights with the same palette, including templates in `json-template`, `yaml-template`, `markdown-template` and `tale-template`, without loading the editor.
+
+## Take the reader to a range
+
+Inside an `IssueFocusProvider`, give the editor an `issueAnchor`. A go-to request for that anchor selects its range in the text, even when it arrives before the editor has loaded. A request for a part below the anchor, such as `/nodes/0/input/to` for an editor at `/nodes/0/input`, finds that key in JSON or YAML text. `locateJsonPointer` and `locateYamlPointer` do the same for your own use, with escapes and block scalars mapped onto the raw text. Pass `issueReveal` when the editor sits behind a tab or a collapsed section. See [field issues](/docs/components/field-issues) for the registry.
+
+## Props
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `value`, `onChange` | — | The text, controlled. |
+| `language` | — | See [Choose a language](#choose-a-language). |
+| `templates` | `false` | `{{ }}` in JSON, YAML, Markdown or text. |
+| `templateScanner` | `scanTemplates` | Your runtime's rule for where a template ends. |
+| `readOnly`, `disabled`, `disabledReason` | `false` | As on `Textarea`: with a reason, a disabled editor stays focusable and shows it. |
+| `placeholder` | — | Shown while the text is empty. |
+| `singleLine` | `false` | One line: Enter submits, Tab leaves. |
+| `minRows`, `maxRows` | 3 and 14; 1 and 4 in one line | The height range. |
+| `fillHeight` | `false` | Fill a flex parent. |
+| `wrap` | On for prose, templates, text and one line | Soft-wrap long lines. |
+| `font` | `mono` | `prose` for prompts. |
+| `size` | `sm` | `sm` is 12 px, `md` 14 px; 16 px on small screens, so phones never zoom. |
+| `lineNumbers`, `fold`, `search` | `false` | Gutter, fold markers, find and replace. |
+| `expandable` | `false` | **Expand editor**; `{ title }` names the dialog. |
+| `diagnostics`, `diagnosticsFor`, `diagnosticsStatus` | — | Problems, the text they were found in, and whether a check runs. |
+| `describeDiagnostics`, `syntaxDiagnostics` | `true` | The problem summary, and the editor's own marks. |
+| `providers` | — | Completion, hover and lint. |
+| `onSubmit`, `submitLabel` | — | ⌘Enter, and the button label the shortcut hint names. |
+| `issueAnchor`, `issueReveal` | — | Go-to from a problems list. |
+| `initialSelection` | — | Where the caret starts. |
+| `id`, `aria-*`, `required` | — | Set on the editable text; a `Field` sets most of them. |
+
+The ref (`CodeEditorHandle`) has `focus(range?)`, `getSelection()`, `openCompletion()` and `nextDiagnostic(direction)`.
+
+## Accessibility
+
+The text is a labelled text box with a "code editor" role description, and the editor's own words (the completion list's name, the search panel, announcements) come in the reader's language. Problems never rely on colour: the underline style and the gutter glyph say the severity, and the words are in the tooltip and the summary. The colours clear 4.5:1 on every code surface in both themes, and the underlines 3:1. In a Windows contrast theme the selection and underlines take the system colours. Under reduced motion the list and tooltips appear without animation and the caret stops blinking. Below the `md` breakpoint the text is 16 px, so iOS does not zoom, and in a sheet, selecting text never drags the sheet.
diff --git a/services/ui-docs/content/components/dialog.md b/services/ui-docs/content/components/dialog.md
index fd7d83cf80..f736e4a762 100644
--- a/services/ui-docs/content/components/dialog.md
+++ b/services/ui-docs/content/components/dialog.md
@@ -86,6 +86,12 @@ Keep descriptions in one place rather than repeating them in the summary and bod
 | `preventCloseAutoFocus` | Opt out of automatic restoration only when the caller explicitly manages the next focus target. `ResponsiveDialogContent` takes it too, for a close that hands the reader on to another panel. |
 | `onCloseAutoFocus` | Called after the close focus handler runs. Available on `Dialog`, `ConfirmDialog` and `DeleteDialog`; use it to release a retained virtual row after focus returns to its opener. |
 
+## Widgets that use Escape
+
+A widget inside a dialog may use Escape itself: a code editor closes its completion list, then arms leaving the field. The dialog hears Escape first, so every `@tale/ui` overlay (`Dialog`, `ResponsiveDialog`, `Sheet`, `Popover`, `DropdownMenu`) leaves an Escape alone when an element around the focus carries `data-claims-escape`: it cancels the event and stays open.
+
+Set the attribute while your widget needs Escape and remove it once it does not; the next Escape then closes the layer. A cancelled event still reaches your widget, but some libraries skip cancelled events. Such a widget handles a claimed Escape before the overlay does, in a capture listener on `window`. [`CodeEditor`](/docs/components/code-editor) does all of this itself.
+
 ## Handle lifecycle and focus deliberately
 
 The modal traps focus while open. Escape and the close control request dismissal; controlled state determines whether the request is accepted. Restore focus to a useful surviving control after close, especially when a successful action removes the original row.
diff --git a/services/ui-docs/content/components/schema-tree.md b/services/ui-docs/content/components/schema-tree.md
new file mode 100644
index 0000000000..4d1b53f218
--- /dev/null
+++ b/services/ui-docs/content/components/schema-tree.md
@@ -0,0 +1,39 @@
+---
+title: Schema tree
+description: Show the fields a value has, with each kind in words, whether it is required, and where it comes from.
+---
+
+`SchemaTree` lists the fields of a value the way a person reads a form: each field's name, what kind of value it holds in words, whether it is required, and a tag your host adds, such as where the value comes from. Use it for a run's input, what a step receives and returns, or a webhook's payload.
+
+```tsx
+import { SchemaTree, schemaKindLabel } from '@tale/ui/schema-tree';
+```
+
+## Show a value's fields
+
+<Demo name="schema-tree/basic" />
+
+Pass `schema`, a JSON Schema subset: `type` (one or several), `properties`, `required`, `items`, `enum`, `anyOf` and `description`. `density="compact"` lists the top-level fields one line each, for a summary or a node. The default, `comfortable`, also nests the fields of objects and of list items and shows each field's description. `maxRows` stops after that many top-level fields and says how many are left.
+
+Descriptions are the author's words and show as written; everything else comes in the reader's language.
+
+## Say more about a field
+
+`tagOf(path)` returns a short tag shown after a field's kind. `path` holds the field names from the top: `['issues', 'title']` is a field of the items of the `issues` list. `maybeEmpty(path)` adds "may be empty". A field the schema lists in `required` says "required". In the comfortable density, the other fields of an object that names required fields say "optional".
+
+`typeScript` adds **Show as TypeScript**: a disclosure with the same shape as highlighted TypeScript, for readers who think in types.
+
+## Say a kind in a sentence
+
+`schemaKindLabel(t, schema, locale)` returns the kind alone. Pass the `t` of the `schemaTree` namespace and the reader's locale, which picks the quotation marks and the word for "or".
+
+| Schema | English | German | French |
+| --- | --- | --- | --- |
+| `{ type: 'string' }` | text | Text | texte |
+| `{ type: 'array', items: { type: 'object' } }` | list of objects | Liste von Objekten | liste d'objets |
+| `{ type: ['number', 'null'] }` | a number or empty | eine Zahl oder leer | un nombre ou vide |
+| `{ enum: ['open', 'closed'] }` | one of “open” or “closed” | eines von „open“ oder „closed“ | l'un de « open » ou « closed » |
+
+## Accessibility
+
+The fields are a list named by `aria-label` (default "Fields"), with nested lists for nested fields. A required field says so in words, not by colour. The text keeps 4.5:1 on the page, a card and the code-block surface in both themes.
diff --git a/services/ui-docs/content/foundations/colors.md b/services/ui-docs/content/foundations/colors.md
index 04916898b8..12cba76b72 100644
--- a/services/ui-docs/content/foundations/colors.md
+++ b/services/ui-docs/content/foundations/colors.md
@@ -60,6 +60,12 @@ Charts have `chart-1` through `chart-5` plus `chart-success`, `chart-failure`, `
 
 Use labels, shapes, or line patterns as well as color to distinguish meaningful series. Verify legends and tooltips in both themes, including small text and a single low-value data point.
 
+## Colour code
+
+Code has roles of its own: `--code-foreground` and `--code-token-keyword`, `-string`, `-string-expression`, `-constant`, `-function`, `-parameter`, `-comment`, `-punctuation`, `-link`, `-inserted`, `-deleted` and `-changed`, with light and dark values in `globals.css`. Read-only code blocks and the [code editor](/docs/components/code-editor) both read them, so a value has one colour wherever it shows, and a theme switch never highlights code again.
+
+Every token clears 4.5:1 on the page, the code-block surface (`bg-bg-elevated`), a card and the muted surface, and on the editor's template tint; `code-palette.test.ts` checks each pair in both themes. The editor's chrome adds `--code-line-number`, `--code-selection`, `--code-template-tint`, `--code-match` and the problem underlines `--code-squiggle-error`, `-warning` and `-info`, which keep 3:1. Use the roles for code, not for other text.
+
 ## Add a color only when the meaning is missing
 
 First inspect the existing tokens and neighboring components. If a new semantic role is needed, add its token and intended theme treatment centrally. Record which foreground/background pairing it supports and check rest, hover, focus, selected, and error states.
diff --git a/services/ui-docs/content/foundations/icons.md b/services/ui-docs/content/foundations/icons.md
index 0d425c3008..d9463901af 100644
--- a/services/ui-docs/content/foundations/icons.md
+++ b/services/ui-docs/content/foundations/icons.md
@@ -41,6 +41,12 @@ The Export icon is decorative because the visible text already names the action.
 
 For a stateful action, name the next action or communicate the current state clearly. A changed glyph alone may be ambiguous; use appropriate state attributes such as `aria-pressed` where the control is a toggle.
 
+## Show a vendor's own icon
+
+<Demo name="foundations/vendor-icon" />
+
+`VendorIcon` from `@tale/ui/vendor-icon` shows the icon a connector or an AI provider ships, from its `iconUrl`, at `size-5` unless you pass a `className`. With no icon, or one that fails to load, it shows Lucide's plug instead. The icon is decoration: its image has an empty alternative text, so put the vendor's name next to it.
+
 ## Reuse custom brand marks
 
 ```tsx
diff --git a/services/ui-docs/content/nav.json b/services/ui-docs/content/nav.json
index 454c782257..261e3636c0 100644
--- a/services/ui-docs/content/nav.json
+++ b/services/ui-docs/content/nav.json
@@ -25,6 +25,8 @@
         "components/button",
         "components/input",
         "components/time-field",
+        "components/code-editor",
+        "components/schema-tree",
         "components/issue-list",
         "components/flow-node-issues",
         "components/field-issues",
diff --git a/services/ui-docs/content/published.json b/services/ui-docs/content/published.json
index d1f421ebce..182ac9eeb9 100644
--- a/services/ui-docs/content/published.json
+++ b/services/ui-docs/content/published.json
@@ -3,6 +3,7 @@
   "slugs": [
     "components/app-shell",
     "components/button",
+    "components/code-editor",
     "components/data-table",
     "components/dialog",
     "components/field-issues",
@@ -12,6 +13,7 @@
     "components/property-list",
     "components/recurrence-picker",
     "components/schedule-occurrence-list",
+    "components/schema-tree",
     "components/tabs-and-navigation",
     "components/time-field",
     "components/toast",

From 534b7e45cace92059525403728f1fa10ee2b45b0 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:53:41 +0200
Subject: [PATCH 15/78] feat(ui): add usePrefersReducedMotion for motion run
 from script

CSS reaches most animation through motion-safe and the global
reduced-motion rule; a React Flow viewport ease, a Web Animations call
or a caret's blink runs from script and must ask itself. The hook and
its one-off reader name the query once, and the code editor reads its
caret blink through it.
---
 packages/ui/package.json                      |  1 +
 .../forms/code-editor/code-editor.tsx         |  4 +-
 .../hooks/use-prefers-reduced-motion.test.ts  | 45 +++++++++++++++++++
 .../src/hooks/use-prefers-reduced-motion.ts   | 24 ++++++++++
 4 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 packages/ui/src/hooks/use-prefers-reduced-motion.test.ts
 create mode 100644 packages/ui/src/hooks/use-prefers-reduced-motion.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 418925e970..b354de5996 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -399,6 +399,7 @@
     "./use-list-page": "./src/hooks/use-list-page.ts",
     "./use-focus-handoff": "./src/hooks/use-focus-handoff.ts",
     "./use-media-query": "./src/hooks/use-media-query.ts",
+    "./use-prefers-reduced-motion": "./src/hooks/use-prefers-reduced-motion.ts",
     "./use-sliding-indicator": "./src/hooks/use-sliding-indicator.ts",
     "./use-swap-fade": "./src/hooks/use-swap-fade.ts",
     "./use-resizable": "./src/hooks/use-resizable.ts",
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.tsx b/packages/ui/src/components/forms/code-editor/code-editor.tsx
index bbd3c50be0..745cfeaa91 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.tsx
@@ -30,7 +30,7 @@ import {
 } from 'react';
 
 import { useIsMac } from '../../../hooks/use-is-mac';
-import { useMediaQuery } from '../../../hooks/use-media-query';
+import { usePrefersReducedMotion } from '../../../hooks/use-prefers-reduced-motion';
 import { useT } from '../../../i18n/client';
 import { cn } from '../../../lib/cn';
 import {
@@ -188,7 +188,7 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
     } = props;
     const { t } = useT('codeEditor');
     const isMac = useIsMac();
-    const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+    const reducedMotion = usePrefersReducedMotion();
     const baseId = useId();
     const keyboardHintId = `${baseId}-keyboard`;
     const submitHintId = `${baseId}-submit`;
diff --git a/packages/ui/src/hooks/use-prefers-reduced-motion.test.ts b/packages/ui/src/hooks/use-prefers-reduced-motion.test.ts
new file mode 100644
index 0000000000..f97225df3c
--- /dev/null
+++ b/packages/ui/src/hooks/use-prefers-reduced-motion.test.ts
@@ -0,0 +1,45 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  prefersReducedMotion,
+  REDUCED_MOTION_QUERY,
+  usePrefersReducedMotion,
+} from './use-prefers-reduced-motion';
+
+const original = window.matchMedia;
+
+function setReduced(reduced: boolean) {
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches: query === REDUCED_MOTION_QUERY && reduced,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+}
+
+afterEach(() => {
+  window.matchMedia = original;
+});
+
+describe('usePrefersReducedMotion', () => {
+  it('reads the reduce-motion setting', () => {
+    setReduced(true);
+    expect(renderHook(() => usePrefersReducedMotion()).result.current).toBe(
+      true,
+    );
+    expect(prefersReducedMotion()).toBe(true);
+  });
+
+  it('is false when the user did not ask for less motion', () => {
+    setReduced(false);
+    expect(renderHook(() => usePrefersReducedMotion()).result.current).toBe(
+      false,
+    );
+    expect(prefersReducedMotion()).toBe(false);
+  });
+});
diff --git a/packages/ui/src/hooks/use-prefers-reduced-motion.ts b/packages/ui/src/hooks/use-prefers-reduced-motion.ts
new file mode 100644
index 0000000000..5b12ba9262
--- /dev/null
+++ b/packages/ui/src/hooks/use-prefers-reduced-motion.ts
@@ -0,0 +1,24 @@
+import { useMediaQuery } from './use-media-query';
+
+/** The media query behind the user's "reduce motion" setting. */
+export const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Whether the user asked for less motion. CSS reaches most animation through
+ * `motion-safe:` / `motion-reduce:` and the global reduced-motion rule; read
+ * this where motion runs from script instead — a React Flow viewport ease,
+ * a Web Animations API call, a caret's blink — so it stops there too.
+ * Follows the setting live.
+ */
+export function usePrefersReducedMotion(): boolean {
+  return useMediaQuery(REDUCED_MOTION_QUERY);
+}
+
+/** The same answer outside React, read once (false without a window). */
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia(REDUCED_MOTION_QUERY).matches
+  );
+}

From 8687e87202765f187fb9fade734e379286487f2e Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 11:54:02 +0200
Subject: [PATCH 16/78] feat(ui): lay out flow graphs with ELK in a worker

A FlowGraph is plain data a host builds from its document: Start,
steps, gates, End, the edges between them and a frame round each
iterating step. layoutFlowGraph hands it to ELK (layered, orthogonal,
model order, one port per edge end) and answers absolute boxes, frame
headers, axis-aligned routes, label boxes and rows. A graph already on
screen is laid out again with position hints, so no row changes order.

ELK runs in elkjs's own same-origin worker, falls back to the bundled
build with one warning when the worker cannot start, and to a single
column when ELK fails or takes five seconds. Sizes are a pure function
of the graph; fresh layouts are cached for the session.

Measured on the fixtures (shipped Triage, review and inbox automations,
a when/elseOf/else-if/repeat graph, a gate on the input, 40 nodes, a
cycle): no edge crosses a box or a frame header, no label overlaps,
five scripted edits keep every row in order. Pinning Start and End to
their own layers cost crossings (2 against 0 on 40 nodes) for no
guarantee the graph does not already give, so they are not pinned.
---
 packages/ui/package.json                      |   2 +
 packages/ui/src/assets.d.ts                   |   7 +
 .../flow/interaction/navigation.test.ts       |  94 +++
 .../components/flow/interaction/navigation.ts | 110 +++
 .../src/components/flow/layout/elk-client.ts  | 155 ++++
 .../src/components/flow/layout/elk-options.ts |  88 +++
 .../components/flow/layout/fallback-column.ts | 169 ++++
 .../components/flow/layout/geometry.test.ts   | 188 +++++
 .../ui/src/components/flow/layout/geometry.ts | 279 +++++++
 .../ui/src/components/flow/layout/index.ts    |  25 +
 .../components/flow/layout/layout-cache.ts    |  50 ++
 .../flow/layout/layout-flow-graph.test.ts     | 478 ++++++++++++
 .../flow/layout/layout-flow-graph.ts          | 506 ++++++++++++
 .../src/components/flow/layout/sizes.test.ts  | 132 ++++
 .../ui/src/components/flow/layout/sizes.ts    | 257 +++++++
 .../components/flow/layout/use-flow-layout.ts | 152 ++++
 .../components/flow/testing/flow-fixtures.ts  | 719 ++++++++++++++++++
 .../components/flow/testing/flow-geometry.ts  | 119 +++
 packages/ui/src/components/flow/types.ts      | 230 ++++++
 .../components/flow/validate-graph.test.ts    |  80 ++
 .../ui/src/components/flow/validate-graph.ts  | 101 +++
 packages/ui/src/testing/flow.ts               |  22 +
 22 files changed, 3963 insertions(+)
 create mode 100644 packages/ui/src/components/flow/interaction/navigation.test.ts
 create mode 100644 packages/ui/src/components/flow/interaction/navigation.ts
 create mode 100644 packages/ui/src/components/flow/layout/elk-client.ts
 create mode 100644 packages/ui/src/components/flow/layout/elk-options.ts
 create mode 100644 packages/ui/src/components/flow/layout/fallback-column.ts
 create mode 100644 packages/ui/src/components/flow/layout/geometry.test.ts
 create mode 100644 packages/ui/src/components/flow/layout/geometry.ts
 create mode 100644 packages/ui/src/components/flow/layout/index.ts
 create mode 100644 packages/ui/src/components/flow/layout/layout-cache.ts
 create mode 100644 packages/ui/src/components/flow/layout/layout-flow-graph.test.ts
 create mode 100644 packages/ui/src/components/flow/layout/layout-flow-graph.ts
 create mode 100644 packages/ui/src/components/flow/layout/sizes.test.ts
 create mode 100644 packages/ui/src/components/flow/layout/sizes.ts
 create mode 100644 packages/ui/src/components/flow/layout/use-flow-layout.ts
 create mode 100644 packages/ui/src/components/flow/testing/flow-fixtures.ts
 create mode 100644 packages/ui/src/components/flow/testing/flow-geometry.ts
 create mode 100644 packages/ui/src/components/flow/types.ts
 create mode 100644 packages/ui/src/components/flow/validate-graph.test.ts
 create mode 100644 packages/ui/src/components/flow/validate-graph.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index b354de5996..ab8c1f7d96 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -148,7 +148,9 @@
     "./flow/edge-palette": "./src/components/flow/edge-palette.ts",
     "./flow/elk-layout": "./src/components/flow/layout/elk-layout.ts",
     "./flow/flow-canvas": "./src/components/flow/flow-canvas.tsx",
+    "./flow/layout": "./src/components/flow/layout/index.ts",
     "./flow/node-issue-marker": "./src/components/flow/node-issue-marker.tsx",
+    "./flow/types": "./src/components/flow/types.ts",
     "./flow/use-elk-layout": "./src/components/flow/layout/use-elk-layout.ts",
     "./form": "./src/components/forms/form.tsx",
     "./form-section": "./src/components/forms/form-section.tsx",
diff --git a/packages/ui/src/assets.d.ts b/packages/ui/src/assets.d.ts
index ed683fc990..4c5f5ee832 100644
--- a/packages/ui/src/assets.d.ts
+++ b/packages/ui/src/assets.d.ts
@@ -18,3 +18,10 @@ declare module '@fontsource/inter/files/inter-latin-500-normal.woff2?url' {
   const src: string;
   export default src;
 }
+
+// The ELK layout worker: elkjs's own worker script, emitted as a
+// same-origin file the flow layout starts a `Worker` from.
+declare module 'elkjs/lib/elk-worker.min.js?url' {
+  const src: string;
+  export default src;
+}
diff --git a/packages/ui/src/components/flow/interaction/navigation.test.ts b/packages/ui/src/components/flow/interaction/navigation.test.ts
new file mode 100644
index 0000000000..c5732fc96a
--- /dev/null
+++ b/packages/ui/src/components/flow/interaction/navigation.test.ts
@@ -0,0 +1,94 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { layoutFlowGraph } from '../layout/layout-flow-graph';
+import { branchFlowGraph, triageFlowGraph } from '../testing/flow-fixtures';
+import type { FlowGraph, FlowLayout } from '../types';
+import { flowNeighbour, flowTabStop } from './navigation';
+
+describe('flowNeighbour', () => {
+  let triage: { graph: FlowGraph; layout: FlowLayout };
+  let branch: { graph: FlowGraph; layout: FlowLayout };
+
+  beforeAll(async () => {
+    const t = triageFlowGraph();
+    const b = branchFlowGraph();
+    triage = { graph: t, layout: await layoutFlowGraph(t) };
+    branch = { graph: b, layout: await layoutFlowGraph(b) };
+  });
+
+  const go = (
+    { graph, layout }: { graph: FlowGraph; layout: FlowLayout },
+    from: string,
+    key: Parameters<typeof flowNeighbour>[3],
+  ) => flowNeighbour(graph, layout, from, key);
+
+  it('follows the lines down and up', () => {
+    expect(go(triage, '__start', 'down')).toBe('issues');
+    expect(go(triage, 'issues', 'down')).toBe('open_issues');
+    expect(go(triage, 'report', 'down')).toBe('__end');
+    expect(go(triage, 'issues', 'up')).toBe('__start');
+    expect(go(triage, '__start', 'up')).toBeNull();
+  });
+
+  it('down from a node with two successors takes the one in line with it', () => {
+    const { layout } = triage;
+    const next = go(triage, 'open_issues', 'down');
+    const open = layout.nodes.open_issues!;
+    const centre = open.x + open.width / 2;
+    const offset = (id: string) =>
+      Math.abs(layout.nodes[id]!.x + layout.nodes[id]!.width / 2 - centre);
+    expect(['score', 'report']).toContain(next);
+    expect(offset(next!)).toBeLessThanOrEqual(
+      Math.min(offset('score'), offset('report')),
+    );
+  });
+
+  it('steps along a row with left and right', () => {
+    expect(go(branch, 'normal', 'right')).toBe('low');
+    expect(go(branch, 'low', 'left')).toBe('normal');
+    expect(go(branch, 'low', 'right')).toBeNull();
+    expect(go(branch, 'urgent', 'right')).toBe('__gate:normal');
+  });
+
+  it('jumps to Start and End', () => {
+    expect(go(branch, 'merge', 'first')).toBe('__start');
+    expect(go(branch, 'merge', 'last')).toBe('__end');
+  });
+
+  it('never follows a layout-only edge', () => {
+    const graph: FlowGraph = {
+      nodes: [
+        { id: 'a', kind: 'step', label: 'A' },
+        { id: 'b', kind: 'step', label: 'B' },
+      ],
+      edges: [
+        {
+          id: 'a>b',
+          source: 'a',
+          target: 'b',
+          kind: 'order',
+          layoutOnly: true,
+        },
+      ],
+    };
+    const layout = {
+      ...triage.layout,
+      nodes: {
+        a: { x: 0, y: 0, width: 10, height: 10 },
+        b: { x: 0, y: 50, width: 10, height: 10 },
+      },
+    };
+    expect(flowNeighbour(graph, layout, 'a', 'down')).toBeNull();
+  });
+});
+
+describe('flowTabStop', () => {
+  const graph = triageFlowGraph();
+
+  it('is the selected node, else the one focused last, else Start', () => {
+    expect(flowTabStop(graph, 'score', 'issues')).toBe('score');
+    expect(flowTabStop(graph, null, 'issues')).toBe('issues');
+    expect(flowTabStop(graph, null, null)).toBe('__start');
+    expect(flowTabStop(graph, 'gone', 'also gone')).toBe('__start');
+  });
+});
diff --git a/packages/ui/src/components/flow/interaction/navigation.ts b/packages/ui/src/components/flow/interaction/navigation.ts
new file mode 100644
index 0000000000..e224ea5903
--- /dev/null
+++ b/packages/ui/src/components/flow/interaction/navigation.ts
@@ -0,0 +1,110 @@
+import type { FlowGraph, FlowLayout } from '../types';
+
+/** A key that moves focus across the chart. */
+export type FlowNavigationKey =
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'first'
+  | 'last';
+
+/**
+ * Where focus goes from `fromId` on `key` — pure, so the keyboard map is
+ * tested without a browser:
+ *
+ *  - down / up follow the drawn edges to a successor / predecessor, the one
+ *    whose centre lines up best with this node's (ties: reading order);
+ *  - left / right step to the neighbour in the same row;
+ *  - first / last jump to Start / End (else the first / last node).
+ *
+ * `null` when there is nowhere to go: focus stays.
+ */
+export function flowNeighbour(
+  graph: FlowGraph,
+  layout: FlowLayout,
+  fromId: string,
+  key: FlowNavigationKey,
+): string | null {
+  if (key === 'first')
+    return (
+      graph.nodes.find((node) => node.kind === 'entry')?.id ??
+      graph.nodes[0]?.id ??
+      null
+    );
+  if (key === 'last')
+    return (
+      graph.nodes.find((node) => node.kind === 'exit')?.id ??
+      graph.nodes.at(-1)?.id ??
+      null
+    );
+  if (key === 'left' || key === 'right') {
+    const row = layout.rows.find((candidate) => candidate.includes(fromId));
+    if (row === undefined) return null;
+    const at = row.indexOf(fromId) + (key === 'right' ? 1 : -1);
+    return row[at] ?? null;
+  }
+  const from = layout.nodes[fromId];
+  if (from === undefined) return null;
+  const centre = from.x + from.width / 2;
+  const order = new Map(graph.nodes.map((node, index) => [node.id, index]));
+  const candidates = graph.edges
+    .filter((edge) => !edge.layoutOnly)
+    .filter((edge) =>
+      key === 'down' ? edge.source === fromId : edge.target === fromId,
+    )
+    .map((edge) => (key === 'down' ? edge.target : edge.source))
+    .filter((id, index, all) => all.indexOf(id) === index)
+    .filter((id) => layout.nodes[id] !== undefined);
+  let best: string | null = null;
+  let bestDistance = Infinity;
+  let bestOrder = Infinity;
+  for (const id of candidates) {
+    const rect = layout.nodes[id];
+    if (rect === undefined) continue;
+    const distance = Math.abs(rect.x + rect.width / 2 - centre);
+    const rank = order.get(id) ?? Infinity;
+    if (
+      distance < bestDistance - 0.5 ||
+      (Math.abs(distance - bestDistance) <= 0.5 && rank < bestOrder)
+    ) {
+      best = id;
+      bestDistance = distance;
+      bestOrder = rank;
+    }
+  }
+  return best;
+}
+
+/** The arrow and jump keys the chart answers, by `KeyboardEvent.key`. */
+export const FLOW_NAVIGATION_KEYS: Readonly<Record<string, FlowNavigationKey>> =
+  {
+    ArrowDown: 'down',
+    ArrowUp: 'up',
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+    Home: 'first',
+    End: 'last',
+  };
+
+/**
+ * The chart's one Tab stop: the selected node, else the one focused last,
+ * else Start, else the first node.
+ */
+export function flowTabStop(
+  graph: FlowGraph,
+  selectedId: string | null | undefined,
+  lastFocusedId: string | null | undefined,
+): string | null {
+  const has = (id: string | null | undefined): id is string =>
+    id !== null &&
+    id !== undefined &&
+    graph.nodes.some((node) => node.id === id);
+  if (has(selectedId)) return selectedId;
+  if (has(lastFocusedId)) return lastFocusedId;
+  return (
+    graph.nodes.find((node) => node.kind === 'entry')?.id ??
+    graph.nodes[0]?.id ??
+    null
+  );
+}
diff --git a/packages/ui/src/components/flow/layout/elk-client.ts b/packages/ui/src/components/flow/layout/elk-client.ts
new file mode 100644
index 0000000000..3b918f67e8
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/elk-client.ts
@@ -0,0 +1,155 @@
+import type { ElkLike, FlowElk, FlowElkNode } from './layout-flow-graph';
+
+/**
+ * The one ELK every canvas in a tab shares.
+ *
+ * It runs in a worker — the same-origin file elkjs ships, so a layout never
+ * blocks typing or scrolling and the CSP needs no `blob:` or `eval` — and
+ * falls back to elkjs's bundled build on the main thread when the worker
+ * cannot start (a policy refusing it, a browser without workers): the
+ * picture is the same, only the thread differs, and a warning says so once.
+ * Both builds load on first use, never with the page.
+ *
+ * Each canvas holds the worker while it is mounted ({@link retainFlowElk});
+ * a minute after the last one goes, the worker ends.
+ */
+
+const IDLE_MS = 60_000;
+
+interface Backend {
+  readonly engine: 'worker' | 'main';
+  readonly elk: ElkLike;
+  terminate(): void;
+}
+
+let backend: Promise<Backend> | null = null;
+let holders = 0;
+let idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+async function mainThread(): Promise<Backend> {
+  const { default: ELK } = await import('elkjs/lib/elk.bundled.js');
+  const elk = new ELK();
+  return {
+    engine: 'main',
+    elk,
+    terminate: () => undefined,
+  };
+}
+
+/** The worker build, or a rejection when it fails before its first answer. */
+async function worker(): Promise<Backend> {
+  const [{ default: ELK }, { default: workerUrl }] = await Promise.all([
+    import('elkjs/lib/elk-api'),
+    import('elkjs/lib/elk-worker.min.js?url'),
+  ]);
+  let failure: ((error: unknown) => void) | undefined;
+  const failed = new Promise<never>((_resolve, reject) => {
+    failure = reject;
+  });
+  // Read by every layout in flight; a failure while none is must not
+  // surface as an unhandled rejection.
+  failed.catch(() => undefined);
+  // A worker whose script cannot load reports it as an `error` event, which
+  // elkjs's own wrapper ignores: every layout would wait forever.
+  const elk = new ELK({
+    workerUrl,
+    workerFactory: (url) => {
+      const created = new Worker(url ?? workerUrl);
+      created.addEventListener('error', (event) => {
+        failure?.(event.error ?? new Error(event.message || 'worker error'));
+      });
+      return created;
+    },
+  });
+  // The worker answers this before anything else once it has loaded.
+  await Promise.race([elk.knownLayoutAlgorithms(), failed]);
+  return {
+    engine: 'worker',
+    elk: {
+      layout: (graph: FlowElkNode) => Promise.race([elk.layout(graph), failed]),
+    },
+    terminate: () => elk.terminateWorker(),
+  };
+}
+
+async function createBackend(): Promise<Backend> {
+  if (typeof Worker === 'undefined') return mainThread();
+  try {
+    return await worker();
+  } catch (error) {
+    console.warn(
+      'Flow layout worker unavailable; laying out on the main thread',
+      error,
+    );
+    return mainThread();
+  }
+}
+
+function current(): Promise<Backend> {
+  if (backend === null) {
+    backend = createBackend();
+    // A build that could not load at all (offline) is tried again next time.
+    backend.catch(() => {
+      backend = null;
+    });
+  }
+  return backend;
+}
+
+/** The shared engine: worker first, the main thread when it cannot run. */
+export function getFlowElk(): Promise<FlowElk> {
+  return Promise.resolve({
+    async layout(graph: FlowElkNode) {
+      const chosen = await current();
+      try {
+        return { graph: await chosen.elk.layout(graph), engine: chosen.engine };
+      } catch (error) {
+        if (chosen.engine !== 'worker') throw error;
+        // The worker died after starting: lay out on the main thread from
+        // now on.
+        console.warn(
+          'Flow layout worker unavailable; laying out on the main thread',
+          error,
+        );
+        chosen.terminate();
+        backend = mainThread();
+        const main = await backend;
+        return { graph: await main.elk.layout(graph), engine: main.engine };
+      }
+    },
+  });
+}
+
+/** Keeps the worker alive while a canvas is mounted; call the returned
+ *  function when it unmounts. */
+export function retainFlowElk(): () => void {
+  holders += 1;
+  clearTimeout(idleTimer);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    holders -= 1;
+    if (holders > 0) return;
+    idleTimer = setTimeout(() => {
+      const ending = backend;
+      backend = null;
+      void ending?.then(
+        (instance) => instance.terminate(),
+        () => undefined,
+      );
+    }, IDLE_MS);
+  };
+}
+
+/** Forgets the shared engine; tests that stub `Worker` start from scratch. */
+export function resetFlowElkForTests(): void {
+  clearTimeout(idleTimer);
+  const ending = backend;
+  backend = null;
+  holders = 0;
+  void ending?.then(
+    (instance) => instance.terminate(),
+    () => undefined,
+  );
+}
diff --git a/packages/ui/src/components/flow/layout/elk-options.ts b/packages/ui/src/components/flow/layout/elk-options.ts
new file mode 100644
index 0000000000..aad10c7c65
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/elk-options.ts
@@ -0,0 +1,88 @@
+/**
+ * Every option the flow layout hands ELK, in one place. The layout is a pure
+ * function of the graph and these: change a number here and every canvas
+ * changes with it, and the layout tests say whether the pictures still hold.
+ *
+ * All spacings sit on the 4-px grid. The choices are measured (ELK 0.11.1 on
+ * the shipped automations and synthetic graphs of 20 and 40 nodes):
+ * orthogonal routing crosses a third as often as splines; model order keeps
+ * the picture deterministic and close to the document's own order; one port
+ * per edge end on fixed sides keeps edges entering at the top and leaving at
+ * the bottom, even the back edge of a cyclic graph.
+ *
+ * Start and End take no layer constraint: every node is reached from Start
+ * and reaches End, so the layering already puts each alone in the first and
+ * the last row (a test holds it), and pinning them with
+ * `FIRST_SEPARATE`/`LAST_SEPARATE` measured more crossings (2 against 0 on a
+ * 40-node graph) and 6–30 % more time for nothing.
+ */
+
+export const FLOW_LAYOUT_SPACING = {
+  nodeNode: 48,
+  betweenLayers: 64,
+  edgeNode: 24,
+  edgeEdge: 16,
+  edgeLabel: 4,
+  components: 48,
+} as const;
+
+/** Inner padding of a frame; a `repeat` frame keeps room on its right for
+ *  the loop arc. */
+export const FLOW_FRAME_PADDING = {
+  top: 12,
+  left: 16,
+  bottom: 16,
+  right: 16,
+  repeatRight: 40,
+} as const;
+
+export const FLOW_ELK_ROOT: Readonly<Record<string, string>> = {
+  'elk.algorithm': 'layered',
+  'elk.direction': 'DOWN',
+  // One graph across frames, so an edge may run into or out of a frame and
+  // still be routed round everything in its way.
+  'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+  'elk.edgeRouting': 'ORTHOGONAL',
+  'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+  'elk.layered.cycleBreaking.strategy': 'MODEL_ORDER',
+  'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+  'elk.layered.thoroughness': '10',
+  'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
+  'elk.layered.nodePlacement.favorStraightEdges': 'true',
+  'elk.spacing.nodeNode': String(FLOW_LAYOUT_SPACING.nodeNode),
+  'elk.layered.spacing.nodeNodeBetweenLayers': String(
+    FLOW_LAYOUT_SPACING.betweenLayers,
+  ),
+  'elk.spacing.edgeNode': String(FLOW_LAYOUT_SPACING.edgeNode),
+  'elk.layered.spacing.edgeNodeBetweenLayers': String(
+    FLOW_LAYOUT_SPACING.edgeNode,
+  ),
+  'elk.spacing.edgeEdge': String(FLOW_LAYOUT_SPACING.edgeEdge),
+  'elk.layered.spacing.edgeEdgeBetweenLayers': String(
+    FLOW_LAYOUT_SPACING.edgeEdge,
+  ),
+  'elk.spacing.edgeLabel': String(FLOW_LAYOUT_SPACING.edgeLabel),
+  'elk.spacing.componentComponent': String(FLOW_LAYOUT_SPACING.components),
+  // "Yes" and "No" sit just under the gate they leave.
+  'elk.edgeLabels.placement': 'TAIL',
+  'elk.layered.edgeLabels.sideSelection': 'SMART_DOWN',
+  // Every coordinate ELK answers with is absolute, frames or not.
+  'elk.json.edgeCoords': 'ROOT',
+  'elk.json.shapeCoords': 'ROOT',
+};
+
+/** Added only when a graph already on screen is laid out again: each node
+ *  keeps its order within its row (with position hints, measured: no row
+ *  order flips after an append, a side branch, a new reference, a removed
+ *  node or a new gate). */
+export const FLOW_ELK_LIVE: Readonly<Record<string, string>> = {
+  'elk.layered.crossingMinimization.semiInteractive': 'true',
+};
+
+/** Every node: ports stay on the side they were given. */
+export const FLOW_ELK_NODE: Readonly<Record<string, string>> = {
+  'elk.portConstraints': 'FIXED_SIDE',
+};
+
+/** The size of the frame header node an incoming edge must route around. */
+export const FLOW_FRAME_HEADER_HEIGHT = 24;
diff --git a/packages/ui/src/components/flow/layout/fallback-column.ts b/packages/ui/src/components/flow/layout/fallback-column.ts
new file mode 100644
index 0000000000..acc00b42c0
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/fallback-column.ts
@@ -0,0 +1,169 @@
+import type { FlowGraph, FlowLayout, FlowPoint, FlowRect } from '../types';
+import { FLOW_FRAME_PADDING, FLOW_LAYOUT_SPACING } from './elk-options';
+import { boundsOf } from './geometry';
+
+interface FallbackInput {
+  signature: string;
+  sizes: ReadonlyMap<string, { width: number; height: number }>;
+  labels: ReadonlyMap<string, { width: number; height: number }>;
+  headers: ReadonlyMap<string, { width: number; height: number }>;
+  ms: number;
+}
+
+/** Room between the column and the first side channel, and between two
+ *  channels. */
+const CHANNEL_GAP = 24;
+const CHANNEL_STEP = 12;
+/** How far a route runs straight out of a box before it turns. */
+const STUB = 16;
+
+/**
+ * Every node in one column, in reading order, when the layout engine could
+ * not run: the canvas still shows the whole graph and stays usable, and an
+ * Alert says why it looks plain. A node right under the one it comes from
+ * gets a straight line; any other edge runs down a channel of its own to the
+ * right of the column, so no line crosses a box.
+ */
+export function layoutFallbackColumn(
+  graph: FlowGraph,
+  input: FallbackInput,
+): FlowLayout {
+  const nodes: Record<string, FlowRect> = {};
+  const groups: Record<string, FlowRect & { header: FlowRect }> = {};
+  const groupOf = new Map<string, string>();
+  for (const group of graph.groups ?? [])
+    for (const member of group.members) groupOf.set(member, group.id);
+
+  const widest = Math.max(
+    ...graph.nodes.map((node) => input.sizes.get(node.id)?.width ?? 0),
+  );
+  const centre = widest / 2 + FLOW_FRAME_PADDING.left;
+  let y = 0;
+  const headed = new Set<string>();
+  for (const node of graph.nodes) {
+    const size = input.sizes.get(node.id) ?? { width: 0, height: 0 };
+    const groupId = groupOf.get(node.id);
+    if (groupId !== undefined && !headed.has(groupId)) {
+      headed.add(groupId);
+      const header = input.headers.get(groupId) ?? { width: 0, height: 0 };
+      y += FLOW_FRAME_PADDING.top;
+      groups[groupId] = {
+        x: 0,
+        y: y - FLOW_FRAME_PADDING.top,
+        width: 0,
+        height: 0,
+        header: {
+          x: centre - widest / 2,
+          y,
+          width: header.width,
+          height: header.height,
+        },
+      };
+      y += header.height + FLOW_FRAME_PADDING.top;
+    }
+    nodes[node.id] = {
+      x: centre - size.width / 2,
+      y,
+      width: size.width,
+      height: size.height,
+    };
+    y += size.height + FLOW_LAYOUT_SPACING.betweenLayers;
+  }
+  // A frame closes round its header and members.
+  for (const group of graph.groups ?? []) {
+    const frame = groups[group.id];
+    if (frame === undefined) continue;
+    const inner = boundsOf([
+      frame.header,
+      ...group.members.flatMap((id) => (nodes[id] ? [nodes[id]] : [])),
+    ]);
+    const right =
+      group.kind === 'repeat'
+        ? FLOW_FRAME_PADDING.repeatRight
+        : FLOW_FRAME_PADDING.right;
+    groups[group.id] = {
+      header: frame.header,
+      x: inner.x - FLOW_FRAME_PADDING.left,
+      y: inner.y - FLOW_FRAME_PADDING.top,
+      width: inner.width + FLOW_FRAME_PADDING.left + right,
+      height: inner.height + FLOW_FRAME_PADDING.top + FLOW_FRAME_PADDING.bottom,
+    };
+  }
+
+  const order = graph.nodes.map((node) => node.id);
+  const columnRight = boundsOf([
+    ...Object.values(nodes),
+    ...Object.values(groups),
+  ]);
+  const edges: Record<string, { points: FlowPoint[]; label?: FlowRect }> = {};
+  let channel = 0;
+  for (const edge of graph.edges) {
+    if (edge.layoutOnly) continue;
+    const source = nodes[edge.source];
+    const target = nodes[edge.target];
+    if (source === undefined || target === undefined) continue;
+    const from = {
+      x: source.x + source.width / 2,
+      y: source.y + source.height,
+    };
+    const to = { x: target.x + target.width / 2, y: target.y };
+    const adjacent =
+      order.indexOf(edge.target) === order.indexOf(edge.source) + 1 &&
+      groupOf.get(edge.target) === groupOf.get(edge.source);
+    let points: FlowPoint[];
+    if (adjacent) {
+      points = [from, { x: from.x, y: to.y }];
+    } else {
+      const x =
+        columnRight.x +
+        columnRight.width +
+        CHANNEL_GAP +
+        channel * CHANNEL_STEP;
+      channel += 1;
+      // Into a frame, the route turns in below the frame's header, inside
+      // the gap the frame's padding leaves above the node.
+      const approach = groupOf.has(edge.target)
+        ? FLOW_FRAME_PADDING.top / 2
+        : STUB;
+      points = [
+        from,
+        { x: from.x, y: from.y + STUB },
+        { x, y: from.y + STUB },
+        { x, y: to.y - approach },
+        { x: to.x, y: to.y - approach },
+        to,
+      ];
+    }
+    const label = input.labels.get(edge.id);
+    edges[edge.id] = {
+      points,
+      ...(label
+        ? {
+            label: {
+              x: from.x + 8,
+              y: from.y + 4,
+              width: label.width,
+              height: label.height,
+            },
+          }
+        : {}),
+    };
+  }
+  const bounds = boundsOf([
+    ...Object.values(nodes),
+    ...Object.values(groups),
+    ...Object.values(edges).flatMap((edge) =>
+      edge.points.map((point) => ({ ...point, width: 0, height: 0 })),
+    ),
+  ]);
+  return {
+    signature: input.signature,
+    nodes,
+    groups,
+    edges,
+    bounds,
+    rows: order.filter((id) => nodes[id] !== undefined).map((id) => [id]),
+    engine: 'fallback-column',
+    ms: input.ms,
+  };
+}
diff --git a/packages/ui/src/components/flow/layout/geometry.test.ts b/packages/ui/src/components/flow/layout/geometry.test.ts
new file mode 100644
index 0000000000..9f4ab8cf4a
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/geometry.test.ts
@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  boundsOf,
+  cleanRoute,
+  dropRedundant,
+  isAxisAligned,
+  joinSections,
+  rectsOverlap,
+  roundedOrthogonalPath,
+  segmentCrossesRect,
+  trimEnd,
+} from './geometry';
+
+describe('joinSections', () => {
+  it('follows the sections of an edge in order, the junction once', () => {
+    const points = joinSections([
+      {
+        id: 'b',
+        startPoint: { x: 10, y: 50 },
+        endPoint: { x: 10, y: 90 },
+        incomingSections: ['a'],
+      },
+      {
+        id: 'a',
+        startPoint: { x: 0, y: 0 },
+        bendPoints: [{ x: 0, y: 50 }],
+        endPoint: { x: 10, y: 50 },
+        outgoingSections: ['b'],
+      },
+    ]);
+    expect(points).toEqual([
+      { x: 0, y: 0 },
+      { x: 0, y: 50 },
+      { x: 10, y: 50 },
+      { x: 10, y: 90 },
+    ]);
+  });
+
+  it('answers nothing for no sections', () => {
+    expect(joinSections([])).toEqual([]);
+  });
+});
+
+describe('cleanRoute', () => {
+  it('straightens the hair-thin diagonals ELK answers', () => {
+    const route = cleanRoute([
+      { x: 100.2499, y: 0 },
+      { x: 100.2501, y: 40 },
+      { x: 180, y: 40.0001 },
+      { x: 180, y: 90 },
+    ]);
+    expect(isAxisAligned(route)).toBe(true);
+    expect(route).toEqual([
+      { x: 100, y: 0 },
+      { x: 100, y: 40 },
+      { x: 180, y: 40 },
+      { x: 180, y: 90 },
+    ]);
+  });
+
+  it('keeps the end point where ELK put it', () => {
+    const route = cleanRoute([
+      { x: 0, y: 0 },
+      { x: 0, y: 30 },
+      { x: 50.3, y: 30 },
+      { x: 50.6, y: 60 },
+    ]);
+    expect(route.at(-1)).toEqual({ x: 50.5, y: 60 });
+    expect(isAxisAligned(route)).toBe(true);
+  });
+
+  it('drops repeated and collinear points', () => {
+    expect(
+      dropRedundant([
+        { x: 0, y: 0 },
+        { x: 0, y: 0 },
+        { x: 0, y: 10 },
+        { x: 0, y: 20 },
+        { x: 5, y: 20 },
+      ]),
+    ).toEqual([
+      { x: 0, y: 0 },
+      { x: 0, y: 20 },
+      { x: 5, y: 20 },
+    ]);
+  });
+});
+
+describe('roundedOrthogonalPath', () => {
+  it('rounds each corner with the radius it is given', () => {
+    expect(
+      roundedOrthogonalPath(
+        [
+          { x: 0, y: 0 },
+          { x: 0, y: 40 },
+          { x: 40, y: 40 },
+        ],
+        8,
+      ),
+    ).toBe('M0 0 L0 32 Q0 40 8 40 L40 40');
+  });
+
+  it('never rounds past half of a short segment', () => {
+    expect(
+      roundedOrthogonalPath(
+        [
+          { x: 0, y: 0 },
+          { x: 0, y: 6 },
+          { x: 40, y: 6 },
+        ],
+        8,
+      ),
+    ).toBe('M0 0 L0 3 Q0 6 3 6 L40 6');
+  });
+
+  it('draws a straight route as one line', () => {
+    expect(
+      roundedOrthogonalPath(
+        [
+          { x: 0, y: 0 },
+          { x: 0, y: 40 },
+        ],
+        8,
+      ),
+    ).toBe('M0 0 L0 40');
+  });
+});
+
+describe('trimEnd', () => {
+  it('shortens the route by the arrow length, across a bend if needed', () => {
+    expect(
+      trimEnd(
+        [
+          { x: 0, y: 0 },
+          { x: 0, y: 40 },
+          { x: 4, y: 40 },
+        ],
+        8,
+      ),
+    ).toEqual([
+      { x: 0, y: 0 },
+      { x: 0, y: 36 },
+    ]);
+  });
+});
+
+describe('segmentCrossesRect', () => {
+  const box = { x: 10, y: 10, width: 20, height: 20 };
+
+  it('sees a segment through a box', () => {
+    expect(segmentCrossesRect({ x: 20, y: 0 }, { x: 20, y: 40 }, box)).toBe(
+      true,
+    );
+  });
+
+  it('lets a segment meet a box at its border', () => {
+    expect(segmentCrossesRect({ x: 20, y: 0 }, { x: 20, y: 10 }, box)).toBe(
+      false,
+    );
+    expect(segmentCrossesRect({ x: 10, y: 0 }, { x: 10, y: 40 }, box)).toBe(
+      false,
+    );
+  });
+
+  it('lets a segment pass beside a box', () => {
+    expect(segmentCrossesRect({ x: 40, y: 0 }, { x: 40, y: 40 }, box)).toBe(
+      false,
+    );
+  });
+});
+
+describe('rectangles', () => {
+  it('overlap only when they share area', () => {
+    const a = { x: 0, y: 0, width: 10, height: 10 };
+    expect(rectsOverlap(a, { x: 5, y: 5, width: 10, height: 10 })).toBe(true);
+    expect(rectsOverlap(a, { x: 10, y: 0, width: 10, height: 10 })).toBe(false);
+  });
+
+  it('bound every rectangle given', () => {
+    expect(
+      boundsOf([
+        { x: 0, y: 5, width: 10, height: 10 },
+        { x: -5, y: 0, width: 4, height: 4 },
+      ]),
+    ).toEqual({ x: -5, y: 0, width: 15, height: 15 });
+  });
+});
diff --git a/packages/ui/src/components/flow/layout/geometry.ts b/packages/ui/src/components/flow/layout/geometry.ts
new file mode 100644
index 0000000000..370a38fa11
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/geometry.ts
@@ -0,0 +1,279 @@
+import type { FlowPoint, FlowRect } from '../types';
+
+/**
+ * Pure geometry for routed edges: turning ELK's sections into one clean
+ * polyline, and that polyline into the SVG path the canvas draws.
+ */
+
+/** The fragment of an ELK edge section this module reads. */
+export interface FlowElkSection {
+  id: string;
+  startPoint: FlowPoint;
+  endPoint: FlowPoint;
+  bendPoints?: readonly FlowPoint[];
+  incomingSections?: readonly string[];
+  outgoingSections?: readonly string[];
+}
+
+/**
+ * One polyline from an edge's sections. An edge that crosses a frame's
+ * border can come back in several sections, each naming the one before and
+ * after it; they are joined in that order, the shared junction point once.
+ */
+export function joinSections(sections: readonly FlowElkSection[]): FlowPoint[] {
+  if (sections.length === 0) return [];
+  const byId = new Map(sections.map((section) => [section.id, section]));
+  const first =
+    sections.find(
+      (section) =>
+        (section.incomingSections ?? []).filter((id) => byId.has(id)).length ===
+        0,
+    ) ?? sections[0];
+  const points: FlowPoint[] = [];
+  const seen = new Set<string>();
+  let current: FlowElkSection | undefined = first;
+  while (current !== undefined && !seen.has(current.id)) {
+    seen.add(current.id);
+    for (const point of [
+      current.startPoint,
+      ...(current.bendPoints ?? []),
+      current.endPoint,
+    ]) {
+      const last = points.at(-1);
+      if (last === undefined || last.x !== point.x || last.y !== point.y)
+        points.push({ x: point.x, y: point.y });
+    }
+    const next: string | undefined = (current.outgoingSections ?? []).find(
+      (id) => byId.has(id),
+    );
+    current = next === undefined ? undefined : byId.get(next);
+  }
+  // Sections no chain reached (ELK never leaves one, but a malformed answer
+  // must not drop a route) follow in the order ELK gave them.
+  for (const section of sections) {
+    if (seen.has(section.id)) continue;
+    for (const point of [
+      section.startPoint,
+      ...(section.bendPoints ?? []),
+      section.endPoint,
+    ])
+      points.push({ x: point.x, y: point.y });
+  }
+  return points;
+}
+
+/** Rounds to the half pixel: strokes land on the pixel grid at any zoom
+ *  that divides it. */
+export const snapHalf = (value: number) => Math.round(value * 2) / 2;
+
+/**
+ * Snaps a route to the half pixel and makes every segment exactly
+ * horizontal or vertical. ELK answers coordinates that differ by a hair
+ * (12.2499 against 12.2501) where it means the same line; drawn as given,
+ * such a segment is a diagonal a fraction of a pixel wide. A segment is
+ * straightened along its longer axis by moving its later end — the earlier
+ * one for the last segment, so the arrow still lands where ELK put it.
+ * Then repeated and collinear points go.
+ */
+export function cleanRoute(points: readonly FlowPoint[]): FlowPoint[] {
+  const snapped = points.map((point) => ({
+    x: snapHalf(point.x),
+    y: snapHalf(point.y),
+  }));
+  for (let index = 0; index + 1 < snapped.length; index++) {
+    const a = snapped[index];
+    const b = snapped[index + 1];
+    const dx = Math.abs(a.x - b.x);
+    const dy = Math.abs(a.y - b.y);
+    if (dx === 0 || dy === 0) continue;
+    const lastSegment = index + 2 === snapped.length;
+    if (dy >= dx) {
+      if (lastSegment && index > 0) a.x = b.x;
+      else b.x = a.x;
+    } else if (lastSegment && index > 0) a.y = b.y;
+    else b.y = a.y;
+  }
+  return dropRedundant(snapped);
+}
+
+/** Drops repeated points and interior points on a straight run. */
+export function dropRedundant(points: readonly FlowPoint[]): FlowPoint[] {
+  const out: FlowPoint[] = [];
+  for (const point of points) {
+    const last = out.at(-1);
+    if (last !== undefined && last.x === point.x && last.y === point.y)
+      continue;
+    const before = out.at(-2);
+    if (
+      before !== undefined &&
+      last !== undefined &&
+      ((before.x === last.x && last.x === point.x) ||
+        (before.y === last.y && last.y === point.y))
+    ) {
+      out[out.length - 1] = { x: point.x, y: point.y };
+      continue;
+    }
+    out.push({ x: point.x, y: point.y });
+  }
+  return out;
+}
+
+/** Every segment is horizontal or vertical. */
+export function isAxisAligned(points: readonly FlowPoint[]): boolean {
+  for (let index = 0; index + 1 < points.length; index++) {
+    const a = points[index];
+    const b = points[index + 1];
+    if (a.x !== b.x && a.y !== b.y) return false;
+  }
+  return true;
+}
+
+const distance = (a: FlowPoint, b: FlowPoint) =>
+  Math.hypot(b.x - a.x, b.y - a.y);
+
+/**
+ * The route with its last `length` px cut off — where the stroke stops so
+ * an arrowhead of that length ends exactly on the route's end point.
+ */
+export function trimEnd(
+  points: readonly FlowPoint[],
+  length: number,
+): FlowPoint[] {
+  const out = points.map((point) => ({ ...point }));
+  let left = length;
+  while (out.length >= 2 && left > 0) {
+    const end = out[out.length - 1];
+    const before = out[out.length - 2];
+    const run = distance(before, end);
+    if (run > left) {
+      const ratio = (run - left) / run;
+      out[out.length - 1] = {
+        x: before.x + (end.x - before.x) * ratio,
+        y: before.y + (end.y - before.y) * ratio,
+      };
+      return out;
+    }
+    left -= run;
+    out.pop();
+  }
+  return out;
+}
+
+const fmt = (value: number) => String(Math.round(value * 100) / 100);
+
+/**
+ * An SVG path through an orthogonal route with rounded corners: each
+ * corner a quadratic curve of radius `min(radius, half of either segment)`,
+ * so two close bends never overshoot each other.
+ */
+export function roundedOrthogonalPath(
+  points: readonly FlowPoint[],
+  radius: number,
+): string {
+  const first = points[0];
+  if (first === undefined) return '';
+  let path = `M${fmt(first.x)} ${fmt(first.y)}`;
+  for (let index = 1; index < points.length - 1; index++) {
+    const before = points[index - 1];
+    const corner = points[index];
+    const after = points[index + 1];
+    const inLength = distance(before, corner);
+    const outLength = distance(corner, after);
+    const r = Math.min(radius, inLength / 2, outLength / 2);
+    if (r <= 0) {
+      path += ` L${fmt(corner.x)} ${fmt(corner.y)}`;
+      continue;
+    }
+    const enter = {
+      x: corner.x - ((corner.x - before.x) / inLength) * r,
+      y: corner.y - ((corner.y - before.y) / inLength) * r,
+    };
+    const leave = {
+      x: corner.x + ((after.x - corner.x) / outLength) * r,
+      y: corner.y + ((after.y - corner.y) / outLength) * r,
+    };
+    path += ` L${fmt(enter.x)} ${fmt(enter.y)} Q${fmt(corner.x)} ${fmt(corner.y)} ${fmt(leave.x)} ${fmt(leave.y)}`;
+  }
+  const last = points[points.length - 1];
+  if (points.length > 1) path += ` L${fmt(last.x)} ${fmt(last.y)}`;
+  return path;
+}
+
+/** The direction of the route's last segment, as a unit vector. */
+export function endDirection(points: readonly FlowPoint[]): FlowPoint {
+  const end = points.at(-1);
+  const before = points.at(-2);
+  if (end === undefined || before === undefined) return { x: 0, y: 1 };
+  const length = distance(before, end) || 1;
+  return { x: (end.x - before.x) / length, y: (end.y - before.y) / length };
+}
+
+/**
+ * Whether the segment `a`–`b` passes through `rect` shrunk by `inset` on
+ * every side — touching a border (where an edge meets its own box) does
+ * not count.
+ */
+export function segmentCrossesRect(
+  a: FlowPoint,
+  b: FlowPoint,
+  rect: FlowRect,
+  inset = 1,
+): boolean {
+  const left = rect.x + inset;
+  const right = rect.x + rect.width - inset;
+  const top = rect.y + inset;
+  const bottom = rect.y + rect.height - inset;
+  if (right <= left || bottom <= top) return false;
+  // Liang–Barsky clipping of the segment against the shrunk rectangle.
+  let t0 = 0;
+  let t1 = 1;
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const edges: [number, number][] = [
+    [-dx, a.x - left],
+    [dx, right - a.x],
+    [-dy, a.y - top],
+    [dy, bottom - a.y],
+  ];
+  for (const [p, q] of edges) {
+    if (p === 0) {
+      if (q <= 0) return false;
+      continue;
+    }
+    const t = q / p;
+    if (p < 0) {
+      if (t > t1) return false;
+      if (t > t0) t0 = t;
+    } else {
+      if (t < t0) return false;
+      if (t < t1) t1 = t;
+    }
+  }
+  return t1 - t0 > 1e-9;
+}
+
+/** Whether two rectangles share any area. */
+export function rectsOverlap(a: FlowRect, b: FlowRect): boolean {
+  return (
+    a.x < b.x + b.width &&
+    b.x < a.x + a.width &&
+    a.y < b.y + b.height &&
+    b.y < a.y + a.height
+  );
+}
+
+/** The smallest rectangle around every given one. */
+export function boundsOf(rects: readonly FlowRect[]): FlowRect {
+  if (rects.length === 0) return { x: 0, y: 0, width: 0, height: 0 };
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const rect of rects) {
+    minX = Math.min(minX, rect.x);
+    minY = Math.min(minY, rect.y);
+    maxX = Math.max(maxX, rect.x + rect.width);
+    maxY = Math.max(maxY, rect.y + rect.height);
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
diff --git a/packages/ui/src/components/flow/layout/index.ts b/packages/ui/src/components/flow/layout/index.ts
new file mode 100644
index 0000000000..dd56d42b8f
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/index.ts
@@ -0,0 +1,25 @@
+/**
+ * `@tale/ui/flow/layout` — lays out a `FlowGraph` with ELK (in a worker,
+ * the main thread when it cannot start, one column when ELK fails) and
+ * answers where every box, frame, route and label goes.
+ */
+export { getFlowElk } from './elk-client';
+export {
+  layoutFlowGraph,
+  type ElkLike,
+  type FlowElk,
+  type LayoutFlowGraphOptions,
+} from './layout-flow-graph';
+export {
+  FLOW_NODE_WIDTH,
+  flowEdgeLabelSize,
+  flowNodeSize,
+  type FlowTextMeasure,
+} from './sizes';
+export {
+  useFlowLayout,
+  type FlowLayoutStatus,
+  type UseFlowLayoutOptions,
+  type UseFlowLayoutResult,
+} from './use-flow-layout';
+export type { FlowLayout, FlowPoint, FlowRect } from '../types';
diff --git a/packages/ui/src/components/flow/layout/layout-cache.ts b/packages/ui/src/components/flow/layout/layout-cache.ts
new file mode 100644
index 0000000000..f3f3bb046d
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/layout-cache.ts
@@ -0,0 +1,50 @@
+import type { FlowLayout } from '../types';
+
+/**
+ * Fresh layouts this session already computed, by structural signature:
+ * switching back to a version or reopening a tab draws at once. Holds the
+ * 32 used last. Live relayouts are not kept — they depend on the picture
+ * they started from — and neither is a one-column fallback, so a later
+ * attempt can still succeed.
+ */
+export class FlowLayoutCache {
+  readonly #entries = new Map<string, FlowLayout>();
+
+  constructor(readonly capacity = 32) {}
+
+  get(signature: string): FlowLayout | undefined {
+    const layout = this.#entries.get(signature);
+    if (layout === undefined) return undefined;
+    // Most recently used goes last; the first entry is evicted next.
+    this.#entries.delete(signature);
+    this.#entries.set(signature, layout);
+    return layout;
+  }
+
+  /** Reads without marking the entry used (safe during a render). */
+  peek(signature: string): FlowLayout | undefined {
+    return this.#entries.get(signature);
+  }
+
+  set(layout: FlowLayout): void {
+    if (layout.engine === 'fallback-column') return;
+    this.#entries.delete(layout.signature);
+    this.#entries.set(layout.signature, layout);
+    while (this.#entries.size > this.capacity) {
+      const oldest = this.#entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.#entries.delete(oldest);
+    }
+  }
+
+  get size(): number {
+    return this.#entries.size;
+  }
+
+  clear(): void {
+    this.#entries.clear();
+  }
+}
+
+/** The cache every canvas in the tab shares. */
+export const flowLayoutCache = new FlowLayoutCache();
diff --git a/packages/ui/src/components/flow/layout/layout-flow-graph.test.ts b/packages/ui/src/components/flow/layout/layout-flow-graph.test.ts
new file mode 100644
index 0000000000..8dbf02e73e
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/layout-flow-graph.test.ts
@@ -0,0 +1,478 @@
+import ELK from 'elkjs/lib/elk.bundled.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  branchFlowGraph,
+  cyclicFlowGraph,
+  inputGateFlowGraph,
+  reviewPullRequestsFlowGraph,
+  syntheticFlowGraph,
+  triageFlowGraph,
+  triageInboxFlowGraph,
+} from '../testing/flow-fixtures';
+import {
+  assertLabelsClear,
+  assertNoEdgeCrossesBox,
+  assertRoutesAxisAligned,
+  flowRowIndex,
+  flowRowOrderFlips,
+} from '../testing/flow-geometry';
+import type { FlowEdge, FlowGraph, FlowLayout, FlowRect } from '../types';
+import { validateFlowGraph } from '../validate-graph';
+import { rectsOverlap, segmentCrossesRect } from './geometry';
+import { FlowLayoutCache } from './layout-cache';
+import {
+  layoutFlowGraph,
+  type FlowElk,
+  type FlowElkNode,
+} from './layout-flow-graph';
+import { flowNodeSize } from './sizes';
+
+/** A fresh bundled ELK, as the main thread runs it. */
+function freshElk(): FlowElk {
+  const elk = new ELK();
+  return {
+    layout: async (graph: FlowElkNode) => ({
+      graph: await elk.layout(graph),
+      engine: 'main',
+    }),
+  };
+}
+
+const FIXTURES: [string, () => FlowGraph][] = [
+  ['Triage GitHub issues', triageFlowGraph],
+  ['review pull requests', reviewPullRequestsFlowGraph],
+  ['triage inbox', triageInboxFlowGraph],
+  ['when/elseOf, else-if and repeat', branchFlowGraph],
+  ['a gate on the run input', inputGateFlowGraph],
+  ['40 nodes', () => syntheticFlowGraph(40)],
+  ['a cycle', cyclicFlowGraph],
+];
+
+const contains = (outer: FlowRect, inner: FlowRect) =>
+  inner.x >= outer.x &&
+  inner.y >= outer.y &&
+  inner.x + inner.width <= outer.x + outer.width &&
+  inner.y + inner.height <= outer.y + outer.height;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('layoutFlowGraph on every fixture', () => {
+  it.each(FIXTURES)(
+    '%s: routes every edge round every box',
+    async (_name, build) => {
+      const graph = build();
+      validateFlowGraph(graph);
+      const layout = await layoutFlowGraph(graph);
+      expect(layout.engine).toBe('main');
+      for (const node of graph.nodes) {
+        const rect = layout.nodes[node.id];
+        expect(rect, node.id).toBeDefined();
+        expect({ width: rect?.width, height: rect?.height }, node.id).toEqual(
+          flowNodeSize(node),
+        );
+      }
+      const drawn = graph.edges.filter((edge) => !edge.layoutOnly);
+      expect(Object.keys(layout.edges).sort()).toEqual(
+        drawn.map((edge) => edge.id).sort(),
+      );
+      assertRoutesAxisAligned(layout);
+      assertNoEdgeCrossesBox(layout);
+      assertLabelsClear(layout);
+    },
+  );
+
+  it.each(FIXTURES)(
+    '%s: Start alone in the first row, End alone in the last',
+    async (_name, build) => {
+      const layout = await layoutFlowGraph(build());
+      expect(layout.rows[0]).toEqual(['__start']);
+      expect(layout.rows.at(-1)).toEqual(['__end']);
+    },
+  );
+
+  it.each(FIXTURES)(
+    '%s: frames hold their header and members',
+    async (_name, build) => {
+      const graph = build();
+      const layout = await layoutFlowGraph(graph);
+      for (const group of graph.groups ?? []) {
+        const frame = layout.groups[group.id];
+        expect(frame, group.id).toBeDefined();
+        if (frame === undefined) continue;
+        expect(contains(frame, frame.header), `${group.id} header`).toBe(true);
+        for (const member of group.members)
+          expect(
+            contains(frame, layout.nodes[member] as FlowRect),
+            member,
+          ).toBe(true);
+        // The header sits above its members.
+        for (const member of group.members)
+          expect(frame.header.y + frame.header.height).toBeLessThanOrEqual(
+            (layout.nodes[member] as FlowRect).y,
+          );
+      }
+    },
+  );
+
+  it('lays out the same graph the same way every time, on any instance', async () => {
+    for (const [, build] of FIXTURES) {
+      const strip = (layout: FlowLayout) => ({ ...layout, ms: 0 });
+      const first = strip(await layoutFlowGraph(build(), { elk: freshElk() }));
+      const again = strip(await layoutFlowGraph(build(), { elk: freshElk() }));
+      const shared = strip(await layoutFlowGraph(build()));
+      expect(again).toEqual(first);
+      expect(shared).toEqual(first);
+    }
+  });
+
+  it('lays out 40 nodes well inside the budget', async () => {
+    const layout = await layoutFlowGraph(syntheticFlowGraph(40));
+    expect(layout.ms).toBeLessThan(1_500);
+  });
+});
+
+describe('the pictures the canvas promises', () => {
+  it('runs Open issues → Report round Score and its frame, never through them', async () => {
+    const layout = await layoutFlowGraph(triageFlowGraph());
+    const route = layout.edges['open_issues>report']?.points ?? [];
+    expect(route.length).toBeGreaterThanOrEqual(2);
+    const frame = layout.groups['each:score'] as FlowRect;
+    const score = layout.nodes.score as FlowRect;
+    for (let index = 0; index + 1 < route.length; index++) {
+      const a = route[index]!;
+      const b = route[index + 1]!;
+      expect(segmentCrossesRect(a, b, score)).toBe(false);
+      expect(segmentCrossesRect(a, b, frame)).toBe(false);
+    }
+  });
+
+  it('puts an if/else pair in one row, Yes on the left, under its gate', async () => {
+    const graph = branchFlowGraph();
+    const layout = await layoutFlowGraph(graph);
+    const pairs: [string, string, string][] = [
+      ['__gate:urgent', 'urgent', '__gate:normal'],
+      ['__gate:normal', 'normal', 'low'],
+    ];
+    for (const [gate, yes, no] of pairs) {
+      expect(flowRowIndex(layout, yes)).toBe(flowRowIndex(layout, no));
+      expect((layout.nodes[yes] as FlowRect).x).toBeLessThan(
+        (layout.nodes[no] as FlowRect).x,
+      );
+      expect(flowRowIndex(layout, gate)).toBeLessThan(
+        flowRowIndex(layout, yes),
+      );
+      // "Yes" and "No" are labelled.
+      const out = graph.edges.filter((edge) => edge.source === gate);
+      for (const edge of out)
+        expect(layout.edges[edge.id]?.label).toBeDefined();
+    }
+  });
+
+  it('hangs a gate on the run input right above its node', async () => {
+    const layout = await layoutFlowGraph(inputGateFlowGraph());
+    const gate = layout.nodes['__gate:notify'] as FlowRect;
+    const node = layout.nodes.notify as FlowRect;
+    expect(flowRowIndex(layout, '__gate:notify')).toBe(
+      flowRowIndex(layout, 'notify') - 1,
+    );
+    const centre = gate.x + gate.width / 2;
+    expect(centre).toBeGreaterThan(node.x);
+    expect(centre).toBeLessThan(node.x + node.width);
+    // The layout-only edge shapes the picture but is never drawn.
+    expect(layout.edges['load>__gate:notify']).toBeUndefined();
+  });
+
+  it('lays out a cycle, its back edge still leaving at the bottom', async () => {
+    const layout = await layoutFlowGraph(cyclicFlowGraph());
+    const back = layout.edges['c>a']?.points ?? [];
+    const c = layout.nodes.c as FlowRect;
+    expect(back[0]?.y).toBe(c.y + c.height);
+  });
+
+  it('measures labels with the measure it is given', async () => {
+    const measure = vi.fn((text: string) => text.length * 10);
+    const labels = (edge: FlowEdge) =>
+      edge.kind === 'branch-yes'
+        ? 'Ja'
+        : edge.kind === 'branch-no'
+          ? 'Nein'
+          : undefined;
+    const layout = await layoutFlowGraph(branchFlowGraph(), {
+      measure,
+      edgeLabel: labels,
+    });
+    expect(layout.edges['__gate:normal>low']?.label?.width).toBe(56);
+    expect(measure).toHaveBeenCalledWith('Nein', '500 12px Inter');
+  });
+});
+
+/** The graph with `change` applied: nodes and edges added or taken away. */
+function edit(
+  graph: FlowGraph,
+  change: {
+    add?: FlowGraph['nodes'];
+    before?: string;
+    edges?: FlowEdge[];
+    remove?: string;
+  },
+): FlowGraph {
+  let nodes = [...graph.nodes];
+  if (change.remove) nodes = nodes.filter((node) => node.id !== change.remove);
+  if (change.add) {
+    const at = nodes.findIndex(
+      (node) => node.id === (change.before ?? '__end'),
+    );
+    nodes.splice(at, 0, ...change.add);
+  }
+  let edges = graph.edges.filter(
+    (edge) => edge.source !== change.remove && edge.target !== change.remove,
+  );
+  edges = [...edges, ...(change.edges ?? [])];
+  if (change.remove) {
+    // A node left without anything leading to it starts from Start; one
+    // left without anything after it ends at End.
+    for (const node of nodes) {
+      if (node.kind === 'entry' || node.kind === 'exit') continue;
+      if (!edges.some((edge) => edge.target === node.id))
+        edges.push({
+          id: `__start>${node.id}`,
+          source: '__start',
+          target: node.id,
+          kind: 'entry',
+        });
+      if (!edges.some((edge) => edge.source === node.id))
+        edges.push({
+          id: `${node.id}>__end`,
+          source: node.id,
+          target: '__end',
+          kind: 'completion',
+        });
+    }
+  }
+  return { ...graph, nodes, edges };
+}
+
+const step = (id: string) => ({ id, kind: 'step' as const, label: id });
+const data = (
+  source: string,
+  target: string,
+  kind: FlowEdge['kind'] = 'data',
+): FlowEdge => ({
+  id: `${source}>${target}`,
+  source,
+  target,
+  kind,
+});
+
+describe('a live relayout keeps each row in order', () => {
+  const EDITS: [
+    string,
+    () => FlowGraph,
+    (graph: FlowGraph) => FlowGraph,
+    string,
+  ][] = [
+    [
+      'append a leaf',
+      branchFlowGraph,
+      (g) =>
+        edit(g, {
+          add: [step('zz')],
+          edges: [data('merge', 'zz'), data('zz', '__end', 'completion')],
+        }),
+      'merge',
+    ],
+    [
+      'add a side branch',
+      branchFlowGraph,
+      (g) =>
+        edit(g, {
+          add: [step('side')],
+          before: 'enrich',
+          edges: [
+            data('classify', 'side'),
+            data('side', '__end', 'completion'),
+          ],
+        }),
+      'classify',
+    ],
+    [
+      'add a reference',
+      branchFlowGraph,
+      (g) => edit(g, { edges: [data('enrich', 'poll')] }),
+      'enrich',
+    ],
+    [
+      'remove a node',
+      branchFlowGraph,
+      (g) => edit(g, { remove: 'enrich' }),
+      'fetch',
+    ],
+    [
+      'add a gate',
+      branchFlowGraph,
+      (g) =>
+        edit(
+          {
+            ...g,
+            edges: g.edges.filter((edge) => edge.id !== 'merge>notify'),
+          },
+          {
+            add: [
+              {
+                id: '__gate:notify',
+                kind: 'gate',
+                label: 'Notify',
+                mode: 'only-if',
+                condition: 'a reply is due',
+              },
+            ],
+            before: 'notify',
+            edges: [
+              data('merge', '__gate:notify', 'order'),
+              data('__gate:notify', 'notify', 'gate'),
+              data('merge', 'notify'),
+            ],
+          },
+        ),
+      'merge',
+    ],
+    [
+      'append a leaf to 40 nodes',
+      () => syntheticFlowGraph(40),
+      (g) =>
+        edit(g, {
+          add: [step('zz')],
+          edges: [data('s39', 'zz'), data('zz', '__end', 'completion')],
+        }),
+      's39',
+    ],
+    [
+      'add a side branch to 40 nodes',
+      () => syntheticFlowGraph(40),
+      (g) =>
+        edit(g, {
+          add: [step('side')],
+          before: 's21',
+          edges: [data('s20', 'side'), data('side', '__end', 'completion')],
+        }),
+      's20',
+    ],
+    [
+      'triage inbox: add a node after Due',
+      triageInboxFlowGraph,
+      (g) =>
+        edit(g, {
+          add: [step('label')],
+          before: 'draft',
+          edges: [data('due', 'label'), data('label', '__end', 'completion')],
+        }),
+      'due',
+    ],
+  ];
+
+  it.each(EDITS)(
+    '%s: no node swaps sides with its neighbour',
+    async (_name, build, change, anchor) => {
+      const base = build();
+      const before = await layoutFlowGraph(base);
+      const edited = change(base);
+      validateFlowGraph(edited);
+      const after = await layoutFlowGraph(edited, { previous: before });
+      expect(flowRowOrderFlips(before, after)).toEqual([]);
+      assertNoEdgeCrossesBox(after);
+      assertLabelsClear(after);
+      // Everything above the edit stays in its row.
+      const anchorRow = flowRowIndex(before, anchor);
+      for (const [index, row] of before.rows.entries()) {
+        if (index >= anchorRow) break;
+        for (const id of row) expect(flowRowIndex(after, id), id).toBe(index);
+      }
+    },
+  );
+});
+
+describe('when ELK cannot lay the graph out', () => {
+  const broken: FlowElk = {
+    layout: () => Promise.reject(new Error('ELK fell over')),
+  };
+
+  it('stands every node in one column, nothing overlapping or crossed', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    for (const [, build] of FIXTURES) {
+      const graph = build();
+      const layout = await layoutFlowGraph(graph, { elk: broken });
+      expect(layout.engine).toBe('fallback-column');
+      const rects = graph.nodes.map(
+        (node) => layout.nodes[node.id] as FlowRect,
+      );
+      expect(rects.every(Boolean)).toBe(true);
+      for (let i = 0; i < rects.length; i++)
+        for (let j = i + 1; j < rects.length; j++)
+          expect(rectsOverlap(rects[i]!, rects[j]!)).toBe(false);
+      assertRoutesAxisAligned(layout);
+      assertNoEdgeCrossesBox(layout);
+      expect(layout.rows.flat()).toEqual(graph.nodes.map((node) => node.id));
+    }
+    expect(warn).toHaveBeenCalledWith(
+      'Flow layout failed; showing the nodes in one column',
+      expect.any(Error),
+    );
+  });
+
+  it('gives up on an ELK that never answers', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const silent: FlowElk = { layout: () => new Promise(() => undefined) };
+    const layout = await layoutFlowGraph(triageFlowGraph(), {
+      elk: silent,
+      timeoutMs: 20,
+    });
+    expect(layout.engine).toBe('fallback-column');
+  });
+
+  it('rejects a cancelled layout rather than answering it', async () => {
+    const controller = new AbortController();
+    const slow: FlowElk = { layout: () => new Promise(() => undefined) };
+    const pending = layoutFlowGraph(triageFlowGraph(), {
+      elk: slow,
+      signal: controller.signal,
+    });
+    controller.abort();
+    await expect(pending).rejects.toMatchObject({ name: 'AbortError' });
+  });
+});
+
+describe('FlowLayoutCache', () => {
+  const layout = (
+    signature: string,
+    engine: FlowLayout['engine'] = 'worker',
+  ): FlowLayout => ({
+    signature,
+    nodes: {},
+    groups: {},
+    edges: {},
+    bounds: { x: 0, y: 0, width: 0, height: 0 },
+    rows: [],
+    engine,
+    ms: 0,
+  });
+
+  it('keeps the layouts used last and drops the oldest', () => {
+    const cache = new FlowLayoutCache(2);
+    cache.set(layout('a'));
+    cache.set(layout('b'));
+    expect(cache.get('a')?.signature).toBe('a');
+    cache.set(layout('c'));
+    expect(cache.get('b')).toBeUndefined();
+    expect(cache.peek('a')?.signature).toBe('a');
+    expect(cache.size).toBe(2);
+  });
+
+  it('never keeps a one-column fallback', () => {
+    const cache = new FlowLayoutCache();
+    cache.set(layout('a', 'fallback-column'));
+    expect(cache.get('a')).toBeUndefined();
+  });
+});
diff --git a/packages/ui/src/components/flow/layout/layout-flow-graph.ts b/packages/ui/src/components/flow/layout/layout-flow-graph.ts
new file mode 100644
index 0000000000..4027ed406f
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/layout-flow-graph.ts
@@ -0,0 +1,506 @@
+import type { ElkExtendedEdge, ElkNode } from 'elkjs/lib/elk-api';
+
+import type {
+  FlowEdge,
+  FlowGraph,
+  FlowGroup,
+  FlowLayout,
+  FlowNode,
+  FlowPoint,
+  FlowRect,
+} from '../types';
+import {
+  FLOW_ELK_LIVE,
+  FLOW_ELK_NODE,
+  FLOW_ELK_ROOT,
+  FLOW_FRAME_PADDING,
+} from './elk-options';
+import { layoutFallbackColumn } from './fallback-column';
+import { boundsOf, cleanRoute, joinSections, snapHalf } from './geometry';
+import {
+  estimateFlowText,
+  flowEdgeLabelSize,
+  flowFrameHeaderSize,
+  flowNodeSize,
+  type FlowTextMeasure,
+} from './sizes';
+
+/** The JSON graph ELK reads and answers with. */
+export type FlowElkNode = ElkNode;
+export type FlowElkEdge = ElkExtendedEdge;
+
+/** Anything that lays out an ELK JSON graph: elkjs's bundled build, the
+ *  worker-backed client, or a test's stand-in. */
+export interface ElkLike {
+  layout(graph: FlowElkNode): Promise<FlowElkNode>;
+}
+
+/** A layout engine and where it runs. */
+export interface FlowElk {
+  layout(graph: FlowElkNode): Promise<{
+    graph: FlowElkNode;
+    engine: 'worker' | 'main';
+  }>;
+}
+
+export interface LayoutFlowGraphOptions {
+  /** The layout of the graph on screen before this change: lays out again
+   *  keeping every row's order (a live relayout). Leave it out to lay out
+   *  afresh — opening a document, switching versions. */
+  previous?: FlowLayout | null;
+  /** Measures text; the layout estimates when left out. */
+  measure?: FlowTextMeasure;
+  /** The words on an edge ("Yes", "No"); English when left out. */
+  edgeLabel?: (edge: FlowEdge) => string | undefined;
+  /** The engine; the shared worker-backed one when left out. */
+  elk?: FlowElk;
+  signal?: AbortSignal;
+  /** Gives up on ELK after this long and lays the graph out in one column.
+   *  @default 5000 */
+  timeoutMs?: number;
+}
+
+/** The id of a frame's header box, which edges route around. */
+export const frameHeaderId = (groupId: string) => `${groupId}:head`;
+const headerEdgeId = (groupId: string, member: string) =>
+  `${groupId}:head>${member}`;
+
+export function defaultEdgeLabel(edge: FlowEdge): string | undefined {
+  if (edge.kind === 'branch-yes') return 'Yes';
+  if (edge.kind === 'branch-no') return 'No';
+  return undefined;
+}
+
+interface Prepared {
+  signature: string;
+  sizes: Map<string, { width: number; height: number }>;
+  labels: Map<string, { text: string; width: number; height: number }>;
+  headers: Map<string, { width: number; height: number }>;
+  /** Layout-only links from a frame's header to its first members. */
+  headerEdges: { id: string; source: string; target: string }[];
+  groupOf: Map<string, FlowGroup>;
+}
+
+function prepare(
+  graph: FlowGraph,
+  measure: FlowTextMeasure,
+  edgeLabel: (edge: FlowEdge) => string | undefined,
+): Prepared {
+  const sizes = new Map(
+    graph.nodes.map((node) => [node.id, flowNodeSize(node, measure)]),
+  );
+  const labels = new Map<
+    string,
+    { text: string; width: number; height: number }
+  >();
+  for (const edge of graph.edges) {
+    if (edge.layoutOnly) continue;
+    const text = edgeLabel(edge);
+    if (text)
+      labels.set(edge.id, { text, ...flowEdgeLabelSize(text, measure) });
+  }
+  const groupOf = new Map<string, FlowGroup>();
+  const headers = new Map<string, { width: number; height: number }>();
+  const headerEdges: Prepared['headerEdges'] = [];
+  for (const group of graph.groups ?? []) {
+    headers.set(group.id, flowFrameHeaderSize(group.label, measure));
+    const inside = new Set(group.members);
+    for (const member of group.members) groupOf.set(member, group);
+    // The header heads every member nothing inside the frame leads to, so
+    // it sits in the frame's first row and incoming edges go round it.
+    for (const member of group.members) {
+      const led = graph.edges.some(
+        (edge) => edge.target === member && inside.has(edge.source),
+      );
+      if (!led)
+        headerEdges.push({
+          id: headerEdgeId(group.id, member),
+          source: frameHeaderId(group.id),
+          target: member,
+        });
+    }
+  }
+  const signature = [
+    graph.nodes
+      .map((node) => {
+        const size = sizes.get(node.id);
+        return `${node.id}:${node.kind}:${size?.width}x${size?.height}`;
+      })
+      .join(','),
+    graph.edges
+      .map(
+        (edge) =>
+          `${edge.id}:${edge.source}>${edge.target}:${edge.kind}${edge.layoutOnly ? ':l' : ''}${labels.has(edge.id) ? `:${labels.get(edge.id)?.width}` : ''}`,
+      )
+      .join(','),
+    (graph.groups ?? [])
+      .map(
+        (group) =>
+          `${group.id}:${group.kind}:${group.members.join('+')}:${headers.get(group.id)?.width}`,
+      )
+      .join(','),
+  ].join('|');
+  return { signature, sizes, labels, headers, headerEdges, groupOf };
+}
+
+/** The structural signature a layout of `graph` would carry. */
+export function flowLayoutSignature(
+  graph: FlowGraph,
+  options: Pick<LayoutFlowGraphOptions, 'measure' | 'edgeLabel'> = {},
+): string {
+  return prepare(
+    graph,
+    options.measure ?? estimateFlowText,
+    options.edgeLabel ?? defaultEdgeLabel,
+  ).signature;
+}
+
+const position = (point: FlowPoint) => `(${point.x},${point.y})`;
+
+/** Where a node sat last time, or — new — just after a neighbour that did,
+ *  so it sorts in beside the node it hangs from. */
+function hintFor(
+  id: string,
+  graph: FlowGraph,
+  previous: FlowLayout,
+): FlowPoint | undefined {
+  const before = previous.nodes[id];
+  if (before) return { x: before.x, y: before.y };
+  for (const edge of graph.edges) {
+    if (edge.target !== id) continue;
+    const source = previous.nodes[edge.source];
+    if (source) return { x: source.x + 0.5, y: source.y + 1 };
+  }
+  const index = graph.nodes.findIndex((node) => node.id === id);
+  for (let at = index - 1; at >= 0; at--) {
+    const earlier = previous.nodes[graph.nodes[at]?.id ?? ''];
+    if (earlier) return { x: earlier.x + 0.5, y: earlier.y + 1 };
+  }
+  return undefined;
+}
+
+/** The ELK graph for `graph`: one port per edge end (targets on top,
+ *  sources at the bottom), frames as compound nodes with a header box. */
+function toElkGraph(
+  graph: FlowGraph,
+  prepared: Prepared,
+  previous?: FlowLayout | null,
+): FlowElkNode {
+  const linked = [
+    ...graph.edges.map((edge) => ({
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+    })),
+    ...prepared.headerEdges,
+  ];
+  const portsOf = (id: string) => [
+    ...linked
+      .filter((edge) => edge.target === id)
+      .map((edge) => ({
+        id: `${edge.id}:t`,
+        width: 0,
+        height: 0,
+        layoutOptions: { 'elk.port.side': 'NORTH' },
+      })),
+    ...linked
+      .filter((edge) => edge.source === id)
+      .map((edge) => ({
+        id: `${edge.id}:s`,
+        width: 0,
+        height: 0,
+        layoutOptions: { 'elk.port.side': 'SOUTH' },
+      })),
+  ];
+  const hinted = (id: string, options: Record<string, string>) => {
+    if (!previous) return options;
+    const hint =
+      hintFor(id, graph, previous) ??
+      (previous.groups[id]
+        ? { x: previous.groups[id].x, y: previous.groups[id].y }
+        : undefined);
+    return hint ? { ...options, 'elk.position': position(hint) } : options;
+  };
+  const leaf = (node: FlowNode): FlowElkNode => {
+    const size = prepared.sizes.get(node.id) ?? { width: 0, height: 0 };
+    return {
+      id: node.id,
+      width: size.width,
+      height: size.height,
+      layoutOptions: hinted(node.id, { ...FLOW_ELK_NODE }),
+      ports: portsOf(node.id),
+    };
+  };
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  const children: FlowElkNode[] = [];
+  const emitted = new Set<string>();
+  for (const node of graph.nodes) {
+    const group = prepared.groupOf.get(node.id);
+    if (!group) {
+      children.push(leaf(node));
+      continue;
+    }
+    if (emitted.has(group.id)) continue;
+    emitted.add(group.id);
+    const header = prepared.headers.get(group.id) ?? { width: 0, height: 0 };
+    const headerHint = previous?.groups[group.id]?.header;
+    const right =
+      group.kind === 'repeat'
+        ? FLOW_FRAME_PADDING.repeatRight
+        : FLOW_FRAME_PADDING.right;
+    children.push({
+      id: group.id,
+      layoutOptions: hinted(group.id, {
+        'elk.padding': `[top=${FLOW_FRAME_PADDING.top},left=${FLOW_FRAME_PADDING.left},bottom=${FLOW_FRAME_PADDING.bottom},right=${right}]`,
+      }),
+      children: [
+        {
+          id: frameHeaderId(group.id),
+          width: header.width,
+          height: header.height,
+          layoutOptions: {
+            ...FLOW_ELK_NODE,
+            ...(headerHint ? { 'elk.position': position(headerHint) } : {}),
+          },
+          ports: portsOf(frameHeaderId(group.id)),
+        },
+        ...graph.nodes
+          .filter((member) => group.members.includes(member.id))
+          .map((member) => leaf(byId.get(member.id) ?? member)),
+      ],
+    });
+  }
+  return {
+    id: 'root',
+    layoutOptions: previous
+      ? { ...FLOW_ELK_ROOT, ...FLOW_ELK_LIVE }
+      : { ...FLOW_ELK_ROOT },
+    children,
+    edges: linked.map((edge) => {
+      const elkEdge: FlowElkEdge = {
+        id: edge.id,
+        sources: [`${edge.id}:s`],
+        targets: [`${edge.id}:t`],
+      };
+      const label = prepared.labels.get(edge.id);
+      if (label)
+        elkEdge.labels = [
+          {
+            id: `${edge.id}:label`,
+            text: label.text,
+            width: label.width,
+            height: label.height,
+          },
+        ];
+      return elkEdge;
+    }),
+  };
+}
+
+const snapRect = (rect: FlowRect): FlowRect => ({
+  x: snapHalf(rect.x),
+  y: snapHalf(rect.y),
+  width: rect.width,
+  height: rect.height,
+});
+
+/** Rows top to bottom: nodes whose centres share a line (ELK centres a
+ *  row's boxes on it), each row left to right. */
+export function rowsOf(
+  nodes: Readonly<Record<string, FlowRect>>,
+  order: readonly string[],
+): string[][] {
+  const placed = order
+    .filter((id) => nodes[id] !== undefined)
+    .map((id) => {
+      const rect = nodes[id];
+      return { id, cy: rect.y + rect.height / 2, x: rect.x };
+    })
+    .sort((a, b) => a.cy - b.cy || a.x - b.x);
+  const rows: { cy: number; ids: { id: string; x: number }[] }[] = [];
+  for (const node of placed) {
+    const row = rows.at(-1);
+    if (row && Math.abs(row.cy - node.cy) <= 1) row.ids.push(node);
+    else rows.push({ cy: node.cy, ids: [node] });
+  }
+  return rows.map((row) =>
+    row.ids.sort((a, b) => a.x - b.x).map((node) => node.id),
+  );
+}
+
+function readLayout(
+  graph: FlowGraph,
+  prepared: Prepared,
+  laid: FlowElkNode,
+  engine: FlowLayout['engine'],
+  ms: number,
+): FlowLayout {
+  const known = new Set(graph.nodes.map((node) => node.id));
+  const groupIds = new Set((graph.groups ?? []).map((group) => group.id));
+  const nodes: Record<string, FlowRect> = {};
+  const groups: Record<string, FlowRect & { header: FlowRect }> = {};
+  const headers = new Map<string, FlowRect>();
+  const elkEdges: FlowElkEdge[] = [];
+  const rectOf = (node: FlowElkNode): FlowRect =>
+    snapRect({
+      x: node.x ?? 0,
+      y: node.y ?? 0,
+      width: node.width ?? 0,
+      height: node.height ?? 0,
+    });
+  const walk = (node: FlowElkNode) => {
+    if (known.has(node.id)) nodes[node.id] = rectOf(node);
+    else if (groupIds.has(node.id))
+      groups[node.id] = {
+        ...rectOf(node),
+        header: { x: 0, y: 0, width: 0, height: 0 },
+      };
+    else if (node.id.endsWith(':head')) headers.set(node.id, rectOf(node));
+    for (const edge of node.edges ?? []) elkEdges.push(edge);
+    for (const child of node.children ?? []) walk(child);
+  };
+  walk(laid);
+  for (const [id, group] of Object.entries(groups)) {
+    const header = headers.get(frameHeaderId(id));
+    if (header) group.header = header;
+  }
+  const drawn = new Map(
+    graph.edges
+      .filter((edge) => !edge.layoutOnly)
+      .map((edge) => [edge.id, edge]),
+  );
+  const edges: Record<string, { points: FlowPoint[]; label?: FlowRect }> = {};
+  for (const elkEdge of elkEdges) {
+    if (!drawn.has(elkEdge.id)) continue;
+    const points = cleanRoute(joinSections(elkEdge.sections ?? []));
+    const label = elkEdge.labels?.[0];
+    const route: { points: FlowPoint[]; label?: FlowRect } = { points };
+    if (label?.x !== undefined && label.y !== undefined)
+      route.label = snapRect({
+        x: label.x,
+        y: label.y,
+        width: label.width ?? 0,
+        height: label.height ?? 0,
+      });
+    edges[elkEdge.id] = route;
+  }
+  const missing = [...drawn.keys()].filter((id) => edges[id] === undefined);
+  if (missing.length > 0)
+    throw new Error(`ELK returned no route for ${missing.join(', ')}`);
+  const extents: FlowRect[] = [
+    ...Object.values(nodes),
+    ...Object.values(groups),
+  ];
+  for (const edge of Object.values(edges)) {
+    for (const point of edge.points)
+      extents.push({ x: point.x, y: point.y, width: 0, height: 0 });
+    if (edge.label) extents.push(edge.label);
+  }
+  const bounds = boundsOf(extents);
+  return {
+    signature: prepared.signature,
+    nodes,
+    groups,
+    edges,
+    bounds,
+    rows: rowsOf(
+      nodes,
+      graph.nodes.map((node) => node.id),
+    ),
+    engine,
+    ms,
+  };
+}
+
+function abortError(): Error {
+  const error = new Error('The flow layout was cancelled');
+  error.name = 'AbortError';
+  return error;
+}
+
+/**
+ * Lays out `graph` with ELK and answers where every box, frame, route and
+ * label goes. Deterministic: the same graph and options give the same
+ * layout. With `previous`, a graph that changed on screen is laid out again
+ * keeping each row's order, so nothing swaps sides with its neighbour.
+ *
+ * Should ELK fail or take longer than `timeoutMs`, the graph is laid out in
+ * one column instead (`engine: 'fallback-column'`): never no picture. A
+ * cancelled layout rejects with an `AbortError`.
+ */
+export async function layoutFlowGraph(
+  graph: FlowGraph,
+  options: LayoutFlowGraphOptions = {},
+): Promise<FlowLayout> {
+  const measure = options.measure ?? estimateFlowText;
+  const prepared = prepare(
+    graph,
+    measure,
+    options.edgeLabel ?? defaultEdgeLabel,
+  );
+  const started = performance.now();
+  if (options.signal?.aborted) throw abortError();
+  if (graph.nodes.length === 0)
+    return {
+      signature: prepared.signature,
+      nodes: {},
+      groups: {},
+      edges: {},
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      rows: [],
+      engine: 'main',
+      ms: 0,
+    };
+  const fallback = (error: unknown) => {
+    console.warn('Flow layout failed; showing the nodes in one column', error);
+    return layoutFallbackColumn(graph, {
+      signature: prepared.signature,
+      sizes: prepared.sizes,
+      labels: prepared.labels,
+      headers: prepared.headers,
+      ms: performance.now() - started,
+    });
+  };
+  let elk: FlowElk;
+  try {
+    elk = options.elk ?? (await (await import('./elk-client')).getFlowElk());
+  } catch (error) {
+    return fallback(error);
+  }
+  const json = toElkGraph(graph, prepared, options.previous);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    const answer = await Promise.race([
+      elk.layout(json),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new Error(
+                `ELK took longer than ${options.timeoutMs ?? 5_000} ms`,
+              ),
+            ),
+          options.timeoutMs ?? 5_000,
+        );
+      }),
+      new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(abortError());
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]);
+    return readLayout(
+      graph,
+      prepared,
+      answer.graph,
+      answer.engine,
+      performance.now() - started,
+    );
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') throw error;
+    return fallback(error);
+  } finally {
+    clearTimeout(timer);
+    if (onAbort) options.signal?.removeEventListener('abort', onAbort);
+  }
+}
diff --git a/packages/ui/src/components/flow/layout/sizes.test.ts b/packages/ui/src/components/flow/layout/sizes.test.ts
new file mode 100644
index 0000000000..b4705c18e2
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/sizes.test.ts
@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+
+import type { FlowEntryNode, FlowExitNode, FlowStepNode } from '../types';
+import {
+  FLOW_NODE_WIDTH,
+  flowEdgeLabelSize,
+  flowFrameHeaderSize,
+  flowNodeSize,
+  visibleRows,
+} from './sizes';
+
+const step = (extra: Partial<FlowStepNode> = {}): FlowStepNode => ({
+  id: 'a',
+  kind: 'step',
+  label: 'A',
+  ...extra,
+});
+
+describe('flowNodeSize', () => {
+  it('pins a step at 88, 108, 116 or 136 px by the rows it has', () => {
+    expect(flowNodeSize(step())).toEqual({
+      width: FLOW_NODE_WIDTH,
+      height: 88,
+    });
+    expect(flowNodeSize(step({ returns: null })).height).toBe(108);
+    expect(
+      flowNodeSize(step({ returns: { text: 'x', code: true } })).height,
+    ).toBe(108);
+    expect(
+      flowNodeSize(step({ chips: [{ id: 'c', label: 'Continues on error' }] }))
+        .height,
+    ).toBe(116);
+    expect(flowNodeSize(step({ unreachable: true })).height).toBe(116);
+    expect(
+      flowNodeSize(
+        step({
+          returns: null,
+          chips: [{ id: 'c', label: 'Continues on error' }],
+        }),
+      ).height,
+    ).toBe(136);
+  });
+
+  it('never sizes a step by its run, its problems or its words', () => {
+    expect(
+      flowNodeSize(step({ label: 'A much longer title than fits' })),
+    ).toEqual(flowNodeSize(step()));
+    expect(flowNodeSize(step({ conditional: true }))).toEqual(
+      flowNodeSize(step()),
+    );
+  });
+
+  it('sums Start from its sections', () => {
+    const entry: FlowEntryNode = {
+      id: '__start',
+      kind: 'entry',
+      triggers: [
+        { id: 's', label: 'Every day', note: 'Next Thu' },
+        { id: 'm', label: 'By hand' },
+      ],
+      inputs: [
+        { id: 'a', label: 'a' },
+        { id: 'b', label: 'b' },
+      ],
+    };
+    // 12 + 20 + (8 + 16 + 4 + 36 + 20) + (8 + 16 + 4 + 40) + 12 + 28
+    expect(flowNodeSize(entry).height).toBe(224);
+    // Five inputs show three and "+2 more": four row slots.
+    const many = {
+      ...entry,
+      inputs: ['a', 'b', 'c', 'd', 'e'].map((id) => ({ id, label: id })),
+    };
+    expect(flowNodeSize(many).height).toBe(224 + 40);
+    // No inputs: one line of words.
+    expect(flowNodeSize({ ...entry, inputs: [] }).height).toBe(224 - 20);
+    expect(
+      flowNodeSize({ ...entry, notice: { tone: 'warning', text: 'x' } }).height,
+    ).toBe(224 + 36);
+  });
+
+  it('sums End from its sections', () => {
+    const exit: FlowExitNode = {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'o', label: 'The output of Report' }],
+    };
+    // 12 + 20 + (8 + 16 + 4 + 20) + 12 + 28
+    expect(flowNodeSize(exit).height).toBe(120);
+    expect(flowNodeSize({ ...exit, shape: '{ a: number }' }).height).toBe(140);
+    const outcomes = ['ok', 'failed', 'stopped'].map((id) => ({
+      id,
+      label: id,
+    }));
+    expect(flowNodeSize({ ...exit, outcomes }).height).toBe(120 + 28 + 60);
+  });
+
+  it('sizes a gate to its condition, 160 to 288 px', () => {
+    const gate = (condition: string) =>
+      flowNodeSize(
+        { id: 'g', kind: 'gate', label: 'A', mode: 'only-if', condition },
+        (text) => text.length * 10,
+      );
+    expect(gate('short')).toEqual({ width: 160, height: 40 });
+    expect(gate('a condition of thirty chars..')).toEqual({
+      width: 288,
+      height: 40,
+    });
+    expect(gate('fifteen chars..').width).toBe(208);
+  });
+});
+
+describe('labels and frame headers', () => {
+  it('pads a label 8 px a side, on the 4-px grid', () => {
+    expect(flowEdgeLabelSize('Yes', () => 21)).toEqual({
+      width: 40,
+      height: 20,
+    });
+  });
+
+  it('keeps a frame header between 96 and 288 px', () => {
+    expect(flowFrameHeaderSize('x', () => 5).width).toBe(96);
+    expect(flowFrameHeaderSize('x', () => 1000).width).toBe(288);
+    expect(flowFrameHeaderSize('x', () => 150).width).toBe(180);
+  });
+});
+
+describe('visibleRows', () => {
+  it('folds what does not fit into "+n more", within the row budget', () => {
+    expect(visibleRows([1, 2, 3], 3)).toEqual({ shown: [1, 2, 3], more: 0 });
+    expect(visibleRows([1, 2, 3, 4, 5], 3)).toEqual({ shown: [1, 2], more: 3 });
+  });
+});
diff --git a/packages/ui/src/components/flow/layout/sizes.ts b/packages/ui/src/components/flow/layout/sizes.ts
new file mode 100644
index 0000000000..b762579530
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/sizes.ts
@@ -0,0 +1,257 @@
+import type {
+  FlowEntryNode,
+  FlowExitNode,
+  FlowGateNode,
+  FlowNode,
+  FlowRow,
+  FlowStepNode,
+} from '../types';
+
+/**
+ * Every box's size, as a pure function of the graph's data.
+ *
+ * The layout reserves exactly these boxes and the renderer draws exactly
+ * these boxes (a browser test measures each one), so a box never grows into
+ * an edge. Nothing a canvas shows on top of a layout — a run's state, a
+ * problem count, a highlight — changes a size, so none of it can move a box.
+ * Every number sits on the 4-px grid.
+ */
+
+export const FLOW_NODE_WIDTH = 288;
+
+/** Pieces every box is built from. */
+export const FLOW_BOX = {
+  padding: 12,
+  titleRow: 20,
+  typeRow: 16,
+  returnsRow: 20,
+  chipsRow: 28,
+  strip: 28,
+  sectionGap: 8,
+  heading: 16,
+  headingGap: 4,
+  row: 20,
+  note: 16,
+  shape: 20,
+  notice: 28,
+} as const;
+
+export const FLOW_GATE = {
+  height: 40,
+  minWidth: 160,
+  maxWidth: FLOW_NODE_WIDTH,
+  /** Padding, icon and gap around the condition, plus 8 px of slack. */
+  chrome: 56,
+} as const;
+
+/** How many rows a Start or End section shows before "+n more". */
+export const FLOW_SECTION_ROWS = {
+  triggers: 3,
+  inputs: 4,
+  outputs: 4,
+  outcomes: 4,
+} as const;
+
+/** Text the layout measures: the font of the gate's condition, a branch
+ *  label and a frame header. */
+export const FLOW_FONTS = {
+  condition: '400 12px Inter',
+  conditionCode:
+    '400 12px ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+  label: '500 12px Inter',
+} as const;
+
+export type FlowFont = (typeof FLOW_FONTS)[keyof typeof FLOW_FONTS];
+
+/** Measures a line of text in a font; returns its width in px. */
+export type FlowTextMeasure = (text: string, font: FlowFont) => number;
+
+const ceil4 = (value: number) => Math.ceil(value / 4) * 4;
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value));
+
+/**
+ * A width estimate for where nothing can measure text (a server, a test
+ * without a canvas): Inter at 12 px averages under 7 px a character, a
+ * monospace face 7.25 px. It errs wide, so a box is never too narrow.
+ */
+export const estimateFlowText: FlowTextMeasure = (text, font) =>
+  text.length * (font === FLOW_FONTS.conditionCode ? 7.25 : 7);
+
+let measureContext: OffscreenCanvasRenderingContext2D | null | undefined;
+const measured = new Map<string, number>();
+
+/**
+ * Measures with an offscreen canvas where there is one (every current
+ * browser, and a worker), else estimates. Call {@link loadFlowFonts} first:
+ * measured before Inter has loaded, the fallback face's widths would size
+ * the boxes.
+ */
+export const measureFlowText: FlowTextMeasure = (text, font) => {
+  if (measureContext === undefined) {
+    measureContext =
+      typeof OffscreenCanvas === 'undefined'
+        ? null
+        : new OffscreenCanvas(1, 1).getContext('2d');
+  }
+  if (measureContext === null) return estimateFlowText(text, font);
+  const key = `${font}\u0000${text}`;
+  const cached = measured.get(key);
+  if (cached !== undefined) return cached;
+  measureContext.font = font;
+  const width = measureContext.measureText(text).width;
+  measured.set(key, width);
+  return width;
+};
+
+/**
+ * Waits (at most `timeout` ms) for the faces the layout measures, so a
+ * label is measured in Inter rather than in the face standing in for it.
+ * A font that never arrives only costs the wait: the layout then measures
+ * what the page actually shows.
+ */
+export async function loadFlowFonts(timeout = 1_500): Promise<void> {
+  if (typeof document === 'undefined' || document.fonts === undefined) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      Promise.all([
+        document.fonts.load(FLOW_FONTS.condition),
+        document.fonts.load(FLOW_FONTS.label),
+      ]),
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, timeout);
+      }),
+    ]);
+  } catch (error) {
+    console.warn(
+      'Flow layout could not load its fonts; measuring as shown',
+      error,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function rowsHeight(rows: readonly FlowRow[], max: number): number {
+  const shown = rows.length > max ? rows.slice(0, max - 1) : rows;
+  const more = rows.length > max ? FLOW_BOX.row : 0;
+  return (
+    shown.reduce(
+      (sum, row) => sum + FLOW_BOX.row + (row.note ? FLOW_BOX.note : 0),
+      0,
+    ) + more
+  );
+}
+
+/** The rows a section shows and how many it folds into "+n more". */
+export function visibleRows<T>(
+  rows: readonly T[],
+  max: number,
+): { shown: readonly T[]; more: number } {
+  if (rows.length <= max) return { shown: rows, more: 0 };
+  return { shown: rows.slice(0, max - 1), more: rows.length - (max - 1) };
+}
+
+/** One section of Start or End: a heading, then its rows (an empty
+ *  section shows one line of words). */
+function sectionHeight(rows: readonly FlowRow[], max: number): number {
+  return (
+    FLOW_BOX.sectionGap +
+    FLOW_BOX.heading +
+    FLOW_BOX.headingGap +
+    (rows.length === 0 ? FLOW_BOX.row : rowsHeight(rows, max))
+  );
+}
+
+const frame = (inner: number) =>
+  FLOW_BOX.padding +
+  FLOW_BOX.titleRow +
+  inner +
+  FLOW_BOX.padding +
+  FLOW_BOX.strip;
+
+function stepHeight(node: FlowStepNode): number {
+  return frame(
+    FLOW_BOX.typeRow +
+      (node.returns !== undefined ? FLOW_BOX.returnsRow : 0) +
+      ((node.chips?.length ?? 0) > 0 || node.unreachable === true
+        ? FLOW_BOX.chipsRow
+        : 0),
+  );
+}
+
+function entryHeight(node: FlowEntryNode): number {
+  return frame(
+    (node.triggers.length > 0
+      ? sectionHeight(node.triggers, FLOW_SECTION_ROWS.triggers)
+      : 0) +
+      sectionHeight(node.inputs, FLOW_SECTION_ROWS.inputs) +
+      (node.notice ? FLOW_BOX.sectionGap + FLOW_BOX.notice : 0),
+  );
+}
+
+function exitHeight(node: FlowExitNode): number {
+  return frame(
+    sectionHeight(node.outputs, FLOW_SECTION_ROWS.outputs) +
+      (node.shape ? FLOW_BOX.shape : 0) +
+      ((node.outcomes?.length ?? 0) > 0
+        ? sectionHeight(node.outcomes ?? [], FLOW_SECTION_ROWS.outcomes)
+        : 0) +
+      (node.notice ? FLOW_BOX.sectionGap + FLOW_BOX.notice : 0),
+  );
+}
+
+/** The gate pill's width: the condition plus its chrome, 160 to 288 px. */
+export function flowGateWidth(
+  node: FlowGateNode,
+  measure: FlowTextMeasure = estimateFlowText,
+): number {
+  const font = node.conditionIsCode
+    ? FLOW_FONTS.conditionCode
+    : FLOW_FONTS.condition;
+  return clamp(
+    ceil4(measure(node.condition, font) + FLOW_GATE.chrome),
+    FLOW_GATE.minWidth,
+    FLOW_GATE.maxWidth,
+  );
+}
+
+/** The size the layout reserves and the renderer draws for `node`. */
+export function flowNodeSize(
+  node: FlowNode,
+  measure: FlowTextMeasure = estimateFlowText,
+): { width: number; height: number } {
+  if (node.kind === 'gate')
+    return { width: flowGateWidth(node, measure), height: FLOW_GATE.height };
+  const height =
+    node.kind === 'step'
+      ? stepHeight(node)
+      : node.kind === 'entry'
+        ? entryHeight(node)
+        : exitHeight(node);
+  return { width: FLOW_NODE_WIDTH, height };
+}
+
+/** A "Yes" / "No" pill: the word plus 8 px each side, 20 px high. */
+export function flowEdgeLabelSize(
+  text: string,
+  measure: FlowTextMeasure = estimateFlowText,
+): { width: number; height: number } {
+  return { width: ceil4(measure(text, FLOW_FONTS.label) + 16), height: 20 };
+}
+
+/** A frame header: its icon, gap and words, 96 to 288 px wide. */
+export function flowFrameHeaderSize(
+  text: string,
+  measure: FlowTextMeasure = estimateFlowText,
+): { width: number; height: number } {
+  return {
+    width: clamp(
+      ceil4(measure(text, FLOW_FONTS.label) + 28),
+      96,
+      FLOW_NODE_WIDTH,
+    ),
+    height: 24,
+  };
+}
diff --git a/packages/ui/src/components/flow/layout/use-flow-layout.ts b/packages/ui/src/components/flow/layout/use-flow-layout.ts
new file mode 100644
index 0000000000..524eac9721
--- /dev/null
+++ b/packages/ui/src/components/flow/layout/use-flow-layout.ts
@@ -0,0 +1,152 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import type { FlowEdge, FlowGraph, FlowLayout } from '../types';
+import { retainFlowElk } from './elk-client';
+import { flowLayoutCache } from './layout-cache';
+import {
+  defaultEdgeLabel,
+  flowLayoutSignature,
+  layoutFlowGraph,
+  type FlowElk,
+} from './layout-flow-graph';
+import { estimateFlowText, loadFlowFonts, measureFlowText } from './sizes';
+
+export type FlowLayoutStatus = 'pending' | 'ready' | 'failed';
+
+export interface UseFlowLayoutOptions {
+  /**
+   * What the graph is a picture of — a document and the version on screen.
+   * The same key with a changed graph lays it out again keeping every row's
+   * order (a live relayout); a new key is another picture, laid out afresh.
+   */
+  layoutKey: string;
+  /** The words on an edge ("Yes", "No"). */
+  edgeLabel?: (edge: FlowEdge) => string | undefined;
+  /** Tests: the engine to use instead of the shared worker. */
+  elk?: FlowElk;
+}
+
+export interface UseFlowLayoutResult {
+  /** The layout on screen; `null` until the first one resolves. */
+  layout: FlowLayout | null;
+  /** The layout before it, while the same picture changed — what a
+   *  transition moves from. */
+  previous: FlowLayout | null;
+  /** `failed` when the engine could not run and the graph stands in one
+   *  column. */
+  status: FlowLayoutStatus;
+}
+
+let fontsReady: Promise<void> | null = null;
+const fonts = () => (fontsReady ??= loadFlowFonts());
+
+/**
+ * Lays out `graph` and keeps the layout current as the graph changes.
+ *
+ * Only a change to the graph's shape — its nodes, edges, frames and their
+ * sizes — lays it out again, so a node's new title or a selection never
+ * moves anything. The latest graph wins: a layout still running when
+ * another change arrives is cancelled. A fresh layout this session already
+ * computed comes from the cache at once.
+ */
+export function useFlowLayout(
+  graph: FlowGraph,
+  { layoutKey, edgeLabel = defaultEdgeLabel, elk }: UseFlowLayoutOptions,
+): UseFlowLayoutResult {
+  const [state, setState] = useState<{
+    key: string | null;
+    layout: FlowLayout | null;
+    previous: FlowLayout | null;
+  }>({ key: null, layout: null, previous: null });
+  const [fontsLoaded, setFontsLoaded] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    void fonts().then(() => {
+      if (live) setFontsLoaded(true);
+    });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  useEffect(() => retainFlowElk(), []);
+
+  // Nothing is laid out before the fonts are in (a label measured in the
+  // face standing in for Inter would size the boxes); the estimate only
+  // stands in for the signature until then.
+  const signature = useMemo(
+    () =>
+      flowLayoutSignature(graph, {
+        measure: fontsLoaded ? measureFlowText : estimateFlowText,
+        edgeLabel,
+      }),
+    [graph, edgeLabel, fontsLoaded],
+  );
+
+  // The newest inputs, read when a layout starts without widening the
+  // effect to the graph's identity (a new object every render).
+  const latest = useRef({ graph, edgeLabel, elk });
+  latest.current = { graph, edgeLabel, elk };
+  const shown = useRef(state);
+  shown.current = state;
+
+  useEffect(() => {
+    if (!fontsLoaded) return undefined;
+    const before = shown.current;
+    const samePicture = before.key === layoutKey && before.layout !== null;
+    if (samePicture && before.layout?.signature === signature) return undefined;
+    if (!samePicture) {
+      const cached = flowLayoutCache.get(signature);
+      if (cached) {
+        setState({ key: layoutKey, layout: cached, previous: null });
+        return undefined;
+      }
+    }
+    const controller = new AbortController();
+    const { graph: current, edgeLabel: label, elk: engine } = latest.current;
+    layoutFlowGraph(current, {
+      previous: samePicture ? before.layout : null,
+      measure: measureFlowText,
+      edgeLabel: label,
+      elk: engine,
+      signal: controller.signal,
+    }).then(
+      (layout) => {
+        if (controller.signal.aborted) return;
+        if (!samePicture) flowLayoutCache.set(layout);
+        setState({
+          key: layoutKey,
+          layout,
+          previous: samePicture ? before.layout : null,
+        });
+      },
+      (error: unknown) => {
+        if (error instanceof Error && error.name === 'AbortError') return;
+        console.error('Flow layout failed', error);
+      },
+    );
+    return () => controller.abort();
+  }, [signature, layoutKey, fontsLoaded]);
+
+  // A picture this session already laid out shows at once, without a
+  // pending frame between two versions.
+  const current =
+    state.key === layoutKey
+      ? state.layout
+      : fontsLoaded
+        ? (flowLayoutCache.peek(signature) ?? null)
+        : null;
+  return {
+    layout: current,
+    previous: state.key === layoutKey ? state.previous : null,
+    status:
+      current === null
+        ? 'pending'
+        : current.engine === 'fallback-column'
+          ? 'failed'
+          : 'ready',
+  };
+}
diff --git a/packages/ui/src/components/flow/testing/flow-fixtures.ts b/packages/ui/src/components/flow/testing/flow-fixtures.ts
new file mode 100644
index 0000000000..b1499f65e9
--- /dev/null
+++ b/packages/ui/src/components/flow/testing/flow-fixtures.ts
@@ -0,0 +1,719 @@
+import {
+  Bot,
+  Braces,
+  CircleCheck,
+  CircleX,
+  Clock,
+  CircleDot,
+  GitPullRequest,
+  Hand,
+  Inbox,
+  Mail,
+  Send,
+  Sparkles,
+  Square,
+} from 'lucide-react';
+
+import type {
+  FlowEdge,
+  FlowEdgeKind,
+  FlowEntryNode,
+  FlowExitNode,
+  FlowGraph,
+  FlowGroup,
+  FlowNode,
+  FlowStepNode,
+} from '../types';
+
+/**
+ * Graphs the flow tests, demos and stories share — each one shaped exactly
+ * as a host's adapter emits it: Start first, each gate immediately before
+ * the step it guards, End last, edges sorted by target then source.
+ */
+
+const edge = (
+  source: string,
+  target: string,
+  kind: FlowEdgeKind,
+  extra: Partial<FlowEdge> = {},
+): FlowEdge => ({ id: `${source}>${target}`, source, target, kind, ...extra });
+
+/** Edges in the order an adapter emits them: by target, then by source,
+ *  in reading order. */
+function sorted(graph: FlowGraph): FlowGraph {
+  const order = new Map(graph.nodes.map((node, index) => [node.id, index]));
+  return {
+    ...graph,
+    edges: [...graph.edges].sort(
+      (a, b) =>
+        (order.get(a.target) ?? 0) - (order.get(b.target) ?? 0) ||
+        (order.get(a.source) ?? 0) - (order.get(b.source) ?? 0),
+    ),
+  };
+}
+
+const OUTCOMES: FlowExitNode['outcomes'] = [
+  {
+    id: 'succeeded',
+    icon: CircleCheck,
+    label: 'Succeeded',
+    detail: 'returns the output',
+  },
+  {
+    id: 'failed',
+    icon: CircleX,
+    label: 'Failed',
+    detail: 'when one of its nodes fails',
+  },
+  {
+    id: 'stopped',
+    icon: Square,
+    label: 'Stopped',
+    detail: 'when someone stops it',
+  },
+];
+
+const start = (
+  inputs: FlowEntryNode['inputs'],
+  triggers: FlowEntryNode['triggers'] = [
+    { id: 'manual', icon: Hand, label: 'By hand, the API or MCP' },
+  ],
+): FlowEntryNode => ({ id: '__start', kind: 'entry', triggers, inputs });
+
+const end = (
+  outputs: FlowExitNode['outputs'],
+  extra: Partial<FlowExitNode> = {},
+): FlowExitNode => ({
+  id: '__end',
+  kind: 'exit',
+  outputs,
+  outcomes: OUTCOMES,
+  ...extra,
+});
+
+const step = (
+  id: string,
+  label: string,
+  extra: Partial<FlowStepNode> = {},
+): FlowStepNode => ({ id, kind: 'step', label, icon: Braces, ...extra });
+
+/** Triage GitHub issues: the long `open_issues → report` edge must run
+ *  round `score`'s frame, never through it. */
+export function triageFlowGraph(): FlowGraph {
+  return sorted({
+    nodes: [
+      start(
+        [
+          {
+            id: 'owner',
+            label: 'owner',
+            detail: 'text · required',
+            code: true,
+          },
+          { id: 'repo', label: 'repo', detail: 'text · required', code: true },
+          { id: 'limit', label: 'limit', detail: 'a number', code: true },
+          {
+            id: 'trigger',
+            label: 'trigger',
+            detail: 'text · from the trigger',
+            code: true,
+          },
+          {
+            id: 'firedAt',
+            label: 'firedAt',
+            detail: 'a number · from the trigger',
+            code: true,
+          },
+        ],
+        [
+          {
+            id: 'schedule',
+            icon: Clock,
+            label: 'Every day at 07:00 · UTC',
+            note: 'Next Thu 9 Oct, 07:00',
+          },
+          { id: 'manual', icon: Hand, label: 'By hand, the API or MCP' },
+        ],
+      ),
+      step('issues', 'Issues', {
+        icon: CircleDot,
+        typeLabel: 'GitHub · List issues',
+        reads: [{ id: 'input', label: 'run input (owner, repo, limit)' }],
+        returns: { text: '{ issues: object[] }', code: true },
+      }),
+      step('open_issues', 'Open issues', {
+        typeLabel: 'Transform',
+        reads: [
+          { id: 'issues', label: 'Issues' },
+          { id: 'input', label: 'run input (limit)' },
+        ],
+        returns: { text: '{ count: number; issues: object[] }', code: true },
+      }),
+      step('score', 'Score', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-haiku-4-5',
+        reads: [
+          { id: 'open_issues', label: 'Open issues' },
+          { id: 'item', label: 'each item' },
+        ],
+        returns: {
+          text: '{ actionable: boolean; priority: string; reason: string }[]',
+          code: true,
+        },
+        description: 'Runs once for each item of issues of Open issues.',
+      }),
+      step('report', 'Report', {
+        typeLabel: 'Transform',
+        reads: [
+          { id: 'open_issues', label: 'Open issues' },
+          { id: 'score', label: 'Score' },
+        ],
+        returns: null,
+      }),
+      end([{ id: 'report', label: 'The output of Report' }], {
+        shape: '{ reviewed: number; actionable: number; issues: object[] }',
+      }),
+    ],
+    edges: [
+      edge('__start', 'issues', 'entry'),
+      edge('issues', 'open_issues', 'data', { detail: 'Carries .issues' }),
+      edge('open_issues', 'score', 'data', { detail: 'Carries .issues' }),
+      edge('open_issues', 'report', 'data', { detail: 'Carries .issues' }),
+      edge('score', 'report', 'data'),
+      edge('report', '__end', 'exit'),
+    ],
+    groups: [
+      {
+        id: 'each:score',
+        kind: 'each',
+        label: 'For each item of issues of Open issues',
+        members: ['score'],
+      },
+    ],
+  });
+}
+
+/** Review pull requests: three consecutive nodes each iterate the same
+ *  list, one frame each. */
+export function reviewPullRequestsFlowGraph(): FlowGraph {
+  const each = (id: string): FlowGroup => ({
+    id: `each:${id}`,
+    kind: 'each',
+    label: 'For each item of pulls of Open pulls',
+    members: [id],
+  });
+  return sorted({
+    nodes: [
+      start([
+        { id: 'owner', label: 'owner', detail: 'text · required', code: true },
+        { id: 'repo', label: 'repo', detail: 'text · required', code: true },
+      ]),
+      step('pulls', 'Pulls', {
+        icon: GitPullRequest,
+        typeLabel: 'GitHub · List pull requests',
+        reads: [{ id: 'input', label: 'run input (owner, repo)' }],
+      }),
+      step('open_pulls', 'Open pulls', {
+        typeLabel: 'Transform',
+        reads: [{ id: 'pulls', label: 'Pulls' }],
+      }),
+      step('diff', 'Diff', {
+        icon: GitPullRequest,
+        typeLabel: 'GitHub · Get pull request diff',
+        reads: [{ id: 'open_pulls', label: 'Open pulls' }],
+      }),
+      step('review', 'Review', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-sonnet-4-5',
+        reads: [
+          { id: 'open_pulls', label: 'Open pulls' },
+          { id: 'diff', label: 'Diff' },
+        ],
+      }),
+      step('post', 'Post', {
+        icon: GitPullRequest,
+        typeLabel: 'GitHub · Create pull request review',
+        reads: [
+          { id: 'open_pulls', label: 'Open pulls' },
+          { id: 'review', label: 'Review' },
+        ],
+      }),
+      end([
+        {
+          id: 'reviewed',
+          label: 'reviewed',
+          detail: 'from Open pulls',
+          code: true,
+        },
+        { id: 'reviews', label: 'reviews', detail: 'from Review', code: true },
+      ]),
+    ],
+    edges: [
+      edge('__start', 'pulls', 'entry'),
+      edge('pulls', 'open_pulls', 'data'),
+      edge('open_pulls', 'diff', 'data'),
+      edge('open_pulls', 'review', 'data'),
+      edge('diff', 'review', 'data'),
+      edge('open_pulls', 'post', 'data'),
+      edge('review', 'post', 'data'),
+      edge('open_pulls', '__end', 'exit'),
+      edge('review', '__end', 'exit'),
+      edge('post', '__end', 'completion'),
+    ],
+    groups: [each('diff'), each('review'), each('post')],
+  });
+}
+
+/** Triage inbox: an only-if gate in front of Triage, and a node that lets
+ *  the run go on when it fails. */
+export function triageInboxFlowGraph(): FlowGraph {
+  const each = (id: string): FlowGroup => ({
+    id: `each:${id}`,
+    kind: 'each',
+    label: 'For each item of conversations of Due',
+    members: [id],
+  });
+  return sorted({
+    nodes: [
+      start([]),
+      step('inbox', 'Inbox', {
+        icon: Inbox,
+        typeLabel: 'Conversations · List untriaged conversations',
+      }),
+      {
+        id: '__gate:triage',
+        kind: 'gate',
+        label: 'Triage',
+        mode: 'only-if',
+        condition: 'the number of conversations of Inbox is greater than 0',
+        decisionKey: 'when:triage',
+      },
+      step('triage', 'Triage', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-haiku-4-5',
+        reads: [{ id: 'inbox', label: 'Inbox' }],
+        conditional: true,
+      }),
+      step('record', 'Record', {
+        icon: Inbox,
+        typeLabel: 'Conversations · Record triage',
+        reads: [{ id: 'triage', label: 'Triage' }],
+        conditional: true,
+      }),
+      step('due', 'Due', {
+        typeLabel: 'Transform',
+        reads: [
+          { id: 'inbox', label: 'Inbox' },
+          { id: 'triage', label: 'Triage' },
+        ],
+        conditional: true,
+      }),
+      step('draft', 'Draft', {
+        icon: Bot,
+        typeLabel: 'Language model · claude-sonnet-4-5',
+        reads: [{ id: 'due', label: 'Due' }],
+        conditional: true,
+      }),
+      step('propose', 'Propose', {
+        icon: Mail,
+        typeLabel: 'Conversations · Draft reply',
+        reads: [
+          { id: 'due', label: 'Due' },
+          { id: 'draft', label: 'Draft' },
+        ],
+        chips: [{ id: 'onError', label: 'Continues on error', tone: 'error' }],
+        description: 'If it fails, the run goes on without it.',
+        conditional: true,
+      }),
+      end([
+        { id: 'read', label: 'read', detail: 'from Inbox', code: true },
+        {
+          id: 'summary',
+          label: 'summary',
+          detail: 'from Triage · may be empty',
+          code: true,
+        },
+        {
+          id: 'recorded',
+          label: 'recorded',
+          detail: 'from Record · may be empty',
+          code: true,
+        },
+        {
+          id: 'needsReply',
+          label: 'needsReply',
+          detail: 'from Due',
+          code: true,
+        },
+        { id: 'drafted', label: 'drafted', detail: 'from Propose', code: true },
+      ]),
+    ],
+    edges: [
+      edge('__start', 'inbox', 'entry'),
+      edge('inbox', '__gate:triage', 'order'),
+      edge('inbox', 'triage', 'data'),
+      edge('__gate:triage', 'triage', 'gate'),
+      edge('triage', 'record', 'data'),
+      edge('inbox', 'due', 'data'),
+      edge('triage', 'due', 'data'),
+      edge('due', 'draft', 'data'),
+      edge('due', 'propose', 'data'),
+      edge('draft', 'propose', 'data'),
+      edge('inbox', '__end', 'exit'),
+      edge('triage', '__end', 'exit'),
+      edge('record', '__end', 'exit'),
+      edge('due', '__end', 'exit'),
+      edge('propose', '__end', 'exit'),
+    ],
+    groups: [each('draft'), each('propose')],
+  });
+}
+
+/**
+ * A when/elseOf pair, an else-if behind it, a node that goes on after a
+ * failure and one that repeats: Yes left of No, the pair in one row.
+ */
+export function branchFlowGraph(): FlowGraph {
+  return sorted({
+    nodes: [
+      start([
+        {
+          id: 'ticket',
+          label: 'ticket',
+          detail: 'an object · required',
+          code: true,
+        },
+      ]),
+      step('fetch', 'Fetch', {
+        icon: Send,
+        typeLabel: 'HTTP · Get',
+        reads: [{ id: 'input', label: 'run input (ticket)' }],
+      }),
+      step('classify', 'Classify', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-haiku-4-5',
+        reads: [{ id: 'fetch', label: 'Fetch' }],
+      }),
+      {
+        id: '__gate:urgent',
+        kind: 'gate',
+        label: 'Urgent',
+        mode: 'if-else',
+        condition: 'urgent of Classify is true',
+        decisionKey: 'when:urgent',
+      },
+      step('urgent', 'Urgent', {
+        icon: Bot,
+        typeLabel: 'Agent',
+        reads: [{ id: 'fetch', label: 'Fetch' }],
+        conditional: true,
+      }),
+      {
+        id: '__gate:normal',
+        kind: 'gate',
+        label: 'Normal',
+        mode: 'if-else',
+        condition: 'nodes.classify.output.priority === "normal"',
+        conditionIsCode: true,
+        decisionKey: 'when:normal',
+      },
+      step('normal', 'Normal', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-haiku-4-5',
+        reads: [{ id: 'fetch', label: 'Fetch' }],
+        conditional: true,
+      }),
+      step('low', 'Low', {
+        icon: Sparkles,
+        typeLabel: 'Language model · claude-haiku-4-5',
+        reads: [{ id: 'fetch', label: 'Fetch' }],
+        conditional: true,
+      }),
+      step('enrich', 'Enrich', {
+        icon: Send,
+        typeLabel: 'HTTP · Get',
+        reads: [{ id: 'fetch', label: 'Fetch' }],
+      }),
+      step('merge', 'Merge', {
+        typeLabel: 'Transform',
+        reads: [
+          { id: 'urgent', label: 'Urgent' },
+          { id: 'normal', label: 'Normal' },
+          { id: 'low', label: 'Low' },
+          { id: 'enrich', label: 'Enrich' },
+        ],
+      }),
+      step('notify', 'Notify', {
+        icon: Mail,
+        typeLabel: 'Email · Send',
+        reads: [{ id: 'merge', label: 'Merge' }],
+        chips: [{ id: 'onError', label: 'Continues on error', tone: 'error' }],
+      }),
+      step('poll', 'Poll', {
+        icon: Send,
+        typeLabel: 'HTTP · Get status',
+        reads: [{ id: 'merge', label: 'Merge' }],
+      }),
+      end([{ id: 'merge', label: 'The output of Merge' }]),
+    ],
+    edges: [
+      edge('__start', 'fetch', 'entry'),
+      edge('fetch', 'classify', 'data'),
+      edge('classify', '__gate:urgent', 'order'),
+      edge('__gate:urgent', 'urgent', 'branch-yes'),
+      edge('fetch', 'urgent', 'data'),
+      edge('__gate:urgent', '__gate:normal', 'branch-no'),
+      edge('classify', '__gate:normal', 'order'),
+      edge('__gate:normal', 'normal', 'branch-yes'),
+      edge('fetch', 'normal', 'data'),
+      edge('__gate:normal', 'low', 'branch-no'),
+      edge('fetch', 'low', 'data'),
+      edge('fetch', 'enrich', 'data'),
+      edge('urgent', 'merge', 'data'),
+      edge('normal', 'merge', 'data'),
+      edge('low', 'merge', 'data'),
+      edge('enrich', 'merge', 'data'),
+      edge('merge', 'notify', 'data'),
+      edge('merge', 'poll', 'data'),
+      edge('merge', '__end', 'exit'),
+      edge('notify', '__end', 'completion'),
+      edge('poll', '__end', 'completion'),
+    ],
+    groups: [
+      {
+        id: 'repeat:poll',
+        kind: 'repeat',
+        label: 'Repeats until done is true, at most 5×',
+        members: ['poll'],
+      },
+    ],
+  });
+}
+
+/** A gate whose condition reads only the run input: it hangs from what its
+ *  node reads through layout-only edges, right above the node. */
+export function inputGateFlowGraph(): FlowGraph {
+  return sorted({
+    nodes: [
+      start([
+        { id: 'notify', label: 'notify', detail: 'true or false', code: true },
+      ]),
+      step('load', 'Load', {
+        icon: Send,
+        typeLabel: 'HTTP · Get',
+      }),
+      step('side', 'Side', {
+        typeLabel: 'Transform',
+        reads: [{ id: 'load', label: 'Load' }],
+      }),
+      {
+        id: '__gate:notify',
+        kind: 'gate',
+        label: 'Notify',
+        mode: 'only-if',
+        condition: 'notify of the run input is true',
+        decisionKey: 'when:notify',
+      },
+      step('notify', 'Notify', {
+        icon: Mail,
+        typeLabel: 'Email · Send',
+        reads: [{ id: 'load', label: 'Load' }],
+        conditional: true,
+      }),
+      end([]),
+    ],
+    edges: [
+      edge('__start', 'load', 'entry'),
+      edge('load', 'side', 'data'),
+      edge('load', '__gate:notify', 'order', { layoutOnly: true }),
+      edge('__gate:notify', 'notify', 'gate'),
+      edge('load', 'notify', 'data'),
+      edge('side', '__end', 'completion'),
+      edge('notify', '__end', 'completion'),
+    ],
+  });
+}
+
+/** A graph whose nodes read each other in a circle (an invalid document):
+ *  it still lays out, with the back edge leaving at the bottom. */
+export function cyclicFlowGraph(): FlowGraph {
+  return sorted({
+    nodes: [
+      start([]),
+      step('a', 'A', { typeLabel: 'Transform' }),
+      step('b', 'B', { typeLabel: 'Transform' }),
+      step('c', 'C', { typeLabel: 'Transform' }),
+      end([]),
+    ],
+    edges: [
+      edge('__start', 'a', 'entry'),
+      edge('c', 'a', 'data'),
+      edge('a', 'b', 'data'),
+      edge('b', 'c', 'data'),
+      edge('c', '__end', 'completion'),
+    ],
+  });
+}
+
+/** A document-like description the synthetic builder reads. */
+export interface SyntheticDocNode {
+  id: string;
+  /** Nodes whose output it reads. */
+  reads: readonly string[];
+  /** Nodes its condition mentions; `[]` = a condition on the input. */
+  when?: readonly string[];
+  elseOf?: string;
+  forEach?: boolean;
+  repeat?: boolean;
+  onErrorContinue?: boolean;
+}
+
+/**
+ * The graph a host's adapter emits for `doc`, by the adapter's rules: a
+ * gate before each conditional node, Yes/No for when/elseOf pairs (an
+ * else-if chain hangs from the previous gate's No), Start into every root,
+ * the read nodes into End and every other sink as a completion, one frame
+ * per iterating node.
+ */
+export function flowGraphFromDoc(
+  doc: readonly SyntheticDocNode[],
+  outputs: readonly string[],
+): FlowGraph {
+  const ids = new Set(doc.map((node) => node.id));
+  const byId = new Map(doc.map((node) => [node.id, node]));
+  const partnerOf = new Map<string, string>();
+  for (const node of doc)
+    if (node.elseOf && byId.get(node.elseOf)?.when)
+      partnerOf.set(node.elseOf, node.id);
+  const nodes: FlowNode[] = [start([])];
+  const edges: FlowEdge[] = [];
+  const gateOf = (id: string) => `__gate:${id}`;
+  for (const node of doc) {
+    if (node.when) {
+      nodes.push({
+        id: gateOf(node.id),
+        kind: 'gate',
+        label: node.id,
+        mode: partnerOf.has(node.id) ? 'if-else' : 'only-if',
+        condition: `${node.id} is ready`,
+        decisionKey: `when:${node.id}`,
+      });
+    }
+    nodes.push(
+      step(node.id, node.id, {
+        typeLabel: 'Transform',
+        reads: node.reads.map((id) => ({ id, label: id })),
+        ...(node.onErrorContinue
+          ? {
+              chips: [
+                {
+                  id: 'onError',
+                  label: 'Continues on error',
+                  tone: 'error' as const,
+                },
+              ],
+            }
+          : {}),
+      }),
+    );
+  }
+  nodes.push(end(outputs.map((id) => ({ id, label: id }))));
+  const add = (
+    source: string,
+    target: string,
+    kind: FlowEdgeKind,
+    layoutOnly = false,
+  ) => {
+    if (edges.some((e) => e.source === source && e.target === target)) return;
+    edges.push(edge(source, target, kind, layoutOnly ? { layoutOnly } : {}));
+  };
+  for (const node of doc) {
+    const reads = node.reads.filter((id) => ids.has(id) && id !== node.id);
+    for (const source of reads) add(source, node.id, 'data');
+    if (node.when) {
+      const gate = gateOf(node.id);
+      const sources = node.when.filter((id) => ids.has(id) && id !== node.id);
+      if (sources.length > 0)
+        for (const source of sources) add(source, gate, 'order');
+      else if (reads.length > 0)
+        for (const source of reads) add(source, gate, 'order', true);
+      const partner = partnerOf.get(node.id);
+      add(gate, node.id, partner ? 'branch-yes' : 'gate');
+      if (partner) {
+        const partnerNode = byId.get(partner);
+        add(gate, partnerNode?.when ? gateOf(partner) : partner, 'branch-no');
+      }
+    }
+    if (node.elseOf && ids.has(node.elseOf) && !byId.get(node.elseOf)?.when)
+      add(node.elseOf, node.id, 'order');
+  }
+  const flowIds = nodes.map((node) => node.id);
+  for (const id of flowIds) {
+    if (id === '__start' || id === '__end') continue;
+    if (!edges.some((e) => e.target === id)) add('__start', id, 'entry');
+  }
+  for (const id of outputs) if (ids.has(id)) add(id, '__end', 'exit');
+  for (const node of doc) {
+    if (!edges.some((e) => e.source === node.id && !e.layoutOnly))
+      add(node.id, '__end', 'completion');
+  }
+  const order = new Map(flowIds.map((id, index) => [id, index]));
+  edges.sort(
+    (a, b) =>
+      (order.get(a.target) ?? 0) - (order.get(b.target) ?? 0) ||
+      (order.get(a.source) ?? 0) - (order.get(b.source) ?? 0),
+  );
+  const groups: FlowGroup[] = doc
+    .filter((node) => node.forEach || node.repeat)
+    .map((node) => ({
+      id: `${node.forEach ? 'each' : 'repeat'}:${node.id}`,
+      kind: node.forEach ? 'each' : 'repeat',
+      label: node.forEach ? 'For each item of its list' : 'Repeats until done',
+      members: [node.id],
+    }));
+  return { nodes, edges, groups };
+}
+
+/**
+ * A 40-node document with conditions, if/else pairs and iterating nodes,
+ * generated from a fixed seed: the size the performance budget is held at.
+ */
+export function syntheticDoc(count = 40, seed = 7): SyntheticDocNode[] {
+  let state = seed;
+  const random = () => {
+    state = (Math.imul(state, 1_664_525) + 1_013_904_223) >>> 0;
+    return state / 2 ** 32;
+  };
+  const doc: SyntheticDocNode[] = [];
+  for (let index = 0; index < count; index++) {
+    const id = `s${String(index).padStart(2, '0')}`;
+    const reads = new Set<string>();
+    if (index > 0) {
+      const many = 1 + Math.floor(random() * 1.7);
+      for (let k = 0; k < many; k++)
+        reads.add(
+          doc[Math.max(0, index - 1 - Math.floor(random() * random() * 6))]
+            ?.id ?? 's00',
+        );
+    }
+    const node: SyntheticDocNode = { id, reads: [...reads] };
+    if (index > 2 && random() < 0.15) node.when = [doc[index - 2]?.id ?? 's00'];
+    const before = doc[index - 1];
+    if (
+      index > 3 &&
+      !node.when &&
+      random() < 0.12 &&
+      before?.when &&
+      !doc.some((other) => other.elseOf === before.id)
+    )
+      node.elseOf = before.id;
+    if (random() < 0.08) node.forEach = true;
+    doc.push(node);
+  }
+  return doc;
+}
+
+export function syntheticFlowGraph(count = 40, seed = 7): FlowGraph {
+  const doc = syntheticDoc(count, seed);
+  return flowGraphFromDoc(doc, [doc.at(-1)?.id ?? 's00']);
+}
diff --git a/packages/ui/src/components/flow/testing/flow-geometry.ts b/packages/ui/src/components/flow/testing/flow-geometry.ts
new file mode 100644
index 0000000000..bff77fd1d8
--- /dev/null
+++ b/packages/ui/src/components/flow/testing/flow-geometry.ts
@@ -0,0 +1,119 @@
+import {
+  isAxisAligned,
+  rectsOverlap,
+  segmentCrossesRect,
+} from '../layout/geometry';
+import type { FlowLayout, FlowPoint, FlowRect } from '../types';
+
+/**
+ * Assertions over a finished layout, for unit tests (bundled ELK) and
+ * browser tests (the worker, and boxes measured on the page) alike. Each
+ * throws with every offence it found, named, so a failure says which edge
+ * ran through which box.
+ */
+
+/** Every box an edge must route round: nodes and frame headers. */
+export function flowObstacles(
+  layout: FlowLayout,
+): { id: string; rect: FlowRect }[] {
+  return [
+    ...Object.entries(layout.nodes).map(([id, rect]) => ({ id, rect })),
+    ...Object.entries(layout.groups).map(([id, group]) => ({
+      id: `${id} (header)`,
+      rect: group.header,
+    })),
+  ];
+}
+
+/** The edges whose routes pass through a box, as "edge ∩ box" lines. */
+export function edgeBoxCrossings(
+  routes: Readonly<Record<string, { points: readonly FlowPoint[] }>>,
+  obstacles: readonly { id: string; rect: FlowRect }[],
+  inset = 1,
+): string[] {
+  const found: string[] = [];
+  for (const [edgeId, { points }] of Object.entries(routes)) {
+    for (let index = 0; index + 1 < points.length; index++) {
+      const a = points[index];
+      const b = points[index + 1];
+      for (const obstacle of obstacles)
+        if (segmentCrossesRect(a, b, obstacle.rect, inset))
+          found.push(`${edgeId} ∩ ${obstacle.id}`);
+    }
+  }
+  return [...new Set(found)];
+}
+
+/** Throws when an edge runs through a node, a gate, Start, End or a frame
+ *  header (shrunk by `inset` px, so meeting a border does not count). */
+export function assertNoEdgeCrossesBox(layout: FlowLayout, inset = 1): void {
+  const crossings = edgeBoxCrossings(
+    layout.edges,
+    flowObstacles(layout),
+    inset,
+  );
+  if (crossings.length > 0)
+    throw new Error(`Edges cross boxes:\n  ${crossings.join('\n  ')}`);
+}
+
+/** Throws when an edge label overlaps a box or another label. */
+export function assertLabelsClear(layout: FlowLayout): void {
+  const problems: string[] = [];
+  const labels = Object.entries(layout.edges).flatMap(([id, edge]) =>
+    edge.label ? [{ id, rect: edge.label }] : [],
+  );
+  for (const label of labels)
+    for (const obstacle of flowObstacles(layout))
+      if (rectsOverlap(label.rect, obstacle.rect))
+        problems.push(`label of ${label.id} ∩ ${obstacle.id}`);
+  for (let i = 0; i < labels.length; i++)
+    for (let j = i + 1; j < labels.length; j++) {
+      const a = labels[i];
+      const b = labels[j];
+      if (a && b && rectsOverlap(a.rect, b.rect))
+        problems.push(`label of ${a.id} ∩ label of ${b.id}`);
+    }
+  if (problems.length > 0)
+    throw new Error(`Labels overlap:\n  ${problems.join('\n  ')}`);
+}
+
+/** Throws when a route has a segment that is neither horizontal nor
+ *  vertical, or fewer than two points. */
+export function assertRoutesAxisAligned(layout: FlowLayout): void {
+  const bad = Object.entries(layout.edges)
+    .filter(([, edge]) => edge.points.length < 2 || !isAxisAligned(edge.points))
+    .map(([id, edge]) => `${id} ${JSON.stringify(edge.points)}`);
+  if (bad.length > 0)
+    throw new Error(`Routes are not axis-aligned:\n  ${bad.join('\n  ')}`);
+}
+
+/** The index of the row `id` sits in, or -1. */
+export function flowRowIndex(layout: FlowLayout, id: string): number {
+  return layout.rows.findIndex((row) => row.includes(id));
+}
+
+/**
+ * Pairs of nodes that share a row before and after a relayout and swapped
+ * sides: what a reader sees as boxes jumping past each other.
+ */
+export function flowRowOrderFlips(
+  before: FlowLayout,
+  after: FlowLayout,
+): string[] {
+  const flips: string[] = [];
+  for (const row of before.rows) {
+    for (let i = 0; i < row.length; i++) {
+      for (let j = i + 1; j < row.length; j++) {
+        const left = row[i];
+        const right = row[j];
+        const afterRow = after.rows.find((candidate) =>
+          candidate.includes(left),
+        );
+        if (afterRow === undefined || !afterRow.includes(right)) continue;
+        if (afterRow.indexOf(left) > afterRow.indexOf(right))
+          flips.push(`${left} ↔ ${right}`);
+      }
+    }
+  }
+  return flips;
+}
diff --git a/packages/ui/src/components/flow/types.ts b/packages/ui/src/components/flow/types.ts
new file mode 100644
index 0000000000..ca128984d1
--- /dev/null
+++ b/packages/ui/src/components/flow/types.ts
@@ -0,0 +1,230 @@
+import type { ComponentType } from 'react';
+
+/**
+ * The graph a workflow canvas draws, and the layout it draws it at.
+ *
+ * A host turns its own document into a `FlowGraph` — plain data: nodes in
+ * reading order, the edges between them, the frames around iterating nodes —
+ * and the package lays it out, renders every node from that data and lets a
+ * keyboard walk it. The graph never carries a position: where a node sits is
+ * a pure function of the graph, so the same document always draws the same
+ * picture and no one ever places a box by hand.
+ */
+
+/** An icon a node, row or chip shows: any component that takes a class. */
+export type FlowIcon = ComponentType<{ className?: string }>;
+
+export type FlowNodeKind = 'entry' | 'exit' | 'step' | 'gate';
+
+interface FlowNodeBase {
+  /** Unique in the graph. */
+  id: string;
+  kind: FlowNodeKind;
+  /**
+   * Extra sentences for the node's accessible description — what it returns,
+   * what its chips and markers mean — in the host's words. The package adds
+   * the node's position, its neighbours and what it reads.
+   */
+  description?: string;
+}
+
+/** A line in a node or in the List view: a trigger, an input field, an
+ *  output row, an outcome. */
+export interface FlowRow {
+  id: string;
+  icon?: FlowIcon;
+  label: string;
+  /** Muted text after a middle dot ("text · required"). */
+  detail?: string;
+  /** A muted second line ("Next Thu 9 Oct, 07:00"). Adds 16 px to the row. */
+  note?: string;
+  /** A short state word on the row's right ("Off"). */
+  badge?: { label: string; tone: 'neutral' | 'warning' };
+  /** Shows the label in the monospace face. */
+  code?: boolean;
+}
+
+/** A short word on a step's face ("Continues on error"). */
+export interface FlowChip {
+  id: string;
+  label: string;
+  icon?: FlowIcon;
+  tone?: 'neutral' | 'info' | 'warning' | 'error';
+}
+
+/** A glyph in a step's title row; `label` is its tooltip and its words for a
+ *  screen reader. */
+export interface FlowMarker {
+  id: string;
+  icon: FlowIcon;
+  label: string;
+  tone?: 'neutral' | 'warning';
+}
+
+/** One line of warning or information at the foot of Start or End. */
+export interface FlowNotice {
+  tone: 'warning' | 'info';
+  text: string;
+}
+
+/** One unit of work. */
+export interface FlowStepNode extends FlowNodeBase {
+  kind: 'step';
+  /** Visible name; also the start of the accessible name. */
+  label: string;
+  icon?: FlowIcon;
+  /** What kind of step it is: "GitHub · List issues". */
+  typeLabel?: string;
+  /** What the step reads, for its strip, its description and the List view. */
+  reads?: readonly FlowRow[];
+  /** The strip's words when `reads` is empty ("Reads no other node"). */
+  readsEmpty?: string;
+  /**
+   * What the step returns: a shape (`code`, shown in mono) or a sentence.
+   * `null` reserves the row while the host still works it out; leave it
+   * out for a step that has no row.
+   */
+  returns?: { text: string; code: boolean } | null;
+  /** Two are shown, the rest as "+n"; put every chip's words in the
+   *  description too. */
+  chips?: readonly FlowChip[];
+  /** Glyphs in the title row. */
+  markers?: readonly FlowMarker[];
+  /** It may be skipped: drawn with a dashed border. */
+  conditional?: boolean;
+  /** No run ever reaches it: dashed, with a "Never runs" chip. */
+  unreachable?: boolean;
+}
+
+/** Start: how a run begins and what it receives. At most one per graph. */
+export interface FlowEntryNode extends FlowNodeBase {
+  kind: 'entry';
+  /** The title; "Start" in the session's language when left out. */
+  label?: string;
+  /** What starts a run; at least one row. */
+  triggers: readonly FlowRow[];
+  /** The fields every run receives. */
+  inputs: readonly FlowRow[];
+  /** The words when `inputs` is empty; "No input" when left out. */
+  inputsEmpty?: string;
+  notice?: FlowNotice;
+}
+
+/** End: what a run returns and how it can end. At most one per graph. */
+export interface FlowExitNode extends FlowNodeBase {
+  kind: 'exit';
+  /** The title; "End" in the session's language when left out. */
+  label?: string;
+  outputs: readonly FlowRow[];
+  /** The words when `outputs` is empty; "Returns nothing" when left out. */
+  outputsEmpty?: string;
+  /** A one-line shape of what it returns, shown in mono. */
+  shape?: string;
+  /** How a run ends: Succeeded, Failed, Stopped. */
+  outcomes?: readonly FlowRow[];
+  notice?: FlowNotice;
+}
+
+/** The condition in front of a step. `only-if` has one plain edge out;
+ *  `if-else` has a Yes and a No edge. */
+export interface FlowGateNode extends FlowNodeBase {
+  kind: 'gate';
+  /** The name of the step it guards, for its accessible name. */
+  label: string;
+  mode: 'only-if' | 'if-else';
+  /** The condition in words, or the expression itself. */
+  condition: string;
+  /** `condition` is code: shown in mono. */
+  conditionIsCode?: boolean;
+  /** The key a path's decisions use for this gate. */
+  decisionKey?: string;
+}
+
+export type FlowNode =
+  | FlowStepNode
+  | FlowEntryNode
+  | FlowExitNode
+  | FlowGateNode;
+
+export type FlowEdgeKind =
+  /** The target reads the source's output. */
+  | 'data'
+  /** The target only mentions the source in a condition or a repeat. */
+  | 'order'
+  /** An only-if gate to the step it guards. */
+  | 'gate'
+  /** An if/else gate to the step that runs when the condition holds. */
+  | 'branch-yes'
+  /** An if/else gate to the step that runs when it does not. */
+  | 'branch-no'
+  /** Start to a node that reads no other. */
+  | 'entry'
+  /** A node the result reads, to End. */
+  | 'exit'
+  /** A node nothing reads, to End. */
+  | 'completion';
+
+export interface FlowEdge {
+  id: string;
+  source: string;
+  target: string;
+  kind: FlowEdgeKind;
+  /** Pointer-hover words ("Carries .issues"); say the same in a node's
+   *  description for the keyboard. */
+  detail?: string;
+  /** Shapes the layout but is never drawn, followed or highlighted. */
+  layoutOnly?: boolean;
+}
+
+/** A frame around the step(s) that run once per item (`each`) or repeat
+ *  (`repeat`). Decoration: every member's description says it too. */
+export interface FlowGroup {
+  id: string;
+  kind: 'each' | 'repeat';
+  /** The header: "For each item of issues of Open issues". */
+  label: string;
+  /** Step ids, consecutive in a path (no path between two members leaves
+   *  the frame). */
+  members: readonly string[];
+}
+
+export interface FlowGraph {
+  /** Reading order: the layout's model order and the List view's order. */
+  nodes: readonly FlowNode[];
+  edges: readonly FlowEdge[];
+  groups?: readonly FlowGroup[];
+}
+
+export interface FlowPoint {
+  x: number;
+  y: number;
+}
+
+export interface FlowRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Where the layout put everything, in flow coordinates (absolute). */
+export interface FlowLayout {
+  /** The graph shape, sizes and options this layout was computed for. */
+  signature: string;
+  nodes: Readonly<Record<string, FlowRect>>;
+  groups: Readonly<Record<string, FlowRect & { header: FlowRect }>>;
+  /** Every drawn edge's route, axis-aligned, and its label's box. */
+  edges: Readonly<
+    Record<string, { points: readonly FlowPoint[]; label?: FlowRect }>
+  >;
+  bounds: FlowRect;
+  /** Rows top to bottom, each left to right: arrow keys walk them. */
+  rows: readonly (readonly string[])[];
+  /** Who laid it out: the worker, the main thread, or the one-column
+   *  fallback when the layout engine failed. */
+  engine: 'worker' | 'main' | 'fallback-column';
+  /** How long the layout took. */
+  ms: number;
+}
+
+export { validateFlowGraph } from './validate-graph';
diff --git a/packages/ui/src/components/flow/validate-graph.test.ts b/packages/ui/src/components/flow/validate-graph.test.ts
new file mode 100644
index 0000000000..c5baf671d2
--- /dev/null
+++ b/packages/ui/src/components/flow/validate-graph.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  branchFlowGraph,
+  syntheticFlowGraph,
+  triageFlowGraph,
+} from './testing/flow-fixtures';
+import type { FlowGraph } from './types';
+import { validateFlowGraph } from './validate-graph';
+
+const base = (): FlowGraph => triageFlowGraph();
+
+describe('validateFlowGraph', () => {
+  it('accepts every fixture', () => {
+    expect(() => validateFlowGraph(base())).not.toThrow();
+    expect(() => validateFlowGraph(branchFlowGraph())).not.toThrow();
+    expect(() => validateFlowGraph(syntheticFlowGraph(40))).not.toThrow();
+  });
+
+  it('refuses a repeated id and an edge to nowhere', () => {
+    const graph = base();
+    expect(() =>
+      validateFlowGraph({ ...graph, nodes: [...graph.nodes, graph.nodes[1]!] }),
+    ).toThrow(/duplicate node id "issues"/);
+    expect(() =>
+      validateFlowGraph({
+        ...graph,
+        edges: [
+          ...graph.edges,
+          { id: 'x', source: 'issues', target: 'ghost', kind: 'data' },
+        ],
+      }),
+    ).toThrow(/unknown node "ghost"/);
+  });
+
+  it('refuses a second Start', () => {
+    const graph = base();
+    expect(() =>
+      validateFlowGraph({
+        ...graph,
+        nodes: [
+          ...graph.nodes,
+          { id: 'again', kind: 'entry', triggers: [], inputs: [] },
+        ],
+      }),
+    ).toThrow(/more than one entry node/);
+  });
+
+  it('refuses an if/else gate without both branches', () => {
+    const graph = branchFlowGraph();
+    expect(() =>
+      validateFlowGraph({
+        ...graph,
+        edges: graph.edges.filter((edge) => edge.kind !== 'branch-no'),
+      }),
+    ).toThrow(/needs a Yes and a No edge/);
+  });
+
+  it('refuses a frame a path leaves and re-enters', () => {
+    const graph = base();
+    expect(() =>
+      validateFlowGraph({
+        ...graph,
+        groups: [
+          { id: 'g', kind: 'each', label: 'x', members: ['issues', 'score'] },
+        ],
+      }),
+    ).toThrow(/not convex/);
+  });
+
+  it('refuses a frame round something other than steps', () => {
+    const graph = base();
+    expect(() =>
+      validateFlowGraph({
+        ...graph,
+        groups: [{ id: 'g', kind: 'each', label: 'x', members: ['__start'] }],
+      }),
+    ).toThrow(/not a step/);
+  });
+});
diff --git a/packages/ui/src/components/flow/validate-graph.ts b/packages/ui/src/components/flow/validate-graph.ts
new file mode 100644
index 0000000000..93e3efd478
--- /dev/null
+++ b/packages/ui/src/components/flow/validate-graph.ts
@@ -0,0 +1,101 @@
+import type { FlowGraph } from './types';
+
+/**
+ * Throws on a graph the canvas cannot draw truthfully: a repeated id, an
+ * edge to a node that is not there, more than one Start or End, a gate with
+ * the wrong edges out, a frame around something other than steps, or a
+ * frame a path leaves and re-enters (its members would not sit together).
+ *
+ * The canvas runs it in development builds and tests; a host's adapter
+ * tests should run it over every graph they build.
+ */
+export function validateFlowGraph(graph: FlowGraph): void {
+  const problems: string[] = [];
+  const kinds = new Map<string, string>();
+  for (const node of graph.nodes) {
+    if (kinds.has(node.id)) problems.push(`duplicate node id "${node.id}"`);
+    kinds.set(node.id, node.kind);
+  }
+  const edgeIds = new Set<string>();
+  for (const edge of graph.edges) {
+    if (edgeIds.has(edge.id)) problems.push(`duplicate edge id "${edge.id}"`);
+    edgeIds.add(edge.id);
+    if (!kinds.has(edge.source))
+      problems.push(
+        `edge "${edge.id}" starts at unknown node "${edge.source}"`,
+      );
+    if (!kinds.has(edge.target))
+      problems.push(`edge "${edge.id}" ends at unknown node "${edge.target}"`);
+    if (edge.source === edge.target)
+      problems.push(`edge "${edge.id}" loops on "${edge.source}"`);
+  }
+  const count = (kind: string) =>
+    graph.nodes.filter((node) => node.kind === kind).length;
+  if (count('entry') > 1) problems.push('more than one entry node');
+  if (count('exit') > 1) problems.push('more than one exit node');
+
+  for (const node of graph.nodes) {
+    if (node.kind !== 'gate') continue;
+    const out = graph.edges.filter(
+      (edge) => edge.source === node.id && !edge.layoutOnly,
+    );
+    const has = (kind: string) => out.some((edge) => edge.kind === kind);
+    if (node.mode === 'only-if' && !has('gate'))
+      problems.push(`only-if gate "${node.id}" has no gate edge out`);
+    if (node.mode === 'if-else' && !(has('branch-yes') && has('branch-no')))
+      problems.push(`if-else gate "${node.id}" needs a Yes and a No edge out`);
+  }
+  for (const edge of graph.edges) {
+    if (
+      (edge.kind === 'gate' ||
+        edge.kind === 'branch-yes' ||
+        edge.kind === 'branch-no') &&
+      kinds.get(edge.source) !== 'gate'
+    )
+      problems.push(`${edge.kind} edge "${edge.id}" does not leave a gate`);
+  }
+
+  const successors = new Map<string, string[]>();
+  for (const edge of graph.edges) {
+    const list = successors.get(edge.source);
+    if (list) list.push(edge.target);
+    else successors.set(edge.source, [edge.target]);
+  }
+  const framed = new Set<string>();
+  for (const group of graph.groups ?? []) {
+    if (group.members.length === 0)
+      problems.push(`group "${group.id}" has no members`);
+    for (const member of group.members) {
+      if (kinds.get(member) !== 'step')
+        problems.push(`group "${group.id}" holds "${member}", not a step`);
+      if (framed.has(member))
+        problems.push(`"${member}" sits in more than one group`);
+      framed.add(member);
+    }
+    // Convex: no path from one member back to another leaves the group.
+    const inside = new Set(group.members);
+    for (const member of group.members) {
+      const stack = (successors.get(member) ?? []).filter(
+        (id) => !inside.has(id),
+      );
+      const seen = new Set<string>();
+      for (let id = stack.pop(); id !== undefined; id = stack.pop()) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        for (const next of successors.get(id) ?? []) {
+          if (inside.has(next)) {
+            problems.push(
+              `group "${group.id}" is not convex: a path from "${member}" leaves it and returns at "${next}"`,
+            );
+            stack.length = 0;
+            break;
+          }
+          stack.push(next);
+        }
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`Invalid flow graph:\n  ${problems.join('\n  ')}`);
+  }
+}
diff --git a/packages/ui/src/testing/flow.ts b/packages/ui/src/testing/flow.ts
index 0948c837ad..f2cf726bae 100644
--- a/packages/ui/src/testing/flow.ts
+++ b/packages/ui/src/testing/flow.ts
@@ -1,3 +1,25 @@
+export {
+  branchFlowGraph,
+  cyclicFlowGraph,
+  flowGraphFromDoc,
+  inputGateFlowGraph,
+  reviewPullRequestsFlowGraph,
+  syntheticDoc,
+  syntheticFlowGraph,
+  triageFlowGraph,
+  triageInboxFlowGraph,
+  type SyntheticDocNode,
+} from '../components/flow/testing/flow-fixtures';
+export {
+  assertLabelsClear,
+  assertNoEdgeCrossesBox,
+  assertRoutesAxisAligned,
+  edgeBoxCrossings,
+  flowObstacles,
+  flowRowIndex,
+  flowRowOrderFlips,
+} from '../components/flow/testing/flow-geometry';
+
 /** The longest delay `setTimeout` holds: 2^31 − 1 ms, about 24.8 days. */
 const MAX_TIMER_DELAY = 2 ** 31 - 1;
 

From eacbad7a41b49b21c4dd00ecd6731080644f673e Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:18:18 +0200
Subject: [PATCH 17/78] feat(ui): draw workflows with WorkflowCanvas, routed
 edges and node kinds

WorkflowCanvas renders a FlowGraph from data on its own layout: Start
with its triggers and inputs, steps with type, returns, chips and what
they read, conditions as pills with Yes and No, End with what a run
returns and how it ends, dashed frames round iterating steps. Every
edge follows its ELK route with rounded corners and a tinted arrow;
none is React Flow's handle-to-handle curve any more.

The chart is one Tab stop: arrows follow the lines and the rows, Home
and End jump, Enter opens. Each node is a real button named and
described in words (position, neighbours, conditions, reads); the
List view (FlowStepList) says the same as text, and FlowLegend explains
the marks. FlowNodeStatus is the one run-state vocabulary.

FlowCanvas loses the unused AI toggle, gains the auto fit policy, top
corners and corner actions, and eases viewport moves out (quint) over
the duration tokens, instantly under reduced motion. The No branch
takes --flow-edge-negative (amber-700 in light, 2.2:1 amber failed).
Package strings live under flow in en, de and fr, with de-CH for ss.
---
 packages/ui/package.json                      |   4 +
 .../ui/src/components/flow/describe.test.ts   |  92 +++
 packages/ui/src/components/flow/describe.ts   | 270 ++++++++
 .../ui/src/components/flow/edge-palette.ts    |  78 ++-
 .../flow/flow-canvas.browser.test.tsx         |  63 +-
 .../ui/src/components/flow/flow-canvas.tsx    | 300 ++++++---
 .../flow/flow-legend.browser.test.tsx         |  70 ++
 .../ui/src/components/flow/flow-legend.tsx    | 116 ++++
 .../flow/flow-step-list.browser.test.tsx      | 131 ++++
 .../ui/src/components/flow/flow-step-list.tsx | 270 ++++++++
 .../src/components/flow/node-status.test.tsx  |  55 ++
 .../ui/src/components/flow/node-status.tsx    | 153 +++++
 .../components/flow/render/edge-markers.tsx   |  46 ++
 .../src/components/flow/render/entry-node.tsx | 164 +++++
 .../src/components/flow/render/exit-node.tsx  |  61 ++
 .../flow/render/flow-render-context.tsx       | 155 +++++
 .../src/components/flow/render/gate-node.tsx  |  64 ++
 .../components/flow/render/group-frame.tsx    |  87 +++
 .../components/flow/render/routed-edge.tsx    | 112 ++++
 .../src/components/flow/render/step-node.tsx  | 164 +++++
 .../flow/workflow-canvas.browser.test.tsx     | 386 +++++++++++
 .../src/components/flow/workflow-canvas.tsx   | 632 ++++++++++++++++++
 packages/ui/src/globals.css                   |   7 +
 packages/ui/src/i18n/keys-dynamic.yml         |   3 +
 packages/ui/src/i18n/messages/de-CH.yml       |   5 +
 packages/ui/src/i18n/messages/de.yml          |  55 +-
 packages/ui/src/i18n/messages/en.yml          |  55 +-
 packages/ui/src/i18n/messages/fr.yml          |  55 +-
 packages/ui/tests/utils/contrast.ts           |  71 ++
 29 files changed, 3620 insertions(+), 104 deletions(-)
 create mode 100644 packages/ui/src/components/flow/describe.test.ts
 create mode 100644 packages/ui/src/components/flow/describe.ts
 create mode 100644 packages/ui/src/components/flow/flow-legend.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/flow-legend.tsx
 create mode 100644 packages/ui/src/components/flow/flow-step-list.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/flow-step-list.tsx
 create mode 100644 packages/ui/src/components/flow/node-status.test.tsx
 create mode 100644 packages/ui/src/components/flow/node-status.tsx
 create mode 100644 packages/ui/src/components/flow/render/edge-markers.tsx
 create mode 100644 packages/ui/src/components/flow/render/entry-node.tsx
 create mode 100644 packages/ui/src/components/flow/render/exit-node.tsx
 create mode 100644 packages/ui/src/components/flow/render/flow-render-context.tsx
 create mode 100644 packages/ui/src/components/flow/render/gate-node.tsx
 create mode 100644 packages/ui/src/components/flow/render/group-frame.tsx
 create mode 100644 packages/ui/src/components/flow/render/routed-edge.tsx
 create mode 100644 packages/ui/src/components/flow/render/step-node.tsx
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.tsx
 create mode 100644 packages/ui/tests/utils/contrast.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index ab8c1f7d96..7bf538fc11 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -148,10 +148,14 @@
     "./flow/edge-palette": "./src/components/flow/edge-palette.ts",
     "./flow/elk-layout": "./src/components/flow/layout/elk-layout.ts",
     "./flow/flow-canvas": "./src/components/flow/flow-canvas.tsx",
+    "./flow/flow-legend": "./src/components/flow/flow-legend.tsx",
+    "./flow/flow-step-list": "./src/components/flow/flow-step-list.tsx",
     "./flow/layout": "./src/components/flow/layout/index.ts",
     "./flow/node-issue-marker": "./src/components/flow/node-issue-marker.tsx",
+    "./flow/node-status": "./src/components/flow/node-status.tsx",
     "./flow/types": "./src/components/flow/types.ts",
     "./flow/use-elk-layout": "./src/components/flow/layout/use-elk-layout.ts",
+    "./flow/workflow-canvas": "./src/components/flow/workflow-canvas.tsx",
     "./form": "./src/components/forms/form.tsx",
     "./form-section": "./src/components/forms/form-section.tsx",
     "./format": "./src/lib/format.ts",
diff --git a/packages/ui/src/components/flow/describe.test.ts b/packages/ui/src/components/flow/describe.test.ts
new file mode 100644
index 0000000000..6c809835ea
--- /dev/null
+++ b/packages/ui/src/components/flow/describe.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  describeFlowGraph,
+  flowListFormat,
+  type FlowTranslate,
+} from './describe';
+import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+
+/** Echoes the key and its values, so the test reads what was asked for. */
+const t: FlowTranslate = (key, options) =>
+  options === undefined
+    ? key
+    : `${key}(${Object.entries(options)
+        .filter(([name]) => name !== 'ns')
+        .map(([name, value]) => `${name}=${String(value)}`)
+        .join(', ')})`;
+
+const words = (
+  graph = triageFlowGraph(),
+  issues?: Map<string, { errors: number; warnings: number }>,
+) =>
+  describeFlowGraph(graph, {
+    t,
+    tIssues: t,
+    list: flowListFormat('en'),
+    issues,
+  });
+
+describe('describeFlowGraph', () => {
+  it('names steps by title, Start and End by their words, gates by condition', () => {
+    const triage = words();
+    expect(triage.names.get('issues')).toBe('Issues');
+    expect(triage.names.get('__start')).toBe('node.entry');
+    expect(triage.names.get('__end')).toBe('node.exit');
+    const branch = words(branchFlowGraph());
+    expect(branch.names.get('__gate:urgent')).toBe(
+      'gate.name(node=Urgent, condition=urgent of Classify is true)',
+    );
+  });
+
+  it('adds the problems to the name', () => {
+    const named = words(
+      triageFlowGraph(),
+      new Map([['score', { errors: 2, warnings: 0 }]]),
+    );
+    expect(named.names.get('score')).toMatch(/^Score nodeSummary/);
+  });
+
+  it('says where a step sits, where it comes from and leads, and what it reads', () => {
+    expect(words().descriptions.get('report')).toBe(
+      [
+        'node.position(index=5, count=6)',
+        'relation.comesFrom(list=Open issues and Score)',
+        'relation.leadsTo(list=node.exit)',
+        'list.reads(list=Open issues and Score)',
+      ].join('. ') + '.',
+    );
+  });
+
+  it('folds a gate into what its targets say', () => {
+    const branch = words(branchFlowGraph());
+    expect(branch.descriptions.get('urgent')).toContain(
+      'relation.onlyIf(condition=urgent of Classify is true)',
+    );
+    expect(branch.descriptions.get('low')).toContain(
+      'relation.otherwise(node=Normal)',
+    );
+    // An else-if: No leads on to the next condition, named for its node.
+    expect(branch.descriptions.get('__gate:urgent')).toContain(
+      'gate.branches(yes=Urgent, no=Normal)',
+    );
+  });
+
+  it('puts what a step reads on its strip, and where Start and End lead', () => {
+    const triage = words();
+    expect(triage.strips.get('open_issues')).toBe(
+      'list.reads(list=Issues and run input (limit))',
+    );
+    expect(triage.strips.get('__start')).toBe('relation.leadsTo(list=Issues)');
+    expect(triage.strips.get('__end')).toBe('relation.comesFrom(list=Report)');
+  });
+
+  it('spells out Start and End when the host gives no description', () => {
+    const start = words().descriptions.get('__start') ?? '';
+    expect(start).toContain('node.section(heading=node.triggers');
+    expect(start).toContain(
+      'rowWithDetail(label=Every day at 07:00 · UTC, detail=Next Thu 9 Oct, 07:00)',
+    );
+    expect(start).toContain('label=firedAt');
+  });
+});
diff --git a/packages/ui/src/components/flow/describe.ts b/packages/ui/src/components/flow/describe.ts
new file mode 100644
index 0000000000..50ee8e8d58
--- /dev/null
+++ b/packages/ui/src/components/flow/describe.ts
@@ -0,0 +1,270 @@
+import type { IssueCounts } from '../feedback/issue-summary';
+import { flowNodeIssueText } from './node-issue-marker';
+import type { FlowEdge, FlowGraph, FlowNode, FlowRow } from './types';
+
+/** Translates a key of the `flow` namespace (or of `issues`, with `ns`). */
+export type FlowTranslate = (
+  key: string,
+  options?: Record<string, unknown>,
+) => string;
+
+/** What a chart says about each node, in words. */
+export interface FlowWords {
+  /** The accessible name: the title, the kind for Start, End and a
+   *  condition, the problems. */
+  names: ReadonlyMap<string, string>;
+  /** The accessible description: where the node sits, what it comes from
+   *  and leads to, when it runs, what it reads, and the host's sentences. */
+  descriptions: ReadonlyMap<string, string>;
+  /** The line along a box's foot when no run is shown. */
+  strips: ReadonlyMap<string, string>;
+  /** The title of a node as other sentences name it. */
+  titles: ReadonlyMap<string, string>;
+  /** The sentences under a node in the List view. */
+  lines: ReadonlyMap<string, readonly string[]>;
+}
+
+const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
+
+/** "and"-joined lists in the reader's language. */
+export function flowListFormat(
+  locale: string,
+): (items: readonly string[]) => string {
+  const format = new Intl.ListFormat(locale, {
+    style: 'long',
+    type: 'conjunction',
+  });
+  return (items) => format.format(items);
+}
+
+/** The words of the boxes' kinds. */
+export function flowNodeTitle(node: FlowNode, t: FlowTranslate): string {
+  if (node.kind === 'entry') return node.label ?? t('node.entry');
+  if (node.kind === 'exit') return node.label ?? t('node.exit');
+  return node.label;
+}
+
+function rowText(row: FlowRow, t: FlowTranslate): string {
+  const detail = [row.detail, row.note, row.badge?.label]
+    .filter(Boolean)
+    .join(', ');
+  return detail === ''
+    ? row.label
+    : t('node.rowWithDetail', { label: row.label, detail });
+}
+
+/**
+ * Every node's name, description, strip and List view lines — one place,
+ * so the chart and the List view say the same.
+ */
+export function describeFlowGraph(
+  graph: FlowGraph,
+  {
+    t,
+    tIssues,
+    list,
+    issues,
+  }: {
+    t: FlowTranslate;
+    /** Reads the `issues` namespace (a node's problem counts). */
+    tIssues: FlowTranslate;
+    list: (items: readonly string[]) => string;
+    issues?: ReadonlyMap<string, IssueCounts>;
+  },
+): FlowWords {
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  const titles = new Map(
+    graph.nodes.map((node) => [node.id, flowNodeTitle(node, t)]),
+  );
+  const drawn = graph.edges.filter((edge) => !edge.layoutOnly);
+  const incoming = new Map<string, FlowEdge[]>();
+  const outgoing = new Map<string, FlowEdge[]>();
+  for (const edge of drawn) {
+    incoming.set(edge.target, [...(incoming.get(edge.target) ?? []), edge]);
+    outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]);
+  }
+  const isGate = (id: string) => byId.get(id)?.kind === 'gate';
+  const titleOf = (id: string) => titles.get(id) ?? id;
+  const unique = (ids: string[]) => [...new Set(ids)];
+
+  /** "Runs only if …" / "Runs when the condition of … is false" for every
+   *  condition in front of `id`. */
+  const conditions = (id: string): string[] =>
+    (incoming.get(id) ?? [])
+      .filter((edge) => isGate(edge.source))
+      .map((edge) => {
+        const gate = byId.get(edge.source);
+        if (gate?.kind !== 'gate') return '';
+        return edge.kind === 'branch-no'
+          ? t('relation.otherwise', { node: gate.label })
+          : t('relation.onlyIf', { condition: gate.condition });
+      })
+      .filter((sentence) => sentence !== '');
+
+  const comesFrom = (id: string): string | null => {
+    const sources = unique(
+      (incoming.get(id) ?? [])
+        .filter((edge) => !isGate(edge.source))
+        .map((edge) => titleOf(edge.source)),
+    );
+    return sources.length > 0
+      ? t('relation.comesFrom', { list: list(sources) })
+      : null;
+  };
+  const leadsTo = (id: string): string | null => {
+    const targets = unique(
+      (outgoing.get(id) ?? []).map((edge) => titleOf(edge.target)),
+    );
+    return targets.length > 0
+      ? t('relation.leadsTo', { list: list(targets) })
+      : null;
+  };
+  const readsOf = (node: FlowNode): string => {
+    if (node.kind !== 'step') return '';
+    if (node.reads !== undefined && node.reads.length > 0)
+      return t('list.reads', {
+        list: list(node.reads.map((row) => row.label)),
+      });
+    return node.readsEmpty ?? '';
+  };
+  const section = (heading: string, rows: readonly FlowRow[], empty: string) =>
+    t('node.section', {
+      heading,
+      items: rows.length > 0 ? list(rows.map((row) => rowText(row, t))) : empty,
+    });
+
+  const names = new Map<string, string>();
+  const descriptions = new Map<string, string>();
+  const strips = new Map<string, string>();
+  const lines = new Map<string, readonly string[]>();
+  const count = graph.nodes.length;
+
+  graph.nodes.forEach((node, index) => {
+    const issueText = flowNodeIssueText(
+      tIssues,
+      issues?.get(node.id) ?? NO_ISSUES,
+    );
+    const title = titleOf(node.id);
+    const base =
+      node.kind === 'gate'
+        ? t('gate.name', { node: node.label, condition: node.condition })
+        : title;
+    names.set(node.id, issueText === '' ? base : `${base} ${issueText}`);
+
+    const parts: (string | null | undefined)[] = [
+      t('node.position', { index: index + 1, count }),
+    ];
+    let listLines: (string | null | undefined)[] = [];
+    if (node.kind === 'step') {
+      const reads = readsOf(node);
+      strips.set(node.id, reads);
+      parts.push(
+        comesFrom(node.id),
+        ...conditions(node.id),
+        leadsTo(node.id),
+        reads,
+      );
+      if (node.unreachable) parts.push(t('node.unreachable'));
+      parts.push(node.description);
+      listLines = [
+        reads,
+        ...conditions(node.id),
+        leadsTo(node.id),
+        node.unreachable ? t('node.unreachable') : null,
+      ];
+    } else if (node.kind === 'gate') {
+      const out = outgoing.get(node.id) ?? [];
+      const yes = out.find((edge) => edge.kind === 'branch-yes');
+      const no = out.find((edge) => edge.kind === 'branch-no');
+      parts.push(comesFrom(node.id), ...conditions(node.id));
+      parts.push(
+        node.mode === 'if-else' && yes && no
+          ? t('gate.branches', {
+              yes: titleOf(yes.target),
+              no: titleOf(no.target),
+            })
+          : leadsTo(node.id),
+      );
+      parts.push(node.description);
+    } else if (node.kind === 'entry') {
+      const leads = leadsTo(node.id);
+      strips.set(node.id, leads ?? '');
+      parts.push(leads);
+      parts.push(
+        node.description ??
+          [
+            node.triggers.length > 0
+              ? section(t('node.triggers'), node.triggers, '')
+              : null,
+            section(
+              t('node.inputs'),
+              node.inputs,
+              node.inputsEmpty ?? t('node.noInput'),
+            ),
+            node.notice?.text,
+          ]
+            .filter(Boolean)
+            .join('. '),
+      );
+      listLines = [
+        node.triggers.length > 0
+          ? section(t('node.triggers'), node.triggers, '')
+          : null,
+        section(
+          t('node.inputs'),
+          node.inputs,
+          node.inputsEmpty ?? t('node.noInput'),
+        ),
+        node.notice?.text,
+      ];
+    } else {
+      const from = comesFrom(node.id);
+      strips.set(node.id, from ?? '');
+      parts.push(from);
+      const outcomes = node.outcomes ?? [];
+      parts.push(
+        node.description ??
+          [
+            section(
+              t('node.outputs'),
+              node.outputs,
+              node.outputsEmpty ?? t('node.noOutput'),
+            ),
+            node.shape,
+            outcomes.length > 0
+              ? section(t('node.outcomes'), outcomes, '')
+              : null,
+            node.notice?.text,
+          ]
+            .filter(Boolean)
+            .join('. '),
+      );
+      listLines = [
+        section(
+          t('node.outputs'),
+          node.outputs,
+          node.outputsEmpty ?? t('node.noOutput'),
+        ),
+        outcomes.length > 0 ? section(t('node.outcomes'), outcomes, '') : null,
+        node.notice?.text,
+      ];
+    }
+    descriptions.set(
+      node.id,
+      parts
+        .filter(
+          (part): part is string => typeof part === 'string' && part !== '',
+        )
+        .map((part) => part.replace(/[.\s]+$/u, ''))
+        .join('. ')
+        .concat('.'),
+    );
+    lines.set(
+      node.id,
+      listLines.filter(
+        (line): line is string => typeof line === 'string' && line !== '',
+      ),
+    );
+  });
+  return { names, descriptions, strips, titles, lines };
+}
diff --git a/packages/ui/src/components/flow/edge-palette.ts b/packages/ui/src/components/flow/edge-palette.ts
index f4305574bd..edc415e361 100644
--- a/packages/ui/src/components/flow/edge-palette.ts
+++ b/packages/ui/src/components/flow/edge-palette.ts
@@ -1,32 +1,78 @@
+import type { FlowEdgeKind } from './types';
+
 /**
  * The ONE edge visual language for React Flow canvases built on `FlowCanvas`
- * (the automations step editor today). Every edge encodes exactly one of these
- * documented meanings (#2370):
+ * (the automations editor and run page). Every edge encodes exactly one of
+ * these documented meanings (#2370):
  *
- *  - `flow`     — nominal progression: the main spine between steps, including
- *                 a loop's exit toward the next step. Calm and neutral so the
- *                 eye follows the happy path; only decisions draw color.
+ *  - `flow`     — nominal progression: the spine between steps. Calm and
+ *                 neutral so the eye follows the happy path; only decisions
+ *                 draw colour.
  *  - `positive` — a decision's yes/true outcome (green = "the check passed").
  *  - `negative` — a decision's no/false outcome. Amber, **never red**: "No" is
- *                 a branch the author designed, not an error state.
- *  - `error`    — an explicit error/failure route out of a step. The only red
- *                 line on the canvas, reserved for genuine failure handling.
- *
- * Loop-back edges reuse the `flow` color but render dashed — the *shape*
- * encodes the cycle, so color keeps its one meaning.
+ *                 a branch the author designed, not an error state. Its own
+ *                 variable (`--flow-edge-negative`): the warning amber is
+ *                 2.2:1 on white, too faint for a line, so light mode takes
+ *                 amber-700.
+ *  - `error`    — the way into a step that failed. The only red line.
+ *  - `emphasis` — a highlighted or travelled edge.
+ *  - `activity` — something moving or running right now.
  *
- * All values are semantic theme tokens (light + dark), never hex. Strokes and
- * arrowheads share one width/size so every edge carries the same arrow.
+ * Shape carries the rest: an `order` edge is dashed, a `completion` edge
+ * dotted, so colour keeps its one meaning and never speaks alone. All values
+ * are semantic theme tokens (light + dark), never hex, and each keeps 3:1
+ * on the canvas in both themes.
  */
 export const FLOW_EDGE_COLORS = {
   flow: 'hsl(var(--muted-foreground))',
   positive: 'hsl(var(--success))',
-  negative: 'hsl(var(--warning))',
+  negative: 'var(--flow-edge-negative)',
   error: 'hsl(var(--destructive))',
+  emphasis: 'hsl(var(--foreground))',
+  activity: 'hsl(var(--info-foreground))',
 } as const;
 
-/** One stroke width for every edge on the canvas. */
+export type FlowEdgeTone = keyof typeof FLOW_EDGE_COLORS;
+
+/** Every edge colour, for what draws one of each (arrowheads, a legend). */
+export const FLOW_EDGE_TONES: readonly FlowEdgeTone[] = [
+  'flow',
+  'positive',
+  'negative',
+  'error',
+  'emphasis',
+  'activity',
+];
+
+/** One stroke width for every edge at rest. */
 export const FLOW_EDGE_STROKE_WIDTH = 2;
 
-/** One arrowhead size for every edge on the canvas. */
+/** Stroke widths per state: quiet (outside a highlight), base, emphasis. */
+export const FLOW_EDGE_STROKE = { quiet: 1, base: 2, emphasis: 2.5 } as const;
+
+/** Dash patterns per edge kind; a kind not listed is solid. */
+export const FLOW_EDGE_DASH = { order: '6 4', completion: '1 4' } as const;
+
+/** One arrowhead size for React Flow's built-in markers. */
 export const FLOW_EDGE_MARKER_SIZE = 18;
+
+/** The arrowhead `WorkflowCanvas` draws: its length along the edge and its
+ *  width across it, in flow pixels. */
+export const FLOW_EDGE_ARROW = { length: 8, width: 10 } as const;
+
+/** The radius of an orthogonal route's rounded corners. */
+export const FLOW_EDGE_CORNER_RADIUS = 8;
+
+/** The colour an edge of this kind is drawn in at rest. */
+export function flowEdgeTone(kind: FlowEdgeKind): FlowEdgeTone {
+  if (kind === 'branch-yes') return 'positive';
+  if (kind === 'branch-no') return 'negative';
+  return 'flow';
+}
+
+/** The dash pattern of an edge of this kind, or `undefined` for solid. */
+export function flowEdgeDash(kind: FlowEdgeKind): string | undefined {
+  if (kind === 'order') return FLOW_EDGE_DASH.order;
+  if (kind === 'completion') return FLOW_EDGE_DASH.completion;
+  return undefined;
+}
diff --git a/packages/ui/src/components/flow/flow-canvas.browser.test.tsx b/packages/ui/src/components/flow/flow-canvas.browser.test.tsx
index e2cadf209e..a4102e9241 100644
--- a/packages/ui/src/components/flow/flow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/flow-canvas.browser.test.tsx
@@ -2,6 +2,7 @@ import { viewportAtRest } from '@tale/ui/testing/flow';
 import type { UserEvent } from '@testing-library/user-event';
 import { useReactFlow, type Node } from '@xyflow/react';
 import { afterEach, describe, expect, it } from 'vitest';
+import { cdp } from 'vitest/browser';
 
 import { cleanup, render, screen, waitFor } from '@/tests/utils/render';
 
@@ -9,8 +10,9 @@ import { FlowCanvas } from './flow-canvas';
 
 import '../../globals.css';
 
-afterEach(() => {
+afterEach(async () => {
   cleanup();
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
 });
 
 // A column of boxes, like an automation: 200×80 each, 160px apart.
@@ -139,3 +141,62 @@ describe('FlowCanvas fit (real layout)', () => {
     await waitFor(() => expect(nodesFitThePane()).toBe(true));
   });
 });
+
+// A column far taller than the pane: 30 boxes, 160px apart.
+const TALL: Node[] = Array.from({ length: 30 }, (_, i) => ({
+  id: `t${i}`,
+  position: { x: 0, y: i * 160 },
+  width: 200,
+  height: 80,
+  data: { label: `Node ${i}` },
+}));
+
+describe('FlowCanvas auto fit', () => {
+  it('shows a graph too tall to read whole from its top, at a readable zoom', async () => {
+    render(
+      <div style={{ width: 900, height: 700 }}>
+        <FlowCanvas nodes={TALL} edges={[]} fitPolicy="auto" />
+      </div>,
+    );
+    await waitFor(() => expect(transform()).not.toBe(DEFAULT_VIEW));
+    const rest = await viewportAtRest();
+    const zoom = Number(/scale\(([\d.]+)\)/.exec(rest)?.[1]);
+    expect(zoom).toBeGreaterThanOrEqual(0.5);
+    const pane = document.querySelector('.react-flow')!.getBoundingClientRect();
+    const first = document
+      .querySelector('[data-id="t0"]')!
+      .getBoundingClientRect();
+    // The first box is at the top, centred across the pane.
+    expect(first.top - pane.top).toBeGreaterThanOrEqual(0);
+    expect(first.top - pane.top).toBeLessThan(80);
+    expect(
+      Math.abs(first.left + first.width / 2 - (pane.left + pane.width / 2)),
+    ).toBeLessThan(2);
+  });
+
+  it('fits a graph that reads whole, like the all policy', async () => {
+    render(
+      <div data-testid="frame" style={{ width: 900, height: 700 }}>
+        <FlowCanvas nodes={NODES} edges={[]} fitPolicy="auto" />
+      </div>,
+    );
+    await fitted();
+    expect(nodesFitThePane()).toBe(true);
+  });
+});
+
+describe('FlowCanvas under reduced motion', () => {
+  it('zooms at once, without an ease', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const { user } = renderCanvas();
+    await fitted();
+    await user.click(screen.getByRole('button', { name: 'Zoom in' }));
+    // One frame later the zoom has landed: nothing eases toward it.
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    const landed = transform();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(transform()).toBe(landed);
+  });
+});
diff --git a/packages/ui/src/components/flow/flow-canvas.tsx b/packages/ui/src/components/flow/flow-canvas.tsx
index 7ae0d750e2..f106f53e95 100644
--- a/packages/ui/src/components/flow/flow-canvas.tsx
+++ b/packages/ui/src/components/flow/flow-canvas.tsx
@@ -13,11 +13,12 @@ import {
   ReactFlow,
   useReactFlow,
   useStore,
+  useStoreApi,
   type FitViewOptions,
   type ReactFlowProps,
   type Viewport,
 } from '@xyflow/react';
-import { Maximize, Minus, Plus, Sparkles } from 'lucide-react';
+import { Maximize, Minus, Plus } from 'lucide-react';
 import {
   useCallback,
   useEffect,
@@ -27,34 +28,67 @@ import {
   type ReactNode,
 } from 'react';
 
+import { usePrefersReducedMotion } from '../../hooks/use-prefers-reduced-motion';
+
+/** The `--ease-out-quint` curve, for viewport moves run from script. */
+export const easeOutQuint = (t: number) => 1 - (1 - t) ** 5;
+
+/** Viewport move durations: the `--duration-*` tokens, 0 under reduced
+ *  motion (React Flow eases in script, out of reach of the CSS rule). */
+export const FLOW_VIEWPORT_DURATION = {
+  zoom: 150,
+  fit: 300,
+  reveal: 200,
+} as const;
+
+/** How a fit treats a graph too big to show whole at a readable size. */
+export type FlowFitPolicy = 'all' | 'auto';
+
+/** Below this zoom an `auto` fit stops shrinking the graph to show it all. */
+const READABLE_ZOOM = 0.5;
+/** Room an `auto` fit leaves above the graph's top. */
+const TOP_MARGIN = 24;
+
 /**
  * The ONE base React Flow canvas every graph editor in the app builds on
- * (the automation canvas today). Owns the
- * shared chrome and house defaults — theme-reactive `colorMode`, hidden
- * attribution, the fit (initial, and kept while the canvas resizes until the
- * reader moves the view), the corner zoom cluster (zoom in / out / reset)
- * and the bottom-center action toolbar (editor actions + the AI-editor
- * toggle) — so editors differ only in nodes/edges/handlers and
+ * (the workflow canvas). Owns the shared chrome and house defaults —
+ * theme-reactive `colorMode`, hidden attribution, the fit (initial, and
+ * kept while the canvas resizes until the reader moves the view), the
+ * corner zoom cluster (zoom in / out / reset) and the bottom-center action
+ * toolbar — so editors differ only in nodes/edges/handlers and
  * minimap/background styling:
  *
- *  - `backgroundProps` — always rendered; pass variant/gap/color to style.
- *  - `minimapProps`    — renders a MiniMap when provided.
- *  - `centerActions`   — editor-specific buttons in the bottom-center toolbar.
- *  - `onOpenAi`        — adds the ✨ button to the bottom-center toolbar.
+ *  - `backgroundProps`  — always rendered; pass variant/gap/color to style.
+ *  - `minimapProps`     — renders a MiniMap when provided.
+ *  - `centerActions`    — editor-specific buttons in the bottom-center toolbar.
+ *  - `cornerActions`    — extra buttons after zoom/reset in the corner cluster.
+ *  - `topStartActions` / `topEndActions` — the top corners (a view switch,
+ *    the canvas's own verbs).
+ *  - `fitPolicy`        — `all` fits every node; `auto` does too while that
+ *    keeps the graph readable (zoom 0.5 or more), else shows its top at a
+ *    readable zoom, centred on its first node.
+ *  - `fitKey`           — refit when it changes, while the view is still
+ *    where the last fit left it (the graph was laid out again).
  *
- * Everything else spreads onto `<ReactFlow>` untouched; overlays and
- * `<Panel>`s ride through `children`.
+ * Viewport moves ease out (quint) over the duration tokens and jump under
+ * reduced motion. Everything else spreads onto `<ReactFlow>` untouched;
+ * overlays and `<Panel>`s ride through `children`.
  */
 export interface FlowCanvasProps extends ReactFlowProps {
   backgroundProps?: ComponentProps<typeof Background>;
   minimapProps?: ComponentProps<typeof MiniMap>;
   /** Editor-specific buttons rendered in the bottom-center toolbar. */
   centerActions?: ReactNode;
-  /** Opens the editor's AI assistant panel (✨ in the bottom-center toolbar). */
-  onOpenAi?: () => void;
-  /** Whether the AI assistant panel is open — drives the ✨ button's pressed
-   *  (active) state so it reads as a toggle rather than a one-way open. */
-  aiOpen?: boolean;
+  /** Buttons after zoom in / zoom out / reset view in the corner cluster. */
+  cornerActions?: ReactNode;
+  /** The top-left corner. */
+  topStartActions?: ReactNode;
+  /** The top-right corner. */
+  topEndActions?: ReactNode;
+  /** @default 'all' */
+  fitPolicy?: FlowFitPolicy;
+  /** Refit when this changes, while the view is still the fit. */
+  fitKey?: unknown;
 }
 
 /** The view the last fit left, or `null` while a fit is under way. */
@@ -65,41 +99,109 @@ const sameView = (a: Viewport, b: Viewport) =>
   Math.abs(a.y - b.y) < 0.5 &&
   Math.abs(a.zoom - b.zoom) < 0.001;
 
-/** Fit, then remember where the fit left the view. */
-function useFitAndRemember(memo: FitMemo) {
-  const { fitView, getViewport } = useReactFlow();
+/** Fit by the policy, then remember where the fit left the view. */
+function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
+  const { fitView, getViewport, setViewport, getNodes, getNodesBounds } =
+    useReactFlow();
+  const store = useStoreApi();
+  const reduced = usePrefersReducedMotion();
   return useCallback(
     async (options?: FitViewOptions) => {
       memo.current = null;
-      await fitView(options);
+      const duration = reduced ? 0 : (options?.duration ?? 0);
+      const { width, height } = store.getState();
+      const minZoom = options?.minZoom ?? store.getState().minZoom;
+      const nodes = getNodes();
+      if (policy === 'auto' && nodes.length > 0 && width > 0 && height > 0) {
+        const bounds = getNodesBounds(nodes);
+        const padding =
+          typeof options?.padding === 'number' ? options.padding : 0.1;
+        const whole = getViewportForBounds(
+          bounds,
+          width,
+          height,
+          0,
+          Number.POSITIVE_INFINITY,
+          padding,
+        );
+        if (whole.zoom < READABLE_ZOOM) {
+          // Too big to read whole: show its top at a readable zoom, centred
+          // on the topmost box (Start), and let the reader scroll on.
+          const zoom = Math.min(
+            1,
+            Math.max(
+              READABLE_ZOOM,
+              minZoom,
+              width / (bounds.width * (1 + padding)),
+            ),
+          );
+          const top = [...nodes].sort(
+            (a, b) =>
+              a.position.y - b.position.y || a.position.x - b.position.x,
+          )[0];
+          const centreX =
+            top === undefined
+              ? bounds.x + bounds.width / 2
+              : top.position.x + (top.measured?.width ?? top.width ?? 0) / 2;
+          await setViewport(
+            {
+              x: width / 2 - centreX * zoom,
+              y: TOP_MARGIN - bounds.y * zoom,
+              zoom,
+            },
+            { duration, ease: easeOutQuint, interpolate: 'linear' },
+          );
+          memo.current = getViewport();
+          return;
+        }
+      }
+      await fitView({
+        ...options,
+        duration,
+        ease: easeOutQuint,
+        interpolate: 'linear',
+      });
       memo.current = getViewport();
     },
-    [memo, fitView, getViewport],
+    [
+      memo,
+      policy,
+      reduced,
+      store,
+      fitView,
+      getViewport,
+      setViewport,
+      getNodes,
+      getNodesBounds,
+    ],
   );
 }
 
 /**
- * Keeps the initial fit true while the canvas's box changes size — a window
+ * Keeps the fit true while the canvas's box changes size — a window
  * resized, a tab strip wrapping onto a second row, an inspector opening
- * beside it. React Flow fits once, against the box it had at mount; a canvas
- * that then narrowed or shortened kept that zoom and cut its last nodes off.
- * It refits only while the view is still where a fit left it: once anything
- * moves it — the reader panning or zooming, the page bringing a picked node
- * into sight — the view is theirs until "reset view" fits it again. And only
- * to a fit that shows every node: past the zoom floor a fit merely
- * re-centres, which would pull a node the page is bringing into sight (a
- * picked box beside the inspector) back out of it.
+ * beside it — and when the graph is laid out again (`fitKey`). It refits
+ * only while the view is still where a fit left it: once anything moves it —
+ * the reader panning or zooming, the page bringing a picked node into
+ * sight — the view is theirs until "reset view" fits it again. Under the
+ * `all` policy, only to a fit that shows every node: past the zoom floor a
+ * fit merely re-centres, which would pull a node the page is bringing into
+ * sight back out of it.
  * Must render INSIDE <ReactFlow>.
  */
 function FlowAutoFit({
   memo,
   fitViewOptions,
+  policy,
+  fitKey,
 }: {
   memo: FitMemo;
   fitViewOptions?: FitViewOptions;
+  policy: FlowFitPolicy;
+  fitKey: unknown;
 }) {
   const { getViewport, getNodes, getNodesBounds } = useReactFlow();
-  const fitAndRemember = useFitAndRemember(memo);
+  const fitAndRemember = useFitAndRemember(memo, policy);
   const minZoom = useStore((state) => state.minZoom);
   const width = useStore((state) => state.width);
   const height = useStore((state) => state.height);
@@ -112,16 +214,18 @@ function FlowAutoFit({
     const fitted = memo.current;
     if (fitted !== null && !sameView(getViewport(), fitted)) return undefined;
     const frame = requestAnimationFrame(() => {
-      // The zoom that would show every node, before the floor clamps it.
-      const { zoom } = getViewportForBounds(
-        getNodesBounds(getNodes()),
-        width,
-        height,
-        0,
-        Number.POSITIVE_INFINITY,
-        fitViewOptions?.padding ?? 0.1,
-      );
-      if (zoom < (fitViewOptions?.minZoom ?? minZoom)) return;
+      if (policy === 'all') {
+        // The zoom that would show every node, before the floor clamps it.
+        const { zoom } = getViewportForBounds(
+          getNodesBounds(getNodes()),
+          width,
+          height,
+          0,
+          Number.POSITIVE_INFINITY,
+          fitViewOptions?.padding ?? 0.1,
+        );
+        if (zoom < (fitViewOptions?.minZoom ?? minZoom)) return;
+      }
       void fitAndRemember(fitViewOptions);
     });
     return () => cancelAnimationFrame(frame);
@@ -131,6 +235,8 @@ function FlowAutoFit({
     hasNodes,
     minZoom,
     memo,
+    policy,
+    fitKey,
     getViewport,
     getNodes,
     getNodesBounds,
@@ -140,13 +246,29 @@ function FlowAutoFit({
   return null;
 }
 
-/** Corner cluster: zoom in / zoom out / reset view.
- *  Must render INSIDE <ReactFlow> — `useReactFlow` reads its store. Resetting
- *  hands the view back to the fit, which then follows the canvas's size. */
-function FlowCornerControls({ memo }: { memo: FitMemo }) {
+/** Corner cluster: zoom in / zoom out / reset view, then the host's own.
+ *  Must render INSIDE <ReactFlow> — `useReactFlow` reads its store.
+ *  Resetting hands the view back to the fit, which then follows the
+ *  canvas's size. */
+function FlowCornerControls({
+  memo,
+  policy,
+  fitViewOptions,
+  children,
+}: {
+  memo: FitMemo;
+  policy: FlowFitPolicy;
+  fitViewOptions?: FitViewOptions;
+  children?: ReactNode;
+}) {
   const { t } = useT('common');
   const { zoomIn, zoomOut } = useReactFlow();
-  const fitAndRemember = useFitAndRemember(memo);
+  const reduced = usePrefersReducedMotion();
+  const fitAndRemember = useFitAndRemember(memo, policy);
+  const zoom = {
+    duration: reduced ? 0 : FLOW_VIEWPORT_DURATION.zoom,
+    ease: easeOutQuint,
+  };
   return (
     <Panel
       position="bottom-left"
@@ -157,7 +279,7 @@ function FlowCornerControls({ memo }: { memo: FitMemo }) {
         variant="secondary"
         title={t('flow.zoomIn')}
         tooltipSide="right"
-        onClick={() => void zoomIn({ duration: 150 })}
+        onClick={() => void zoomIn(zoom)}
       >
         <Plus className="size-4" />
       </Button>
@@ -166,7 +288,7 @@ function FlowCornerControls({ memo }: { memo: FitMemo }) {
         variant="secondary"
         title={t('flow.zoomOut')}
         tooltipSide="right"
-        onClick={() => void zoomOut({ duration: 150 })}
+        onClick={() => void zoomOut(zoom)}
       >
         <Minus className="size-4" />
       </Button>
@@ -175,26 +297,24 @@ function FlowCornerControls({ memo }: { memo: FitMemo }) {
         variant="secondary"
         title={t('flow.resetView')}
         tooltipSide="right"
-        onClick={() => void fitAndRemember({ padding: 0.2, duration: 300 })}
+        onClick={() =>
+          void fitAndRemember({
+            padding: 0.2,
+            ...fitViewOptions,
+            duration: FLOW_VIEWPORT_DURATION.fit,
+          })
+        }
       >
         <Maximize className="size-4" />
       </Button>
+      {children}
     </Panel>
   );
 }
 
-/** Bottom-center toolbar: the editor's primary actions (+ the AI toggle). */
-function FlowCenterToolbar({
-  centerActions,
-  onOpenAi,
-  aiOpen,
-}: {
-  centerActions?: ReactNode;
-  onOpenAi?: () => void;
-  aiOpen?: boolean;
-}) {
-  const { t } = useT('common');
-  if (!centerActions && !onOpenAi) return null;
+/** Bottom-center toolbar: the editor's primary actions. */
+function FlowCenterToolbar({ centerActions }: { centerActions?: ReactNode }) {
+  if (!centerActions) return null;
   return (
     <Panel
       position="bottom-center"
@@ -205,17 +325,6 @@ function FlowCenterToolbar({
         className="ring-border bg-background rounded-lg p-1 shadow-sm ring-1"
       >
         {centerActions}
-        {onOpenAi && (
-          <Button
-            variant="secondary"
-            size="icon"
-            title={t('flow.aiEditor')}
-            aria-pressed={aiOpen}
-            onClick={onOpenAi}
-          >
-            <Sparkles className="size-4" />
-          </Button>
-        )}
       </HStack>
     </Panel>
   );
@@ -225,30 +334,53 @@ export function FlowCanvas({
   backgroundProps,
   minimapProps,
   centerActions,
-  onOpenAi,
-  aiOpen,
+  cornerActions,
+  topStartActions,
+  topEndActions,
+  fitPolicy = 'all',
+  fitKey,
   children,
   ...flowProps
 }: FlowCanvasProps) {
   const { resolvedTheme } = useTheme();
   const fitMemo = useRef<Viewport | null>(null);
+  // The `auto` fit is the canvas's own: React Flow's built-in fit would show
+  // a tall graph whole at an unreadable zoom first.
+  const builtInFit = fitPolicy === 'all' && flowProps.fitView !== false;
   return (
     <ReactFlow
       colorMode={resolvedTheme}
-      fitView
       proOptions={{ hideAttribution: true }}
       {...flowProps}
+      fitView={builtInFit}
     >
       <Background {...backgroundProps} />
       {flowProps.fitView !== false && (
-        <FlowAutoFit memo={fitMemo} fitViewOptions={flowProps.fitViewOptions} />
+        <FlowAutoFit
+          memo={fitMemo}
+          fitViewOptions={flowProps.fitViewOptions}
+          policy={fitPolicy}
+          fitKey={fitKey}
+        />
+      )}
+      {topStartActions && (
+        <Panel position="top-left" className="flex items-center gap-1">
+          {topStartActions}
+        </Panel>
       )}
-      <FlowCornerControls memo={fitMemo} />
-      <FlowCenterToolbar
-        centerActions={centerActions}
-        onOpenAi={onOpenAi}
-        aiOpen={aiOpen}
-      />
+      {topEndActions && (
+        <Panel position="top-right" className="flex items-center gap-1">
+          {topEndActions}
+        </Panel>
+      )}
+      <FlowCornerControls
+        memo={fitMemo}
+        policy={fitPolicy}
+        fitViewOptions={flowProps.fitViewOptions}
+      >
+        {cornerActions}
+      </FlowCornerControls>
+      <FlowCenterToolbar centerActions={centerActions} />
       {minimapProps && <MiniMap {...minimapProps} />}
       {children}
     </ReactFlow>
diff --git a/packages/ui/src/components/flow/flow-legend.browser.test.tsx b/packages/ui/src/components/flow/flow-legend.browser.test.tsx
new file mode 100644
index 0000000000..c09a7a434e
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-legend.browser.test.tsx
@@ -0,0 +1,70 @@
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { afterEach, describe, expect, it } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+import { ratioAgainst } from '@/tests/utils/contrast';
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { FlowLegend, type FlowLegendEntry } from './flow-legend';
+
+import '../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+});
+
+const ENTRIES: FlowLegendEntry[] = [
+  { id: 'data', swatch: { edge: 'data' }, label: 'Reads the output above' },
+  { id: 'order', swatch: { edge: 'order' }, label: 'Runs after it' },
+  { id: 'yes', swatch: { edge: 'branch-yes' }, label: 'Yes' },
+  { id: 'no', swatch: { edge: 'branch-no' }, label: 'No' },
+  {
+    id: 'done',
+    swatch: { edge: 'completion' },
+    label: 'The run ends after it',
+  },
+  { id: 'dashed', swatch: { node: 'dashed' }, label: 'May not run' },
+  { id: 'frame', swatch: { node: 'frame' }, label: 'Runs once per item' },
+];
+
+describe('FlowLegend', () => {
+  it.each(['light', 'dark'])(
+    'opens how to read the chart, each mark in its real colour (%s)',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      render(<FlowLegend entries={ENTRIES} />);
+      const button = screen.getByRole('button', { name: 'Legend' });
+      await userEvent.click(button);
+      const dialog = await screen.findByRole('dialog', {
+        name: 'How to read the chart',
+      });
+      // The popover fades in; colours are judged once it is fully there.
+      await Promise.all(
+        document.getAnimations().map((animation) => animation.finished),
+      );
+      for (const entry of ENTRIES)
+        expect(dialog).toHaveTextContent(entry.label);
+      // Every line keeps 3:1 on the popover.
+      for (const path of dialog.querySelectorAll('svg path:first-child')) {
+        expect(
+          ratioAgainst(dialog, getComputedStyle(path).stroke),
+          `${theme} swatch`,
+        ).toBeGreaterThanOrEqual(3);
+      }
+      const result = await axe.run(dialog, {
+        runOnly: ['color-contrast', 'aria-dialog-name', 'list', 'listitem'],
+      });
+      expect(result.violations).toEqual([]);
+      await userEvent.keyboard('{Escape}');
+      await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+      expect(document.activeElement).toBe(button);
+    },
+  );
+
+  it('renders nothing without entries', () => {
+    const { container } = render(<FlowLegend entries={[]} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+});
diff --git a/packages/ui/src/components/flow/flow-legend.tsx b/packages/ui/src/components/flow/flow-legend.tsx
new file mode 100644
index 0000000000..939424ee80
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-legend.tsx
@@ -0,0 +1,116 @@
+'use client';
+
+import { CircleHelp } from 'lucide-react';
+import { useId } from 'react';
+
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import { Popover } from '../overlays/popover';
+import { Button } from '../primitives/button';
+import {
+  FLOW_EDGE_COLORS,
+  FLOW_EDGE_STROKE,
+  flowEdgeDash,
+  flowEdgeTone,
+} from './edge-palette';
+import type { FlowEdgeKind } from './types';
+
+/** One line of the legend: what a mark looks like and what it means. */
+export interface FlowLegendEntry {
+  id: string;
+  /** A line of this edge kind, or one of the boxes. */
+  swatch: { edge: FlowEdgeKind } | { node: 'dashed' | 'gate' | 'frame' };
+  /** The meaning, in the host's words. */
+  label: string;
+}
+
+/** A 32 × 12 picture of the mark, drawn with the canvas's own tokens. */
+function Swatch({ swatch }: { swatch: FlowLegendEntry['swatch'] }) {
+  if ('edge' in swatch) {
+    const color = FLOW_EDGE_COLORS[flowEdgeTone(swatch.edge)];
+    return (
+      <svg
+        aria-hidden="true"
+        width={32}
+        height={12}
+        viewBox="0 0 32 12"
+        className="shrink-0"
+      >
+        <path
+          d="M1 6 H24"
+          fill="none"
+          strokeWidth={FLOW_EDGE_STROKE.base}
+          strokeDasharray={flowEdgeDash(swatch.edge)}
+          strokeLinecap={swatch.edge === 'completion' ? 'round' : 'butt'}
+          style={{ stroke: color }}
+        />
+        <path d="M24 1 L31 6 L24 11 Z" style={{ fill: color }} />
+      </svg>
+    );
+  }
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        'border-muted-foreground bg-card inline-block h-3 w-8 shrink-0 border',
+        swatch.node === 'dashed' && 'rounded-sm border-dashed',
+        swatch.node === 'gate' && 'rounded-full',
+        swatch.node === 'frame' && 'bg-muted/30 rounded-sm border-dashed',
+      )}
+    />
+  );
+}
+
+/**
+ * How to read the chart: a button in the canvas's corner cluster that opens
+ * a popover with one line per mark — each drawn with the real stroke or box
+ * style beside the host's words for it. The host decides which marks its
+ * charts use and what they mean.
+ */
+export function FlowLegend({
+  entries,
+  className,
+}: {
+  entries: readonly FlowLegendEntry[];
+  className?: string;
+}) {
+  const { t } = useT('flow');
+  const titleId = useId();
+  if (entries.length === 0) return null;
+  return (
+    <Popover
+      side="right"
+      align="end"
+      aria-labelledby={titleId}
+      contentClassName="max-w-80"
+      trigger={
+        <Button
+          size="icon"
+          variant="secondary"
+          title={t('controls.legend')}
+          tooltipSide="right"
+          className={className}
+        >
+          <CircleHelp className="size-4" />
+        </Button>
+      }
+    >
+      <h2 id={titleId} className="mb-2 text-sm font-medium">
+        {t('legend.title')}
+      </h2>
+      <ul className="flex flex-col gap-2">
+        {entries.map((entry) => (
+          <li
+            key={entry.id}
+            className="flex items-start gap-3 text-xs leading-4"
+          >
+            <span className="flex h-4 items-center">
+              <Swatch swatch={entry.swatch} />
+            </span>
+            <span>{entry.label}</span>
+          </li>
+        ))}
+      </ul>
+    </Popover>
+  );
+}
diff --git a/packages/ui/src/components/flow/flow-step-list.browser.test.tsx b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
new file mode 100644
index 0000000000..a5ab562f19
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
@@ -0,0 +1,131 @@
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+import { render, screen, within } from '@/tests/utils/render';
+
+import { FlowStepList } from './flow-step-list';
+import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+import type { FlowGraph } from './types';
+
+import '../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+});
+
+function Harness({
+  graph,
+  onSelect,
+}: {
+  graph: FlowGraph;
+  onSelect?: (id: string | null) => void;
+}) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <FlowStepList
+      graph={graph}
+      aria-label="Nodes of Triage"
+      selectedId={selected}
+      onSelect={(id) => {
+        setSelected(id);
+        onSelect?.(id);
+      }}
+      issues={new Map([['report', { errors: 1, warnings: 0 }]])}
+    />
+  );
+}
+
+describe('FlowStepList', () => {
+  it('lists Start, every node in order and End, frames indented', () => {
+    render(<Harness graph={triageFlowGraph()} />);
+    const list = screen.getByRole('list', { name: 'Nodes of Triage' });
+    const names = within(list)
+      .getAllByRole('button')
+      .map((button) => button.getAttribute('aria-label'));
+    expect(names).toEqual([
+      'Start',
+      'Issues',
+      'Open issues',
+      'Score',
+      'Report (1 error)',
+      'End',
+    ]);
+    // Score sits in a nested list under its frame's words.
+    const score = screen.getByRole('button', { name: 'Score' });
+    expect(score.closest('ol')).not.toBe(list);
+    expect(
+      score.closest('li')?.parentElement?.closest('li')?.textContent,
+    ).toContain('For each item of issues of Open issues');
+    expect(score).toHaveAccessibleDescription(
+      /Reads Open issues and each item/,
+    );
+  });
+
+  it('folds a condition into the node it guards', () => {
+    render(<Harness graph={branchFlowGraph()} />);
+    expect(screen.queryByRole('button', { name: /^Condition for/ })).toBeNull();
+    expect(
+      screen.getByRole('button', { name: 'Urgent' }),
+    ).toHaveAccessibleDescription(/Runs only if urgent of Classify is true/);
+    expect(
+      screen.getByRole('button', { name: 'Low' }),
+    ).toHaveAccessibleDescription(/Runs when the condition of Normal is false/);
+  });
+
+  it('is one Tab stop: arrows move, Home and End jump, Enter opens', async () => {
+    const onSelect = vi.fn();
+    render(<Harness graph={triageFlowGraph()} onSelect={onSelect} />);
+    const buttons = screen.getAllByRole('button');
+    expect(buttons.filter((button) => button.tabIndex === 0)).toHaveLength(1);
+    await userEvent.tab();
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Start' }),
+    );
+    await userEvent.keyboard('{ArrowDown}{ArrowDown}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Open issues' }),
+    );
+    await userEvent.keyboard('{End}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'End' }),
+    );
+    await userEvent.keyboard('{Home}{ArrowDown}{Enter}');
+    expect(onSelect).toHaveBeenLastCalledWith('issues');
+    expect(screen.getByRole('button', { name: 'Issues' })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    );
+  });
+
+  it.each(['light', 'dark'])('passes axe (%s)', async (theme) => {
+    document.documentElement.classList.toggle('dark', theme === 'dark');
+    const { container } = render(<Harness graph={branchFlowGraph()} />);
+    const result = await axe.run(container, {
+      runOnly: [
+        'color-contrast',
+        'list',
+        'listitem',
+        'button-name',
+        'aria-allowed-attr',
+        'aria-valid-attr-value',
+      ],
+    });
+    expect(result.violations).toEqual([]);
+  });
+
+  it('is named "Nodes" unless the host names it', () => {
+    render(<FlowStepList graph={triageFlowGraph()} />);
+    expect(screen.getByRole('list', { name: 'Nodes' })).toBeInTheDocument();
+  });
+
+  it('says so when there is nothing to list', () => {
+    render(
+      <FlowStepList graph={{ nodes: [], edges: [] }} aria-label="Nodes" />,
+    );
+    expect(screen.getByText('No nodes yet')).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/flow/flow-step-list.tsx b/packages/ui/src/components/flow/flow-step-list.tsx
new file mode 100644
index 0000000000..5b3a06c638
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-step-list.tsx
@@ -0,0 +1,270 @@
+'use client';
+
+import { Box, Flag, Play, RefreshCw, Repeat } from 'lucide-react';
+import {
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import type { IssueCounts } from '../feedback/issue-summary';
+import { describeFlowGraph, flowListFormat, type FlowWords } from './describe';
+import {
+  FlowNodeIssueMarker,
+  flowNodeIssueFrameClass,
+} from './node-issue-marker';
+import type { FlowGraph, FlowGroup, FlowNode } from './types';
+
+export interface FlowStepListProps {
+  graph: FlowGraph;
+  /** The list's name; "Nodes" in the session's language when left out. */
+  'aria-label'?: string;
+  selectedId?: string | null;
+  onSelect?: (id: string | null) => void;
+  /** Problem counts by node id. */
+  issues?: ReadonlyMap<string, IssueCounts>;
+  /** The region a row's button opens (an inspector), if the host has one. */
+  controlsId?: string;
+  className?: string;
+}
+
+const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
+
+type Item =
+  | { kind: 'node'; node: FlowNode }
+  | { kind: 'frame'; group: FlowGroup; nodes: FlowNode[] };
+
+/** Nodes in reading order, conditions folded into the step they guard,
+ *  each frame's members under it. */
+function itemsOf(graph: FlowGraph): Item[] {
+  const groupOf = new Map<string, FlowGroup>();
+  for (const group of graph.groups ?? [])
+    for (const member of group.members) groupOf.set(member, group);
+  const items: Item[] = [];
+  for (const node of graph.nodes) {
+    if (node.kind === 'gate') continue;
+    const group = groupOf.get(node.id);
+    const last = items.at(-1);
+    if (group === undefined) items.push({ kind: 'node', node });
+    else if (last?.kind === 'frame' && last.group.id === group.id)
+      last.nodes.push(node);
+    else items.push({ kind: 'frame', group, nodes: [node] });
+  }
+  return items;
+}
+
+function iconOf(node: FlowNode) {
+  if (node.kind === 'entry') return Play;
+  if (node.kind === 'exit') return Flag;
+  if (node.kind === 'step') return node.icon ?? Box;
+  return Box;
+}
+
+/**
+ * The chart as a list — its text alternative, and the List view of a
+ * workflow canvas: Start, every node in reading order, End, as an ordered
+ * list of buttons. Each row says what the node is and, under it, what it
+ * reads, when it runs (its condition folded in) and where it leads; members
+ * of a frame sit indented under the frame's words. One Tab stop: ↑ and ↓
+ * move between rows, Home and End jump, Enter or Space opens a row.
+ */
+export function FlowStepList({
+  graph,
+  'aria-label': ariaLabel,
+  selectedId = null,
+  onSelect,
+  issues,
+  controlsId,
+  className,
+}: FlowStepListProps) {
+  const { t } = useT('flow');
+  const { t: tIssues } = useT('issues');
+  const { i18n } = useTranslation();
+  const locale = i18n?.resolvedLanguage ?? i18n?.language ?? 'en';
+  const baseId = useId();
+  const words = useMemo(
+    () =>
+      describeFlowGraph(graph, {
+        t,
+        tIssues,
+        list: flowListFormat(locale),
+        issues,
+      }),
+    [graph, t, tIssues, locale, issues],
+  );
+  const items = useMemo(() => itemsOf(graph), [graph]);
+  const order = useMemo(
+    () =>
+      items.flatMap((item) =>
+        item.kind === 'node'
+          ? [item.node.id]
+          : item.nodes.map((node) => node.id),
+      ),
+    [items],
+  );
+  const [focused, setFocused] = useState<string | null>(null);
+  const tabStop =
+    [selectedId, focused].find((id) => id !== null && order.includes(id)) ??
+    order[0] ??
+    null;
+  const listRef = useRef<HTMLOListElement>(null);
+
+  const move = (from: string, event: KeyboardEvent<HTMLButtonElement>) => {
+    const at = order.indexOf(from);
+    const next =
+      event.key === 'ArrowDown'
+        ? order[at + 1]
+        : event.key === 'ArrowUp'
+          ? order[at - 1]
+          : event.key === 'Home'
+            ? order[0]
+            : event.key === 'End'
+              ? order.at(-1)
+              : undefined;
+    if (next === undefined) return;
+    event.preventDefault();
+    listRef.current
+      ?.querySelector<HTMLButtonElement>(
+        `[data-flow-row="${CSS.escape(next)}"]`,
+      )
+      ?.focus();
+  };
+
+  if (order.length === 0) {
+    return (
+      <p className={cn('text-muted-foreground p-4 text-sm', className)}>
+        {t('list.empty')}
+      </p>
+    );
+  }
+
+  const row = (node: FlowNode): ReactNode => (
+    <FlowListRow
+      key={node.id}
+      node={node}
+      words={words}
+      baseId={baseId}
+      selected={selectedId === node.id}
+      tabbable={tabStop === node.id}
+      counts={issues?.get(node.id) ?? NO_ISSUES}
+      controlsId={controlsId}
+      onActivate={() => onSelect?.(selectedId === node.id ? null : node.id)}
+      onKeyDown={(event) => move(node.id, event)}
+      onFocus={() => setFocused(node.id)}
+    />
+  );
+
+  return (
+    <ol
+      ref={listRef}
+      aria-label={ariaLabel ?? t('list.label')}
+      className={cn('flex flex-col gap-1 p-3', className)}
+    >
+      {items.map((item) =>
+        item.kind === 'node' ? (
+          row(item.node)
+        ) : (
+          <li key={item.group.id} className="flex flex-col gap-1">
+            <span className="text-muted-foreground flex items-center gap-1.5 px-2 pt-1 text-xs font-medium">
+              {item.group.kind === 'repeat' ? (
+                <RefreshCw aria-hidden="true" className="size-3.5 shrink-0" />
+              ) : (
+                <Repeat aria-hidden="true" className="size-3.5 shrink-0" />
+              )}
+              {item.group.label}
+            </span>
+            <ol className="border-border ml-3 flex flex-col gap-1 border-l border-dashed pl-2">
+              {item.nodes.map(row)}
+            </ol>
+          </li>
+        ),
+      )}
+    </ol>
+  );
+}
+
+function FlowListRow({
+  node,
+  words,
+  baseId,
+  selected,
+  tabbable,
+  counts,
+  controlsId,
+  onActivate,
+  onKeyDown,
+  onFocus,
+}: {
+  node: FlowNode;
+  words: FlowWords;
+  baseId: string;
+  selected: boolean;
+  tabbable: boolean;
+  counts: IssueCounts;
+  controlsId?: string;
+  onActivate: () => void;
+  onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+  onFocus: () => void;
+}) {
+  const Icon = iconOf(node);
+  const lines = words.lines.get(node.id) ?? [];
+  const linesId = `${baseId}-lines-${node.id}`;
+  const disclosure = controlsId !== undefined;
+  return (
+    <li className="flex flex-col">
+      <button
+        type="button"
+        data-flow-row={node.id}
+        tabIndex={tabbable ? 0 : -1}
+        aria-label={words.names.get(node.id)}
+        aria-describedby={lines.length > 0 ? linesId : undefined}
+        aria-pressed={disclosure ? undefined : selected}
+        aria-expanded={disclosure ? selected : undefined}
+        aria-controls={disclosure && selected ? controlsId : undefined}
+        onClick={onActivate}
+        onKeyDown={onKeyDown}
+        onFocus={onFocus}
+        className={cn(
+          'hover:bg-muted/60 flex min-h-9 w-full cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-1.5 text-left',
+          'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none',
+          flowNodeIssueFrameClass(counts),
+          selected && 'bg-muted ring-ring ring-2',
+        )}
+      >
+        <span className="bg-muted text-muted-foreground flex size-5 shrink-0 items-center justify-center rounded-md">
+          <Icon aria-hidden="true" className="size-3.5" />
+        </span>
+        <span className="min-w-0 flex-1">
+          <span className="block truncate text-sm font-medium">
+            {words.titles.get(node.id)}
+          </span>
+          {node.kind === 'step' && node.typeLabel && (
+            <span className="text-muted-foreground block truncate text-xs">
+              {node.typeLabel}
+            </span>
+          )}
+        </span>
+        <FlowNodeIssueMarker
+          errors={counts.errors}
+          warnings={counts.warnings}
+        />
+      </button>
+      {lines.length > 0 && (
+        <span
+          id={linesId}
+          className="text-muted-foreground flex flex-col pr-2 pl-9 text-xs leading-5"
+        >
+          {lines.map((line) => (
+            <span key={line}>{line}</span>
+          ))}
+        </span>
+      )}
+    </li>
+  );
+}
diff --git a/packages/ui/src/components/flow/node-status.test.tsx b/packages/ui/src/components/flow/node-status.test.tsx
new file mode 100644
index 0000000000..077be4fb6e
--- /dev/null
+++ b/packages/ui/src/components/flow/node-status.test.tsx
@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import { render, screen } from '@/tests/utils/render';
+
+import {
+  FLOW_NODE_STATE,
+  FlowNodeStatusBadge,
+  FlowNodeStatusIcon,
+  type FlowShownState,
+} from './node-status';
+
+const STATES = Object.keys(FLOW_NODE_STATE) as FlowShownState[];
+
+describe('the flow node status vocabulary', () => {
+  it('gives every state its own glyph and its own word', () => {
+    const icons = new Set(STATES.map((state) => FLOW_NODE_STATE[state].icon));
+    expect(icons.size).toBe(STATES.length);
+    for (const state of STATES) {
+      render(<FlowNodeStatusIcon state={state} />);
+    }
+    const names = screen
+      .getAllByRole('img')
+      .map((img) => img.getAttribute('aria-label'));
+    expect(names).toEqual([
+      'Not reached yet',
+      'Running',
+      'Waiting',
+      'Succeeded',
+      'Failed',
+      'Skipped',
+      'Stopped here',
+      'Not run',
+    ]);
+  });
+
+  it('never paints a glyph in slate-400, which is too faint', () => {
+    for (const state of STATES)
+      expect(FLOW_NODE_STATE[state].iconClass).not.toMatch(/slate-400/);
+  });
+
+  it('shows nothing while no run is shown', () => {
+    const { container } = render(
+      <>
+        <FlowNodeStatusIcon state="idle" />
+        <FlowNodeStatusBadge state="idle" />
+      </>,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('says the state in a badge', () => {
+    render(<FlowNodeStatusBadge state="failed" />);
+    expect(screen.getByText('Failed')).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/flow/node-status.tsx b/packages/ui/src/components/flow/node-status.tsx
new file mode 100644
index 0000000000..320643d657
--- /dev/null
+++ b/packages/ui/src/components/flow/node-status.tsx
@@ -0,0 +1,153 @@
+'use client';
+
+import {
+  Ban,
+  CircleCheck,
+  CircleDashed,
+  CircleMinus,
+  CircleX,
+  Clock,
+  Hourglass,
+  LoaderCircle,
+  type LucideIcon,
+} from 'lucide-react';
+import type { ComponentProps } from 'react';
+
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import { Badge } from '../feedback/badge';
+import type { FlowIcon } from './types';
+
+/**
+ * The one vocabulary for where a node stands in a run — the canvas, the List
+ * view, a run's step list and a badge all say it the same way. Every state
+ * has its own glyph and its own word, so none is told by colour alone.
+ */
+export type FlowNodeState =
+  /** No run is shown. */
+  | 'idle'
+  | 'pending'
+  | 'running'
+  | 'waiting'
+  | 'succeeded'
+  | 'failed'
+  | 'skipped'
+  | 'stopped'
+  | 'not-run';
+
+export type FlowShownState = Exclude<FlowNodeState, 'idle'>;
+
+/** Spins unless the reader asked for less motion. */
+function SpinningLoader({ className, ...props }: ComponentProps<LucideIcon>) {
+  return (
+    <LoaderCircle
+      {...props}
+      className={cn(className, 'motion-safe:animate-spin')}
+    />
+  );
+}
+
+/**
+ * Glyph, badge tint, glyph colour and the key of the state's word (in the
+ * `flow` namespace). Every glyph colour keeps 3:1 on the page, a card and
+ * a muted fill in both themes (none is `slate-400`, which read 2.6:1).
+ */
+export const FLOW_NODE_STATE: Readonly<
+  Record<
+    FlowShownState,
+    {
+      icon: FlowIcon;
+      badge: 'blue' | 'yellow' | 'green' | 'destructive' | 'slate';
+      iconClass: string;
+      labelKey: string;
+    }
+  >
+> = {
+  pending: {
+    icon: Clock,
+    badge: 'slate',
+    iconClass: 'text-muted-foreground',
+    labelKey: 'state.pending',
+  },
+  running: {
+    icon: SpinningLoader,
+    badge: 'blue',
+    iconClass: 'text-[hsl(var(--info-foreground))]',
+    labelKey: 'state.running',
+  },
+  waiting: {
+    icon: Hourglass,
+    badge: 'yellow',
+    iconClass: 'text-amber-700 dark:text-amber-500',
+    labelKey: 'state.waiting',
+  },
+  succeeded: {
+    icon: CircleCheck,
+    badge: 'green',
+    iconClass: 'text-[hsl(var(--success))]',
+    labelKey: 'state.succeeded',
+  },
+  failed: {
+    icon: CircleX,
+    badge: 'destructive',
+    iconClass: 'text-destructive',
+    labelKey: 'state.failed',
+  },
+  skipped: {
+    icon: CircleMinus,
+    badge: 'slate',
+    iconClass: 'text-muted-foreground',
+    labelKey: 'state.skipped',
+  },
+  stopped: {
+    icon: Ban,
+    badge: 'slate',
+    iconClass: 'text-muted-foreground',
+    labelKey: 'state.stopped',
+  },
+  'not-run': {
+    icon: CircleDashed,
+    badge: 'slate',
+    iconClass: 'text-muted-foreground',
+    labelKey: 'state.notRun',
+  },
+};
+
+/** The state's word in the session's language ("Skipped"). */
+export function useFlowNodeStateLabel(): (state: FlowShownState) => string {
+  const { t } = useT('flow');
+  return (state) => t(FLOW_NODE_STATE[state].labelKey);
+}
+
+/** The state's glyph, named for a screen reader; nothing while idle. */
+export function FlowNodeStatusIcon({
+  state,
+  className,
+}: {
+  state: FlowNodeState;
+  className?: string;
+}) {
+  const label = useFlowNodeStateLabel();
+  if (state === 'idle') return null;
+  const { icon: Icon, iconClass } = FLOW_NODE_STATE[state];
+  return (
+    <span role="img" aria-label={label(state)} className="inline-flex">
+      <Icon
+        aria-hidden="true"
+        className={cn('size-4 shrink-0', iconClass, className)}
+      />
+    </span>
+  );
+}
+
+/** The state as a badge — glyph and word; nothing while idle. */
+export function FlowNodeStatusBadge({ state }: { state: FlowNodeState }) {
+  const label = useFlowNodeStateLabel();
+  if (state === 'idle') return null;
+  const { icon, badge } = FLOW_NODE_STATE[state];
+  return (
+    <Badge variant={badge} icon={icon}>
+      {label(state)}
+    </Badge>
+  );
+}
diff --git a/packages/ui/src/components/flow/render/edge-markers.tsx b/packages/ui/src/components/flow/render/edge-markers.tsx
new file mode 100644
index 0000000000..6c828ff618
--- /dev/null
+++ b/packages/ui/src/components/flow/render/edge-markers.tsx
@@ -0,0 +1,46 @@
+import {
+  FLOW_EDGE_ARROW,
+  FLOW_EDGE_COLORS,
+  FLOW_EDGE_TONES,
+  type FlowEdgeTone,
+} from '../edge-palette';
+
+/** The id of a canvas's arrowhead in `tone`. */
+export const flowArrowId = (baseId: string, tone: FlowEdgeTone) =>
+  `${baseId}-arrow-${tone}`;
+
+/**
+ * One closed arrowhead per edge colour, defined once per canvas: a tinted
+ * edge ends in an arrow of its own tint. The arrow's base sits where the
+ * stroke stops and its tip on the route's end point — the target box's
+ * border — so the line never pokes through the tip.
+ */
+export function FlowEdgeMarkers({ baseId }: { baseId: string }) {
+  const { length, width } = FLOW_EDGE_ARROW;
+  return (
+    <svg
+      aria-hidden="true"
+      className="pointer-events-none absolute size-0 overflow-hidden"
+    >
+      <defs>
+        {FLOW_EDGE_TONES.map((tone) => (
+          <marker
+            key={tone}
+            id={flowArrowId(baseId, tone)}
+            markerUnits="userSpaceOnUse"
+            markerWidth={length}
+            markerHeight={width}
+            refX={0}
+            refY={width / 2}
+            orient="auto"
+          >
+            <path
+              d={`M0 0 L${length} ${width / 2} L0 ${width} Z`}
+              style={{ fill: FLOW_EDGE_COLORS[tone] }}
+            />
+          </marker>
+        ))}
+      </defs>
+    </svg>
+  );
+}
diff --git a/packages/ui/src/components/flow/render/entry-node.tsx b/packages/ui/src/components/flow/render/entry-node.tsx
new file mode 100644
index 0000000000..0cce3d6fe9
--- /dev/null
+++ b/packages/ui/src/components/flow/render/entry-node.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import type { NodeProps } from '@xyflow/react';
+import { Play, TriangleAlert, Info } from 'lucide-react';
+import { memo } from 'react';
+
+import { useT } from '../../../i18n/client';
+import { cn } from '../../../lib/cn';
+import { flowNodeTitle } from '../describe';
+import { FLOW_SECTION_ROWS, visibleRows } from '../layout/sizes';
+import type { FlowEntryNode, FlowNotice, FlowRow } from '../types';
+import { FlowNodeButton, FlowNodeStrip } from './flow-render-context';
+import { FlowNodeTitleRow, type FlowNodeData } from './step-node';
+
+/** One line of a Start or End section: icon, words, detail, a state word;
+ *  20 px, plus 16 for a note. */
+function FlowRowLine({ row }: { row: FlowRow }) {
+  const Icon = row.icon;
+  return (
+    <span className="flex flex-col">
+      <span className="flex h-5 items-center gap-1.5 text-xs leading-4">
+        {Icon ? (
+          <Icon className="text-muted-foreground size-3.5 shrink-0" />
+        ) : null}
+        <span className="flex min-w-0 flex-1 items-baseline gap-1">
+          <span
+            className={cn(
+              'text-foreground max-w-full shrink-0 truncate',
+              row.code && 'font-mono',
+            )}
+          >
+            {row.label}
+          </span>
+          {row.detail && (
+            <span className="text-muted-foreground min-w-0 truncate">
+              · {row.detail}
+            </span>
+          )}
+        </span>
+        {row.badge && (
+          <span
+            className={cn(
+              'shrink-0 rounded-full px-1.5 text-xs leading-4 font-medium',
+              row.badge.tone === 'warning'
+                ? 'bg-amber-500/15 text-amber-800 dark:text-amber-300'
+                : 'bg-muted text-muted-foreground',
+            )}
+          >
+            {row.badge.label}
+          </span>
+        )}
+      </span>
+      {row.note && (
+        <span
+          className={cn(
+            'text-muted-foreground h-4 truncate text-xs leading-4',
+            Icon && 'pl-5',
+          )}
+        >
+          {row.note}
+        </span>
+      )}
+    </span>
+  );
+}
+
+/** A section of Start or End: its heading, at most `max` row slots (the
+ *  rest as "+n more"), or one line of words when it has no rows. */
+export function FlowNodeSection({
+  heading,
+  rows,
+  max,
+  empty,
+}: {
+  heading: string;
+  rows: readonly FlowRow[];
+  max: number;
+  empty: string;
+}) {
+  const { t } = useT('flow');
+  const { shown, more } = visibleRows(rows, max);
+  return (
+    <span className="mt-2 flex flex-col">
+      <span className="text-muted-foreground mb-1 h-4 text-xs leading-4 font-medium">
+        {heading}
+      </span>
+      {rows.length === 0 ? (
+        <span className="text-muted-foreground flex h-5 items-center text-xs">
+          {empty}
+        </span>
+      ) : (
+        shown.map((row) => <FlowRowLine key={row.id} row={row} />)
+      )}
+      {more > 0 && (
+        <span className="text-muted-foreground flex h-5 items-center text-xs">
+          {t('node.more', { count: more })}
+        </span>
+      )}
+    </span>
+  );
+}
+
+/** A warning or a note at the foot of Start or End: one line, 28 px. */
+export function FlowNodeNotice({ notice }: { notice: FlowNotice }) {
+  const Icon = notice.tone === 'warning' ? TriangleAlert : Info;
+  return (
+    <span className="mt-2 flex h-7 items-center gap-1.5 text-xs leading-4">
+      <Icon
+        aria-hidden="true"
+        className={cn(
+          'size-3.5 shrink-0',
+          notice.tone === 'warning'
+            ? 'text-amber-700 dark:text-amber-500'
+            : 'text-muted-foreground',
+        )}
+      />
+      <span className="text-foreground truncate" title={notice.text}>
+        {notice.text}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * Start: what starts a run (triggers in words) and what each run receives
+ * (its input fields), above everything else. Its strip names the nodes it
+ * leads to.
+ */
+export const FlowEntryNodeView = memo(function FlowEntryNodeView({
+  data,
+}: NodeProps & { data: FlowNodeData<FlowEntryNode> }) {
+  const { t } = useT('flow');
+  const { node } = data;
+  return (
+    <FlowNodeButton
+      id={node.id}
+      className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
+    >
+      <span className="flex min-h-0 flex-1 flex-col px-3 pt-3">
+        <FlowNodeTitleRow
+          id={node.id}
+          icon={Play}
+          title={flowNodeTitle(node, t)}
+        />
+        {node.triggers.length > 0 && (
+          <FlowNodeSection
+            heading={t('node.triggers')}
+            rows={node.triggers}
+            max={FLOW_SECTION_ROWS.triggers}
+            empty=""
+          />
+        )}
+        <FlowNodeSection
+          heading={t('node.inputs')}
+          rows={node.inputs}
+          max={FLOW_SECTION_ROWS.inputs}
+          empty={node.inputsEmpty ?? t('node.noInput')}
+        />
+        {node.notice && <FlowNodeNotice notice={node.notice} />}
+      </span>
+      <FlowNodeStrip id={node.id} />
+    </FlowNodeButton>
+  );
+});
diff --git a/packages/ui/src/components/flow/render/exit-node.tsx b/packages/ui/src/components/flow/render/exit-node.tsx
new file mode 100644
index 0000000000..5acf6e7cf8
--- /dev/null
+++ b/packages/ui/src/components/flow/render/exit-node.tsx
@@ -0,0 +1,61 @@
+'use client';
+
+import type { NodeProps } from '@xyflow/react';
+import { Flag } from 'lucide-react';
+import { memo } from 'react';
+
+import { useT } from '../../../i18n/client';
+import { flowNodeTitle } from '../describe';
+import { FLOW_SECTION_ROWS } from '../layout/sizes';
+import type { FlowExitNode } from '../types';
+import { FlowNodeNotice, FlowNodeSection } from './entry-node';
+import { FlowNodeButton, FlowNodeStrip } from './flow-render-context';
+import { FlowNodeTitleRow, type FlowNodeData } from './step-node';
+
+/**
+ * End: what a successful run returns (and its shape) and every way a run
+ * can end, below everything else. Its strip names the nodes that finish
+ * the run.
+ */
+export const FlowExitNodeView = memo(function FlowExitNodeView({
+  data,
+}: NodeProps & { data: FlowNodeData<FlowExitNode> }) {
+  const { t } = useT('flow');
+  const { node } = data;
+  const outcomes = node.outcomes ?? [];
+  return (
+    <FlowNodeButton
+      id={node.id}
+      className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
+    >
+      <span className="flex min-h-0 flex-1 flex-col px-3 pt-3">
+        <FlowNodeTitleRow
+          id={node.id}
+          icon={Flag}
+          title={flowNodeTitle(node, t)}
+        />
+        <FlowNodeSection
+          heading={t('node.outputs')}
+          rows={node.outputs}
+          max={FLOW_SECTION_ROWS.outputs}
+          empty={node.outputsEmpty ?? t('node.noOutput')}
+        />
+        {node.shape && (
+          <span className="text-muted-foreground mt-1 h-4 truncate font-mono text-xs leading-4">
+            {node.shape}
+          </span>
+        )}
+        {outcomes.length > 0 && (
+          <FlowNodeSection
+            heading={t('node.outcomes')}
+            rows={outcomes}
+            max={FLOW_SECTION_ROWS.outcomes}
+            empty=""
+          />
+        )}
+        {node.notice && <FlowNodeNotice notice={node.notice} />}
+      </span>
+      <FlowNodeStrip id={node.id} />
+    </FlowNodeButton>
+  );
+});
diff --git a/packages/ui/src/components/flow/render/flow-render-context.tsx b/packages/ui/src/components/flow/render/flow-render-context.tsx
new file mode 100644
index 0000000000..e966b2a5c2
--- /dev/null
+++ b/packages/ui/src/components/flow/render/flow-render-context.tsx
@@ -0,0 +1,155 @@
+'use client';
+
+import { Handle, Position } from '@xyflow/react';
+import {
+  createContext,
+  useContext,
+  type FocusEvent,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import { cn } from '../../../lib/cn';
+import type { IssueCounts } from '../../feedback/issue-summary';
+import { Tooltip } from '../../overlays/tooltip';
+import { flowNodeIssueFrameClass } from '../node-issue-marker';
+
+/**
+ * What the chart hands every box: kept in context rather than in React
+ * Flow's node data, so moving the selection or the focus re-renders the
+ * boxes without rebuilding the node array React Flow lays out.
+ */
+export interface FlowRenderContextValue {
+  /** Prefix for the ids of the hidden names and descriptions. */
+  baseId: string;
+  selectedId: string | null;
+  /** The node that holds the chart's one Tab stop. */
+  tabStopId: string | null;
+  /** The region a node's button opens (an inspector), if the host has one. */
+  controlsId?: string;
+  issues: ReadonlyMap<string, IssueCounts>;
+  names: ReadonlyMap<string, string>;
+  descriptions: ReadonlyMap<string, string>;
+  strips: ReadonlyMap<string, string>;
+  onActivate: (id: string) => void;
+  onKeyDown: (id: string, event: KeyboardEvent<HTMLButtonElement>) => void;
+  onFocusNode: (id: string, event: FocusEvent<HTMLButtonElement>) => void;
+}
+
+const FlowRenderContext = createContext<FlowRenderContextValue | null>(null);
+
+export const FlowRenderProvider = FlowRenderContext.Provider;
+
+export function useFlowRender(): FlowRenderContextValue {
+  const value = useContext(FlowRenderContext);
+  if (value === null)
+    throw new Error('A flow node must render inside <WorkflowCanvas>.');
+  return value;
+}
+
+const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
+
+/** The id of a node's hidden description. */
+export const flowDescriptionId = (baseId: string, nodeId: string) =>
+  `${baseId}-description-${nodeId}`;
+
+/**
+ * Hover lifts a box: a `shadow-md` layer fades in over its resting shadow
+ * (a shadow itself never animates).
+ */
+export const FLOW_NODE_LIFT =
+  'after:pointer-events-none after:absolute after:inset-[-1px] after:rounded-[inherit] after:opacity-0 after:shadow-md after:transition-opacity after:duration-[var(--duration-short)] after:ease-[var(--ease-out-quint)] hover:after:opacity-100';
+
+/** Selection and keyboard focus draw the same ring; a problem keeps its own
+ *  frame colour beside it. */
+export const FLOW_NODE_RING =
+  'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none';
+
+/**
+ * A box on the chart: one real `<button>` (no control inside it), named and
+ * described for a screen reader, holding the chart's roving Tab stop when it
+ * is its turn. The handles are invisible stubs React Flow needs to attach
+ * edges; every line is drawn from the layout's own routes.
+ */
+export function FlowNodeButton({
+  id,
+  className,
+  children,
+  dashed = false,
+  tooltip,
+}: {
+  id: string;
+  className?: string;
+  children: ReactNode;
+  dashed?: boolean;
+  /** Pointer-hover words (the full condition of a gate). */
+  tooltip?: ReactNode;
+}) {
+  const context = useFlowRender();
+  const selected = context.selectedId === id;
+  const counts = context.issues.get(id) ?? NO_ISSUES;
+  const descriptionId = flowDescriptionId(context.baseId, id);
+  const disclosure = context.controlsId !== undefined;
+  const button = (
+    <button
+      type="button"
+      data-flow-node={id}
+      tabIndex={context.tabStopId === id ? 0 : -1}
+      aria-label={context.names.get(id)}
+      aria-describedby={descriptionId}
+      aria-pressed={disclosure ? undefined : selected}
+      aria-expanded={disclosure ? selected : undefined}
+      aria-controls={disclosure && selected ? context.controlsId : undefined}
+      onClick={() => context.onActivate(id)}
+      onKeyDown={(event) => context.onKeyDown(id, event)}
+      onFocus={(event) => context.onFocusNode(id, event)}
+      className={cn(
+        'relative block size-full cursor-pointer text-left',
+        FLOW_NODE_LIFT,
+        FLOW_NODE_RING,
+        dashed && 'border-dashed',
+        // The frame takes the worst problem's colour; the selection ring
+        // stays its own, so a picked node with a problem shows both.
+        flowNodeIssueFrameClass(counts),
+        selected && 'ring-ring ring-2 ring-offset-1',
+        className,
+      )}
+    >
+      {children}
+    </button>
+  );
+  return (
+    <>
+      <Handle
+        type="target"
+        position={Position.Top}
+        isConnectable={false}
+        className="pointer-events-none! invisible!"
+      />
+      {tooltip ? <Tooltip content={tooltip}>{button}</Tooltip> : button}
+      <span id={descriptionId} hidden>
+        {context.descriptions.get(id)}
+      </span>
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        isConnectable={false}
+        className="pointer-events-none! invisible!"
+      />
+    </>
+  );
+}
+
+/** The line along a box's foot: what it reads, or (in a run) how it went. */
+export function FlowNodeStrip({ id }: { id: string }) {
+  const { strips } = useFlowRender();
+  const text = strips.get(id) ?? '';
+  return (
+    <span
+      data-slot="flow-node-strip"
+      className="border-border text-muted-foreground flex h-7 shrink-0 items-center border-t px-3 text-xs"
+    >
+      <span className="truncate">{text}</span>
+    </span>
+  );
+}
diff --git a/packages/ui/src/components/flow/render/gate-node.tsx b/packages/ui/src/components/flow/render/gate-node.tsx
new file mode 100644
index 0000000000..808e168e54
--- /dev/null
+++ b/packages/ui/src/components/flow/render/gate-node.tsx
@@ -0,0 +1,64 @@
+'use client';
+
+import type { NodeProps } from '@xyflow/react';
+import { Filter, Split } from 'lucide-react';
+import { memo } from 'react';
+
+import { useT } from '../../../i18n/client';
+import { cn } from '../../../lib/cn';
+import { FlowNodeIssueMarker } from '../node-issue-marker';
+import type { FlowGateNode } from '../types';
+import { FlowNodeButton, useFlowRender } from './flow-render-context';
+import type { FlowNodeData } from './step-node';
+
+/**
+ * A condition: a pill above the step it guards, the condition in words
+ * (in mono when it is the expression itself), as wide as its words need
+ * (160 to 288 px). `only-if` (a filter) has one plain line out; `if-else`
+ * (a split) leads to Yes on the left and No on the right. A pointer gets the
+ * full condition in a tooltip; a keyboard gets it in the name.
+ */
+export const FlowGateNodeView = memo(function FlowGateNodeView({
+  data,
+}: NodeProps & { data: FlowNodeData<FlowGateNode> }) {
+  const { t } = useT('flow');
+  const { issues } = useFlowRender();
+  const { node } = data;
+  const Icon = node.mode === 'if-else' ? Split : Filter;
+  const counts = issues.get(node.id);
+  return (
+    <FlowNodeButton
+      id={node.id}
+      tooltip={
+        <span className="flex max-w-xs flex-col gap-0.5">
+          <span className="font-medium">
+            {t(node.mode === 'if-else' ? 'gate.ifElse' : 'gate.onlyIf')}
+          </span>
+          <span className={cn(node.conditionIsCode && 'font-mono')}>
+            {node.condition}
+          </span>
+        </span>
+      }
+      className="bg-card text-card-foreground border-border flex items-center gap-2 rounded-full border px-3 shadow-sm"
+    >
+      <Icon
+        aria-hidden="true"
+        className="text-muted-foreground size-4 shrink-0"
+      />
+      <span
+        className={cn(
+          'min-w-0 flex-1 truncate text-xs leading-4',
+          node.conditionIsCode && 'font-mono',
+        )}
+      >
+        {node.condition}
+      </span>
+      {counts && (
+        <FlowNodeIssueMarker
+          errors={counts.errors}
+          warnings={counts.warnings}
+        />
+      )}
+    </FlowNodeButton>
+  );
+});
diff --git a/packages/ui/src/components/flow/render/group-frame.tsx b/packages/ui/src/components/flow/render/group-frame.tsx
new file mode 100644
index 0000000000..dc1a288f6d
--- /dev/null
+++ b/packages/ui/src/components/flow/render/group-frame.tsx
@@ -0,0 +1,87 @@
+'use client';
+
+import type { NodeProps } from '@xyflow/react';
+import { RefreshCw, Repeat } from 'lucide-react';
+import { memo } from 'react';
+
+import { FLOW_EDGE_COLORS, FLOW_EDGE_DASH } from '../edge-palette';
+import { roundedOrthogonalPath } from '../layout/geometry';
+import type { FlowGroup, FlowRect } from '../types';
+
+export interface FlowFrameData extends Record<string, unknown> {
+  group: FlowGroup;
+  /** The header's box, relative to the frame. */
+  header: FlowRect;
+  /** The members' boxes, relative to the frame (where a repeat's loop
+   *  arc runs). */
+  members: readonly FlowRect[];
+}
+
+/** How far a repeat's loop arc stands off its node's right side. */
+const ARC_OFFSET = 20;
+
+/**
+ * The frame round a step that runs once per item (`each`) or repeats
+ * (`repeat`): a dashed, lightly filled box behind its member with the
+ * host's words in its header. Decoration only — every member's description
+ * says the same — so it is hidden from assistive technology and never
+ * takes a pointer. A repeat draws its loop as a dashed arc in its right
+ * gutter, from the node's foot back to its head.
+ */
+export const FlowGroupFrameView = memo(function FlowGroupFrameView({
+  data,
+}: NodeProps & { data: FlowFrameData }) {
+  const { group, header, members } = data;
+  const Icon = group.kind === 'repeat' ? RefreshCw : Repeat;
+  const member = members[0];
+  return (
+    <div
+      aria-hidden="true"
+      data-flow-frame={group.id}
+      className="border-border bg-muted/30 pointer-events-none relative size-full rounded-xl border border-dashed"
+    >
+      <div
+        data-slot="flow-frame-header"
+        className="text-muted-foreground absolute flex items-center gap-1.5 px-1 text-xs leading-4 font-medium"
+        style={{
+          left: header.x,
+          top: header.y,
+          width: header.width,
+          height: header.height,
+        }}
+      >
+        <Icon className="size-3.5 shrink-0" />
+        <span className="truncate">{group.label}</span>
+      </div>
+      {group.kind === 'repeat' && member && (
+        <svg className="absolute inset-0 size-full overflow-visible">
+          <path
+            d={roundedOrthogonalPath(
+              [
+                {
+                  x: member.x + member.width,
+                  y: member.y + member.height - 16,
+                },
+                {
+                  x: member.x + member.width + ARC_OFFSET,
+                  y: member.y + member.height - 16,
+                },
+                { x: member.x + member.width + ARC_OFFSET, y: member.y + 16 },
+                { x: member.x + member.width + 8, y: member.y + 16 },
+              ],
+              8,
+            )}
+            fill="none"
+            strokeWidth={2}
+            strokeDasharray={FLOW_EDGE_DASH.order}
+            style={{ stroke: FLOW_EDGE_COLORS.flow }}
+          />
+          <path
+            d={`M${member.x + member.width + 8} ${member.y + 11} L${member.x + member.width} ${member.y + 16} L${member.x + member.width + 8} ${member.y + 21} Z`}
+            style={{ fill: FLOW_EDGE_COLORS.flow }}
+          />
+        </svg>
+      )}
+    </div>
+  );
+});
diff --git a/packages/ui/src/components/flow/render/routed-edge.tsx b/packages/ui/src/components/flow/render/routed-edge.tsx
new file mode 100644
index 0000000000..5326f7a912
--- /dev/null
+++ b/packages/ui/src/components/flow/render/routed-edge.tsx
@@ -0,0 +1,112 @@
+'use client';
+
+import { EdgeLabelRenderer, type EdgeProps } from '@xyflow/react';
+import { memo } from 'react';
+
+import {
+  FLOW_EDGE_ARROW,
+  FLOW_EDGE_COLORS,
+  FLOW_EDGE_CORNER_RADIUS,
+  FLOW_EDGE_STROKE,
+  flowEdgeDash,
+  flowEdgeTone,
+} from '../edge-palette';
+import { roundedOrthogonalPath, trimEnd } from '../layout/geometry';
+import type { FlowEdge, FlowPoint, FlowRect } from '../types';
+import { flowArrowId } from './edge-markers';
+
+export interface FlowRoutedEdgeData extends Record<string, unknown> {
+  edge: FlowEdge;
+  points: readonly FlowPoint[];
+  label?: { text: string; rect: FlowRect };
+  /** Prefix of the canvas's arrowhead ids. */
+  baseId: string;
+}
+
+/**
+ * The SVG paths of a route: `full` along all of it (the pointer's), and
+ * `stroke` stopping where the arrowhead's base sits — never cut back past
+ * the last bend, so the arrow keeps pointing along the last segment (a
+ * shorter last segment lets the tip end under the target box instead).
+ */
+export function flowEdgePaths(points: readonly FlowPoint[]): {
+  full: string;
+  stroke: string;
+} {
+  const end = points[points.length - 1];
+  const before = points[points.length - 2];
+  const last =
+    end && before ? Math.hypot(end.x - before.x, end.y - before.y) : 0;
+  const cut = Math.min(FLOW_EDGE_ARROW.length, Math.max(0, last - 1));
+  return {
+    full: roundedOrthogonalPath(points, FLOW_EDGE_CORNER_RADIUS),
+    stroke: roundedOrthogonalPath(
+      trimEnd(points, cut),
+      FLOW_EDGE_CORNER_RADIUS,
+    ),
+  };
+}
+
+/** Pointer room round a line, wider than the line itself. */
+const HIT_WIDTH = 12;
+
+/**
+ * An edge drawn along the route the layout gave it — orthogonal, corners
+ * rounded at 8 px — never along React Flow's own handle-to-handle curve,
+ * which ignored the boxes in its way. The kind sets the line: a `data`
+ * edge solid, `order` dashed, `completion` dotted, `branch-yes` green and
+ * `branch-no` amber with a "Yes" / "No" pill at the layout's label box.
+ * Hidden from assistive technology: the nodes say what the lines mean.
+ */
+export const FlowRoutedEdgeView = memo(function FlowRoutedEdgeView({
+  data,
+}: EdgeProps & { data: FlowRoutedEdgeData }) {
+  const { edge, points, label, baseId } = data;
+  const tone = flowEdgeTone(edge.kind);
+  const color = FLOW_EDGE_COLORS[tone];
+  const { full, stroke } = flowEdgePaths(points);
+  return (
+    <>
+      <path
+        d={stroke}
+        fill="none"
+        data-flow-edge={edge.id}
+        data-kind={edge.kind}
+        className="react-flow__edge-path"
+        strokeWidth={FLOW_EDGE_STROKE.base}
+        strokeDasharray={flowEdgeDash(edge.kind)}
+        strokeLinecap={edge.kind === 'completion' ? 'round' : 'butt'}
+        markerEnd={`url(#${flowArrowId(baseId, tone)})`}
+        style={{ stroke: color }}
+      />
+      {edge.detail && (
+        <path
+          d={full}
+          fill="none"
+          stroke="transparent"
+          strokeWidth={HIT_WIDTH}
+          style={{ pointerEvents: 'stroke' }}
+        >
+          <title>{edge.detail}</title>
+        </path>
+      )}
+      {label && (
+        <EdgeLabelRenderer>
+          <div
+            aria-hidden="true"
+            data-flow-edge-label={edge.id}
+            className="bg-background pointer-events-none absolute flex items-center justify-center rounded-full text-xs leading-4 font-medium"
+            style={{
+              width: label.rect.width,
+              height: label.rect.height,
+              transform: `translate(${label.rect.x}px, ${label.rect.y}px)`,
+              color,
+            }}
+          >
+            {label.text}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  );
+});
diff --git a/packages/ui/src/components/flow/render/step-node.tsx b/packages/ui/src/components/flow/render/step-node.tsx
new file mode 100644
index 0000000000..91de0fcaaa
--- /dev/null
+++ b/packages/ui/src/components/flow/render/step-node.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import type { NodeProps } from '@xyflow/react';
+import { Box, CornerDownRight } from 'lucide-react';
+import { memo, type ReactNode } from 'react';
+
+import { useT } from '../../../i18n/client';
+import { cn } from '../../../lib/cn';
+import { ISSUE_SEVERITY_CHIP_CLASS } from '../../feedback/issue-severity';
+import { SKELETON_PULSE } from '../../feedback/skeleton';
+import { FlowNodeIssueMarker } from '../node-issue-marker';
+import type { FlowChip, FlowIcon, FlowStepNode } from '../types';
+import {
+  FlowNodeButton,
+  FlowNodeStrip,
+  useFlowRender,
+} from './flow-render-context';
+
+/** The data React Flow carries for a box. */
+export interface FlowNodeData<T> extends Record<string, unknown> {
+  node: T;
+}
+
+const CHIP_TONE: Record<NonNullable<FlowChip['tone']>, string> = {
+  neutral: 'border-border text-foreground border',
+  info: 'border border-current/30 text-[hsl(var(--info-foreground))]',
+  warning: ISSUE_SEVERITY_CHIP_CLASS.warning,
+  error: ISSUE_SEVERITY_CHIP_CLASS.error,
+};
+
+/** A short word on a box's face: 20 px, never wrapping. */
+export function FlowChipPill({ chip }: { chip: FlowChip }) {
+  const Icon = chip.icon;
+  return (
+    <span
+      className={cn(
+        'inline-flex h-5 max-w-[11rem] shrink-0 items-center gap-1 rounded-full px-2 text-xs font-medium whitespace-nowrap',
+        CHIP_TONE[chip.tone ?? 'neutral'],
+      )}
+    >
+      {Icon && <Icon className="size-3 shrink-0" />}
+      <span className="truncate">{chip.label}</span>
+    </span>
+  );
+}
+
+/** The title row every box shares: icon tile, title, glyphs, problems. */
+export function FlowNodeTitleRow({
+  id,
+  icon: Icon,
+  title,
+  trailing,
+}: {
+  id: string;
+  icon: FlowIcon;
+  title: string;
+  trailing?: ReactNode;
+}) {
+  const { issues } = useFlowRender();
+  const counts = issues.get(id);
+  return (
+    <span className="flex h-5 items-center gap-2">
+      <span className="bg-muted text-muted-foreground flex size-5 shrink-0 items-center justify-center rounded-md">
+        <Icon className="size-3.5" />
+      </span>
+      <span className="min-w-0 flex-1 truncate text-sm leading-5 font-medium">
+        {title}
+      </span>
+      <span className="flex shrink-0 items-center gap-1">
+        {trailing}
+        {counts && (
+          <FlowNodeIssueMarker
+            errors={counts.errors}
+            warnings={counts.warnings}
+          />
+        )}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * A step: icon, title, what kind of step it is, what it returns, up to two
+ * chips, and a strip saying what it reads. 288 px wide; 88 to 136 px high
+ * by the rows its data has (`flowNodeSize`). A step that may be skipped, or
+ * never runs, has a dashed border — never faded text.
+ */
+export const FlowStepNodeView = memo(function FlowStepNodeView({
+  data,
+}: NodeProps & { data: FlowNodeData<FlowStepNode> }) {
+  const { t } = useT('flow');
+  const { node } = data;
+  const chips = node.chips ?? [];
+  const shown = chips.slice(0, 2);
+  const hidden = chips.length - shown.length;
+  const hasChips = chips.length > 0 || node.unreachable === true;
+  return (
+    <FlowNodeButton
+      id={node.id}
+      dashed={node.conditional === true || node.unreachable === true}
+      className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
+    >
+      <span className="flex min-h-0 flex-1 flex-col px-3 pt-3">
+        <FlowNodeTitleRow
+          id={node.id}
+          icon={node.icon ?? Box}
+          title={node.label}
+          trailing={(node.markers ?? []).map((marker) => (
+            <span
+              key={marker.id}
+              title={marker.label}
+              className={cn(
+                'inline-flex',
+                marker.tone === 'warning'
+                  ? 'text-amber-700 dark:text-amber-500'
+                  : 'text-muted-foreground',
+              )}
+            >
+              <marker.icon className="size-3.5" />
+            </span>
+          ))}
+        />
+        <span className="text-muted-foreground h-4 truncate text-xs leading-4">
+          {node.typeLabel}
+        </span>
+        {node.returns !== undefined && (
+          <span className="text-muted-foreground mt-1 flex h-4 items-center gap-1 text-xs leading-4">
+            <CornerDownRight className="size-3 shrink-0" aria-hidden="true" />
+            {node.returns === null ? (
+              <span
+                aria-hidden="true"
+                className={cn(SKELETON_PULSE, 'h-2.5 w-3/5 rounded')}
+              />
+            ) : (
+              <span
+                className={cn('truncate', node.returns.code && 'font-mono')}
+              >
+                {node.returns.text}
+              </span>
+            )}
+          </span>
+        )}
+        {hasChips && (
+          <span className="mt-2 flex h-5 items-center gap-1 overflow-hidden">
+            {node.unreachable && (
+              <FlowChipPill
+                chip={{ id: 'unreachable', label: t('node.unreachable') }}
+              />
+            )}
+            {shown.map((chip) => (
+              <FlowChipPill key={chip.id} chip={chip} />
+            ))}
+            {hidden > 0 && (
+              <span className="text-muted-foreground shrink-0 text-xs">
+                {t('node.more', { count: hidden })}
+              </span>
+            )}
+          </span>
+        )}
+      </span>
+      <FlowNodeStrip id={node.id} />
+    </FlowNodeButton>
+  );
+});
diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
new file mode 100644
index 0000000000..3b35d77ec4
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -0,0 +1,386 @@
+import { viewportAtRest } from '@tale/ui/testing/flow';
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { page, userEvent } from 'vitest/browser';
+
+import { ratioAgainst } from '@/tests/utils/contrast';
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { resetFlowElkForTests } from './layout/elk-client';
+import { flowNodeSize } from './layout/sizes';
+import { flowEdgePaths } from './render/routed-edge';
+import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+import { edgeBoxCrossings } from './testing/flow-geometry';
+import type { FlowGraph, FlowLayout, FlowRect } from './types';
+import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
+
+import '../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  window.localStorage.removeItem('tale:flow-view');
+  vi.restoreAllMocks();
+});
+
+function Harness({
+  graph,
+  onLayout,
+  onSelect,
+  width = 1100,
+  height = 1500,
+  ...rest
+}: Partial<WorkflowCanvasProps> & {
+  graph: FlowGraph;
+  width?: number;
+  height?: number;
+}) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div>
+      <button type="button">Before the chart</button>
+      <div data-testid="frame" style={{ width, height }}>
+        <WorkflowCanvas
+          graph={graph}
+          aria-label="Triage GitHub issues"
+          layoutKey="triage"
+          selectedId={selected}
+          onSelect={(id) => {
+            setSelected(id);
+            onSelect?.(id);
+          }}
+          onLayout={onLayout}
+          fitPolicy="all"
+          {...rest}
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Triage with one more node: a graph this session has not laid out yet, so
+ * no cached layout answers it.
+ */
+function freshGraph(tag: string): FlowGraph {
+  const graph = triageFlowGraph();
+  const id = `probe_${tag}`;
+  return {
+    ...graph,
+    nodes: [
+      ...graph.nodes.slice(0, -1),
+      { id, kind: 'step', label: 'Probe' },
+      ...graph.nodes.slice(-1),
+    ],
+    edges: [
+      ...graph.edges,
+      { id: `report>${id}`, source: 'report', target: id, kind: 'data' },
+      { id: `${id}>__end`, source: id, target: '__end', kind: 'completion' },
+    ],
+  };
+}
+
+/** Renders a graph and resolves once its layout is on the page, at rest. */
+async function renderLaidOut(
+  graph: FlowGraph,
+  props: Partial<WorkflowCanvasProps> & {
+    width?: number;
+    height?: number;
+  } = {},
+) {
+  await page.viewport(1280, 1600);
+  let layout: FlowLayout | null = null;
+  const view = render(
+    <Harness
+      graph={graph}
+      onLayout={(next) => {
+        layout = next;
+      }}
+      {...props}
+    />,
+  );
+  await waitFor(
+    () => {
+      if (layout === null) throw new Error('not laid out yet');
+    },
+    { timeout: 20_000 },
+  );
+  // Every drawn edge is on the page (React Flow draws them once the boxes'
+  // handles are measured), and the fit has come to rest.
+  const drawn = graph.edges.filter((edge) => !edge.layoutOnly).length;
+  await waitFor(
+    () =>
+      expect(
+        view.container.querySelectorAll('path[data-flow-edge]'),
+      ).toHaveLength(drawn),
+    { timeout: 10_000 },
+  );
+  await viewportAtRest();
+  // The chart fades in; colours are judged once it is fully there (a
+  // reserved row's pulse runs for ever and is left alone).
+  await Promise.all(
+    document
+      .getAnimations()
+      .filter(
+        (animation) =>
+          animation.effect?.getComputedTiming().endTime !== Infinity,
+      )
+      .map((animation) => animation.finished),
+  );
+  return { ...view, layout: layout as unknown as FlowLayout };
+}
+
+/** The view's translate and scale, from React Flow's viewport element. */
+function viewTransform(container: HTMLElement) {
+  const viewport = container.querySelector<HTMLElement>(
+    '.react-flow__viewport',
+  );
+  const match = /translate\(([-\d.]+)px, ([-\d.]+)px\) scale\(([-\d.]+)\)/.exec(
+    viewport?.style.transform ?? '',
+  );
+  if (match === null) throw new Error('no viewport transform');
+  return { x: Number(match[1]), y: Number(match[2]), zoom: Number(match[3]) };
+}
+
+/** Each node's box as the page draws it, mapped back to flow coordinates. */
+function renderedBoxes(container: HTMLElement): Map<string, FlowRect> {
+  const pane = container.querySelector('.react-flow')?.getBoundingClientRect();
+  if (pane === undefined) throw new Error('no pane');
+  const { x, y, zoom } = viewTransform(container);
+  const boxes = new Map<string, FlowRect>();
+  for (const button of container.querySelectorAll<HTMLElement>(
+    '[data-flow-node]',
+  )) {
+    const rect = button.getBoundingClientRect();
+    boxes.set(button.dataset.flowNode ?? '', {
+      x: (rect.left - pane.left - x) / zoom,
+      y: (rect.top - pane.top - y) / zoom,
+      width: rect.width / zoom,
+      height: rect.height / zoom,
+    });
+  }
+  return boxes;
+}
+
+describe('WorkflowCanvas', () => {
+  it('lays Triage out in the worker and draws each edge along its route', async () => {
+    const graph = triageFlowGraph();
+    const { container, layout } = await renderLaidOut(graph);
+    expect(layout.engine).toBe('worker');
+    expect(
+      container
+        .querySelector('[data-flow-engine]')
+        ?.getAttribute('data-flow-engine'),
+    ).toBe('worker');
+    for (const edge of graph.edges) {
+      const path = container.querySelector(`path[data-flow-edge="${edge.id}"]`);
+      expect(path?.getAttribute('d'), edge.id).toBe(
+        flowEdgePaths(layout.edges[edge.id]?.points ?? []).stroke,
+      );
+    }
+    // No edge is React Flow's own curve: every edge group holds a routed path.
+    for (const group of container.querySelectorAll('.react-flow__edge'))
+      expect(group.querySelector('path[data-flow-edge]')).not.toBeNull();
+  });
+
+  it('draws every box at its size and no line through any box on the page', async () => {
+    const graph = triageFlowGraph();
+    const { container, layout } = await renderLaidOut(graph);
+    const boxes = renderedBoxes(container);
+    for (const node of graph.nodes) {
+      const box = boxes.get(node.id);
+      const size = flowNodeSize(node);
+      expect(box, node.id).toBeDefined();
+      expect(
+        Math.abs((box?.width ?? 0) - size.width),
+        `${node.id} width`,
+      ).toBeLessThan(1);
+      expect(
+        Math.abs((box?.height ?? 0) - size.height),
+        `${node.id} height`,
+      ).toBeLessThan(1);
+    }
+    const obstacles = [...boxes].map(([id, rect]) => ({ id, rect }));
+    expect(edgeBoxCrossings(layout.edges, obstacles)).toEqual([]);
+    // The frame header is a box too.
+    const header = container.querySelector('[data-slot="flow-frame-header"]');
+    expect(header?.textContent).toContain(
+      'For each item of issues of Open issues',
+    );
+  });
+
+  it('is one Tab stop that the arrows walk along the lines', async () => {
+    const onSelect = vi.fn();
+    await renderLaidOut(triageFlowGraph(), { onSelect });
+    const nodes = Array.from(
+      document.querySelectorAll<HTMLElement>('[data-flow-node]'),
+    );
+    expect(nodes.filter((node) => node.tabIndex === 0)).toHaveLength(1);
+
+    screen.getByRole('button', { name: 'Before the chart' }).focus();
+    await userEvent.tab();
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Start' }),
+    );
+    await userEvent.keyboard('{ArrowDown}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Issues' }),
+    );
+    await userEvent.keyboard('{ArrowDown}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Open issues' }),
+    );
+    await userEvent.keyboard('{ArrowRight}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Open issues' }),
+    );
+    await userEvent.keyboard('{End}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'End' }),
+    );
+    await userEvent.keyboard('{ArrowUp}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Report' }),
+    );
+    await userEvent.keyboard('{Home}');
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Start' }),
+    );
+    await userEvent.keyboard('{ArrowDown}{Enter}');
+    expect(onSelect).toHaveBeenLastCalledWith('issues');
+    // The selected node now holds the Tab stop, and Tab leaves the chart.
+    const issues = screen.getByRole('button', { name: 'Issues' });
+    expect(issues).toHaveAttribute('aria-pressed', 'true');
+    expect(issues.tabIndex).toBe(0);
+    await userEvent.tab();
+    expect(document.activeElement?.closest('[data-flow-node]')).toBeNull();
+  });
+
+  it('describes each node: where it sits, where it leads, what it reads', async () => {
+    await renderLaidOut(triageFlowGraph());
+    const score = screen.getByRole('button', { name: 'Score' });
+    expect(score).toHaveAccessibleDescription(
+      'Node 4 of 6. Comes from Open issues. Leads to Report. Reads Open issues and each item. Runs once for each item of issues of Open issues.',
+    );
+    const chart = screen.getByRole('group', { name: 'Triage GitHub issues' });
+    expect(chart).toHaveAttribute('aria-roledescription', 'flow chart');
+    expect(chart).toHaveAccessibleDescription(/Use the arrow keys/);
+  });
+
+  it('names a condition and its branches, and labels Yes and No', async () => {
+    const { container } = await renderLaidOut(branchFlowGraph());
+    const gate = screen.getByRole('button', {
+      name: 'Condition for Urgent: urgent of Classify is true',
+    });
+    expect(gate).toHaveAccessibleDescription(
+      /Yes leads to Urgent, No leads to Normal/,
+    );
+    const labels = Array.from(
+      container.querySelectorAll('[data-flow-edge-label]'),
+      (label) => label.textContent,
+    );
+    expect(labels.sort()).toEqual(['No', 'No', 'Yes', 'Yes']);
+  });
+
+  it.each(['light', 'dark'])(
+    'passes axe and keeps every line and word readable (%s)',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      const { container } = await renderLaidOut(branchFlowGraph());
+      const result = await axe.run(container, {
+        runOnly: [
+          'color-contrast',
+          'aria-allowed-attr',
+          'aria-valid-attr-value',
+          'aria-roledescription',
+          'button-name',
+          'nested-interactive',
+        ],
+      });
+      expect(result.violations).toEqual([]);
+
+      const pane = container.querySelector('.react-flow__pane');
+      if (pane === null) throw new Error('no pane');
+      for (const path of container.querySelectorAll('path[data-flow-edge]')) {
+        expect(
+          ratioAgainst(pane, getComputedStyle(path).stroke),
+          `${theme} ${path.getAttribute('data-flow-edge')} line`,
+        ).toBeGreaterThanOrEqual(3);
+      }
+      for (const label of container.querySelectorAll<HTMLElement>(
+        '[data-flow-edge-label]',
+      ))
+        expect(
+          ratioAgainst(label, getComputedStyle(label).color),
+          `${theme} label`,
+        ).toBeGreaterThanOrEqual(4.5);
+      for (const strip of container.querySelectorAll(
+        '[data-slot="flow-node-strip"]',
+      ))
+        expect(
+          ratioAgainst(strip, getComputedStyle(strip).color),
+          `${theme} strip`,
+        ).toBeGreaterThanOrEqual(4.5);
+      for (const header of container.querySelectorAll(
+        '[data-slot="flow-frame-header"]',
+      ))
+        expect(
+          ratioAgainst(header, getComputedStyle(header).color),
+          `${theme} frame header`,
+        ).toBeGreaterThanOrEqual(4.5);
+    },
+  );
+
+  it('lays out on the main thread, and says so once, when the worker cannot start', async () => {
+    resetFlowElkForTests();
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const RealWorker = window.Worker;
+    class RefusedWorker {
+      constructor() {
+        throw new Error('Refused by policy');
+      }
+    }
+    window.Worker = RefusedWorker as unknown as typeof Worker;
+    try {
+      const { layout } = await renderLaidOut(freshGraph('refused'));
+      expect(layout.engine).toBe('main');
+      expect(warn).toHaveBeenCalledWith(
+        'Flow layout worker unavailable; laying out on the main thread',
+        expect.any(Error),
+      );
+    } finally {
+      window.Worker = RealWorker;
+      resetFlowElkForTests();
+    }
+  });
+
+  it('switches to the List view and back, and remembers the choice', async () => {
+    await renderLaidOut(triageFlowGraph());
+    await userEvent.click(screen.getByRole('button', { name: 'Show as list' }));
+    const list = await screen.findByRole('list', {
+      name: 'Triage GitHub issues',
+    });
+    expect(list).toBeInTheDocument();
+    expect(window.localStorage.getItem('tale:flow-view')).toBe('list');
+    await userEvent.click(
+      screen.getByRole('button', { name: 'Show as chart' }),
+    );
+    await screen.findByRole('group', { name: 'Triage GitHub issues' });
+    expect(window.localStorage.getItem('tale:flow-view')).toBe('chart');
+  });
+
+  it('shows a skeleton column, busy, until the first layout lands', async () => {
+    const { container } = render(
+      <Harness graph={triageFlowGraph()} layoutKey="fresh-key" />,
+    );
+    const chart = screen.getByRole('group', { name: 'Triage GitHub issues' });
+    // A fresh picture of a graph nobody laid out before starts busy.
+    expect(chart).toHaveAttribute('aria-busy', 'true');
+    expect(container.querySelector('[data-skeleton-mask]')).not.toBeNull();
+    await waitFor(() => expect(chart).toHaveAttribute('aria-busy', 'false'), {
+      timeout: 20_000,
+    });
+  });
+});
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
new file mode 100644
index 0000000000..3a2ded6230
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -0,0 +1,632 @@
+'use client';
+
+import {
+  ReactFlowProvider,
+  useReactFlow,
+  type Edge,
+  type Node,
+} from '@xyflow/react';
+import { ListOrdered, Workflow } from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type FocusEvent,
+  type KeyboardEvent,
+  type ReactNode,
+  type TouchEvent,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useMediaQuery } from '../../hooks/use-media-query';
+import { usePrefersReducedMotion } from '../../hooks/use-prefers-reduced-motion';
+import { useSwapFade } from '../../hooks/use-swap-fade';
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import { Alert } from '../feedback/alert';
+import type { IssueCounts } from '../feedback/issue-summary';
+import { SkeletonBox } from '../feedback/skeleton';
+import { Skeletonize } from '../feedback/skeleton-context';
+import { Button } from '../primitives/button';
+import { describeFlowGraph, flowListFormat } from './describe';
+import {
+  easeOutQuint,
+  FLOW_VIEWPORT_DURATION,
+  FlowCanvas,
+  type FlowFitPolicy,
+} from './flow-canvas';
+import { FlowLegend, type FlowLegendEntry } from './flow-legend';
+import { FlowStepList } from './flow-step-list';
+import {
+  FLOW_NAVIGATION_KEYS,
+  flowNeighbour,
+  flowTabStop,
+} from './interaction/navigation';
+import { useFlowLayout } from './layout/use-flow-layout';
+import { FlowEdgeMarkers } from './render/edge-markers';
+import { FlowEntryNodeView } from './render/entry-node';
+import { FlowExitNodeView } from './render/exit-node';
+import {
+  FlowRenderProvider,
+  type FlowRenderContextValue,
+} from './render/flow-render-context';
+import { FlowGateNodeView } from './render/gate-node';
+import { FlowGroupFrameView, type FlowFrameData } from './render/group-frame';
+import {
+  FlowRoutedEdgeView,
+  type FlowRoutedEdgeData,
+} from './render/routed-edge';
+import { FlowStepNodeView } from './render/step-node';
+import type { FlowEdge, FlowGraph, FlowLayout, FlowRect } from './types';
+import { validateFlowGraph } from './validate-graph';
+
+export type FlowView = 'chart' | 'list';
+
+export interface WorkflowCanvasProps {
+  graph: FlowGraph;
+  'aria-label': string;
+  /** What the graph is a picture of; a change is another picture (laid
+   *  out afresh, swapped in with a fade), the same key with a changed graph
+   *  a live relayout. */
+  layoutKey: string;
+  selectedId?: string | null;
+  onSelect?: (id: string | null) => void;
+  /** Bring this node into view, with the least pan. */
+  revealId?: string | null;
+  /** Problem counts by node id (Start, End and gates included). */
+  issues?: ReadonlyMap<string, IssueCounts>;
+  /** The region a node's button opens (an inspector): nodes then say
+   *  whether it is open (`aria-expanded`) instead of `aria-pressed`. */
+  controlsId?: string;
+  /** Controlled view; the built-in chart/list toggle is hidden. */
+  view?: FlowView;
+  onViewChange?: (view: FlowView) => void;
+  /** A bordered frame for a page (a run's page); off for a workbench. */
+  framed?: boolean;
+  /** `page-scroll`: on a touch screen one finger scrolls the page and two
+   *  move the chart. @default framed ? 'page-scroll' : 'pan' */
+  touchPolicy?: 'pan' | 'page-scroll';
+  /** @default 'auto' */
+  fitPolicy?: FlowFitPolicy;
+  /** The canvas's top-left corner (a view switch). */
+  topStart?: ReactNode;
+  /** The canvas's top-right corner (its verbs). */
+  topEnd?: ReactNode;
+  /** The bottom-centre toolbar. */
+  toolbar?: ReactNode;
+  /** Extra buttons in the corner cluster, after zoom, reset and legend. */
+  cornerActions?: ReactNode;
+  /** The legend's lines; no legend button without them. */
+  legend?: readonly FlowLegendEntry[];
+  /** Shown instead of the chart when the graph has no nodes. */
+  empty?: ReactNode;
+  /** Shown above the chart (a warning about the graph). */
+  notice?: ReactNode;
+  className?: string;
+  /** Every finished layout (tests, demos). */
+  onLayout?: (layout: FlowLayout) => void;
+}
+
+const NODE_TYPES = {
+  step: FlowStepNodeView,
+  entry: FlowEntryNodeView,
+  exit: FlowExitNodeView,
+  gate: FlowGateNodeView,
+  frame: FlowGroupFrameView,
+};
+const EDGE_TYPES = { routed: FlowRoutedEdgeView };
+
+const NO_ISSUES: ReadonlyMap<string, IssueCounts> = new Map();
+const VIEW_STORAGE_KEY = 'tale:flow-view';
+const TOUCH_HINT_KEY = 'tale:flow-touch-hint';
+/** Room left between a box brought into view and the frame's edge. */
+const REVEAL_MARGIN = 24;
+/** How long the two-finger hint stays. */
+const TOUCH_HINT_MS = 1_500;
+
+/** The frame node behind a group's members. */
+const frameNodeId = (groupId: string) => `__frame:${groupId}`;
+
+/**
+ * How far to move the span `[start, end]` so it shows inside `[min, max]`:
+ * nothing when it already does, otherwise the least shift that leaves the
+ * margin — aligned to its start when the span is longer than the room.
+ */
+function revealShift(start: number, end: number, min: number, max: number) {
+  if (start >= min && end <= max) return 0;
+  const lo = min + REVEAL_MARGIN;
+  const hi = max - REVEAL_MARGIN;
+  if (end - start > hi - lo) return lo - start;
+  if (end > hi) return hi - end;
+  return lo - start;
+}
+
+function readStoredView(): FlowView | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const stored = window.localStorage.getItem(VIEW_STORAGE_KEY);
+    return stored === 'list' || stored === 'chart' ? stored : null;
+  } catch (error) {
+    console.warn('Flow canvas could not read the stored view', error);
+    return null;
+  }
+}
+
+const relative = (rect: FlowRect, origin: FlowRect): FlowRect => ({
+  x: rect.x - origin.x,
+  y: rect.y - origin.y,
+  width: rect.width,
+  height: rect.height,
+});
+
+/** React Flow's nodes for a layout: frames behind, boxes on top. */
+function toFlowNodes(graph: FlowGraph, layout: FlowLayout): Node[] {
+  const nodes: Node[] = [];
+  for (const group of graph.groups ?? []) {
+    const frame = layout.groups[group.id];
+    if (frame === undefined) continue;
+    const data: FlowFrameData = {
+      group,
+      header: relative(frame.header, frame),
+      members: group.members.flatMap((id) => {
+        const rect = layout.nodes[id];
+        return rect ? [relative(rect, frame)] : [];
+      }),
+    };
+    nodes.push({
+      id: frameNodeId(group.id),
+      type: 'frame',
+      position: { x: frame.x, y: frame.y },
+      width: frame.width,
+      height: frame.height,
+      zIndex: -1,
+      selectable: false,
+      focusable: false,
+      draggable: false,
+      style: { pointerEvents: 'none' },
+      domAttributes: { 'aria-roledescription': undefined },
+      data,
+    });
+  }
+  for (const node of graph.nodes) {
+    const rect = layout.nodes[node.id];
+    if (rect === undefined) continue;
+    nodes.push({
+      id: node.id,
+      type: node.kind,
+      position: { x: rect.x, y: rect.y },
+      width: rect.width,
+      height: rect.height,
+      selectable: false,
+      focusable: false,
+      draggable: false,
+      // React Flow turns pointer events off on a node that is neither
+      // selectable nor draggable; the box is a real button and needs them.
+      style: { pointerEvents: 'all' },
+      domAttributes: { 'aria-roledescription': undefined },
+      data: { node },
+    });
+  }
+  return nodes;
+}
+
+function toFlowEdges(
+  graph: FlowGraph,
+  layout: FlowLayout,
+  baseId: string,
+  labelOf: (edge: FlowEdge) => string | undefined,
+): Edge[] {
+  const edges: Edge[] = [];
+  for (const edge of graph.edges) {
+    if (edge.layoutOnly) continue;
+    const route = layout.edges[edge.id];
+    if (
+      route === undefined ||
+      layout.nodes[edge.source] === undefined ||
+      layout.nodes[edge.target] === undefined
+    )
+      continue;
+    const text = labelOf(edge);
+    const data: FlowRoutedEdgeData = {
+      edge,
+      points: route.points,
+      baseId,
+      ...(text && route.label ? { label: { text, rect: route.label } } : {}),
+    };
+    edges.push({
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      type: 'routed',
+      selectable: false,
+      focusable: false,
+      // The nodes say what the lines mean; the lines stay out of the
+      // accessibility tree (React Flow names each in English).
+      domAttributes: { 'aria-hidden': true },
+      data,
+    });
+  }
+  return edges;
+}
+
+/** A column of placeholder boxes in the real frame while the first layout
+ *  is computed. */
+function ArrangingSkeleton({ label }: { label: string }) {
+  return (
+    <Skeletonize
+      loading
+      label={label}
+      className="flex size-full flex-col items-center gap-16 overflow-hidden pt-12"
+    >
+      {[160, 88, 108, 88, 120].map((height, index) => (
+        <SkeletonBox asChild key={index}>
+          <div
+            className="border-border w-72 shrink-0 rounded-lg border"
+            style={{ height }}
+          />
+        </SkeletonBox>
+      ))}
+    </Skeletonize>
+  );
+}
+
+function WorkflowCanvasInner({
+  graph,
+  'aria-label': ariaLabel,
+  layoutKey,
+  selectedId = null,
+  onSelect,
+  revealId = null,
+  issues = NO_ISSUES,
+  controlsId,
+  view: controlledView,
+  onViewChange,
+  framed = false,
+  touchPolicy,
+  fitPolicy = 'auto',
+  topStart,
+  topEnd,
+  toolbar,
+  cornerActions,
+  legend,
+  empty,
+  notice,
+  className,
+  onLayout,
+}: WorkflowCanvasProps) {
+  const { t } = useT('flow');
+  const { t: tIssues } = useT('issues');
+  const { i18n } = useTranslation();
+  const locale = i18n?.resolvedLanguage ?? i18n?.language ?? 'en';
+  const baseId = useId();
+  const helpId = `${baseId}-help`;
+  const reduced = usePrefersReducedMotion();
+  const narrow = useMediaQuery('(max-width: 23.99rem)');
+  const coarse = useMediaQuery('(pointer: coarse)');
+  const { getViewport, setViewport } = useReactFlow();
+
+  // A host's adapter bug shows in development, without taking the page down.
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    try {
+      validateFlowGraph(graph);
+    } catch (error) {
+      console.error('WorkflowCanvas was given a graph it cannot draw', error);
+    }
+  }, [graph]);
+
+  // The view: the host's, else the reader's last choice, else the chart
+  // (the list on a phone too narrow for one).
+  const [storedView, setStoredView] = useState<FlowView | null>(readStoredView);
+  const view: FlowView =
+    controlledView ?? storedView ?? (narrow ? 'list' : 'chart');
+  const changeView = (next: FlowView) => {
+    if (controlledView === undefined) {
+      setStoredView(next);
+      try {
+        window.localStorage.setItem(VIEW_STORAGE_KEY, next);
+      } catch (error) {
+        console.warn('Flow canvas could not store the view', error);
+      }
+    }
+    onViewChange?.(next);
+  };
+
+  const edgeLabel = useCallback(
+    (edge: FlowEdge) =>
+      edge.kind === 'branch-yes'
+        ? t('branch.yes')
+        : edge.kind === 'branch-no'
+          ? t('branch.no')
+          : undefined,
+    [t],
+  );
+  const { layout, status } = useFlowLayout(graph, { layoutKey, edgeLabel });
+
+  useEffect(() => {
+    if (layout) onLayout?.(layout);
+  }, [layout, onLayout]);
+
+  const words = useMemo(
+    () =>
+      describeFlowGraph(graph, {
+        t,
+        tIssues,
+        list: flowListFormat(locale),
+        issues,
+      }),
+    [graph, t, tIssues, locale, issues],
+  );
+
+  const nodes = useMemo(
+    () => (layout ? toFlowNodes(graph, layout) : []),
+    [graph, layout],
+  );
+  const edges = useMemo(
+    () => (layout ? toFlowEdges(graph, layout, baseId, edgeLabel) : []),
+    [graph, layout, baseId, edgeLabel],
+  );
+
+  const frameRef = useRef<HTMLDivElement>(null);
+  const [lastFocused, setLastFocused] = useState<string | null>(null);
+  const tabStopId = flowTabStop(graph, selectedId, lastFocused);
+
+  const buttonOf = useCallback(
+    (id: string) =>
+      frameRef.current?.querySelector<HTMLButtonElement>(
+        `[data-flow-node="${CSS.escape(id)}"]`,
+      ) ?? null,
+    [],
+  );
+
+  // Bring a box fully into the frame with the least pan, at the zoom the
+  // reader chose. Measured on the page, so it holds even right after the
+  // frame changed size.
+  const reveal = useCallback(
+    (id: string) => {
+      const frame = frameRef.current;
+      const box = buttonOf(id);
+      if (frame === null || box === null) return;
+      const bounds = frame.getBoundingClientRect();
+      const rect = box.getBoundingClientRect();
+      const dx = revealShift(rect.left, rect.right, bounds.left, bounds.right);
+      const dy = revealShift(rect.top, rect.bottom, bounds.top, bounds.bottom);
+      if (dx === 0 && dy === 0) return;
+      const viewport = getViewport();
+      void setViewport(
+        { x: viewport.x + dx, y: viewport.y + dy, zoom: viewport.zoom },
+        {
+          duration: reduced ? 0 : FLOW_VIEWPORT_DURATION.reveal,
+          ease: easeOutQuint,
+          interpolate: 'linear',
+        },
+      );
+    },
+    [buttonOf, getViewport, setViewport, reduced],
+  );
+
+  useEffect(() => {
+    if (revealId === null || layout === null || view !== 'chart')
+      return undefined;
+    // After React Flow has placed the box.
+    const frame = requestAnimationFrame(() => reveal(revealId));
+    return () => cancelAnimationFrame(frame);
+  }, [revealId, layout, view, reveal]);
+
+  const context = useMemo<FlowRenderContextValue>(
+    () => ({
+      baseId,
+      selectedId,
+      tabStopId,
+      controlsId,
+      issues,
+      names: words.names,
+      descriptions: words.descriptions,
+      strips: words.strips,
+      onActivate: (id) => onSelect?.(selectedId === id ? null : id),
+      onKeyDown: (id, event: KeyboardEvent<HTMLButtonElement>) => {
+        const key = FLOW_NAVIGATION_KEYS[event.key];
+        if (key === undefined || layout === null) return;
+        event.preventDefault();
+        const next = flowNeighbour(graph, layout, id, key);
+        if (next !== null) buttonOf(next)?.focus();
+      },
+      onFocusNode: (id, event: FocusEvent<HTMLButtonElement>) => {
+        setLastFocused(id);
+        // A mouse press focuses the button too, and panning then would drag
+        // the box out from under the pointer mid-click — follow keyboard
+        // focus only.
+        if (event.currentTarget.matches(':focus-visible')) reveal(id);
+      },
+    }),
+    [
+      baseId,
+      selectedId,
+      tabStopId,
+      controlsId,
+      issues,
+      words,
+      onSelect,
+      layout,
+      graph,
+      buttonOf,
+      reveal,
+    ],
+  );
+
+  // A new picture swaps in with a fade, as another item in the same place.
+  const swapRef = useSwapFade<HTMLDivElement>(layoutKey);
+
+  const pageScroll =
+    (touchPolicy ?? (framed ? 'page-scroll' : 'pan')) === 'page-scroll' &&
+    coarse;
+  const [touchHint, setTouchHint] = useState(false);
+  const onTouchMove = (event: TouchEvent<HTMLDivElement>) => {
+    if (!pageScroll || event.touches.length !== 1 || touchHint) return;
+    try {
+      if (window.sessionStorage.getItem(TOUCH_HINT_KEY) !== null) return;
+      window.sessionStorage.setItem(TOUCH_HINT_KEY, '1');
+    } catch (error) {
+      console.warn('Flow canvas could not remember the touch hint', error);
+    }
+    setTouchHint(true);
+  };
+  useEffect(() => {
+    if (!touchHint) return undefined;
+    const timer = setTimeout(() => setTouchHint(false), TOUCH_HINT_MS);
+    return () => clearTimeout(timer);
+  }, [touchHint]);
+
+  const viewToggle =
+    controlledView === undefined ? (
+      <Button
+        size="icon"
+        variant="secondary"
+        title={t(view === 'chart' ? 'controls.showList' : 'controls.showChart')}
+        tooltipSide="right"
+        onClick={() => changeView(view === 'chart' ? 'list' : 'chart')}
+      >
+        {view === 'chart' ? (
+          <ListOrdered className="size-4" />
+        ) : (
+          <Workflow className="size-4" />
+        )}
+      </Button>
+    ) : null;
+
+  if (graph.nodes.length === 0 && empty !== undefined) {
+    return <div className={cn('flex h-full flex-col', className)}>{empty}</div>;
+  }
+
+  const frameClass = cn(
+    'relative min-h-48 flex-1 overflow-hidden',
+    framed && 'border-border min-h-[24rem] rounded-lg border',
+  );
+
+  return (
+    <div className={cn('flex h-full min-h-0 flex-col', className)}>
+      {notice}
+      {view === 'list' ? (
+        <div ref={swapRef} className={cn(frameClass, 'overflow-y-auto')}>
+          <div className="flex items-center justify-end gap-1 px-3 pt-3">
+            {topEnd}
+            {viewToggle}
+          </div>
+          <FlowStepList
+            graph={graph}
+            aria-label={ariaLabel}
+            selectedId={selectedId}
+            onSelect={onSelect}
+            issues={issues}
+            controlsId={controlsId}
+          />
+        </div>
+      ) : (
+        <div
+          ref={frameRef}
+          role="group"
+          aria-roledescription={t('canvas.roleDescription')}
+          aria-label={ariaLabel}
+          aria-describedby={helpId}
+          aria-busy={layout === null}
+          data-flow-engine={layout?.engine}
+          className={frameClass}
+          onTouchMove={onTouchMove}
+        >
+          <span id={helpId} hidden>
+            {t('canvas.keyboardHelp')}
+          </span>
+          <FlowEdgeMarkers baseId={baseId} />
+          {layout === null ? (
+            <ArrangingSkeleton label={t('canvas.arranging')} />
+          ) : (
+            <div
+              ref={swapRef}
+              className="animate-in fade-in size-full duration-[var(--duration-standard)] ease-[var(--ease-out-quint)] motion-reduce:animate-none"
+            >
+              <FlowRenderProvider value={context}>
+                <FlowCanvas
+                  nodes={nodes}
+                  edges={edges}
+                  nodeTypes={NODE_TYPES}
+                  edgeTypes={EDGE_TYPES}
+                  fitPolicy={fitPolicy}
+                  fitKey={layout.signature}
+                  minZoom={0.25}
+                  maxZoom={1.5}
+                  // Every box is a real button holding the chart's one Tab
+                  // stop: React Flow's own focus and keys stay off.
+                  nodesFocusable={false}
+                  edgesFocusable={false}
+                  disableKeyboardA11y
+                  nodesDraggable={false}
+                  nodesConnectable={false}
+                  elementsSelectable={false}
+                  panOnDrag={!pageScroll}
+                  preventScrolling={!pageScroll}
+                  zoomOnScroll={!pageScroll}
+                  onPaneClick={() => {
+                    if (selectedId !== null) onSelect?.(null);
+                  }}
+                  backgroundProps={{ gap: 16 }}
+                  centerActions={toolbar}
+                  topStartActions={topStart}
+                  topEndActions={topEnd}
+                  cornerActions={
+                    viewToggle || legend || cornerActions ? (
+                      <>
+                        {legend && <FlowLegend entries={legend} />}
+                        {viewToggle}
+                        {cornerActions}
+                      </>
+                    ) : undefined
+                  }
+                />
+              </FlowRenderProvider>
+            </div>
+          )}
+          {status === 'failed' && (
+            <div className="pointer-events-none absolute inset-x-3 top-3 flex justify-center">
+              <Alert
+                variant="warning"
+                description={t('canvas.arrangeFailed')}
+                className="pointer-events-auto max-w-lg"
+              />
+            </div>
+          )}
+          {touchHint && (
+            <div
+              role="status"
+              className="animate-in fade-in bg-popover text-popover-foreground ring-border pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg px-3 py-2 text-sm shadow-md ring-1 duration-[var(--duration-standard)] motion-reduce:animate-none"
+            >
+              {t('canvas.touchHint')}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A workflow drawn from its data, laid out automatically: Start above, End
+ * below, every step from its own words, conditions as pills with Yes and
+ * No, frames round iterating steps, and lines along routes that never cross
+ * a box. Nobody places a node — the same graph always draws the same
+ * picture, and a graph that changes on screen keeps every row in order.
+ *
+ * The chart is one Tab stop: arrows follow the lines and the rows, Home and
+ * End jump to Start and End, Enter or Space opens a node. The List view
+ * says the same as text. Layout runs in a worker; until the first one
+ * lands the frame shows a skeleton column, then the chart fades in.
+ */
+export function WorkflowCanvas(props: WorkflowCanvasProps) {
+  return (
+    <ReactFlowProvider>
+      <WorkflowCanvasInner {...props} />
+    </ReactFlowProvider>
+  );
+}
diff --git a/packages/ui/src/globals.css b/packages/ui/src/globals.css
index 1817c5baad..2454c411a5 100644
--- a/packages/ui/src/globals.css
+++ b/packages/ui/src/globals.css
@@ -291,6 +291,12 @@
   --code-squiggle-error: hsl(var(--destructive));
   --code-squiggle-warning: #b45309;
   --code-squiggle-info: hsl(var(--info-foreground));
+
+  /* A flow chart's "No" branch: amber, never red ("No" is a path the author
+     drew, not an error). The warning amber is 2.2:1 on white, too faint for
+     a line, so light mode takes amber-700 (5:1); the edge palette reads it
+     through FLOW_EDGE_COLORS.negative. */
+  --flow-edge-negative: #b45309;
 }
 
 .dark {
@@ -395,6 +401,7 @@
   --code-template-tint: hsl(var(--info-foreground) / 0.1);
   --code-match: hsl(var(--info-foreground) / 0.25);
   --code-squiggle-warning: #f59e0b;
+  --flow-edge-negative: #f59e0b;
 }
 
 /* Windows contrast themes repaint text in their own colours; the selection
diff --git a/packages/ui/src/i18n/keys-dynamic.yml b/packages/ui/src/i18n/keys-dynamic.yml
index b227591cf6..adb8f1a949 100644
--- a/packages/ui/src/i18n/keys-dynamic.yml
+++ b/packages/ui/src/i18n/keys-dynamic.yml
@@ -11,3 +11,6 @@ entries:
   - 'themeSwitcher.light'
   - 'themeSwitcher.dark'
   - 'themeSwitcher.system'
+  # `t(FLOW_NODE_STATE[state].labelKey)` in components/flow/node-status.tsx —
+  # the state is the key, chosen from the typed `FlowNodeState` union.
+  - 'flow.state'
diff --git a/packages/ui/src/i18n/messages/de-CH.yml b/packages/ui/src/i18n/messages/de-CH.yml
index f2f33bb8f0..87699440c1 100644
--- a/packages/ui/src/i18n/messages/de-CH.yml
+++ b/packages/ui/src/i18n/messages/de-CH.yml
@@ -11,6 +11,8 @@ docs:
 common:
   aria:
     close: Schliessen
+  flow:
+    zoomIn: Vergrössern
 envEditor:
   projectSecretBadKey: «{key}» muss mit einem Grossbuchstaben beginnen und darf nur Grossbuchstaben, Ziffern oder Unterstriche enthalten (maximal 64 Zeichen).
 codeEditor:
@@ -20,3 +22,6 @@ codeEditor:
   phrases:
     close: Schliessen
     matchCase: Gross-/Kleinschreibung
+flow:
+  canvas:
+    arrangeFailed: Die Nodes liessen sich nicht anordnen und stehen deshalb untereinander.
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index 23a37c8206..a2e41da2d9 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -195,7 +195,6 @@ common:
     somethingWentWrong: Etwas ist schiefgelaufen. Versuch es erneut.
     tryAgain: Erneut versuchen
   flow:
-    aiEditor: KI-Editor
     resetView: Ansicht zurücksetzen
     zoomIn: Vergrößern
     zoomOut: Verkleinern
@@ -523,3 +522,57 @@ schemaTree:
   maybeEmpty: kann leer sein
   more: '{count, plural, one {# weiteres Feld} other {# weitere Felder}}'
   asTypeScript: Als TypeScript zeigen
+
+flow:
+  canvas:
+    roleDescription: Ablaufdiagramm
+    keyboardHelp: Folge mit den Pfeiltasten den Verbindungen zwischen den Nodes. Pos1 und Ende springen zu Start und Ende, mit der Eingabetaste öffnest du eine Node.
+    arranging: Nodes werden angeordnet…
+    arrangeFailed: Die Nodes ließen sich nicht anordnen und stehen deshalb untereinander.
+    touchHint: Verschiebe das Diagramm mit zwei Fingern
+  controls:
+    showList: Als Liste anzeigen
+    showChart: Als Diagramm anzeigen
+    legend: Legende
+  legend:
+    title: So liest du das Diagramm
+  node:
+    entry: Start
+    exit: Ende
+    triggers: Startet
+    inputs: Eingabe
+    outputs: Gibt zurück
+    outcomes: Endet
+    noInput: Keine Eingabe
+    noOutput: Gibt nichts zurück
+    more: +{count} weitere
+    unreachable: Läuft nie
+    position: Node {index} von {count}
+    section: '{heading}: {items}'
+    rowWithDetail: '{label} ({detail})'
+  gate:
+    onlyIf: Nur wenn
+    ifElse: Wenn
+    name: 'Bedingung für {node}: {condition}'
+    branches: Ja führt zu {yes}, Nein zu {no}
+  branch:
+    'yes': Ja
+    'no': Nein
+  relation:
+    comesFrom: Kommt von {list}
+    leadsTo: Führt zu {list}
+    onlyIf: Läuft nur, wenn {condition}
+    otherwise: Läuft, wenn die Bedingung von {node} nicht zutrifft
+  state:
+    pending: Noch nicht erreicht
+    running: Läuft
+    waiting: Wartet
+    succeeded: Erfolgreich
+    failed: Fehlgeschlagen
+    skipped: Übersprungen
+    stopped: Hier gestoppt
+    notRun: Nicht ausgeführt
+  list:
+    label: Nodes
+    reads: Liest {list}
+    empty: Noch keine Nodes
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index cd745a45f4..5f7d2f225a 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -195,7 +195,6 @@ common:
     somethingWentWrong: Something went wrong. Try again.
     tryAgain: Try again
   flow:
-    aiEditor: AI editor
     resetView: Reset view
     zoomIn: Zoom in
     zoomOut: Zoom out
@@ -523,3 +522,57 @@ schemaTree:
   maybeEmpty: may be empty
   more: '{count, plural, one {# more field} other {# more fields}}'
   asTypeScript: Show as TypeScript
+
+flow:
+  canvas:
+    roleDescription: flow chart
+    keyboardHelp: Use the arrow keys to follow the connections between nodes, Home and End to jump to Start and End, and Enter to open a node.
+    arranging: Arranging the nodes…
+    arrangeFailed: Couldn't arrange the nodes, so they're shown in one column.
+    touchHint: Use two fingers to move the chart
+  controls:
+    showList: Show as list
+    showChart: Show as chart
+    legend: Legend
+  legend:
+    title: How to read the chart
+  node:
+    entry: Start
+    exit: End
+    triggers: Starts
+    inputs: Input
+    outputs: Returns
+    outcomes: Ends
+    noInput: No input
+    noOutput: Returns nothing
+    more: +{count} more
+    unreachable: Never runs
+    position: Node {index} of {count}
+    section: '{heading}: {items}'
+    rowWithDetail: '{label} ({detail})'
+  gate:
+    onlyIf: Only if
+    ifElse: If
+    name: 'Condition for {node}: {condition}'
+    branches: Yes leads to {yes}, No leads to {no}
+  branch:
+    'yes': 'Yes'
+    'no': 'No'
+  relation:
+    comesFrom: Comes from {list}
+    leadsTo: Leads to {list}
+    onlyIf: Runs only if {condition}
+    otherwise: Runs when the condition of {node} is false
+  state:
+    pending: Not reached yet
+    running: Running
+    waiting: Waiting
+    succeeded: Succeeded
+    failed: Failed
+    skipped: Skipped
+    stopped: Stopped here
+    notRun: Not run
+  list:
+    label: Nodes
+    reads: Reads {list}
+    empty: No nodes yet
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 7f69f43a2a..ab73d28bbd 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -195,7 +195,6 @@ common:
     somethingWentWrong: Une erreur s'est produite. Réessaie.
     tryAgain: Réessayer
   flow:
-    aiEditor: Éditeur IA
     resetView: Réinitialiser la vue
     zoomIn: Zoomer
     zoomOut: Dézoomer
@@ -523,3 +522,57 @@ schemaTree:
   maybeEmpty: peut être vide
   more: '{count, plural, one {# autre champ} many {# autres champs} other {# autres champs}}'
   asTypeScript: Afficher en TypeScript
+
+flow:
+  canvas:
+    roleDescription: diagramme de flux
+    keyboardHelp: Utilise les flèches pour suivre les liens entre les nœuds, Début et Fin pour aller au début et à la fin, et Entrée pour ouvrir un nœud.
+    arranging: Disposition des nœuds…
+    arrangeFailed: Impossible de disposer les nœuds, ils sont donc affichés en une colonne.
+    touchHint: Utilise deux doigts pour déplacer le diagramme
+  controls:
+    showList: Afficher en liste
+    showChart: Afficher en diagramme
+    legend: Légende
+  legend:
+    title: Comment lire le diagramme
+  node:
+    entry: Début
+    exit: Fin
+    triggers: Démarre
+    inputs: Entrée
+    outputs: Renvoie
+    outcomes: Se termine
+    noInput: Aucune entrée
+    noOutput: Ne renvoie rien
+    more: +{count} de plus
+    unreachable: Ne s'exécute jamais
+    position: Nœud {index} sur {count}
+    section: '{heading} : {items}'
+    rowWithDetail: '{label} ({detail})'
+  gate:
+    onlyIf: Seulement si
+    ifElse: Si
+    name: 'Condition pour {node} : {condition}'
+    branches: Oui mène à {yes}, Non à {no}
+  branch:
+    'yes': Oui
+    'no': Non
+  relation:
+    comesFrom: Vient de {list}
+    leadsTo: Mène à {list}
+    onlyIf: S'exécute seulement si {condition}
+    otherwise: S'exécute quand la condition de {node} est fausse
+  state:
+    pending: Pas encore atteint
+    running: En cours
+    waiting: En attente
+    succeeded: Réussi
+    failed: Échoué
+    skipped: Ignoré
+    stopped: Arrêté ici
+    notRun: Non exécuté
+  list:
+    label: Nœuds
+    reads: Lit {list}
+    empty: Aucun nœud pour l'instant
diff --git a/packages/ui/tests/utils/contrast.ts b/packages/ui/tests/utils/contrast.ts
new file mode 100644
index 0000000000..fe88d1a18b
--- /dev/null
+++ b/packages/ui/tests/utils/contrast.ts
@@ -0,0 +1,71 @@
+/**
+ * Contrast as the browser paints it, for real-Chromium tests: reads the
+ * colours the shipped CSS resolves to, lays each over what lies behind it
+ * on a 1×1 canvas, and answers the WCAG ratio. axe judges text only (and
+ * gives up on short text); lines, glyphs and borders need this.
+ */
+
+type Rgb = readonly [number, number, number];
+
+let context: CanvasRenderingContext2D | null = null;
+
+function pixel(): CanvasRenderingContext2D {
+  if (context === null) {
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    context = canvas.getContext('2d', { willReadFrequently: true });
+    if (context === null)
+      throw new Error('No 2D canvas to measure contrast on');
+  }
+  return context;
+}
+
+/** Paints `layers` bottom-up on white and reads the colour that results. */
+export function composite(layers: readonly string[]): Rgb {
+  const ctx = pixel();
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, 1, 1);
+  for (const layer of layers) {
+    ctx.fillStyle = layer;
+    ctx.fillRect(0, 0, 1, 1);
+  }
+  const [r = 0, g = 0, b = 0] = ctx.getImageData(0, 0, 1, 1).data;
+  return [r, g, b];
+}
+
+function luminance(rgb: Rgb): number {
+  const [r, g, b] = rgb.map((value) => {
+    const channel = value / 255;
+    return channel <= 0.039_28
+      ? channel / 12.92
+      : ((channel + 0.055) / 1.055) ** 2.4;
+  }) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a: Rgb, b: Rgb): number {
+  const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [
+    number,
+    number,
+  ];
+  return (light + 0.05) / (dark + 0.05);
+}
+
+/** Every background from the page down to `element`, outermost first. */
+export function backgroundsOf(element: Element): string[] {
+  const layers: string[] = [];
+  for (
+    let node: Element | null = element;
+    node !== null;
+    node = node.parentElement
+  )
+    layers.unshift(getComputedStyle(node).backgroundColor);
+  return layers;
+}
+
+/** The ratio of `color` (any CSS colour) to the layers behind `element`. */
+export function ratioAgainst(element: Element, color: string): number {
+  const behind = backgroundsOf(element);
+  return contrast(composite([...behind, color]), composite(behind));
+}

From 156d969640b5e1ea2a4bbaabd34ac4b9b561d914 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:26:07 +0200
Subject: [PATCH 18/78] refactor(ui): keep the flow layout's helpers inside
 their modules

Knip found constants and helpers the flow modules exported but nothing
outside them reads: the box and gate size tables, the frame header id,
the row grouping, the node ring and lift classes, the chip pill and the
contrast helper's internals. They stay module-private; an unused frame
header height and end-direction helper go.
---
 packages/ui/src/components/flow/layout/elk-options.ts    | 3 ---
 packages/ui/src/components/flow/layout/geometry.ts       | 9 ---------
 .../ui/src/components/flow/layout/layout-flow-graph.ts   | 4 ++--
 packages/ui/src/components/flow/layout/sizes.ts          | 6 +++---
 .../src/components/flow/render/flow-render-context.tsx   | 6 +++---
 packages/ui/src/components/flow/render/step-node.tsx     | 2 +-
 packages/ui/tests/utils/contrast.ts                      | 6 +++---
 7 files changed, 12 insertions(+), 24 deletions(-)

diff --git a/packages/ui/src/components/flow/layout/elk-options.ts b/packages/ui/src/components/flow/layout/elk-options.ts
index aad10c7c65..f60756744f 100644
--- a/packages/ui/src/components/flow/layout/elk-options.ts
+++ b/packages/ui/src/components/flow/layout/elk-options.ts
@@ -83,6 +83,3 @@ export const FLOW_ELK_LIVE: Readonly<Record<string, string>> = {
 export const FLOW_ELK_NODE: Readonly<Record<string, string>> = {
   'elk.portConstraints': 'FIXED_SIDE',
 };
-
-/** The size of the frame header node an incoming edge must route around. */
-export const FLOW_FRAME_HEADER_HEIGHT = 24;
diff --git a/packages/ui/src/components/flow/layout/geometry.ts b/packages/ui/src/components/flow/layout/geometry.ts
index 370a38fa11..23caebc8d5 100644
--- a/packages/ui/src/components/flow/layout/geometry.ts
+++ b/packages/ui/src/components/flow/layout/geometry.ts
@@ -199,15 +199,6 @@ export function roundedOrthogonalPath(
   return path;
 }
 
-/** The direction of the route's last segment, as a unit vector. */
-export function endDirection(points: readonly FlowPoint[]): FlowPoint {
-  const end = points.at(-1);
-  const before = points.at(-2);
-  if (end === undefined || before === undefined) return { x: 0, y: 1 };
-  const length = distance(before, end) || 1;
-  return { x: (end.x - before.x) / length, y: (end.y - before.y) / length };
-}
-
 /**
  * Whether the segment `a`–`b` passes through `rect` shrunk by `inset` on
  * every side — touching a border (where an edge meets its own box) does
diff --git a/packages/ui/src/components/flow/layout/layout-flow-graph.ts b/packages/ui/src/components/flow/layout/layout-flow-graph.ts
index 4027ed406f..1cfb1197a1 100644
--- a/packages/ui/src/components/flow/layout/layout-flow-graph.ts
+++ b/packages/ui/src/components/flow/layout/layout-flow-graph.ts
@@ -61,7 +61,7 @@ export interface LayoutFlowGraphOptions {
 }
 
 /** The id of a frame's header box, which edges route around. */
-export const frameHeaderId = (groupId: string) => `${groupId}:head`;
+const frameHeaderId = (groupId: string) => `${groupId}:head`;
 const headerEdgeId = (groupId: string, member: string) =>
   `${groupId}:head>${member}`;
 
@@ -306,7 +306,7 @@ const snapRect = (rect: FlowRect): FlowRect => ({
 
 /** Rows top to bottom: nodes whose centres share a line (ELK centres a
  *  row's boxes on it), each row left to right. */
-export function rowsOf(
+function rowsOf(
   nodes: Readonly<Record<string, FlowRect>>,
   order: readonly string[],
 ): string[][] {
diff --git a/packages/ui/src/components/flow/layout/sizes.ts b/packages/ui/src/components/flow/layout/sizes.ts
index b762579530..0eec3130fe 100644
--- a/packages/ui/src/components/flow/layout/sizes.ts
+++ b/packages/ui/src/components/flow/layout/sizes.ts
@@ -20,7 +20,7 @@ import type {
 export const FLOW_NODE_WIDTH = 288;
 
 /** Pieces every box is built from. */
-export const FLOW_BOX = {
+const FLOW_BOX = {
   padding: 12,
   titleRow: 20,
   typeRow: 16,
@@ -36,7 +36,7 @@ export const FLOW_BOX = {
   notice: 28,
 } as const;
 
-export const FLOW_GATE = {
+const FLOW_GATE = {
   height: 40,
   minWidth: 160,
   maxWidth: FLOW_NODE_WIDTH,
@@ -203,7 +203,7 @@ function exitHeight(node: FlowExitNode): number {
 }
 
 /** The gate pill's width: the condition plus its chrome, 160 to 288 px. */
-export function flowGateWidth(
+function flowGateWidth(
   node: FlowGateNode,
   measure: FlowTextMeasure = estimateFlowText,
 ): number {
diff --git a/packages/ui/src/components/flow/render/flow-render-context.tsx b/packages/ui/src/components/flow/render/flow-render-context.tsx
index e966b2a5c2..4be6929e20 100644
--- a/packages/ui/src/components/flow/render/flow-render-context.tsx
+++ b/packages/ui/src/components/flow/render/flow-render-context.tsx
@@ -50,19 +50,19 @@ export function useFlowRender(): FlowRenderContextValue {
 const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
 
 /** The id of a node's hidden description. */
-export const flowDescriptionId = (baseId: string, nodeId: string) =>
+const flowDescriptionId = (baseId: string, nodeId: string) =>
   `${baseId}-description-${nodeId}`;
 
 /**
  * Hover lifts a box: a `shadow-md` layer fades in over its resting shadow
  * (a shadow itself never animates).
  */
-export const FLOW_NODE_LIFT =
+const FLOW_NODE_LIFT =
   'after:pointer-events-none after:absolute after:inset-[-1px] after:rounded-[inherit] after:opacity-0 after:shadow-md after:transition-opacity after:duration-[var(--duration-short)] after:ease-[var(--ease-out-quint)] hover:after:opacity-100';
 
 /** Selection and keyboard focus draw the same ring; a problem keeps its own
  *  frame colour beside it. */
-export const FLOW_NODE_RING =
+const FLOW_NODE_RING =
   'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none';
 
 /**
diff --git a/packages/ui/src/components/flow/render/step-node.tsx b/packages/ui/src/components/flow/render/step-node.tsx
index 91de0fcaaa..8a1e3a9369 100644
--- a/packages/ui/src/components/flow/render/step-node.tsx
+++ b/packages/ui/src/components/flow/render/step-node.tsx
@@ -29,7 +29,7 @@ const CHIP_TONE: Record<NonNullable<FlowChip['tone']>, string> = {
 };
 
 /** A short word on a box's face: 20 px, never wrapping. */
-export function FlowChipPill({ chip }: { chip: FlowChip }) {
+function FlowChipPill({ chip }: { chip: FlowChip }) {
   const Icon = chip.icon;
   return (
     <span
diff --git a/packages/ui/tests/utils/contrast.ts b/packages/ui/tests/utils/contrast.ts
index fe88d1a18b..eaae1e7ed8 100644
--- a/packages/ui/tests/utils/contrast.ts
+++ b/packages/ui/tests/utils/contrast.ts
@@ -22,7 +22,7 @@ function pixel(): CanvasRenderingContext2D {
 }
 
 /** Paints `layers` bottom-up on white and reads the colour that results. */
-export function composite(layers: readonly string[]): Rgb {
+function composite(layers: readonly string[]): Rgb {
   const ctx = pixel();
   ctx.fillStyle = '#ffffff';
   ctx.fillRect(0, 0, 1, 1);
@@ -44,7 +44,7 @@ function luminance(rgb: Rgb): number {
   return 0.2126 * r + 0.7152 * g + 0.0722 * b;
 }
 
-export function contrast(a: Rgb, b: Rgb): number {
+function contrast(a: Rgb, b: Rgb): number {
   const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [
     number,
     number,
@@ -53,7 +53,7 @@ export function contrast(a: Rgb, b: Rgb): number {
 }
 
 /** Every background from the page down to `element`, outermost first. */
-export function backgroundsOf(element: Element): string[] {
+function backgroundsOf(element: Element): string[] {
   const layers: string[] = [];
   for (
     let node: Element | null = element;

From 47ac517923460f0431ee0e59b2755370576ae7fa Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:26:14 +0200
Subject: [PATCH 19/78] test(ui): time 40-node flow layouts in the worker

Three 40-node graphs laid out in the worker in Chromium, after one
warm-up layout, must each finish under 1.5 s (an order-of-magnitude
guard for a loaded runner; locally 45 to 84 ms). The times are logged.
---
 .../flow/workflow-canvas.browser.test.tsx     | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
index 3b35d77ec4..3363a6dd0a 100644
--- a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -9,9 +9,14 @@ import { ratioAgainst } from '@/tests/utils/contrast';
 import { render, screen, waitFor } from '@/tests/utils/render';
 
 import { resetFlowElkForTests } from './layout/elk-client';
+import { layoutFlowGraph } from './layout/layout-flow-graph';
 import { flowNodeSize } from './layout/sizes';
 import { flowEdgePaths } from './render/routed-edge';
-import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+import {
+  branchFlowGraph,
+  syntheticFlowGraph,
+  triageFlowGraph,
+} from './testing/flow-fixtures';
 import { edgeBoxCrossings } from './testing/flow-geometry';
 import type { FlowGraph, FlowLayout, FlowRect } from './types';
 import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
@@ -371,6 +376,21 @@ describe('WorkflowCanvas', () => {
     expect(window.localStorage.getItem('tale:flow-view')).toBe('chart');
   });
 
+  it('lays 40 nodes out in the worker inside the budget', async () => {
+    // Warm the worker, then time a layout of a graph it has not seen.
+    await layoutFlowGraph(syntheticFlowGraph(20, 3));
+    const times: number[] = [];
+    for (const seed of [7, 11, 23]) {
+      const layout = await layoutFlowGraph(syntheticFlowGraph(40, seed));
+      expect(layout.engine).toBe('worker');
+      times.push(layout.ms);
+    }
+    console.info(
+      `40-node layouts in the worker: ${times.map((ms) => Math.round(ms)).join(', ')} ms`,
+    );
+    expect(Math.max(...times)).toBeLessThan(1_500);
+  });
+
   it('shows a skeleton column, busy, until the first layout lands', async () => {
     const { container } = render(
       <Harness graph={triageFlowGraph()} layoutKey="fresh-key" />,

From 51272c77ef7d893c6b22f383d8ffa4139255c3c0 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:27:20 +0200
Subject: [PATCH 20/78] test(ui): check a pointer reaches a flow edge's detail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

React Flow turns pointer events off on an edge nothing selects; the
routed edge's wide hit path takes them back. Hit-testing the middle of
Open issues → Report finds the path whose title carries its detail.
---
 .../flow/workflow-canvas.browser.test.tsx           | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
index 3363a6dd0a..a1b19cb993 100644
--- a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -188,6 +188,19 @@ describe('WorkflowCanvas', () => {
     // No edge is React Flow's own curve: every edge group holds a routed path.
     for (const group of container.querySelectorAll('.react-flow__edge'))
       expect(group.querySelector('path[data-flow-edge]')).not.toBeNull();
+    // A pointer resting on a line with a detail reaches its words.
+    const path = container.querySelector<SVGPathElement>(
+      'path[data-flow-edge="open_issues>report"]',
+    );
+    const middle = path?.getPointAtLength(path.getTotalLength() / 2);
+    const svg = path?.ownerSVGElement?.getScreenCTM();
+    if (middle === undefined || svg === null || svg === undefined)
+      throw new Error('no route to point at');
+    const point = new DOMPoint(middle.x, middle.y).matrixTransform(svg);
+    const hit = document
+      .elementsFromPoint(point.x, point.y)
+      .find((element) => element.querySelector(':scope > title') !== null);
+    expect(hit?.querySelector('title')?.textContent).toBe('Carries .issues');
   });
 
   it('draws every box at its size and no line through any box on the page', async () => {

From ca4ccc376e94fdfd5aa200ee803b7688fb5a0a2a Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:27:30 +0200
Subject: [PATCH 21/78] docs(ui): guide the workflow canvas

ui.tale.dev gains a Workflow canvas guide after Flow node issues: the
graph a host builds, the routed lines and their kinds, frames, Start
and End, problem markers, the List view, the keyboard, fit and touch,
layoutFlowGraph and flowNodeSize, and every prop. Six live demos show
a laid-out workflow, a route round a frame, frames, Start and End,
problems and the List view; Colors explains the lines' tokens,
including --flow-edge-negative. Stories mirror the demos on the shared
fixtures, and the package README names the new imports.
---
 packages/ui/README.md                         |   2 +-
 .../flow/workflow-canvas.stories.tsx          | 125 +++++++++++++
 services/ui-docs/app/content/frontmatter.json |   7 +
 .../ui-docs/app/demos/flow/containers.tsx     |  68 ++++++++
 .../ui-docs/app/demos/flow/entry-exit.tsx     | 100 +++++++++++
 services/ui-docs/app/demos/flow/issues.tsx    |  68 ++++++++
 services/ui-docs/app/demos/flow/layout.tsx    | 164 ++++++++++++++++++
 services/ui-docs/app/demos/flow/list-view.tsx |  61 +++++++
 .../ui-docs/app/demos/flow/routed-edges.tsx   |  84 +++++++++
 .../content/components/workflow-canvas.md     | 130 ++++++++++++++
 .../ui-docs/content/foundations/colors.md     |   4 +
 services/ui-docs/content/nav.json             |   1 +
 services/ui-docs/content/published.json       |   1 +
 13 files changed, 814 insertions(+), 1 deletion(-)
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.stories.tsx
 create mode 100644 services/ui-docs/app/demos/flow/containers.tsx
 create mode 100644 services/ui-docs/app/demos/flow/entry-exit.tsx
 create mode 100644 services/ui-docs/app/demos/flow/issues.tsx
 create mode 100644 services/ui-docs/app/demos/flow/layout.tsx
 create mode 100644 services/ui-docs/app/demos/flow/list-view.tsx
 create mode 100644 services/ui-docs/app/demos/flow/routed-edges.tsx
 create mode 100644 services/ui-docs/content/components/workflow-canvas.md

diff --git a/packages/ui/README.md b/packages/ui/README.md
index 165a4063dd..f86c741eaa 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -19,7 +19,7 @@ and stories live together under `src/components/<family>/`.
 | Layout and navigation | `page-layout`, `adaptive-header`, `sub-panel`, `header-breadcrumbs`, `tab-navigation` |
 | Dialogs and feedback | `dialog/form-dialog`, `dialog/delete-dialog`, `toaster`, `use-toast`, `use-retry-focus` |
 | Problems a check found | `issue-list`, `issue-summary`, `issue-severity`, `field-issue-messages`, `issue-focus`, `flow/node-issue-marker` |
-| Editing and diagrams | `editor`, `wizard/*`, `catalog/*`, `filters/*`, `flow/*` |
+| Editing and diagrams | `editor`, `wizard/*`, `catalog/*`, `filters/*`, `flow/workflow-canvas`, `flow/flow-step-list`, `flow/layout`, `flow/*` |
 | Documentation sites | `docs/docs-layout`, `docs/docs-header`, `docs/docs-article`, `docs/docs-not-found`, `docs/page-actions`, `search/static-index/*` |
 | Shared infrastructure | `i18n/*`, `markdown/*`, `seo/*`, `server`, `monitoring/*`, `theme`, `testing/*` |
 | Large custom collections | `use-virtual-list`; [windowing and focus guidance](https://ui.tale.dev/docs/patterns/list-page#bound-a-custom-collections-rendering) |
diff --git a/packages/ui/src/components/flow/workflow-canvas.stories.tsx b/packages/ui/src/components/flow/workflow-canvas.stories.tsx
new file mode 100644
index 0000000000..0838cd9d30
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.stories.tsx
@@ -0,0 +1,125 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { TooltipProvider } from '../overlays/tooltip';
+import { FlowStepList } from './flow-step-list';
+import {
+  branchFlowGraph,
+  reviewPullRequestsFlowGraph,
+  syntheticFlowGraph,
+  triageFlowGraph,
+  triageInboxFlowGraph,
+} from './testing/flow-fixtures';
+import type { FlowGraph } from './types';
+import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
+
+const meta: Meta<typeof WorkflowCanvas> = {
+  title: 'Flow/WorkflowCanvas',
+  component: WorkflowCanvas,
+  tags: ['autodocs'],
+  // Conditions show their full words in a tooltip, which needs a provider;
+  // the app gets one from `AppShell`.
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <Story />
+      </TooltipProvider>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `
+A workflow drawn from its data with an automatic ELK layout: Start, steps,
+conditions with Yes and No, frames round iterating steps, End, and lines
+along routes that never cross a box. One Tab stop, arrows follow the lines;
+the List view says the same in text. See the guide on ui.tale.dev.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof WorkflowCanvas>;
+
+/** A canvas whose selection the story keeps, in a frame of its own size. */
+function Selectable({
+  graph,
+  height = 720,
+  ...props
+}: Partial<WorkflowCanvasProps> & { graph: FlowGraph; height?: number }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ height }} className="p-4">
+      <WorkflowCanvas
+        aria-label="Workflow"
+        layoutKey="story"
+        framed
+        {...props}
+        graph={graph}
+        selectedId={selected}
+        onSelect={setSelected}
+      />
+    </div>
+  );
+}
+
+/** Triage GitHub issues: the long edge runs round Score's frame. */
+export const Layout: Story = {
+  render: () => (
+    <Selectable
+      graph={triageFlowGraph()}
+      legend={[
+        {
+          id: 'data',
+          swatch: { edge: 'data' },
+          label: 'Reads the output above',
+        },
+        { id: 'exit', swatch: { edge: 'exit' }, label: 'The run returns it' },
+        { id: 'frame', swatch: { node: 'frame' }, label: 'Runs once per item' },
+      ]}
+    />
+  ),
+};
+
+/** If/else, an else-if, a step that goes on after failing, a repeat. */
+export const Branches: Story = {
+  render: () => <Selectable graph={branchFlowGraph()} height={900} />,
+};
+
+/** Three steps over the same list, a frame each. */
+export const Frames: Story = {
+  render: () => <Selectable graph={reviewPullRequestsFlowGraph()} />,
+};
+
+/** Problems marked on a condition, a step and End. */
+export const Problems: Story = {
+  render: () => (
+    <Selectable
+      graph={triageInboxFlowGraph()}
+      issues={
+        new Map([
+          ['__gate:triage', { errors: 1, warnings: 0 }],
+          ['propose', { errors: 0, warnings: 2 }],
+          ['__end', { errors: 1, warnings: 0 }],
+        ])
+      }
+    />
+  ),
+};
+
+/** Forty nodes: shown from the top at a readable zoom. */
+export const Large: Story = {
+  render: () => <Selectable graph={syntheticFlowGraph(40)} />,
+};
+
+/** The same graph as a list. */
+export const ListView: Story = {
+  render: () => (
+    <div className="max-w-md p-4">
+      <FlowStepList graph={branchFlowGraph()} aria-label="Route a ticket" />
+    </div>
+  ),
+};
diff --git a/services/ui-docs/app/content/frontmatter.json b/services/ui-docs/app/content/frontmatter.json
index ccf3024a38..1145e3830a 100644
--- a/services/ui-docs/app/content/frontmatter.json
+++ b/services/ui-docs/app/content/frontmatter.json
@@ -111,6 +111,13 @@
       "description": "Show brief completion feedback, avoid duplicate viewports, and keep essential information on the page."
     }
   },
+  "components/workflow-canvas": {
+    "slug": "components/workflow-canvas",
+    "frontmatter": {
+      "title": "Workflow canvas",
+      "description": "Draw a workflow from its data with an automatic layout, lines that route round every box, a keyboard path through it and a List view that says the same in text."
+    }
+  },
   "foundations/accessibility": {
     "slug": "foundations/accessibility",
     "frontmatter": {
diff --git a/services/ui-docs/app/demos/flow/containers.tsx b/services/ui-docs/app/demos/flow/containers.tsx
new file mode 100644
index 0000000000..d244f9ce1c
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/containers.tsx
@@ -0,0 +1,68 @@
+import type { FlowGraph, FlowGroup } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+
+const step = (id: string, label: string, typeLabel: string) => ({
+  id,
+  kind: 'step' as const,
+  label,
+  typeLabel,
+});
+
+const each = (id: string): FlowGroup => ({
+  id: `each:${id}`,
+  kind: 'each',
+  label: 'For each item of pulls of Open pulls',
+  members: [id],
+});
+
+// Three nodes each go through the same list, one after the other: one frame
+// each, since each finishes every item before the next one starts. "Poll"
+// repeats until it is done; its frame draws the loop.
+const GRAPH: FlowGraph = {
+  nodes: [
+    { id: '__start', kind: 'entry', triggers: [], inputs: [] },
+    step('open_pulls', 'Open pulls', 'GitHub · List pull requests'),
+    step('diff', 'Diff', 'GitHub · Get pull request diff'),
+    step('review', 'Review', 'Language model'),
+    step('post', 'Post', 'GitHub · Create pull request review'),
+    step('poll', 'Poll', 'HTTP · Get status'),
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'r', label: 'The output of Review' }],
+    },
+  ],
+  edges: [
+    { id: 'a', source: '__start', target: 'open_pulls', kind: 'entry' },
+    { id: 'b', source: 'open_pulls', target: 'diff', kind: 'data' },
+    { id: 'c', source: 'diff', target: 'review', kind: 'data' },
+    { id: 'd', source: 'review', target: 'post', kind: 'data' },
+    { id: 'e', source: 'post', target: 'poll', kind: 'data' },
+    { id: 'f', source: 'review', target: '__end', kind: 'exit' },
+    { id: 'g', source: 'poll', target: '__end', kind: 'completion' },
+  ],
+  groups: [
+    each('diff'),
+    each('review'),
+    each('post'),
+    {
+      id: 'repeat:poll',
+      kind: 'repeat',
+      label: 'Repeats until done is true, at most 5×',
+      members: ['poll'],
+    },
+  ],
+};
+
+export default function FlowContainersDemo() {
+  return (
+    <div className="h-[40rem] w-full">
+      <WorkflowCanvas
+        graph={GRAPH}
+        aria-label="Review pull requests"
+        layoutKey="containers"
+        framed
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/entry-exit.tsx b/services/ui-docs/app/demos/flow/entry-exit.tsx
new file mode 100644
index 0000000000..bcaf1a618c
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/entry-exit.tsx
@@ -0,0 +1,100 @@
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Ban, CircleCheck, CircleX, Clock, Hand, Webhook } from 'lucide-react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    {
+      id: '__start',
+      kind: 'entry',
+      triggers: [
+        {
+          id: 'schedule',
+          icon: Clock,
+          label: 'Every Monday at 08:00 · Europe/Zurich',
+          note: 'Next Mon 12 Oct, 08:00',
+        },
+        {
+          id: 'webhook',
+          icon: Webhook,
+          label: 'A request to its webhook URL',
+          badge: { label: 'Off', tone: 'neutral' },
+        },
+        { id: 'manual', icon: Hand, label: 'By hand, the API or MCP' },
+      ],
+      inputs: [
+        { id: 'owner', label: 'owner', detail: 'text · required', code: true },
+        { id: 'repo', label: 'repo', detail: 'text · required', code: true },
+        { id: 'limit', label: 'limit', detail: 'a whole number', code: true },
+        { id: 'label', label: 'label', detail: 'text', code: true },
+        { id: 'since', label: 'since', detail: 'text', code: true },
+      ],
+      notice: {
+        tone: 'warning',
+        text: 'The schedule starts runs without owner and repo.',
+      },
+    },
+    {
+      id: 'fetch',
+      kind: 'step',
+      label: 'Fetch',
+      typeLabel: 'GitHub · List issues',
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [
+        {
+          id: 'count',
+          label: 'count',
+          detail: 'a number · from Fetch',
+          code: true,
+        },
+        {
+          id: 'issues',
+          label: 'issues',
+          detail: 'list of objects · from Fetch',
+          code: true,
+        },
+      ],
+      shape: '{ count: number; issues: object[] }',
+      outcomes: [
+        {
+          id: 'ok',
+          icon: CircleCheck,
+          label: 'Succeeded',
+          detail: 'returns the output',
+        },
+        {
+          id: 'failed',
+          icon: CircleX,
+          label: 'Failed',
+          detail: 'when Fetch fails',
+        },
+        {
+          id: 'stopped',
+          icon: Ban,
+          label: 'Stopped',
+          detail: 'when someone stops it',
+        },
+      ],
+    },
+  ],
+  edges: [
+    { id: 'a', source: '__start', target: 'fetch', kind: 'entry' },
+    { id: 'b', source: 'fetch', target: '__end', kind: 'exit' },
+  ],
+};
+
+export default function FlowEntryExitDemo() {
+  return (
+    <div className="h-[44rem] w-full">
+      <WorkflowCanvas
+        graph={GRAPH}
+        aria-label="Import issues"
+        layoutKey="entry-exit"
+        framed
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/issues.tsx b/services/ui-docs/app/demos/flow/issues.tsx
new file mode 100644
index 0000000000..db63b86d95
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/issues.tsx
@@ -0,0 +1,68 @@
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import type { IssueCounts } from '@tale/ui/issue-summary';
+import { useState } from 'react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    { id: '__start', kind: 'entry', triggers: [], inputs: [] },
+    {
+      id: 'inbox',
+      kind: 'step',
+      label: 'Inbox',
+      typeLabel: 'Conversations · List untriaged',
+    },
+    {
+      id: '__gate:triage',
+      kind: 'gate',
+      label: 'Triage',
+      mode: 'only-if',
+      condition: 'Inbox has conversations',
+    },
+    {
+      id: 'triage',
+      kind: 'step',
+      label: 'Triage',
+      typeLabel: 'Language model',
+      reads: [{ id: 'inbox', label: 'Inbox' }],
+      conditional: true,
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 's', label: 'summary', code: true }],
+    },
+  ],
+  edges: [
+    { id: 'a', source: '__start', target: 'inbox', kind: 'entry' },
+    { id: 'b', source: 'inbox', target: '__gate:triage', kind: 'order' },
+    { id: 'c', source: 'inbox', target: 'triage', kind: 'data' },
+    { id: 'd', source: '__gate:triage', target: 'triage', kind: 'gate' },
+    { id: 'e', source: 'triage', target: '__end', kind: 'exit' },
+  ],
+};
+
+// Problems a check found, grouped by the node each one names — Start,
+// End and a condition can carry them too.
+const ISSUES: ReadonlyMap<string, IssueCounts> = new Map([
+  ['__start', { errors: 0, warnings: 1 }],
+  ['__gate:triage', { errors: 1, warnings: 0 }],
+  ['triage', { errors: 2, warnings: 1 }],
+]);
+
+export default function FlowIssuesDemo() {
+  const [selected, setSelected] = useState<string | null>('triage');
+  return (
+    <div className="h-[34rem] w-full">
+      <WorkflowCanvas
+        graph={GRAPH}
+        aria-label="Triage inbox"
+        layoutKey="issues"
+        issues={ISSUES}
+        selectedId={selected}
+        onSelect={setSelected}
+        framed
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/layout.tsx b/services/ui-docs/app/demos/flow/layout.tsx
new file mode 100644
index 0000000000..c2783d0cde
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/layout.tsx
@@ -0,0 +1,164 @@
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import {
+  Braces,
+  CircleCheck,
+  CircleDot,
+  CircleX,
+  Clock,
+  Hand,
+  Sparkles,
+  Square,
+} from 'lucide-react';
+import { useState } from 'react';
+
+// A host builds this from its own document: Start, then each node in the
+// order it runs, then End; edges from what each node reads.
+const GRAPH: FlowGraph = {
+  nodes: [
+    {
+      id: '__start',
+      kind: 'entry',
+      triggers: [
+        {
+          id: 'schedule',
+          icon: Clock,
+          label: 'Every day at 07:00 · UTC',
+          note: 'Next Thu 9 Oct, 07:00',
+        },
+        { id: 'manual', icon: Hand, label: 'By hand, the API or MCP' },
+      ],
+      inputs: [
+        { id: 'owner', label: 'owner', detail: 'text · required', code: true },
+        { id: 'repo', label: 'repo', detail: 'text · required', code: true },
+      ],
+    },
+    {
+      id: 'issues',
+      kind: 'step',
+      label: 'Issues',
+      icon: CircleDot,
+      typeLabel: 'GitHub · List issues',
+      reads: [{ id: 'input', label: 'run input (owner, repo)' }],
+      returns: { text: '{ issues: object[] }', code: true },
+    },
+    {
+      id: 'open_issues',
+      kind: 'step',
+      label: 'Open issues',
+      icon: Braces,
+      typeLabel: 'Transform',
+      reads: [{ id: 'issues', label: 'Issues' }],
+    },
+    {
+      id: 'score',
+      kind: 'step',
+      label: 'Score',
+      icon: Sparkles,
+      typeLabel: 'Language model · claude-haiku-4-5',
+      reads: [
+        { id: 'open_issues', label: 'Open issues' },
+        { id: 'item', label: 'each item' },
+      ],
+      description: 'Runs once for each item of issues of Open issues.',
+    },
+    {
+      id: 'report',
+      kind: 'step',
+      label: 'Report',
+      icon: Braces,
+      typeLabel: 'Transform',
+      reads: [
+        { id: 'open_issues', label: 'Open issues' },
+        { id: 'score', label: 'Score' },
+      ],
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'report', label: 'The output of Report' }],
+      outcomes: [
+        {
+          id: 'ok',
+          icon: CircleCheck,
+          label: 'Succeeded',
+          detail: 'returns the output',
+        },
+        {
+          id: 'failed',
+          icon: CircleX,
+          label: 'Failed',
+          detail: 'when one of 4 nodes fails',
+        },
+        {
+          id: 'stopped',
+          icon: Square,
+          label: 'Stopped',
+          detail: 'when someone stops it',
+        },
+      ],
+    },
+  ],
+  edges: [
+    { id: 'start>issues', source: '__start', target: 'issues', kind: 'entry' },
+    {
+      id: 'issues>open',
+      source: 'issues',
+      target: 'open_issues',
+      kind: 'data',
+    },
+    { id: 'open>score', source: 'open_issues', target: 'score', kind: 'data' },
+    {
+      id: 'open>report',
+      source: 'open_issues',
+      target: 'report',
+      kind: 'data',
+    },
+    { id: 'score>report', source: 'score', target: 'report', kind: 'data' },
+    { id: 'report>end', source: 'report', target: '__end', kind: 'exit' },
+  ],
+  groups: [
+    {
+      id: 'each:score',
+      kind: 'each',
+      label: 'For each item of issues of Open issues',
+      members: ['score'],
+    },
+  ],
+};
+
+export default function FlowLayoutDemo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div className="flex h-[36rem] w-full flex-col gap-2">
+      <WorkflowCanvas
+        graph={GRAPH}
+        aria-label="Triage GitHub issues"
+        layoutKey="triage"
+        selectedId={selected}
+        onSelect={setSelected}
+        framed
+        legend={[
+          {
+            id: 'data',
+            swatch: { edge: 'data' },
+            label: 'Reads the output of the node above',
+          },
+          {
+            id: 'exit',
+            swatch: { edge: 'exit' },
+            label: 'The run returns this node’s output',
+          },
+          {
+            id: 'frame',
+            swatch: { node: 'frame' },
+            label: 'Runs once for each item',
+          },
+        ]}
+      />
+      <p className="text-muted-foreground text-sm" aria-live="polite">
+        {selected === null ? 'Nothing selected' : `Selected: ${selected}`}
+      </p>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/list-view.tsx b/services/ui-docs/app/demos/flow/list-view.tsx
new file mode 100644
index 0000000000..7a1db60bf8
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/list-view.tsx
@@ -0,0 +1,61 @@
+import { FlowStepList } from '@tale/ui/flow/flow-step-list';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { useState } from 'react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    { id: '__start', kind: 'entry', triggers: [], inputs: [] },
+    {
+      id: 'classify',
+      kind: 'step',
+      label: 'Classify',
+      typeLabel: 'Language model',
+    },
+    {
+      id: '__gate:urgent',
+      kind: 'gate',
+      label: 'Urgent',
+      mode: 'if-else',
+      condition: 'urgent of Classify is true',
+    },
+    {
+      id: 'urgent',
+      kind: 'step',
+      label: 'Urgent',
+      typeLabel: 'Agent',
+      reads: [{ id: 'classify', label: 'Classify' }],
+    },
+    {
+      id: 'normal',
+      kind: 'step',
+      label: 'Normal',
+      typeLabel: 'Language model',
+      reads: [{ id: 'classify', label: 'Classify' }],
+    },
+    { id: '__end', kind: 'exit', outputs: [] },
+  ],
+  edges: [
+    { id: 'a', source: '__start', target: 'classify', kind: 'entry' },
+    { id: 'b', source: 'classify', target: '__gate:urgent', kind: 'order' },
+    { id: 'c', source: 'classify', target: 'urgent', kind: 'data' },
+    { id: 'd', source: '__gate:urgent', target: 'urgent', kind: 'branch-yes' },
+    { id: 'e', source: 'classify', target: 'normal', kind: 'data' },
+    { id: 'f', source: '__gate:urgent', target: 'normal', kind: 'branch-no' },
+    { id: 'g', source: 'urgent', target: '__end', kind: 'completion' },
+    { id: 'h', source: 'normal', target: '__end', kind: 'completion' },
+  ],
+};
+
+export default function FlowListViewDemo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div className="w-full max-w-md">
+      <FlowStepList
+        graph={GRAPH}
+        aria-label="Route a ticket"
+        selectedId={selected}
+        onSelect={setSelected}
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/routed-edges.tsx b/services/ui-docs/app/demos/flow/routed-edges.tsx
new file mode 100644
index 0000000000..d7561f83c1
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/routed-edges.tsx
@@ -0,0 +1,84 @@
+import type { FlowLayout } from '@tale/ui/flow/layout';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Switch } from '@tale/ui/switch';
+import { Braces, Sparkles } from 'lucide-react';
+import { useState } from 'react';
+
+const step = (id: string, label: string, typeLabel: string) => ({
+  id,
+  kind: 'step' as const,
+  label,
+  typeLabel,
+  icon: typeLabel === 'Transform' ? Braces : Sparkles,
+});
+
+// "Split" leads to "Report" directly and through "Score". A straight line
+// from Split to Report would cross Score's frame; the route goes round it.
+const GRAPH: FlowGraph = {
+  nodes: [
+    { id: '__start', kind: 'entry', triggers: [], inputs: [] },
+    step('split', 'Split', 'Transform'),
+    step('score', 'Score', 'Language model'),
+    step('report', 'Report', 'Transform'),
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'r', label: 'The output of Report' }],
+    },
+  ],
+  edges: [
+    { id: 'start>split', source: '__start', target: 'split', kind: 'entry' },
+    { id: 'split>score', source: 'split', target: 'score', kind: 'data' },
+    {
+      id: 'split>report',
+      source: 'split',
+      target: 'report',
+      kind: 'data',
+      detail: 'Carries .items',
+    },
+    { id: 'score>report', source: 'score', target: 'report', kind: 'data' },
+    { id: 'report>end', source: 'report', target: '__end', kind: 'exit' },
+  ],
+  groups: [
+    {
+      id: 'each:score',
+      kind: 'each',
+      label: 'For each item of Split',
+      members: ['score'],
+    },
+  ],
+};
+
+export default function FlowRoutedEdgesDemo() {
+  const [layout, setLayout] = useState<FlowLayout | null>(null);
+  const [showRoute, setShowRoute] = useState(false);
+  const route = layout?.edges['split>report']?.points ?? [];
+  return (
+    <div className="flex w-full flex-col gap-3">
+      <div className="h-[30rem]">
+        <WorkflowCanvas
+          graph={GRAPH}
+          aria-label="Split, score and report"
+          layoutKey="routed-edges"
+          framed
+          onLayout={setLayout}
+        />
+      </div>
+      <Switch
+        label="Show the route of Split → Report"
+        checked={showRoute}
+        onCheckedChange={setShowRoute}
+      />
+      {showRoute && (
+        <ol className="text-muted-foreground flex flex-wrap gap-x-3 font-mono text-xs">
+          {route.map((point, index) => (
+            <li key={index}>
+              ({point.x}, {point.y})
+            </li>
+          ))}
+        </ol>
+      )}
+    </div>
+  );
+}
diff --git a/services/ui-docs/content/components/workflow-canvas.md b/services/ui-docs/content/components/workflow-canvas.md
new file mode 100644
index 0000000000..5f08823f32
--- /dev/null
+++ b/services/ui-docs/content/components/workflow-canvas.md
@@ -0,0 +1,130 @@
+---
+title: Workflow canvas
+description: Draw a workflow from its data with an automatic layout, lines that route round every box, a keyboard path through it and a List view that says the same in text.
+---
+
+`WorkflowCanvas` draws a workflow from plain data: Start, the steps in the order they run, the conditions in front of them, End, and the frames round steps that run once per item or repeat. Nobody places a box. The layout is a pure function of the graph, so the same graph always draws the same picture, and lines follow routes that never cross a box.
+
+```tsx
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { FlowStepList } from '@tale/ui/flow/flow-step-list';
+import { FlowLegend } from '@tale/ui/flow/flow-legend';
+import { FlowNodeStatusBadge } from '@tale/ui/flow/node-status';
+import { layoutFlowGraph, flowNodeSize } from '@tale/ui/flow/layout';
+```
+
+## Draw a workflow
+
+<Demo name="flow/layout" />
+
+Build a `FlowGraph` and pass it with an `aria-label` and a `layoutKey`. Choose a box to see `onSelect` report it; choosing it again clears the selection.
+
+A graph has three parts:
+
+| Part | What it holds |
+| --- | --- |
+| `nodes` | In reading order: one `entry` (Start), the `step` nodes, a `gate` for each condition, placed right before the step it guards, and one `exit` (End). The order is the layout's model order and the List view's order. |
+| `edges` | `source`, `target` and a `kind`. An edge marked `layoutOnly` shapes the picture but is never drawn. |
+| `groups` | A frame round the steps that run once per item (`each`) or repeat (`repeat`), with the words of its header. |
+
+Every node is drawn from its data. A step shows its `icon`, `label` and `typeLabel`, what it `returns` (a shape in mono, or a sentence), up to two `chips` and `markers` in its title row. Its strip says what it `reads`. Pass `returns: null` to reserve the row while your host is still working the shape out: a pulse fills it, and the box does not grow when the shape arrives. A step that may be skipped (`conditional`) is drawn with a dashed border; one that never runs (`unreachable`) also carries a **Never runs** chip. Its text is never faded.
+
+`layoutKey` names what the picture shows, such as a document and the version on screen. When the same key gets a changed graph, the canvas lays it out again and keeps each row in its order, so no box swaps sides with its neighbour. A new key is another picture: it is laid out afresh and fades in.
+
+## Follow the lines
+
+<Demo name="flow/routed-edges" />
+
+Each line follows the route the layout computed: orthogonal, with 8 px rounded corners and an arrowhead tinted like the line. Split leads to Report past Score's frame, and its route goes round the frame instead of through it. Turn on the switch to see the route's points, which `onLayout` hands you with the rest of the layout.
+
+| `kind` | Drawn as | Means |
+| --- | --- | --- |
+| `data` | Solid | The target reads the source's output. |
+| `order` | Dashed | The target only mentions the source in a condition or a repeat. |
+| `gate` | Solid, from a condition | The step runs only if the condition holds. |
+| `branch-yes` / `branch-no` | Green / amber, with a Yes / No pill | Which step runs when the condition holds or does not. |
+| `entry` | Solid, from Start | The node reads no other node. |
+| `exit` | Solid, into End | The run returns this node's output. |
+| `completion` | Dotted, into End | Nothing reads this node: the run ends after it. |
+
+Colour never speaks alone: an `order` line is dashed, a `completion` line dotted, and the branches carry their words. Every line keeps 3:1 against the canvas in both themes. The No branch uses its own variable, `--flow-edge-negative`, because the warning amber is too faint for a line on white. Give an edge a `detail` ("Carries .items") to show it when a pointer rests on the line; put the same words in a node's description for the keyboard.
+
+## Frame steps that repeat
+
+<Demo name="flow/containers" />
+
+A frame is drawn round each step that runs once per item or repeats, with its header in your words. Give each iterating step a frame of its own, even when three steps go through the same list: each finishes every item before the next one starts, so one shared frame would claim the opposite. A `repeat` frame draws its loop as a dashed arc on its right.
+
+A frame is decoration, hidden from assistive technology. Repeat its words in the member's `description`, as `Runs once for each item of …`, so a screen reader hears them too. The header is a box the layout routes round, so no incoming line runs through its words.
+
+## Show Start and End
+
+<Demo name="flow/entry-exit" />
+
+Start lists what starts a run (`triggers`, three rows) and what each run receives (`inputs`, four rows). A section with more rows shows the first ones and "+2 more"; the List view and the node's description keep every row. A row takes a muted `detail`, a second-line `note`, a `badge` such as "Off", and `code` for a field name. `inputsEmpty` replaces "No input" with your own words, such as "Any JSON input". A `notice` adds one line of warning or information.
+
+End lists what a successful run returns (`outputs`), an optional one-line `shape`, and how a run can end (`outcomes`). Start's strip names the nodes it leads to; End's names the nodes it comes from.
+
+## Mark problems
+
+<Demo name="flow/issues" />
+
+Pass `issues`, a map from node id to error and warning counts. Each box shows the counts with [flow node issue markers](/docs/components/flow-node-issues), takes the frame colour of its worst problem, and says the counts at the end of its name. Start, End and conditions take counts like any step: key them by their ids, such as `__start`, `__end` and `__gate:triage`.
+
+## Read it as a list
+
+<Demo name="flow/list-view" />
+
+The List view says the same as the chart in text. `FlowStepList` renders an ordered list: Start, each node in reading order, End. Under each row it says what the node reads, when it runs, with the condition folded in as "Runs only if …" or "Runs when the condition of … is false", and where it leads. The members of a frame sit indented under the frame's words.
+
+Inside `WorkflowCanvas`, **Show as list** in the corner switches to this view and **Show as chart** switches back. The choice is stored in the browser under `tale:flow-view`. On a screen narrower than 24rem the list is the default. Pass `view` and `onViewChange` to control it yourself; the built-in button then goes away.
+
+## Use the keyboard
+
+The chart is one Tab stop: the selected node, else the node focused last, else Start. From there:
+
+| Key | Moves to |
+| --- | --- |
+| ↓ / ↑ | The next or previous node along a line, the one most in line with the current node |
+| ← / → | The neighbour in the same row |
+| Home / End | Start / End |
+| Enter / Space | Opens the node (`onSelect`); again on the selected node clears it |
+
+A box that takes keyboard focus outside the view is brought into it with the least pan. Each box is a real button, named by its title (a condition by "Condition for Triage: …") and its problems, and described by its position, the nodes it comes from and leads to, its conditions, what it reads, and your `description`. React Flow's own focus handling and keys stay off.
+
+When the button opens a panel, pass that panel's id as `controlsId`: each node then says whether the panel is open (`aria-expanded`) instead of whether it is pressed. Handle Escape in your page, where the panel lives.
+
+## Fit, zoom and touch
+
+`fitPolicy="auto"`, the default, fits the whole graph while the zoom stays at 0.5 or more. A taller graph is shown from its top at a readable zoom, centred on Start, and the reader scrolls on. `all` always fits every node. The fit follows the frame's size and a new layout while the view is still where the fit left it; once the reader zooms or pans, the view is theirs until **Reset view**.
+
+Viewport moves ease out over the duration tokens: zoom 150 ms, reveal 200 ms, reset 300 ms. Under reduced motion they jump. `framed` draws a bordered frame for a page; on a touch screen one finger then scrolls the page and two move the chart, and the first one-finger drag says so once. Set `touchPolicy` to choose either behaviour yourself.
+
+`topStart`, `topEnd`, `toolbar` and `cornerActions` place your own controls. `legend` adds a **Legend** button that explains the marks your chart uses in your words. `notice` sits above the chart and `empty` replaces it when the graph has no nodes.
+
+## Lay out without the canvas
+
+`layoutFlowGraph(graph, options)` answers the layout itself: absolute boxes, frame headers, routes, label boxes and rows. It runs ELK (`layered`, orthogonal) in a worker started from the file elkjs ships, so a layout never blocks typing and needs no `blob:` worker or `eval`. Where the worker cannot start, it lays out on the main thread and warns once. Where ELK fails or takes five seconds, it stands every node in one column and the canvas says it could not arrange the nodes; the chart never stays empty. Layouts of graphs already seen this session come from a cache.
+
+`flowNodeSize(node)` gives the size every box is drawn at, a pure function of its data. A step is 288 px wide and 88, 108, 116 or 136 px high, by whether it has a returns row and chips. Nothing a canvas shows on top, such as a run's state, a problem or a selection, changes a size, so none of it moves a box. A 40-node graph lays out in about a tenth of a second in the worker.
+
+## Props
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `graph` | `FlowGraph` | — | The workflow, in reading order. |
+| `aria-label` | `string` | — | The chart's name. |
+| `layoutKey` | `string` | — | What the picture shows; a new key lays out afresh. |
+| `selectedId` / `onSelect` | `string \| null` / `(id) => void` | — | The open node. |
+| `revealId` | `string \| null` | — | Brings this node into view. |
+| `issues` | `ReadonlyMap<string, IssueCounts>` | — | Problem counts by node id. |
+| `controlsId` | `string` | — | The panel a node opens. |
+| `view` / `onViewChange` | `'chart' \| 'list'` | stored choice | Controls the view. |
+| `framed` | `boolean` | `false` | A bordered frame for a page. |
+| `touchPolicy` | `'pan' \| 'page-scroll'` | `framed ? 'page-scroll' : 'pan'` | What one finger does on a touch screen. |
+| `fitPolicy` | `'all' \| 'auto'` | `'auto'` | How the view fits the graph. |
+| `topStart`, `topEnd`, `toolbar`, `cornerActions` | `ReactNode` | — | Your controls. |
+| `legend` | `FlowLegendEntry[]` | — | The legend's lines. |
+| `empty`, `notice` | `ReactNode` | — | Instead of, and above, the chart. |
+| `onLayout` | `(layout: FlowLayout) => void` | — | Every finished layout. |
diff --git a/services/ui-docs/content/foundations/colors.md b/services/ui-docs/content/foundations/colors.md
index 12cba76b72..8394a6a5de 100644
--- a/services/ui-docs/content/foundations/colors.md
+++ b/services/ui-docs/content/foundations/colors.md
@@ -66,6 +66,10 @@ Code has roles of its own: `--code-foreground` and `--code-token-keyword`, `-str
 
 Every token clears 4.5:1 on the page, the code-block surface (`bg-bg-elevated`), a card and the muted surface, and on the editor's template tint; `code-palette.test.ts` checks each pair in both themes. The editor's chrome adds `--code-line-number`, `--code-selection`, `--code-template-tint`, `--code-match` and the problem underlines `--code-squiggle-error`, `-warning` and `-info`, which keep 3:1. Use the roles for code, not for other text.
 
+## Colour the lines of a workflow
+
+A [workflow canvas](/docs/components/workflow-canvas) draws its lines from `FLOW_EDGE_COLORS` in `@tale/ui/flow/edge-palette`: `--muted-foreground` for the flow, `--success` for a Yes branch, `--destructive` only for the way into a failure, `--foreground` for emphasis and `--info-foreground` for activity. A No branch is amber, never red, through its own `--flow-edge-negative`: amber-700 in the light theme, because the warning amber is 2.2:1 on white and too faint for a line, and amber-500 in the dark one. Every line keeps 3:1 against the canvas in both themes, and shape carries the rest: dashed for an order, dotted for the end of a run.
+
 ## Add a color only when the meaning is missing
 
 First inspect the existing tokens and neighboring components. If a new semantic role is needed, add its token and intended theme treatment centrally. Record which foreground/background pairing it supports and check rest, hover, focus, selected, and error states.
diff --git a/services/ui-docs/content/nav.json b/services/ui-docs/content/nav.json
index 261e3636c0..2dedb5daab 100644
--- a/services/ui-docs/content/nav.json
+++ b/services/ui-docs/content/nav.json
@@ -29,6 +29,7 @@
         "components/schema-tree",
         "components/issue-list",
         "components/flow-node-issues",
+        "components/workflow-canvas",
         "components/field-issues",
         "components/recurrence-picker",
         "components/schedule-occurrence-list",
diff --git a/services/ui-docs/content/published.json b/services/ui-docs/content/published.json
index 182ac9eeb9..6098792c95 100644
--- a/services/ui-docs/content/published.json
+++ b/services/ui-docs/content/published.json
@@ -17,6 +17,7 @@
     "components/tabs-and-navigation",
     "components/time-field",
     "components/toast",
+    "components/workflow-canvas",
     "foundations/accessibility",
     "foundations/colors",
     "foundations/icons",

From 67a6f1e1316ce8c3615b1acae50ad7854d86ed03 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:29:32 +0200
Subject: [PATCH 22/78] fix(ui): pan a flow node into view without scrolling
 the frame

An arrow key moved focus with focus(), whose scroll-into-view shifted
the clipped canvas frame under the chart before the canvas could pan.
Focus now moves without scrolling and the canvas pans the box in with
the least move. A browser test walks to End and back to Start through
revealId on a frame too short for the graph.
---
 .../flow/workflow-canvas.browser.test.tsx     | 40 +++++++++++++++++++
 .../src/components/flow/workflow-canvas.tsx   |  4 +-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
index a1b19cb993..a43c2faa01 100644
--- a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -276,6 +276,46 @@ describe('WorkflowCanvas', () => {
     expect(document.activeElement?.closest('[data-flow-node]')).toBeNull();
   });
 
+  it('brings a node that takes keyboard focus, or that the host names, into view', async () => {
+    const { getByTestId, rerender } = await renderLaidOut(triageFlowGraph(), {
+      width: 600,
+      height: 320,
+      fitPolicy: 'auto',
+    });
+    const frame = getByTestId('frame').getBoundingClientRect();
+    const inside = (id: string) => {
+      const box = document
+        .querySelector(`[data-flow-node="${id}"]`)
+        ?.getBoundingClientRect();
+      return (
+        box !== undefined &&
+        box.top >= frame.top - 1 &&
+        box.bottom <= frame.bottom + 1 &&
+        box.left >= frame.left - 1 &&
+        box.right <= frame.right + 1
+      );
+    };
+    // Too tall to read whole: shown from Start at a readable zoom.
+    expect(inside('__start')).toBe(true);
+    expect(inside('__end')).toBe(false);
+    screen.getByRole('button', { name: 'Before the chart' }).focus();
+    await userEvent.tab();
+    await userEvent.keyboard('{End}');
+    await waitFor(() => expect(inside('__end')).toBe(true));
+    await viewportAtRest();
+    expect(inside('__end')).toBe(true);
+    rerender(
+      <Harness
+        graph={triageFlowGraph()}
+        width={600}
+        height={320}
+        fitPolicy="auto"
+        revealId="__start"
+      />,
+    );
+    await waitFor(() => expect(inside('__start')).toBe(true));
+  });
+
   it('describes each node: where it sits, where it leads, what it reads', async () => {
     await renderLaidOut(triageFlowGraph());
     const score = screen.getByRole('button', { name: 'Score' });
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
index 3a2ded6230..866c6f8ecd 100644
--- a/packages/ui/src/components/flow/workflow-canvas.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -432,7 +432,9 @@ function WorkflowCanvasInner({
         if (key === undefined || layout === null) return;
         event.preventDefault();
         const next = flowNeighbour(graph, layout, id, key);
-        if (next !== null) buttonOf(next)?.focus();
+        // The canvas pans the box into view itself; the browser's own
+        // scroll-into-view would shift the clipped frame instead.
+        if (next !== null) buttonOf(next)?.focus({ preventScroll: true });
       },
       onFocusNode: (id, event: FocusEvent<HTMLButtonElement>) => {
         setLastFocused(id);

From afdf90186e637869a630e270b36ac24b6836a036 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:34:03 +0200
Subject: [PATCH 23/78] test(ui): wait for the completion list to follow the
 dot

The list opens on "nodes" while the test types; under a loaded full
browser run the update after the dot landed after the test read the
options and it failed once (it passes alone). The test now waits for
the list to show what follows the dot.
---
 .../forms/code-editor/code-editor.browser.test.tsx | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
index 3db5e35784..dc18a32698 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -782,12 +782,16 @@ describe('CodeEditor completion', () => {
     await userEvent.keyboard('nodes.');
     const list = await listbox();
     expect(box).toHaveAttribute('aria-autocomplete', 'list');
+    // The list opens on "nodes" while typing; on a loaded runner the
+    // update after the dot can land a moment later.
+    await waitFor(() =>
+      expect(
+        [...list.querySelectorAll('[role="option"]')].map(
+          (option) => option.querySelector('.cm-completionLabel')?.textContent,
+        ),
+      ).toEqual(['score', 'open issues']),
+    );
     const options = [...list.querySelectorAll('[role="option"]')];
-    expect(
-      options.map(
-        (option) => option.querySelector('.cm-completionLabel')?.textContent,
-      ),
-    ).toEqual(['score', 'open issues']);
     expect(box.getAttribute('aria-activedescendant')).toBe(options[0].id);
     await userEvent.keyboard('{ArrowDown}');
     expect(box.getAttribute('aria-activedescendant')).toBe(options[1].id);

From 367a6ed7124edfa87568ce98165992d3d7b1ac3f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 12:36:32 +0200
Subject: [PATCH 24/78] fix(ui): keep a host's top-left controls in the List
 view

A host that controls the view puts its own switch in topStart; the
List view dropped it, so the reader could not switch back. The list's
top row now holds topStart on the left and topEnd on the right.
onLayout fires once per layout, whatever the callback's identity.
---
 .../flow/workflow-canvas.browser.test.tsx     | 24 +++++++++++++++++++
 .../src/components/flow/workflow-canvas.tsx   | 16 +++++++++----
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
index a43c2faa01..8bada3f104 100644
--- a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -414,6 +414,30 @@ describe('WorkflowCanvas', () => {
     }
   });
 
+  it("keeps the host's corner controls in a controlled List view", async () => {
+    const onLayout = vi.fn();
+    render(
+      <WorkflowCanvas
+        graph={triageFlowGraph()}
+        aria-label="Triage GitHub issues"
+        layoutKey="controlled-list"
+        view="list"
+        topStart={<button type="button">Canvas, List or Source</button>}
+        topEnd={<button type="button">Paths</button>}
+        onLayout={onLayout}
+      />,
+    );
+    expect(
+      screen.getByRole('list', { name: 'Triage GitHub issues' }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: 'Canvas, List or Source' }),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Paths' })).toBeInTheDocument();
+    // A controlled view hides the built-in toggle.
+    expect(screen.queryByRole('button', { name: 'Show as chart' })).toBeNull();
+  });
+
   it('switches to the List view and back, and remembers the choice', async () => {
     await renderLaidOut(triageFlowGraph());
     await userEvent.click(screen.getByRole('button', { name: 'Show as list' }));
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
index 866c6f8ecd..6a785e06c8 100644
--- a/packages/ui/src/components/flow/workflow-canvas.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -346,9 +346,12 @@ function WorkflowCanvasInner({
   );
   const { layout, status } = useFlowLayout(graph, { layoutKey, edgeLabel });
 
+  // Once per layout, whatever the identity of the host's callback.
+  const onLayoutRef = useRef(onLayout);
+  onLayoutRef.current = onLayout;
   useEffect(() => {
-    if (layout) onLayout?.(layout);
-  }, [layout, onLayout]);
+    if (layout) onLayoutRef.current?.(layout);
+  }, [layout]);
 
   const words = useMemo(
     () =>
@@ -513,9 +516,12 @@ function WorkflowCanvasInner({
       {notice}
       {view === 'list' ? (
         <div ref={swapRef} className={cn(frameClass, 'overflow-y-auto')}>
-          <div className="flex items-center justify-end gap-1 px-3 pt-3">
-            {topEnd}
-            {viewToggle}
+          <div className="flex items-center gap-1 px-3 pt-3">
+            {topStart}
+            <span className="ml-auto flex items-center gap-1">
+              {topEnd}
+              {viewToggle}
+            </span>
           </div>
           <FlowStepList
             graph={graph}

From 18799e12c9a6601020a2bdcc6a10facb3acd920f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 13:18:33 +0200
Subject: [PATCH 25/78] feat(ui): highlight possible paths and list them in
 FlowPathList
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow's possible paths are plain data now (@tale/ui/flow/paths):
which nodes run on each and how each condition decided. Pure helpers
turn them into the highlight a canvas draws — every path, the paths
through one branch of a condition (or, when the host could not list
them, what lies below the branch), a set of nodes in the error tone,
a node's own lines — Start and End on every path, a Yes or No line
only where its condition decided that way.

FlowPathList is the list a reader explores them with: pointing at or
focusing a row previews its path, Enter, Space or a click pins it and
says so once, Escape or Show all unpins. Rows that are not paths (the
nodes that end a run when they fail) activate instead. One Tab stop
across every section, arrows and Home/End between rows, and while a
path is pinned the list claims Escape from a sheet around it.
---
 packages/ui/package.json                      |   2 +
 .../flow/flow-path-list.browser.test.tsx      | 176 +++++++++
 .../ui/src/components/flow/flow-path-list.tsx | 352 ++++++++++++++++++
 .../components/flow/paths/highlight.test.ts   | 225 +++++++++++
 .../ui/src/components/flow/paths/highlight.ts | 234 ++++++++++++
 packages/ui/src/i18n/messages/de.yml          |   2 +
 packages/ui/src/i18n/messages/en.yml          |   2 +
 packages/ui/src/i18n/messages/fr.yml          |   2 +
 8 files changed, 995 insertions(+)
 create mode 100644 packages/ui/src/components/flow/flow-path-list.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/flow-path-list.tsx
 create mode 100644 packages/ui/src/components/flow/paths/highlight.test.ts
 create mode 100644 packages/ui/src/components/flow/paths/highlight.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 7bf538fc11..872fb871d7 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -149,10 +149,12 @@
     "./flow/elk-layout": "./src/components/flow/layout/elk-layout.ts",
     "./flow/flow-canvas": "./src/components/flow/flow-canvas.tsx",
     "./flow/flow-legend": "./src/components/flow/flow-legend.tsx",
+    "./flow/flow-path-list": "./src/components/flow/flow-path-list.tsx",
     "./flow/flow-step-list": "./src/components/flow/flow-step-list.tsx",
     "./flow/layout": "./src/components/flow/layout/index.ts",
     "./flow/node-issue-marker": "./src/components/flow/node-issue-marker.tsx",
     "./flow/node-status": "./src/components/flow/node-status.tsx",
+    "./flow/paths": "./src/components/flow/paths/highlight.ts",
     "./flow/types": "./src/components/flow/types.ts",
     "./flow/use-elk-layout": "./src/components/flow/layout/use-elk-layout.ts",
     "./flow/workflow-canvas": "./src/components/flow/workflow-canvas.tsx",
diff --git a/packages/ui/src/components/flow/flow-path-list.browser.test.tsx b/packages/ui/src/components/flow/flow-path-list.browser.test.tsx
new file mode 100644
index 0000000000..476449f106
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-path-list.browser.test.tsx
@@ -0,0 +1,176 @@
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import {
+  FlowPathList,
+  type FlowPathListProps,
+  type FlowPathListSection,
+} from './flow-path-list';
+
+import '../../globals.css';
+
+afterEach(() => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+});
+
+const SECTIONS: FlowPathListSection[] = [
+  {
+    id: 'paths',
+    rows: [
+      {
+        id: 'p1',
+        title: 'Path 1',
+        meta: '6 of 6 nodes run',
+        clauses: [{ id: 'urgent', label: 'Urgent: Yes', tone: 'positive' }],
+      },
+      {
+        id: 'p2',
+        title: 'Path 2',
+        meta: '5 of 6 nodes run',
+        clauses: [{ id: 'urgent', label: 'Urgent: No', tone: 'negative' }],
+      },
+    ],
+  },
+  {
+    id: 'halts',
+    title: 'Ends the run when it fails',
+    rows: [
+      { id: 'fetch', title: 'Fetch', pinnable: false },
+      { id: 'merge', title: 'Merge', pinnable: false },
+    ],
+  },
+];
+
+function Harness({ onPin, onPreview, ...props }: Partial<FlowPathListProps>) {
+  const [pinned, setPinned] = useState<string | null>(null);
+  const [preview, setPreview] = useState<string | null>(null);
+  return (
+    <div style={{ width: 320 }}>
+      <button type="button">Before the list</button>
+      <FlowPathList
+        sections={SECTIONS}
+        aria-label="Paths a run can take"
+        pinnedId={pinned}
+        previewId={preview}
+        onPin={(id) => {
+          setPinned(id);
+          onPin?.(id);
+        }}
+        onPreview={(id) => {
+          setPreview(id);
+          onPreview?.(id);
+        }}
+        announce={(row) => `Showing ${row.title}`}
+        {...props}
+      />
+      <p data-testid="preview">{preview ?? 'none'}</p>
+    </div>
+  );
+}
+
+const row = (name: RegExp) => screen.getByRole('button', { name });
+
+describe('FlowPathList', () => {
+  it('is one Tab stop that the arrows walk across every section', async () => {
+    render(<Harness />);
+    screen.getByRole('button', { name: 'Before the list' }).focus();
+    await userEvent.tab();
+    expect(document.activeElement).toBe(row(/^Path 1/));
+    expect(screen.getByTestId('preview')).toHaveTextContent('p1');
+    await userEvent.keyboard('{ArrowDown}');
+    expect(document.activeElement).toBe(row(/^Path 2/));
+    await userEvent.keyboard('{End}');
+    expect(document.activeElement).toBe(row(/^Merge/));
+    await userEvent.keyboard('{Home}');
+    expect(document.activeElement).toBe(row(/^Path 1/));
+    await userEvent.keyboard('{ArrowUp}');
+    expect(document.activeElement).toBe(row(/^Path 1/));
+    const tabbable = Array.from(
+      document.querySelectorAll<HTMLElement>('[data-flow-path-row]'),
+    ).filter((element) => element.tabIndex === 0);
+    expect(tabbable).toHaveLength(1);
+    await userEvent.tab();
+    expect(screen.getByTestId('preview')).toHaveTextContent('none');
+  });
+
+  it('pins with Enter, says so once, and unpins with Escape or Show all', async () => {
+    const onPin = vi.fn();
+    render(<Harness onPin={onPin} />);
+    screen.getByRole('button', { name: 'Before the list' }).focus();
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}{Enter}');
+    expect(onPin).toHaveBeenLastCalledWith('p2');
+    expect(row(/^Path 2/)).toHaveAttribute('aria-pressed', 'true');
+    expect(row(/^Path 1/)).toHaveAttribute('aria-pressed', 'false');
+    const status = screen.getByRole('status');
+    await waitFor(() => expect(status).toHaveTextContent('Showing Path 2'));
+    expect(status.querySelectorAll('span')).toHaveLength(1);
+    // While a path is pinned the list claims Escape from a sheet around it.
+    expect(
+      document.querySelector('[data-slot="flow-path-list"]'),
+    ).toHaveAttribute('data-claims-escape');
+
+    await userEvent.keyboard('{Escape}');
+    expect(onPin).toHaveBeenLastCalledWith(null);
+    expect(row(/^Path 2/)).toHaveAttribute('aria-pressed', 'false');
+    expect(
+      document.querySelector('[data-slot="flow-path-list"]'),
+    ).not.toHaveAttribute('data-claims-escape');
+
+    await userEvent.click(row(/^Path 1/));
+    await waitFor(() => expect(status).toHaveTextContent('Showing Path 1'));
+    await userEvent.click(screen.getByRole('button', { name: 'Show all' }));
+    expect(onPin).toHaveBeenLastCalledWith(null);
+    expect(screen.queryByRole('button', { name: 'Show all' })).toBeNull();
+    expect(document.activeElement).toBe(row(/^Path 1/));
+  });
+
+  it('activates a row that is not a path instead of pinning it', async () => {
+    const onActivate = vi.fn();
+    const onPin = vi.fn();
+    render(<Harness onActivate={onActivate} onPin={onPin} />);
+    const merge = row(/^Merge/);
+    expect(merge).not.toHaveAttribute('aria-pressed');
+    await userEvent.click(merge);
+    expect(onActivate).toHaveBeenCalledWith('merge');
+    expect(onPin).not.toHaveBeenCalled();
+    // Pointing previews it, as it does a path.
+    await userEvent.hover(row(/^Fetch/));
+    expect(screen.getByTestId('preview')).toHaveTextContent('fetch');
+  });
+
+  it('names each section and shows the empty words without rows', async () => {
+    const { rerender } = render(<Harness />);
+    expect(
+      screen.getByRole('list', { name: 'Ends the run when it fails' }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('group', { name: 'Paths a run can take' }),
+    ).toBeInTheDocument();
+    rerender(
+      <Harness
+        sections={[{ id: 'none', rows: [] }]}
+        empty="Every run takes the same path."
+      />,
+    );
+    expect(
+      screen.getByText('Every run takes the same path.'),
+    ).toBeInTheDocument();
+  });
+
+  it.each(['light', 'dark'])('passes axe (%s)', async (theme) => {
+    document.documentElement.classList.toggle('dark', theme === 'dark');
+    const { container } = render(<Harness />);
+    await userEvent.click(row(/^Path 2/));
+    const result = await axe.run(container, {
+      runOnly: ['wcag2a', 'wcag2aa'],
+    });
+    expect(result.violations).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/components/flow/flow-path-list.tsx b/packages/ui/src/components/flow/flow-path-list.tsx
new file mode 100644
index 0000000000..9660d1241a
--- /dev/null
+++ b/packages/ui/src/components/flow/flow-path-list.tsx
@@ -0,0 +1,352 @@
+'use client';
+
+import { Pin } from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import { useT } from '../../i18n/client';
+import { cn } from '../../lib/cn';
+import { CLAIMS_ESCAPE_ATTRIBUTE } from '../overlays/claims-escape';
+import { Button } from '../primitives/button';
+
+/** A short fact about a path ("Urgent: No"), with a tone dot; the words
+ *  always say it, the dot only repeats it. */
+export interface FlowPathClause {
+  id: string;
+  label: string;
+  tone?: 'neutral' | 'positive' | 'negative' | 'error';
+}
+
+/** One row: a path, or (with `pinnable: false`) a node to go to. */
+export interface FlowPathListRow {
+  id: string;
+  /** "Path 2". */
+  title: string;
+  /** "5 of 6 nodes run". */
+  meta?: string;
+  clauses?: readonly FlowPathClause[];
+  /**
+   * A path pins (Enter, Space or a click toggles it); a row that is not
+   * pinnable — a node that ends a run when it fails — activates instead.
+   * @default true
+   */
+  pinnable?: boolean;
+}
+
+export interface FlowPathListSection {
+  id: string;
+  /** Names the section's rows ("Ends the run when it fails"). */
+  title?: string;
+  description?: string;
+  rows: readonly FlowPathListRow[];
+  /** Under the rows (the host's "Too many conditions to list every path"). */
+  footer?: ReactNode;
+}
+
+export interface FlowPathListProps {
+  sections: readonly FlowPathListSection[];
+  /** The row a pointer rests on or focus is on. */
+  previewId?: string | null;
+  /** The row the reader pinned. */
+  pinnedId?: string | null;
+  /** A row is pointed at or focused (`id`), or left (`null`). */
+  onPreview?: (id: string | null) => void;
+  /** A path is pinned (`id`) or unpinned (`null`). */
+  onPin?: (id: string | null) => void;
+  /** A row that is not pinnable is chosen. */
+  onActivate?: (id: string) => void;
+  /** What a screen reader hears, once, when a row is pinned ("Showing
+   *  path 2: …"). */
+  announce?: (row: FlowPathListRow) => string;
+  'aria-label': string;
+  /** Shown when no section has a row. */
+  empty?: ReactNode;
+  className?: string;
+}
+
+const CLAUSE_DOT: Record<NonNullable<FlowPathClause['tone']>, string> = {
+  neutral: 'bg-muted-foreground',
+  positive: 'bg-[hsl(var(--success))]',
+  negative: 'bg-[var(--flow-edge-negative)]',
+  error: 'bg-destructive',
+};
+
+/**
+ * The possible paths through a workflow, as a list a reader explores the
+ * chart with: pointing at or focusing a row previews its path on the
+ * canvas, Enter, Space or a click pins it (and again unpins it), Escape
+ * unpins, and **Show all** returns to every path. A section of rows that
+ * are not paths — the nodes that end a run when they fail — activates a
+ * row instead of pinning it.
+ *
+ * One Tab stop for every row of every section: ↑ and ↓ move between rows,
+ * Home and End jump. Pinning says so once in a polite live region, in the
+ * host's words. While a path is pinned the list claims Escape, so the
+ * first Escape inside a sheet unpins and only the next one closes it.
+ */
+export function FlowPathList({
+  sections,
+  previewId = null,
+  pinnedId = null,
+  onPreview,
+  onPin,
+  onActivate,
+  announce,
+  'aria-label': ariaLabel,
+  empty,
+  className,
+}: FlowPathListProps) {
+  const { t } = useT('flow');
+  const baseId = useId();
+  const rows = sections.flatMap((section) => section.rows);
+  const ids = rows.map((row) => row.id);
+  const buttons = useRef(new Map<string, HTMLButtonElement>());
+  const [focusedId, setFocusedId] = useState<string | null>(null);
+  const [spoken, setSpoken] = useState({ text: '', serial: 0 });
+
+  // The one Tab stop: the row last focused while it is still listed, else
+  // the pinned row, else the first.
+  const listed = (id: string | null): id is string =>
+    id !== null && ids.includes(id);
+  const rovingId = listed(focusedId)
+    ? focusedId
+    : listed(pinnedId)
+      ? pinnedId
+      : (ids[0] ?? null);
+
+  // Say a pin once, when it happens; a row pinned again is said again.
+  const lastPinned = useRef(pinnedId);
+  useEffect(() => {
+    if (lastPinned.current === pinnedId) return;
+    lastPinned.current = pinnedId;
+    if (pinnedId === null || announce === undefined) return;
+    const row = rows.find((candidate) => candidate.id === pinnedId);
+    if (row === undefined) return;
+    const text = announce(row);
+    setSpoken((previous) => ({ text, serial: previous.serial + 1 }));
+  }, [pinnedId, announce, rows]);
+
+  const focusRow = useCallback((id: string) => {
+    buttons.current.get(id)?.focus();
+  }, []);
+
+  const choose = (row: FlowPathListRow) => {
+    if (row.pinnable === false) onActivate?.(row.id);
+    else onPin?.(pinnedId === row.id ? null : row.id);
+  };
+
+  const onRowKeyDown = (
+    event: KeyboardEvent<HTMLButtonElement>,
+    index: number,
+  ) => {
+    let next: string | undefined;
+    switch (event.key) {
+      case 'ArrowDown':
+        next = ids[Math.min(index + 1, ids.length - 1)];
+        break;
+      case 'ArrowUp':
+        next = ids[Math.max(index - 1, 0)];
+        break;
+      case 'Home':
+        next = ids[0];
+        break;
+      case 'End':
+        next = ids.at(-1);
+        break;
+      case 'Escape':
+        if (pinnedId === null) return;
+        event.preventDefault();
+        event.stopPropagation();
+        onPin?.(null);
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+    if (next !== undefined) focusRow(next);
+  };
+
+  if (rows.length === 0) {
+    return (
+      <div className={cn('text-muted-foreground p-3 text-sm', className)}>
+        {empty}
+      </div>
+    );
+  }
+
+  let index = -1;
+  return (
+    <div
+      data-slot="flow-path-list"
+      className={cn('flex flex-col', className)}
+      {...(pinnedId === null ? {} : { [CLAIMS_ESCAPE_ATTRIBUTE]: '' })}
+    >
+      <div
+        role="group"
+        aria-label={ariaLabel}
+        className="flex flex-col gap-3"
+        onPointerLeave={() => {
+          if (previewId !== null) onPreview?.(null);
+        }}
+      >
+        {sections.map((section) => {
+          const titleId = `${baseId}-${section.id}-title`;
+          const descriptionId = `${baseId}-${section.id}-description`;
+          if (section.rows.length === 0 && section.footer === undefined)
+            return null;
+          return (
+            <div key={section.id} className="flex flex-col">
+              {section.title && (
+                <p
+                  id={titleId}
+                  className="text-muted-foreground px-3 pb-1 text-xs font-medium"
+                >
+                  {section.title}
+                </p>
+              )}
+              {section.description && (
+                <p
+                  id={descriptionId}
+                  className="text-muted-foreground px-3 pb-1 text-xs"
+                >
+                  {section.description}
+                </p>
+              )}
+              {section.rows.length > 0 && (
+                <ul
+                  role="list"
+                  aria-labelledby={section.title ? titleId : undefined}
+                  aria-describedby={
+                    section.description ? descriptionId : undefined
+                  }
+                  className="flex flex-col"
+                >
+                  {section.rows.map((row) => {
+                    index += 1;
+                    const at = index;
+                    const pinnable = row.pinnable !== false;
+                    const pinned = pinnable && pinnedId === row.id;
+                    const previewed = previewId === row.id;
+                    return (
+                      <li key={row.id}>
+                        <button
+                          ref={(node) => {
+                            if (node === null) buttons.current.delete(row.id);
+                            else buttons.current.set(row.id, node);
+                          }}
+                          type="button"
+                          data-flow-path-row={row.id}
+                          tabIndex={rovingId === row.id ? 0 : -1}
+                          aria-pressed={pinnable ? pinned : undefined}
+                          onClick={() => choose(row)}
+                          onKeyDown={(event) => onRowKeyDown(event, at)}
+                          onFocus={() => {
+                            setFocusedId(row.id);
+                            onPreview?.(row.id);
+                          }}
+                          onBlur={(event) => {
+                            // Leaving the list ends the preview; moving
+                            // to the next row hands it over.
+                            const next = event.relatedTarget;
+                            if (
+                              !(next instanceof Element) ||
+                              next.closest('[data-flow-path-row]') === null
+                            )
+                              onPreview?.(null);
+                          }}
+                          onPointerEnter={() => onPreview?.(row.id)}
+                          className={cn(
+                            'flex w-full cursor-pointer items-start gap-2 rounded-md px-3 py-2 text-left',
+                            'hover:bg-muted/60 focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none focus-visible:ring-inset',
+                            previewed && 'bg-muted/60',
+                            pinned && 'bg-muted',
+                          )}
+                        >
+                          <span className="flex min-w-0 flex-1 flex-col gap-1">
+                            <span className="flex items-baseline gap-2">
+                              <span className="text-foreground text-sm font-medium">
+                                {row.title}
+                              </span>
+                              {row.meta && (
+                                <span className="text-muted-foreground text-xs">
+                                  {row.meta}
+                                </span>
+                              )}
+                            </span>
+                            {row.clauses && row.clauses.length > 0 && (
+                              <span className="flex flex-wrap gap-1">
+                                {row.clauses.map((clause) => (
+                                  <span
+                                    key={clause.id}
+                                    className="border-border text-foreground inline-flex h-5 max-w-full items-center gap-1.5 rounded-full border px-2 text-xs"
+                                  >
+                                    <span
+                                      aria-hidden="true"
+                                      className={cn(
+                                        'size-1.5 shrink-0 rounded-full',
+                                        CLAUSE_DOT[clause.tone ?? 'neutral'],
+                                      )}
+                                    />
+                                    <span className="truncate">
+                                      {clause.label}
+                                    </span>
+                                  </span>
+                                ))}
+                              </span>
+                            )}
+                          </span>
+                          {pinned && (
+                            <Pin
+                              aria-hidden="true"
+                              className="text-foreground mt-0.5 size-3.5 shrink-0"
+                            />
+                          )}
+                        </button>
+                      </li>
+                    );
+                  })}
+                </ul>
+              )}
+              {section.footer !== undefined && (
+                <div className="text-muted-foreground px-3 pt-1 text-xs">
+                  {section.footer}
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+      {pinnedId !== null && (
+        <div className="px-3 pt-2">
+          <Button
+            size="sm"
+            variant="secondary"
+            onClick={() => {
+              onPin?.(null);
+              focusRow(pinnedId);
+            }}
+          >
+            {t('paths.showAll')}
+          </Button>
+        </div>
+      )}
+      <div
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        className="sr-only"
+      >
+        {spoken.text === '' ? null : (
+          <span key={spoken.serial}>{spoken.text}</span>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/flow/paths/highlight.test.ts b/packages/ui/src/components/flow/paths/highlight.test.ts
new file mode 100644
index 0000000000..00b2c3bd2f
--- /dev/null
+++ b/packages/ui/src/components/flow/paths/highlight.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  branchFlowGraph,
+  triageInboxFlowGraph,
+} from '../testing/flow-fixtures';
+import {
+  highlightForBranch,
+  highlightForIncident,
+  highlightForNodes,
+  highlightForPaths,
+  sameFlowHighlight,
+  type FlowPath,
+} from './highlight';
+
+const sorted = (set: ReadonlySet<string>) => [...set].sort();
+
+/** The branch fixture's paths, as a host's analysis lists them. */
+const BRANCH_PATHS: FlowPath[] = [
+  {
+    id: 'urgent',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      'urgent',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': true },
+  },
+  {
+    id: 'normal',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      '__gate:normal',
+      'normal',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': true },
+  },
+  {
+    id: 'low',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      '__gate:normal',
+      'low',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': false },
+  },
+];
+
+describe('highlightForPaths', () => {
+  it('puts Start and End on every path and keeps only the lines a run follows', () => {
+    const graph = branchFlowGraph();
+    const path = BRANCH_PATHS[0];
+    if (path === undefined) throw new Error('no path');
+    const highlight = highlightForPaths(graph, [path]);
+    expect(highlight.nodes.has('__start')).toBe(true);
+    expect(highlight.nodes.has('__end')).toBe(true);
+    expect(highlight.nodes.has('normal')).toBe(false);
+    expect(highlight.edges.has('__gate:urgent>urgent')).toBe(true);
+    // The No line leaves a gate that is on the path, to a gate that is not.
+    expect(highlight.edges.has('__gate:urgent>__gate:normal')).toBe(false);
+    expect(highlight.edges.has('__start>fetch')).toBe(true);
+    expect(highlight.edges.has('merge>__end')).toBe(true);
+  });
+
+  it('takes a Yes or No line only on a path where the condition decided that way', () => {
+    const graph = branchFlowGraph();
+    // A path that lists both ends of the No line but decided Yes.
+    const odd: FlowPath = {
+      id: 'odd',
+      nodes: ['__gate:urgent', '__gate:normal'],
+      decisions: { 'when:urgent': true },
+    };
+    expect(
+      highlightForPaths(graph, [odd]).edges.has('__gate:urgent>__gate:normal'),
+    ).toBe(false);
+    const low = BRANCH_PATHS[2];
+    if (low === undefined) throw new Error('no path');
+    const highlight = highlightForPaths(graph, [low]);
+    expect(highlight.edges.has('__gate:urgent>__gate:normal')).toBe(true);
+    expect(highlight.edges.has('__gate:normal>low')).toBe(true);
+    expect(highlight.edges.has('__gate:normal>normal')).toBe(false);
+  });
+
+  it('joins several paths', () => {
+    const highlight = highlightForPaths(branchFlowGraph(), BRANCH_PATHS);
+    expect(
+      ['urgent', 'normal', 'low'].every((id) => highlight.nodes.has(id)),
+    ).toBe(true);
+  });
+
+  it('never holds a layout-only line', () => {
+    const inbox = triageInboxFlowGraph();
+    const graph = {
+      ...inbox,
+      edges: [
+        ...inbox.edges,
+        {
+          id: 'hidden',
+          source: 'inbox',
+          target: 'due',
+          kind: 'order' as const,
+          layoutOnly: true,
+        },
+      ],
+    };
+    const highlight = highlightForPaths(graph, [
+      { id: 'all', nodes: ['inbox', 'due'], decisions: {} },
+    ]);
+    expect(highlight.edges.has('hidden')).toBe(false);
+    expect(highlight.edges.has('inbox>due')).toBe(true);
+  });
+});
+
+describe('highlightForBranch', () => {
+  it('highlights the paths through one branch of a condition', () => {
+    const graph = branchFlowGraph();
+    const no = highlightForBranch(graph, BRANCH_PATHS, '__gate:urgent', false);
+    expect(no.nodes.has('normal')).toBe(true);
+    expect(no.nodes.has('low')).toBe(true);
+    expect(no.nodes.has('urgent')).toBe(false);
+    const yes = highlightForBranch(graph, BRANCH_PATHS, '__gate:urgent', true);
+    expect(sorted(yes.nodes)).toEqual(
+      sorted(highlightForPaths(graph, [BRANCH_PATHS[0] as FlowPath]).nodes),
+    );
+  });
+
+  it('highlights every path that consults the condition without a decision', () => {
+    const graph = branchFlowGraph();
+    const all = highlightForBranch(graph, BRANCH_PATHS, '__gate:normal');
+    expect(all.nodes.has('normal')).toBe(true);
+    expect(all.nodes.has('low')).toBe(true);
+    expect(all.nodes.has('urgent')).toBe(false);
+  });
+
+  it('follows the branch down the lines when the host could not list the paths', () => {
+    const graph = branchFlowGraph();
+    const no = highlightForBranch(graph, [], '__gate:urgent', false);
+    expect(no.nodes.has('__gate:urgent')).toBe(true);
+    expect(no.nodes.has('__gate:normal')).toBe(true);
+    expect(no.nodes.has('low')).toBe(true);
+    expect(no.nodes.has('merge')).toBe(true);
+    expect(no.nodes.has('urgent')).toBe(false);
+    expect(no.edges.has('__gate:urgent>__gate:normal')).toBe(true);
+    expect(no.edges.has('__gate:urgent>urgent')).toBe(false);
+    // An only-if condition that does not hold leads nowhere.
+    const inbox = triageInboxFlowGraph();
+    const off = highlightForBranch(inbox, [], '__gate:triage', false);
+    expect(sorted(off.nodes)).toEqual(['__gate:triage']);
+    const on = highlightForBranch(inbox, [], '__gate:triage', true);
+    expect(on.nodes.has('triage')).toBe(true);
+    expect(on.edges.has('__gate:triage>triage')).toBe(true);
+  });
+
+  it('is empty for a gate the graph does not have', () => {
+    const none = highlightForBranch(branchFlowGraph(), BRANCH_PATHS, 'nope');
+    expect(none.nodes.size).toBe(0);
+    expect(none.edges.size).toBe(0);
+  });
+});
+
+describe('highlightForNodes and highlightForIncident', () => {
+  it('rings a set of nodes in a tone, with the lines between them', () => {
+    const highlight = highlightForNodes(
+      branchFlowGraph(),
+      ['fetch', 'classify', 'ghost'],
+      {
+        tone: 'error',
+      },
+    );
+    expect(sorted(highlight.nodes)).toEqual(['classify', 'fetch']);
+    expect(sorted(highlight.edges)).toEqual(['fetch>classify']);
+    expect(highlight.tone).toBe('error');
+  });
+
+  it('brings a node’s own lines forward without quieting the rest', () => {
+    const highlight = highlightForIncident(branchFlowGraph(), 'merge');
+    expect(highlight.quietRest).toBe(false);
+    expect(sorted(highlight.edges)).toEqual(
+      [
+        'enrich>merge',
+        'low>merge',
+        'merge>__end',
+        'merge>notify',
+        'merge>poll',
+        'normal>merge',
+        'urgent>merge',
+      ].sort(),
+    );
+  });
+
+  it('compares highlights by what they bring forward', () => {
+    const graph = branchFlowGraph();
+    expect(
+      sameFlowHighlight(
+        highlightForIncident(graph, 'merge'),
+        highlightForIncident(graph, 'merge'),
+      ),
+    ).toBe(true);
+    expect(
+      sameFlowHighlight(
+        highlightForIncident(graph, 'merge'),
+        highlightForIncident(graph, 'fetch'),
+      ),
+    ).toBe(false);
+    expect(sameFlowHighlight(null, undefined)).toBe(false);
+    expect(sameFlowHighlight(null, null)).toBe(true);
+  });
+});
diff --git a/packages/ui/src/components/flow/paths/highlight.ts b/packages/ui/src/components/flow/paths/highlight.ts
new file mode 100644
index 0000000000..1f9e72e501
--- /dev/null
+++ b/packages/ui/src/components/flow/paths/highlight.ts
@@ -0,0 +1,234 @@
+import type { FlowEdge, FlowGraph, FlowNode } from '../types';
+
+/**
+ * Possible paths through a workflow, and the highlight a canvas draws for
+ * one or more of them.
+ *
+ * A host works its paths out from its own analysis — which nodes run and
+ * how each condition decided — and hands them over as plain data. These
+ * functions turn paths, a branch or a set of nodes into a highlight: the
+ * nodes and lines to bring forward. Everything else steps back (quiet), so
+ * the reader sees one way through the chart at a time.
+ */
+
+/** One way a run can go through the workflow. */
+export interface FlowPath {
+  id: string;
+  /**
+   * The steps and the conditions that run on this path. Start and End are
+   * on every path and need not be listed.
+   */
+  nodes: readonly string[];
+  /** How each condition decided on this path, keyed by the gate's
+   *  `decisionKey` (else by its id): `true` takes Yes, `false` takes No. */
+  decisions: Readonly<Record<string, boolean>>;
+  /** The host's name for the path ("Path 2"). */
+  label?: string;
+}
+
+/** What a canvas brings forward; the rest steps back. */
+export interface FlowHighlight {
+  nodes: ReadonlySet<string>;
+  edges: ReadonlySet<string>;
+  /** `error` rings the nodes in the error red (the nodes that end a run
+   *  when they fail). @default 'default' */
+  tone?: 'default' | 'error';
+  /**
+   * Whether everything outside the highlight steps back. `false` only
+   * brings the highlight forward (a node a pointer rests on, the node that
+   * has keyboard focus). @default true
+   */
+  quietRest?: boolean;
+  /** Words for a quiet node's strip, by node id ("Skipped: the condition
+   *  is false"). */
+  reasons?: Readonly<Record<string, string>>;
+  /** Said once, politely, when a host shows this highlight. */
+  announcement?: string;
+}
+
+/** The key a path's `decisions` use for this gate. */
+export const flowDecisionKey = (gate: FlowNode): string =>
+  (gate.kind === 'gate' ? gate.decisionKey : undefined) ?? gate.id;
+
+/** The edges a highlight can hold: drawn ones only. */
+const drawnEdges = (graph: FlowGraph): FlowEdge[] =>
+  graph.edges.filter((edge) => !edge.layoutOnly);
+
+/** Start and End: on every path. */
+const terminalIds = (graph: FlowGraph): string[] =>
+  graph.nodes
+    .filter((node) => node.kind === 'entry' || node.kind === 'exit')
+    .map((node) => node.id);
+
+/**
+ * Whether `edge` lies on `path`: both its ends run on the path, and a Yes
+ * or No line only on a path where its condition decided that way.
+ */
+function edgeOnPath(
+  edge: FlowEdge,
+  path: FlowPath,
+  on: ReadonlySet<string>,
+  byId: ReadonlyMap<string, FlowNode>,
+): boolean {
+  if (!on.has(edge.source) || !on.has(edge.target)) return false;
+  if (edge.kind !== 'branch-yes' && edge.kind !== 'branch-no') return true;
+  const gate = byId.get(edge.source);
+  if (gate === undefined) return false;
+  const decision = path.decisions[flowDecisionKey(gate)];
+  return decision === (edge.kind === 'branch-yes');
+}
+
+/**
+ * The highlight of one or more paths: every node that runs on any of
+ * them, Start and End, and every line a run on one of them follows.
+ */
+export function highlightForPaths(
+  graph: FlowGraph,
+  paths: readonly FlowPath[],
+): FlowHighlight {
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  const terminals = terminalIds(graph);
+  const nodes = new Set<string>();
+  const edges = new Set<string>();
+  const drawn = drawnEdges(graph);
+  for (const path of paths) {
+    const on = new Set([...terminals, ...path.nodes]);
+    for (const id of on) if (byId.has(id)) nodes.add(id);
+    for (const edge of drawn)
+      if (edgeOnPath(edge, path, on, byId)) edges.add(edge.id);
+  }
+  return { nodes, edges };
+}
+
+/**
+ * Every node below `from` along the drawn lines, `from` included — the
+ * stand-in for a branch's paths when the host could not list them.
+ */
+function descendants(graph: FlowGraph, from: readonly string[]): Set<string> {
+  const out = new Map<string, string[]>();
+  for (const edge of drawnEdges(graph))
+    out.set(edge.source, [...(out.get(edge.source) ?? []), edge.target]);
+  const seen = new Set<string>();
+  const stack = [...from];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (id === undefined || seen.has(id)) continue;
+    seen.add(id);
+    stack.push(...(out.get(id) ?? []));
+  }
+  return seen;
+}
+
+/**
+ * The highlight of a condition, or of one of its branches: the paths that
+ * consult the gate, only those where it decided `decision` when given.
+ *
+ * With no paths (the host's analysis gave up: too many conditions to list
+ * every path), the gate's branch leads the way instead — the gate and
+ * everything below the branch's target.
+ */
+export function highlightForBranch(
+  graph: FlowGraph,
+  paths: readonly FlowPath[],
+  gateId: string,
+  decision?: boolean,
+): FlowHighlight {
+  const gate = graph.nodes.find((node) => node.id === gateId);
+  if (gate === undefined) return { nodes: new Set(), edges: new Set() };
+  const key = flowDecisionKey(gate);
+  if (paths.length > 0) {
+    return highlightForPaths(
+      graph,
+      paths.filter(
+        (path) =>
+          (path.nodes.includes(gateId) || key in path.decisions) &&
+          (decision === undefined || path.decisions[key] === decision),
+      ),
+    );
+  }
+  // The lines the decision takes: Yes or No from an if/else gate; an
+  // only-if gate's one line when it holds, none when it does not.
+  const taken = (edge: FlowEdge) =>
+    decision === undefined ||
+    (edge.kind === 'branch-yes' && decision) ||
+    (edge.kind === 'branch-no' && !decision) ||
+    (edge.kind === 'gate' && decision);
+  const out = drawnEdges(graph).filter(
+    (edge) => edge.source === gateId && taken(edge),
+  );
+  const nodes = descendants(
+    graph,
+    out.map((edge) => edge.target),
+  );
+  nodes.add(gateId);
+  const edges = new Set(
+    drawnEdges(graph)
+      .filter(
+        (edge) =>
+          (edge.source === gateId && out.includes(edge)) ||
+          (edge.source !== gateId &&
+            nodes.has(edge.source) &&
+            nodes.has(edge.target)),
+      )
+      .map((edge) => edge.id),
+  );
+  return { nodes, edges };
+}
+
+/**
+ * The highlight of a set of nodes — the nodes that end a run when they
+ * fail, say — and the lines between them. `tone: 'error'` rings them red.
+ */
+export function highlightForNodes(
+  graph: FlowGraph,
+  ids: readonly string[],
+  options: { tone?: 'default' | 'error' } = {},
+): FlowHighlight {
+  const known = new Set(graph.nodes.map((node) => node.id));
+  const nodes = new Set(ids.filter((id) => known.has(id)));
+  const edges = new Set(
+    drawnEdges(graph)
+      .filter((edge) => nodes.has(edge.source) && nodes.has(edge.target))
+      .map((edge) => edge.id),
+  );
+  return options.tone === undefined
+    ? { nodes, edges }
+    : { nodes, edges, tone: options.tone };
+}
+
+/**
+ * The lines into and out of one node, brought forward without quieting
+ * anything — what a pointer resting on a node, or keyboard focus on it,
+ * shows. Nothing else moves, so tabbing through the chart never flickers.
+ */
+export function highlightForIncident(
+  graph: FlowGraph,
+  id: string,
+): FlowHighlight {
+  return {
+    nodes: new Set([id]),
+    edges: new Set(
+      drawnEdges(graph)
+        .filter((edge) => edge.source === id || edge.target === id)
+        .map((edge) => edge.id),
+    ),
+    quietRest: false,
+  };
+}
+
+/** Whether two highlights bring the same things forward the same way. */
+export function sameFlowHighlight(
+  a: FlowHighlight | null | undefined,
+  b: FlowHighlight | null | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const sameSet = (x: ReadonlySet<string>, y: ReadonlySet<string>) =>
+    x.size === y.size && [...x].every((id) => y.has(id));
+  return (
+    (a.tone ?? 'default') === (b.tone ?? 'default') &&
+    (a.quietRest ?? true) === (b.quietRest ?? true) &&
+    sameSet(a.nodes, b.nodes) &&
+    sameSet(a.edges, b.edges)
+  );
+}
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index a2e41da2d9..c3c0a4268d 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -576,3 +576,5 @@ flow:
     label: Nodes
     reads: Liest {list}
     empty: Noch keine Nodes
+  paths:
+    showAll: Alle zeigen
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index 5f7d2f225a..e582826583 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -576,3 +576,5 @@ flow:
     label: Nodes
     reads: Reads {list}
     empty: No nodes yet
+  paths:
+    showAll: Show all
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index ab73d28bbd..d3292d6985 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -576,3 +576,5 @@ flow:
     label: Nœuds
     reads: Lit {list}
     empty: Aucun nœud pour l'instant
+  paths:
+    showAll: Tout afficher

From 4deda60ea68c7b976dd289c32043cf7adad020fe Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 13:18:59 +0200
Subject: [PATCH 26/78] feat(ui): replay runs with flow playback and
 FlowPlaybackBar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

@tale/ui/flow/playback carries a run onto a workflow chart: an overlay
(where each node ended, no time) or a playback timeline (spans of work,
values travelling the lines, wait and failure marks) at the host's
moment t. flowStateAt and flowStateFromOverlay derive the one frame a
chart draws — each node's state, items and passes, each condition's
decision, which lines were travelled or not taken, and the first
failure with the way the run took to it.

buildPlaybackTimeline compresses a recorded run piece by piece (a
step plays at least 240 ms, a gap at most 1.2 s, a long wait becomes
a mark with its real length), gives each value time to reach its
target, and maps playback time back to real time both ways.
usePlaybackClock drives it: it opens on the end of the run, plays at
0.5x to 4x, follows a live run's end, and under reduced motion steps
from event to event instead of sweeping.

FlowPlaybackBar is the replay's control row: play or pause, previous
and next event, a named scrubber that says where it is in words, event
ticks with failures in the error red and waits hatched, the time, the
speed (a menu on a phone) and Live with Follow live. Fixtures of a
failed Triage run and a branching run with a wait ship in
@tale/ui/testing/flow.
---
 packages/ui/package.json                      |   2 +
 .../flow/playback/build-timeline.test.ts      |  96 ++++++
 .../flow/playback/build-timeline.ts           | 210 ++++++++++++
 .../flow/playback/derive-state.test.ts        | 173 ++++++++++
 .../components/flow/playback/derive-state.ts  | 318 ++++++++++++++++++
 .../flow-playback-bar.browser.test.tsx        | 165 +++++++++
 .../flow/playback/flow-playback-bar.tsx       | 276 +++++++++++++++
 .../ui/src/components/flow/playback/index.ts  |  36 ++
 .../ui/src/components/flow/playback/types.ts  | 129 +++++++
 .../flow/playback/use-playback-clock.ts       | 136 ++++++++
 .../components/flow/testing/flow-fixtures.ts  | 245 ++++++++++++++
 packages/ui/src/i18n/messages/de.yml          |  11 +
 packages/ui/src/i18n/messages/en.yml          |  11 +
 packages/ui/src/i18n/messages/fr.yml          |  11 +
 packages/ui/src/testing/flow.ts               |   3 +
 15 files changed, 1822 insertions(+)
 create mode 100644 packages/ui/src/components/flow/playback/build-timeline.test.ts
 create mode 100644 packages/ui/src/components/flow/playback/build-timeline.ts
 create mode 100644 packages/ui/src/components/flow/playback/derive-state.test.ts
 create mode 100644 packages/ui/src/components/flow/playback/derive-state.ts
 create mode 100644 packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/playback/flow-playback-bar.tsx
 create mode 100644 packages/ui/src/components/flow/playback/index.ts
 create mode 100644 packages/ui/src/components/flow/playback/types.ts
 create mode 100644 packages/ui/src/components/flow/playback/use-playback-clock.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 872fb871d7..7c297c4859 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -155,6 +155,8 @@
     "./flow/node-issue-marker": "./src/components/flow/node-issue-marker.tsx",
     "./flow/node-status": "./src/components/flow/node-status.tsx",
     "./flow/paths": "./src/components/flow/paths/highlight.ts",
+    "./flow/playback": "./src/components/flow/playback/index.ts",
+    "./flow/playback-bar": "./src/components/flow/playback/flow-playback-bar.tsx",
     "./flow/types": "./src/components/flow/types.ts",
     "./flow/use-elk-layout": "./src/components/flow/layout/use-elk-layout.ts",
     "./flow/workflow-canvas": "./src/components/flow/workflow-canvas.tsx",
diff --git a/packages/ui/src/components/flow/playback/build-timeline.test.ts b/packages/ui/src/components/flow/playback/build-timeline.test.ts
new file mode 100644
index 0000000000..2ca55ea23e
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/build-timeline.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import { branchRun, triageFailedRun } from '../testing/flow-fixtures';
+import { buildPlaybackTimeline, type FlowRealRun } from './build-timeline';
+
+describe('buildPlaybackTimeline', () => {
+  it('plays each stretch for its real length, never shorter than a step nor longer than a gap', () => {
+    const run: FlowRealRun = {
+      startedAt: 0,
+      endedAt: 10_000_000,
+      spans: [
+        { nodeId: 'a', startedAt: 0, endedAt: 2, outcome: 'succeeded' },
+        { nodeId: 'b', startedAt: 2, endedAt: 500, outcome: 'succeeded' },
+        {
+          nodeId: 'c',
+          startedAt: 500,
+          endedAt: 10_000_000,
+          outcome: 'succeeded',
+        },
+      ],
+      travels: [],
+    };
+    const timeline = buildPlaybackTimeline(run);
+    const [a, b, c] = timeline.spans;
+    // 2 ms plays as the 240 ms floor, 498 ms as itself, hours as 1.2 s.
+    expect(a?.end).toBe(240);
+    expect(b?.end).toBe(240 + 498);
+    expect((c?.end ?? 0) - (c?.start ?? 0)).toBe(1_200);
+    expect(timeline.duration).toBe(240 + 498 + 1_200);
+    expect(timeline.live).toBeUndefined();
+  });
+
+  it('gives a value time to travel before its target starts', () => {
+    const run: FlowRealRun = {
+      startedAt: 0,
+      endedAt: 1_000,
+      spans: [
+        { nodeId: 'a', startedAt: 0, endedAt: 300, outcome: 'succeeded' },
+        { nodeId: 'b', startedAt: 301, endedAt: 1_000, outcome: 'succeeded' },
+      ],
+      travels: [{ edgeId: 'a>b', at: 300, target: 'b' }],
+    };
+    const timeline = buildPlaybackTimeline(run, { travelMs: 320 });
+    const travel = timeline.travels[0];
+    const b = timeline.spans[1];
+    expect(travel?.end).toBe((travel?.start ?? 0) + 320);
+    expect(b?.start).toBeGreaterThanOrEqual(travel?.end ?? Infinity);
+    expect(timeline.events).toContain(travel?.start);
+  });
+
+  it('marks a long wait with its real words and a failure with its reason', () => {
+    const timeline = buildPlaybackTimeline(branchRun());
+    const wait = timeline.marks?.find((mark) => mark.kind === 'wait');
+    expect(wait?.label).toBe('Waited 0.8 s for approval');
+    const failure = buildPlaybackTimeline(triageFailedRun()).marks?.find(
+      (mark) => mark.kind === 'failure',
+    );
+    expect(failure?.label).toBe('The model provider refused the request');
+  });
+
+  it('maps real time and playback time back and forth', () => {
+    const run = branchRun();
+    const timeline = buildPlaybackTimeline(run);
+    for (const t of [0, 100, 777, 1_234.5, timeline.duration / 2]) {
+      expect(timeline.fromReal(timeline.toReal(t))).toBeCloseTo(t, 6);
+    }
+    for (const span of run.spans) {
+      const played = timeline.fromReal(span.startedAt);
+      expect(timeline.toReal(played)).toBeCloseTo(span.startedAt, 6);
+    }
+    expect(timeline.toReal(0)).toBe(run.startedAt);
+    expect(timeline.toReal(timeline.fromReal(run.endedAt ?? 0))).toBe(
+      run.endedAt,
+    );
+  });
+
+  it('keeps events in order and the duration past every travel', () => {
+    const timeline = buildPlaybackTimeline(branchRun());
+    expect([...timeline.events]).toEqual(
+      [...timeline.events].sort((a, b) => a - b),
+    );
+    for (const travel of timeline.travels)
+      expect(timeline.duration).toBeGreaterThanOrEqual(travel.end);
+  });
+
+  it('is live while the run has no end, and plays past its last moment one to one', () => {
+    const run = { ...triageFailedRun(), endedAt: undefined };
+    const timeline = buildPlaybackTimeline(run);
+    expect(timeline.live).toBe(true);
+    const last = timeline.duration;
+    expect(timeline.fromReal(timeline.toReal(last) + 500)).toBeCloseTo(
+      last + 500,
+      6,
+    );
+  });
+});
diff --git a/packages/ui/src/components/flow/playback/build-timeline.ts b/packages/ui/src/components/flow/playback/build-timeline.ts
new file mode 100644
index 0000000000..e4187d9522
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/build-timeline.ts
@@ -0,0 +1,210 @@
+import type {
+  FlowEdgeTravel,
+  FlowNodeSpan,
+  FlowPlaybackTimeline,
+  FlowTimelineMark,
+} from './types';
+
+/** A span as a run recorded it: epoch milliseconds. */
+export interface FlowRealSpan extends Omit<FlowNodeSpan, 'start' | 'end'> {
+  startedAt: number;
+  /** Left out: still running. */
+  endedAt?: number;
+}
+
+/** A value leaving its source, as a run recorded it. */
+export interface FlowRealTravel {
+  edgeId: string;
+  /** Epoch milliseconds the value left the source. */
+  at: number;
+  /** The node the value goes to. With it, the target's next span plays
+   *  only once the value has arrived. */
+  target?: string;
+  item?: number;
+  summary?: string;
+}
+
+/** A stretch the run waited (an approval, a question, an agent). */
+export interface FlowRealWait {
+  startedAt: number;
+  endedAt?: number;
+  /** "Waited 3 h for approval". */
+  label: string;
+}
+
+export interface FlowRealRun {
+  startedAt: number;
+  /** Left out: the run is still going (a live timeline). */
+  endedAt?: number;
+  spans: readonly FlowRealSpan[];
+  travels: readonly FlowRealTravel[];
+  waits?: readonly FlowRealWait[];
+}
+
+export interface BuildPlaybackTimelineOptions {
+  /** Playback time a value takes along a line. @default 320 */
+  travelMs?: number;
+  /** The shortest a stretch between two moments plays for. @default 240 */
+  minStepMs?: number;
+  /** The longest a stretch between two moments plays for. @default 1200 */
+  maxGapMs?: number;
+}
+
+export interface FlowBuiltTimeline extends FlowPlaybackTimeline {
+  /** The real time (epoch ms) at playback moment `t`. */
+  toReal(t: number): number;
+  /** The playback moment of real time `ms` (epoch ms). */
+  fromReal(ms: number): number;
+}
+
+/**
+ * Turns a run as it was recorded (real start and end times, the moments
+ * values left their nodes, the waits) into a timeline a reader can follow.
+ *
+ * Real time is compressed piece by piece: the stretch between two
+ * consecutive moments plays for its real length, but never less than
+ * `minStepMs` (a 3 ms step stays visible) nor more than `maxGapMs` (a
+ * three-hour wait for approval does not stall the replay — it gets a
+ * `wait` mark that says how long it really was). Each value gets
+ * `travelMs` to reach its target before the target starts. The mapping is
+ * monotonic and piecewise linear, so `toReal` and `fromReal` invert each
+ * other and a clock can show real elapsed time.
+ */
+export function buildPlaybackTimeline(
+  run: FlowRealRun,
+  {
+    travelMs = 320,
+    minStepMs = 240,
+    maxGapMs = 1200,
+  }: BuildPlaybackTimelineOptions = {},
+): FlowBuiltTimeline {
+  const moments = new Set<number>([run.startedAt]);
+  for (const span of run.spans) {
+    moments.add(span.startedAt);
+    if (span.endedAt !== undefined) moments.add(span.endedAt);
+  }
+  for (const travel of run.travels) moments.add(travel.at);
+  for (const wait of run.waits ?? []) {
+    moments.add(wait.startedAt);
+    if (wait.endedAt !== undefined) moments.add(wait.endedAt);
+  }
+  if (run.endedAt !== undefined) moments.add(run.endedAt);
+  const real = [...moments]
+    .filter((moment) => moment >= run.startedAt)
+    .sort((a, b) => a - b);
+  const indexOf = new Map(real.map((moment, index) => [moment, index]));
+
+  // A value must reach its target before the target starts: the moment
+  // the target's next span starts plays at least `travelMs` after the
+  // value left.
+  const arrivals = new Map<number, number[]>();
+  for (const travel of run.travels) {
+    if (travel.target === undefined) continue;
+    const target = run.spans
+      .filter(
+        (span) => span.nodeId === travel.target && span.startedAt >= travel.at,
+      )
+      .sort((a, b) => a.startedAt - b.startedAt)[0];
+    if (target === undefined) continue;
+    const to = indexOf.get(target.startedAt);
+    const from = indexOf.get(travel.at);
+    if (to === undefined || from === undefined || to <= from) continue;
+    arrivals.set(to, [...(arrivals.get(to) ?? []), from]);
+  }
+
+  const played: number[] = [0];
+  for (let index = 1; index < real.length; index += 1) {
+    const step = (real[index] ?? 0) - (real[index - 1] ?? 0);
+    let at =
+      (played[index - 1] ?? 0) + Math.min(maxGapMs, Math.max(minStepMs, step));
+    for (const from of arrivals.get(index) ?? [])
+      at = Math.max(at, (played[from] ?? 0) + travelMs);
+    played.push(at);
+  }
+
+  const fromReal = (ms: number): number => {
+    if (real.length === 0 || ms <= (real[0] ?? 0)) return 0;
+    for (let index = 1; index < real.length; index += 1) {
+      const r1 = real[index] ?? 0;
+      if (ms <= r1) {
+        const r0 = real[index - 1] ?? 0;
+        const p0 = played[index - 1] ?? 0;
+        const p1 = played[index] ?? 0;
+        return p0 + ((ms - r0) / (r1 - r0)) * (p1 - p0);
+      }
+    }
+    // Past the last moment (a live run): real time plays one to one.
+    return (played.at(-1) ?? 0) + (ms - (real.at(-1) ?? 0));
+  };
+  const toReal = (t: number): number => {
+    if (real.length === 0) return run.startedAt + t;
+    if (t <= 0) return real[0] ?? run.startedAt;
+    for (let index = 1; index < played.length; index += 1) {
+      const p1 = played[index] ?? 0;
+      if (t <= p1) {
+        const p0 = played[index - 1] ?? 0;
+        const r0 = real[index - 1] ?? 0;
+        const r1 = real[index] ?? 0;
+        return r0 + ((t - p0) / (p1 - p0)) * (r1 - r0);
+      }
+    }
+    return (real.at(-1) ?? 0) + (t - (played.at(-1) ?? 0));
+  };
+
+  const spans: FlowNodeSpan[] = run.spans.map(
+    ({ startedAt, endedAt, ...rest }) => ({
+      ...rest,
+      start: fromReal(startedAt),
+      ...(endedAt === undefined ? {} : { end: fromReal(endedAt) }),
+    }),
+  );
+  const travels: FlowEdgeTravel[] = run.travels.map(
+    ({ at, target: _target, ...rest }) => {
+      const start = fromReal(at);
+      return { ...rest, start, end: start + travelMs };
+    },
+  );
+
+  const marks: FlowTimelineMark[] = [];
+  for (const wait of run.waits ?? [])
+    marks.push({
+      at: fromReal(wait.startedAt),
+      kind: 'wait',
+      label: wait.label,
+    });
+  for (const span of spans)
+    if (span.outcome === 'failed')
+      marks.push({
+        at: span.end ?? span.start,
+        kind: 'failure',
+        label: span.reason ?? span.detail ?? span.nodeId,
+      });
+  marks.sort((a, b) => a.at - b.at);
+
+  const events = [
+    ...new Set([
+      ...spans.flatMap((span) =>
+        span.end === undefined ? [span.start] : [span.start, span.end],
+      ),
+      ...travels.map((travel) => travel.start),
+    ]),
+  ].sort((a, b) => a - b);
+
+  const lastPlayed = played.at(-1) ?? 0;
+  const duration = Math.max(
+    run.endedAt === undefined ? lastPlayed : fromReal(run.endedAt),
+    ...travels.map((travel) => travel.end),
+    ...spans.map((span) => span.end ?? span.start),
+  );
+
+  return {
+    duration,
+    spans,
+    travels,
+    marks,
+    events,
+    ...(run.endedAt === undefined ? { live: true } : {}),
+    toReal,
+    fromReal,
+  };
+}
diff --git a/packages/ui/src/components/flow/playback/derive-state.test.ts b/packages/ui/src/components/flow/playback/derive-state.test.ts
new file mode 100644
index 0000000000..0d42e0518a
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/derive-state.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  branchFlowGraph,
+  branchRun,
+  branchRunOverlay,
+  triageFailedRun,
+  triageFlowGraph,
+} from '../testing/flow-fixtures';
+import { buildPlaybackTimeline } from './build-timeline';
+import { flowStateAt, flowStateFromOverlay } from './derive-state';
+
+const triage = () => {
+  const timeline = buildPlaybackTimeline(triageFailedRun());
+  const real = (ms: number) =>
+    timeline.fromReal(triageFailedRun().startedAt + ms);
+  return { graph: triageFlowGraph(), timeline, real };
+};
+
+describe('flowStateAt', () => {
+  it('says where every node stands at a moment', () => {
+    const { graph, timeline, real } = triage();
+    const before = flowStateAt(graph, timeline, real(20));
+    expect(before.nodes.__start?.state).toBe('succeeded');
+    expect(before.nodes.issues?.state).toBe('pending');
+    expect(before.nodes.__end?.state).toBe('pending');
+
+    const fetching = flowStateAt(graph, timeline, real(600));
+    expect(fetching.nodes.issues?.state).toBe('running');
+    expect(fetching.nodes.issues?.detail).toBe('1.2 s');
+
+    const done = flowStateAt(graph, timeline, real(1_255));
+    expect(done.nodes.issues?.state).toBe('succeeded');
+  });
+
+  it('counts the items of a node that runs once per item, and fails with an item', () => {
+    const { graph, timeline, real } = triage();
+    const second = flowStateAt(graph, timeline, real(3_000));
+    expect(second.nodes.score?.state).toBe('running');
+    expect(second.nodes.score?.items).toEqual({ done: 1, total: 4 });
+    const end = flowStateAt(graph, timeline, timeline.duration);
+    expect(end.nodes.score?.state).toBe('failed');
+    expect(end.nodes.score?.reason).toBe(
+      'The model provider refused the request',
+    );
+    expect(end.nodes.score?.items).toEqual({ done: 4, total: 4, failed: 1 });
+    // A node the run never reached did not run; End took the run's outcome.
+    expect(end.nodes.report?.state).toBe('not-run');
+    expect(end.nodes.__end?.state).toBe('failed');
+  });
+
+  it('travels values along lines, with their progress', () => {
+    const { graph, timeline } = triage();
+    const travel = timeline.travels.find(
+      (candidate) => candidate.edgeId === 'issues>open_issues',
+    );
+    if (travel === undefined) throw new Error('no travel');
+    const halfway = travel.start + (travel.end - travel.start) / 2;
+    const frame = flowStateAt(graph, timeline, halfway);
+    expect(frame.edges['issues>open_issues']).toBe('travelling');
+    expect(frame.travelling).toEqual([
+      { edgeId: 'issues>open_issues', progress: 0.5 },
+    ]);
+    expect(frame.edges['__start>issues']).toBe('travelled');
+    expect(frame.edges['open_issues>score']).toBe('idle');
+    const after = flowStateAt(graph, timeline, travel.end);
+    expect(after.edges['issues>open_issues']).toBe('travelled');
+    expect(after.travelling).toEqual([]);
+  });
+
+  it('focuses the first failure and the way the run took to it', () => {
+    const { graph, timeline } = triage();
+    const end = flowStateAt(graph, timeline, timeline.duration);
+    expect(end.failure?.nodeId).toBe('score');
+    expect([...(end.failure?.pathNodes ?? [])].sort()).toEqual(
+      ['__start', 'issues', 'open_issues', 'score'].sort(),
+    );
+    expect([...(end.failure?.pathEdges ?? [])].sort()).toEqual(
+      ['__start>issues', 'issues>open_issues', 'open_issues>score'].sort(),
+    );
+    // Lines past the failure were not taken.
+    expect(end.edges['score>report']).toBe('not-taken');
+    expect(end.edges['report>__end']).toBe('not-taken');
+  });
+
+  it('decides conditions and leaves the other branch not taken', () => {
+    const graph = branchFlowGraph();
+    const timeline = buildPlaybackTimeline(branchRun());
+    const end = flowStateAt(graph, timeline, timeline.duration);
+    expect(end.nodes['__gate:urgent']?.decision).toBe(false);
+    expect(end.nodes['__gate:normal']?.decision).toBe(true);
+    expect(end.edges['__gate:urgent>urgent']).toBe('not-taken');
+    expect(end.edges['__gate:urgent>__gate:normal']).toBe('travelled');
+    expect(end.edges['__gate:normal>low']).toBe('not-taken');
+    expect(end.edges['__gate:normal>normal']).toBe('travelled');
+    expect(end.nodes.urgent?.state).toBe('skipped');
+    expect(end.nodes.urgent?.reason).toBe('Skipped: the condition is false');
+    // Lines out of a skipped node are not taken either.
+    expect(end.edges['urgent>merge']).toBe('not-taken');
+    expect(end.nodes.poll?.pass).toEqual({ current: 3, max: 3 });
+    // The host's own End span speaks for the run.
+    expect(end.nodes.__end?.state).toBe('succeeded');
+    expect(end.nodes.__end?.detail).toBe('Succeeded in 4.6 s');
+  });
+
+  it('waits while a wait is open and runs again after it', () => {
+    const graph = branchFlowGraph();
+    const run = branchRun();
+    const timeline = buildPlaybackTimeline(run);
+    const at = (ms: number) => timeline.fromReal(run.startedAt + ms);
+    expect(flowStateAt(graph, timeline, at(2_000)).nodes.normal?.state).toBe(
+      'waiting',
+    );
+    expect(flowStateAt(graph, timeline, at(2_000)).nodes.normal?.reason).toBe(
+      'Waiting for approval',
+    );
+    expect(flowStateAt(graph, timeline, at(2_500)).nodes.normal?.state).toBe(
+      'running',
+    );
+  });
+
+  it('keeps an open span running on a live timeline, and nothing is final', () => {
+    const graph = triageFlowGraph();
+    const run = triageFailedRun();
+    const live = buildPlaybackTimeline({
+      ...run,
+      endedAt: undefined,
+      spans: run.spans
+        .filter((span) => span.item === undefined || span.item < 2)
+        .concat({
+          nodeId: 'score',
+          startedAt: run.startedAt + 4_100,
+          outcome: 'succeeded',
+          item: 2,
+        }),
+    });
+    const now = flowStateAt(graph, live, live.duration);
+    expect(now.nodes.score?.state).toBe('running');
+    // The run is not over: a live list has no known length yet.
+    expect(now.nodes.score?.items).toEqual({ done: 2 });
+    expect(now.nodes.report?.state).toBe('pending');
+    expect(now.nodes.__end?.state).toBe('pending');
+  });
+});
+
+describe('flowStateFromOverlay', () => {
+  it('derives the lines from where their ends stand', () => {
+    const graph = branchFlowGraph();
+    const frame = flowStateFromOverlay(graph, branchRunOverlay());
+    expect(frame.edges['__gate:urgent>urgent']).toBe('not-taken');
+    expect(frame.edges['__gate:normal>normal']).toBe('travelled');
+    expect(frame.edges['fetch>classify']).toBe('travelled');
+    expect(frame.edges['merge>notify']).toBe('travelled');
+    expect(frame.travelling).toEqual([]);
+    expect(frame.failure?.nodeId).toBe('notify');
+    expect(frame.failure?.pathEdges.has('merge>notify')).toBe(true);
+  });
+
+  it('takes the host’s lines when it gives them, and leaves unknown nodes not run', () => {
+    const graph = triageFlowGraph();
+    const frame = flowStateFromOverlay(graph, {
+      finished: true,
+      nodes: { issues: { state: 'succeeded' } },
+      edges: { 'issues>open_issues': 'not-taken' },
+    });
+    expect(frame.edges['issues>open_issues']).toBe('not-taken');
+    expect(frame.nodes.open_issues?.state).toBe('not-run');
+    expect(frame.nodes.__end?.state).toBe('succeeded');
+    const running = flowStateFromOverlay(graph, { finished: false, nodes: {} });
+    expect(running.nodes.issues?.state).toBe('pending');
+    expect(running.nodes.__end?.state).toBe('pending');
+  });
+});
diff --git a/packages/ui/src/components/flow/playback/derive-state.ts b/packages/ui/src/components/flow/playback/derive-state.ts
new file mode 100644
index 0000000000..a06a7dc336
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/derive-state.ts
@@ -0,0 +1,318 @@
+import type { FlowNodeState } from '../node-status';
+import type { FlowEdge, FlowGraph, FlowNode } from '../types';
+import type {
+  FlowEdgeRunState,
+  FlowFrameState,
+  FlowNodeRunInfo,
+  FlowNodeSpan,
+  FlowPlaybackTimeline,
+  FlowRunOverlay,
+} from './types';
+
+/**
+ * Where every node and line of a chart stands in a run — at a moment of a
+ * playback timeline, or as an overlay without time. Pure: the canvas, the
+ * List view and a scrubber's words all read the same frame.
+ *
+ * A node's state at `t` comes from its spans that have started: running
+ * (or waiting) while one is open, else the outcome of the last to end; a
+ * node that runs once per item stays running between items and fails when
+ * an item failed. A node no span reached is pending, or did not run once
+ * the run is over. Start counts as done from the first moment; End takes
+ * the run's outcome when it is over.
+ *
+ * A line is travelling while a value moves along it, travelled once one
+ * arrived, and not taken when its condition decided the other way or its
+ * target was skipped. Where the host recorded no travel for a line, it is
+ * travelled when its source succeeded and its target started.
+ */
+
+/** A node that has started, whatever came of it. */
+const STARTED: ReadonlySet<FlowNodeState> = new Set([
+  'running',
+  'waiting',
+  'succeeded',
+  'failed',
+  'stopped',
+]);
+
+/** A node the run passed by. */
+const PASSED_BY: ReadonlySet<FlowNodeState> = new Set(['skipped', 'not-run']);
+
+const drawn = (graph: FlowGraph) =>
+  graph.edges.filter((edge) => !edge.layoutOnly);
+
+/** The state of a node no span (or overlay entry) speaks for. */
+function untouched(node: FlowNode, finished: boolean): FlowNodeRunInfo {
+  if (node.kind === 'entry') return { state: 'succeeded' };
+  return { state: finished ? 'not-run' : 'pending' };
+}
+
+/** End's state: the run's outcome once it is over. */
+function exitState(
+  nodes: Readonly<Record<string, FlowNodeRunInfo>>,
+  finished: boolean,
+): FlowNodeRunInfo {
+  if (!finished) return { state: 'pending' };
+  const states = new Set(Object.values(nodes).map((info) => info.state));
+  if (states.has('failed')) return { state: 'failed' };
+  if (states.has('stopped')) return { state: 'stopped' };
+  return { state: 'succeeded' };
+}
+
+/** A node's state from its spans at `t`; `null` when none has started. */
+function stateFromSpans(
+  spans: readonly FlowNodeSpan[],
+  t: number,
+  live: boolean,
+): FlowNodeRunInfo | null {
+  const started = spans.filter((span) => span.start <= t);
+  if (started.length === 0) return null;
+  const open = started.filter((span) => span.end === undefined || t < span.end);
+  const more = spans.some((span) => span.start > t);
+  // The span that started last speaks for the words (ties: the later one).
+  const latest = started.reduce((a, b) => (b.start >= a.start ? b : a));
+  const lastEnded = started
+    .filter((span) => span.end !== undefined && span.end <= t)
+    .reduce<FlowNodeSpan | null>(
+      (a, b) => (a === null || (b.end ?? 0) >= (a.end ?? 0) ? b : a),
+      null,
+    );
+  const itemSpans = spans.filter((span) => span.item !== undefined);
+  const failedItem = started.some(
+    (span) =>
+      span.item !== undefined &&
+      span.outcome === 'failed' &&
+      span.end !== undefined &&
+      span.end <= t,
+  );
+
+  let state: FlowNodeState;
+  if (open.length > 0)
+    state = open.every((span) => span.outcome === 'waiting')
+      ? 'waiting'
+      : 'running';
+  else if (more)
+    // Between two stretches of work: still at it (or still waiting).
+    state = lastEnded?.outcome === 'waiting' ? 'waiting' : 'running';
+  else if (itemSpans.length > 0 && failedItem) state = 'failed';
+  else state = lastEnded?.outcome ?? 'succeeded';
+
+  const info: FlowNodeRunInfo = { state };
+  const failing =
+    state === 'failed'
+      ? started.find((span) => span.outcome === 'failed')
+      : undefined;
+  const words = failing ?? latest;
+  if (words.reason !== undefined) info.reason = words.reason;
+  if (words.detail !== undefined) info.detail = words.detail;
+  const decided = [...started]
+    .reverse()
+    .find((span) => span.decision !== undefined);
+  if (decided?.decision !== undefined) info.decision = decided.decision;
+  if (itemSpans.length > 0) {
+    const ended = itemSpans.filter(
+      (span) => span.end !== undefined && span.end <= t,
+    );
+    const failed = ended.filter((span) => span.outcome === 'failed').length;
+    info.items = {
+      done: new Set(ended.map((span) => span.item)).size,
+      ...(live
+        ? {}
+        : { total: new Set(itemSpans.map((span) => span.item)).size }),
+      ...(failed > 0 ? { failed } : {}),
+    };
+  }
+  const passes = spans.filter((span) => span.pass !== undefined);
+  if (passes.length > 0) {
+    const current = started
+      .filter((span) => span.pass !== undefined)
+      .reduce((max, span) => Math.max(max, span.pass ?? 0), 0);
+    info.pass = {
+      current,
+      ...(live
+        ? {}
+        : {
+            max: passes.reduce((max, span) => Math.max(max, span.pass ?? 0), 0),
+          }),
+    };
+  }
+  return info;
+}
+
+/** A line's state from where its two ends stand. */
+function edgeFromNodes(
+  edge: FlowEdge,
+  nodes: Readonly<Record<string, FlowNodeRunInfo>>,
+): FlowEdgeRunState {
+  const source = nodes[edge.source];
+  const target = nodes[edge.target];
+  if (
+    edge.kind === 'branch-yes' ||
+    edge.kind === 'branch-no' ||
+    edge.kind === 'gate'
+  ) {
+    const decision = source?.decision;
+    if (decision !== undefined) {
+      const takes = edge.kind === 'branch-no' ? !decision : decision;
+      return takes ? 'travelled' : 'not-taken';
+    }
+  }
+  // A skip travels down: nothing leaves a node the run passed by.
+  if (
+    (target !== undefined && PASSED_BY.has(target.state)) ||
+    (source !== undefined && PASSED_BY.has(source.state))
+  )
+    return 'not-taken';
+  if (
+    source?.state === 'succeeded' &&
+    target !== undefined &&
+    STARTED.has(target.state)
+  )
+    return 'travelled';
+  return 'idle';
+}
+
+/**
+ * The first failure and the way the run took to it: every line it
+ * travelled, back from the failed node, and the nodes those lines came
+ * from.
+ */
+function failureOf(
+  graph: FlowGraph,
+  nodes: Readonly<Record<string, FlowNodeRunInfo>>,
+  edges: Readonly<Record<string, FlowEdgeRunState>>,
+  first: string | undefined,
+): FlowFrameState['failure'] {
+  if (first === undefined) return undefined;
+  const incoming = new Map<string, FlowEdge[]>();
+  for (const edge of drawn(graph))
+    incoming.set(edge.target, [...(incoming.get(edge.target) ?? []), edge]);
+  const pathNodes = new Set<string>([first]);
+  const pathEdges = new Set<string>();
+  const stack = [first];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (id === undefined) continue;
+    for (const edge of incoming.get(id) ?? []) {
+      const state = edges[edge.id];
+      if (state !== 'travelled' && state !== 'travelling') continue;
+      const source = nodes[edge.source];
+      if (source === undefined || !STARTED.has(source.state)) continue;
+      pathEdges.add(edge.id);
+      if (!pathNodes.has(edge.source)) {
+        pathNodes.add(edge.source);
+        stack.push(edge.source);
+      }
+    }
+  }
+  return { nodeId: first, pathNodes, pathEdges };
+}
+
+const isWork = (node: FlowNode) =>
+  node.kind !== 'entry' && node.kind !== 'exit';
+
+/** The frame at moment `t` of a playback timeline. */
+export function flowStateAt(
+  graph: FlowGraph,
+  timeline: FlowPlaybackTimeline,
+  t: number,
+): FlowFrameState {
+  const live = timeline.live === true;
+  const finished = !live && t >= timeline.duration;
+  const spansOf = new Map<string, FlowNodeSpan[]>();
+  for (const span of timeline.spans)
+    spansOf.set(span.nodeId, [...(spansOf.get(span.nodeId) ?? []), span]);
+
+  const nodes: Record<string, FlowNodeRunInfo> = {};
+  for (const node of graph.nodes) {
+    if (node.kind === 'exit') continue;
+    nodes[node.id] =
+      stateFromSpans(spansOf.get(node.id) ?? [], t, live) ??
+      untouched(node, finished);
+  }
+  for (const node of graph.nodes) {
+    if (node.kind !== 'exit') continue;
+    nodes[node.id] =
+      stateFromSpans(spansOf.get(node.id) ?? [], t, live) ??
+      exitState(nodes, finished);
+  }
+
+  const travelsOf = new Map<
+    string,
+    FlowPlaybackTimeline['travels'][number][]
+  >();
+  for (const travel of timeline.travels)
+    travelsOf.set(travel.edgeId, [
+      ...(travelsOf.get(travel.edgeId) ?? []),
+      travel,
+    ]);
+
+  const edges: Record<string, FlowEdgeRunState> = {};
+  const travelling: FlowFrameState['travelling'] = [];
+  for (const edge of drawn(graph)) {
+    const travels = travelsOf.get(edge.id) ?? [];
+    let state: FlowEdgeRunState | null = null;
+    for (const travel of travels) {
+      if (travel.start <= t && t < travel.end) {
+        state = 'travelling';
+        travelling.push({
+          edgeId: edge.id,
+          progress: (t - travel.start) / (travel.end - travel.start),
+          ...(travel.item === undefined ? {} : { item: travel.item }),
+        });
+      } else if (travel.end <= t && state === null) state = 'travelled';
+    }
+    if (state === null) {
+      const fallback = edgeFromNodes(edge, nodes);
+      // A line with recorded travels is travelled only by one of them.
+      state =
+        travels.length > 0 && fallback === 'travelled' ? 'idle' : fallback;
+    }
+    edges[edge.id] = state;
+  }
+
+  // The first failure in time (ties: reading order).
+  let first: { id: string; at: number } | undefined;
+  for (const node of graph.nodes) {
+    if (!isWork(node) || nodes[node.id]?.state !== 'failed') continue;
+    const at = Math.min(
+      ...(spansOf.get(node.id) ?? [])
+        .filter((span) => span.outcome === 'failed' && span.start <= t)
+        .map((span) => span.end ?? span.start),
+    );
+    if (first === undefined || at < first.at) first = { id: node.id, at };
+  }
+  const failure = failureOf(graph, nodes, edges, first?.id);
+  return failure === undefined
+    ? { nodes, edges, travelling }
+    : { nodes, edges, travelling, failure };
+}
+
+/** The frame of a run shown without time. */
+export function flowStateFromOverlay(
+  graph: FlowGraph,
+  overlay: FlowRunOverlay,
+): FlowFrameState {
+  const nodes: Record<string, FlowNodeRunInfo> = {};
+  for (const node of graph.nodes) {
+    if (node.kind === 'exit') continue;
+    nodes[node.id] =
+      overlay.nodes[node.id] ?? untouched(node, overlay.finished);
+  }
+  for (const node of graph.nodes) {
+    if (node.kind !== 'exit') continue;
+    nodes[node.id] =
+      overlay.nodes[node.id] ?? exitState(nodes, overlay.finished);
+  }
+  const edges: Record<string, FlowEdgeRunState> = {};
+  for (const edge of drawn(graph))
+    edges[edge.id] = overlay.edges?.[edge.id] ?? edgeFromNodes(edge, nodes);
+  const first = graph.nodes.find(
+    (node) => isWork(node) && nodes[node.id]?.state === 'failed',
+  )?.id;
+  const failure = failureOf(graph, nodes, edges, first);
+  return failure === undefined
+    ? { nodes, edges, travelling: [] }
+    : { nodes, edges, travelling: [], failure };
+}
diff --git a/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx b/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
new file mode 100644
index 0000000000..7d7c18dfca
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
@@ -0,0 +1,165 @@
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { cdp, page, userEvent } from 'vitest/browser';
+
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { branchRun, triageFailedRun } from '../testing/flow-fixtures';
+import { buildPlaybackTimeline } from './build-timeline';
+import { FlowPlaybackBar } from './flow-playback-bar';
+import type { FlowPlaybackTimeline } from './types';
+import { usePlaybackClock } from './use-playback-clock';
+
+import '../../../globals.css';
+
+beforeEach(async () => {
+  await page.viewport(1280, 900);
+});
+
+afterEach(async () => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+});
+
+function Harness({ timeline }: { timeline: FlowPlaybackTimeline }) {
+  const clock = usePlaybackClock({ timeline });
+  return (
+    <div style={{ width: 720 }}>
+      <button type="button">Before the bar</button>
+      <FlowPlaybackBar
+        timeline={timeline}
+        t={clock.t}
+        onTChange={clock.setT}
+        playing={clock.playing}
+        onPlayingChange={clock.setPlaying}
+        speed={clock.speed}
+        onSpeedChange={clock.setSpeed}
+        activity={clock.t >= timeline.duration ? 'Score (Failed)' : undefined}
+        onFollowLive={clock.follow}
+      />
+      <output data-testid="t">{Math.round(clock.t)}</output>
+      <output data-testid="speed">{clock.speed}</output>
+    </div>
+  );
+}
+
+const shownT = () => Number(screen.getByTestId('t').textContent);
+
+describe('FlowPlaybackBar', () => {
+  it('names the scrubber and says where it is, in words', async () => {
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    render(<Harness timeline={timeline} />);
+    const slider = screen.getByRole('slider', { name: 'Run timeline' });
+    // A replay opens on the end of the run: the whole story.
+    expect(shownT()).toBe(Math.round(timeline.duration));
+    expect(slider).toHaveAttribute(
+      'aria-valuetext',
+      expect.stringMatching(/^\d\d:\d\d of \d\d:\d\d — Score \(Failed\)$/),
+    );
+    expect(
+      screen.getByRole('group', { name: 'Run timeline' }),
+    ).toBeInTheDocument();
+    // A tick for every event, one in the error red for the failure.
+    expect(document.querySelectorAll('[data-flow-mark="event"]')).toHaveLength(
+      timeline.events.length,
+    );
+    expect(
+      document.querySelectorAll('[data-flow-mark="failure"]'),
+    ).toHaveLength(1);
+  });
+
+  it('moves with the keys: arrows 1 %, pages 10 %, Home and End, brackets by event', async () => {
+    const timeline = buildPlaybackTimeline(branchRun());
+    render(<Harness timeline={timeline} />);
+    const slider = screen.getByRole('slider', { name: 'Run timeline' });
+    slider.focus();
+    await userEvent.keyboard('{Home}');
+    expect(shownT()).toBe(0);
+    await userEvent.keyboard('{ArrowRight}');
+    expect(shownT()).toBe(Math.round(timeline.duration * 0.01));
+    await userEvent.keyboard('{PageUp}');
+    expect(shownT()).toBe(Math.round(timeline.duration * 0.11));
+    await userEvent.keyboard('{Home}]');
+    const first = timeline.events.find((at) => at > 0.5) ?? 0;
+    expect(shownT()).toBe(Math.round(first));
+    await userEvent.keyboard(']');
+    const second = timeline.events.find((at) => at > first + 0.5) ?? 0;
+    expect(shownT()).toBe(Math.round(second));
+    await userEvent.keyboard('[[');
+    expect(shownT()).toBe(Math.round(first));
+    await userEvent.keyboard('{End}');
+    expect(shownT()).toBe(Math.round(timeline.duration));
+    // The wait shows as a band.
+    expect(document.querySelector('[data-flow-mark="wait"]')).not.toBeNull();
+  });
+
+  it('plays with Space and the button, whose name says what it does', async () => {
+    const timeline = buildPlaybackTimeline(branchRun());
+    render(<Harness timeline={timeline} />);
+    const slider = screen.getByRole('slider', { name: 'Run timeline' });
+    slider.focus();
+    await userEvent.keyboard('{Home}');
+    await userEvent.keyboard(' ');
+    const pause = await screen.findByRole('button', { name: 'Pause' });
+    await waitFor(() => expect(shownT()).toBeGreaterThan(50));
+    await userEvent.click(pause);
+    const stopped = shownT();
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(shownT()).toBe(stopped);
+    expect(screen.getByRole('button', { name: 'Play' })).toBeInTheDocument();
+  });
+
+  it('changes speed, and steps event to event under reduced motion', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const timeline = buildPlaybackTimeline(branchRun());
+    render(<Harness timeline={timeline} />);
+    await userEvent.click(screen.getByRole('radio', { name: '2×' }));
+    expect(screen.getByTestId('speed')).toHaveTextContent('2');
+    screen.getByRole('slider', { name: 'Run timeline' }).focus();
+    await userEvent.keyboard('{Home}');
+    await userEvent.click(screen.getByRole('button', { name: 'Play' }));
+    const first = timeline.events.find((at) => at > 0.5) ?? 0;
+    // No sweep: the first change lands exactly on the next event.
+    await waitFor(() => expect(shownT()).toBe(Math.round(first)), {
+      timeout: 2_000,
+    });
+  });
+
+  it('offers to follow a live run once the reader moved back', async () => {
+    const timeline = buildPlaybackTimeline({
+      ...triageFailedRun(),
+      endedAt: undefined,
+    });
+    render(<Harness timeline={timeline} />);
+    expect(screen.getByText('Live')).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Follow live' })).toBeNull();
+    screen.getByRole('slider', { name: 'Run timeline' }).focus();
+    await userEvent.keyboard('{Home}');
+    await userEvent.click(screen.getByRole('button', { name: 'Follow live' }));
+    expect(shownT()).toBe(Math.round(timeline.duration));
+  });
+
+  it('folds the speed into a menu on a phone', async () => {
+    await page.viewport(390, 844);
+    const timeline = buildPlaybackTimeline(branchRun());
+    render(<Harness timeline={timeline} />);
+    expect(
+      screen.getByRole('combobox', { name: 'Playback speed' }),
+    ).toBeVisible();
+    expect(screen.queryByRole('radio', { name: '2×' })).toBeNull();
+  });
+
+  it.each(['light', 'dark'])('passes axe (%s)', async (theme) => {
+    document.documentElement.classList.toggle('dark', theme === 'dark');
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const { container } = render(<Harness timeline={timeline} />);
+    const result = await axe.run(container, {
+      runOnly: ['wcag2a', 'wcag2aa'],
+    });
+    expect(result.violations).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/components/flow/playback/flow-playback-bar.tsx b/packages/ui/src/components/flow/playback/flow-playback-bar.tsx
new file mode 100644
index 0000000000..be85fcb94c
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/flow-playback-bar.tsx
@@ -0,0 +1,276 @@
+'use client';
+
+import { Pause, Play, Radio, SkipBack, SkipForward } from 'lucide-react';
+import { useMemo, type KeyboardEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useT } from '../../../i18n/client';
+import { cn } from '../../../lib/cn';
+import { Badge } from '../../feedback/badge';
+import { SegmentedControl } from '../../forms/segmented-control';
+import { Select } from '../../forms/select';
+import { Slider } from '../../forms/slider';
+import { Card } from '../../layout/card';
+import { Button } from '../../primitives/button';
+import {
+  FLOW_PLAYBACK_SPEEDS,
+  type FlowPlaybackSpeed,
+  type FlowPlaybackTimeline,
+} from './types';
+import { nextFlowEvent, previousFlowEvent } from './use-playback-clock';
+
+export interface FlowPlaybackBarProps {
+  timeline: FlowPlaybackTimeline;
+  t: number;
+  onTChange: (t: number) => void;
+  playing: boolean;
+  onPlayingChange: (playing: boolean) => void;
+  speed?: FlowPlaybackSpeed;
+  /** Shows the speed choice when given. */
+  onSpeedChange?: (speed: FlowPlaybackSpeed) => void;
+  /**
+   * The clock's words for a moment ("00:42"). Defaults to playback time;
+   * pass `toReal`-based words to show how long the run really took.
+   */
+  formatTime?: (t: number) => string;
+  /** What is happening at `t` ("Score (Running)"), for the scrubber's
+   *  spoken value. */
+  activity?: string;
+  /** A live run: a "Follow live" button shows while `t` is behind its end. */
+  onFollowLive?: () => void;
+  className?: string;
+}
+
+/** "01:05", or "1:02:05" past an hour. */
+export function formatFlowClock(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return hours > 0
+    ? `${hours}:${pad(minutes)}:${pad(seconds)}`
+    : `${pad(minutes)}:${pad(seconds)}`;
+}
+
+/** The speed an option's value names; 1× for anything else. */
+const speedOf = (value: string): FlowPlaybackSpeed =>
+  FLOW_PLAYBACK_SPEEDS.find((speed) => String(speed) === value) ?? 1;
+
+/** Share of the timeline a key moves by. */
+const STEP = 0.01;
+const PAGE = 0.1;
+
+/**
+ * The controls of a run's replay: play or pause, the previous and next
+ * event, a scrubber with a tick for every event (failures in the error
+ * red, waits as a hatched band), the time, the speed, and on a live run
+ * "Live" with a way back to its end.
+ *
+ * The host owns time (`t`, `playing`, `speed`) — pair it with
+ * `usePlaybackClock`. Keys: Space plays or pauses anywhere on the bar
+ * except a button, ←/→ move the scrubber by 1 % and Page Up/Page Down by
+ * 10 %, Home/End jump to the ends, `[` and `]` step between events.
+ */
+export function FlowPlaybackBar({
+  timeline,
+  t,
+  onTChange,
+  playing,
+  onPlayingChange,
+  speed = 1,
+  onSpeedChange,
+  formatTime = formatFlowClock,
+  activity,
+  onFollowLive,
+  className,
+}: FlowPlaybackBarProps) {
+  const { t: tr } = useT('flow');
+  const { i18n } = useTranslation();
+  const locale = i18n?.resolvedLanguage ?? i18n?.language ?? 'en';
+  const duration = Math.max(0, timeline.duration);
+  const position = tr('playback.position', {
+    elapsed: formatTime(t),
+    total: formatTime(duration),
+  });
+  const valueText =
+    activity === undefined || activity === ''
+      ? position
+      : tr('playback.valueText', { position, events: activity });
+
+  const speedOptions = useMemo(() => {
+    const number = new Intl.NumberFormat(locale);
+    return FLOW_PLAYBACK_SPEEDS.map((value) => ({
+      value: String(value),
+      label: `${number.format(value)}×`,
+    }));
+  }, [locale]);
+
+  const percent = (at: number) =>
+    duration > 0 ? Math.min(100, Math.max(0, (at / duration) * 100)) : 0;
+  const failures = (timeline.marks ?? []).filter(
+    (mark) => mark.kind === 'failure',
+  );
+  const waits = (timeline.marks ?? []).filter((mark) => mark.kind === 'wait');
+
+  const move = (to: number) => onTChange(Math.min(duration, Math.max(0, to)));
+
+  const onSliderKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    const by: Record<string, number> = {
+      ArrowLeft: -STEP,
+      ArrowDown: -STEP,
+      ArrowRight: STEP,
+      ArrowUp: STEP,
+      PageDown: -PAGE,
+      PageUp: PAGE,
+    };
+    const step = by[event.key];
+    if (step !== undefined) {
+      event.preventDefault();
+      move(t + step * duration);
+    } else if (event.key === 'Home') {
+      event.preventDefault();
+      move(0);
+    } else if (event.key === 'End') {
+      event.preventDefault();
+      move(duration);
+    }
+  };
+
+  const onBarKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const target = event.target;
+    const onButton =
+      target instanceof HTMLElement &&
+      target.closest('button, [role="combobox"], [role="radio"]') !== null;
+    if (event.key === ' ' && !onButton) {
+      event.preventDefault();
+      onPlayingChange(!playing);
+    } else if (event.key === '[') {
+      event.preventDefault();
+      move(previousFlowEvent(timeline, t));
+    } else if (event.key === ']') {
+      event.preventDefault();
+      move(nextFlowEvent(timeline, t));
+    }
+  };
+
+  const behindLive = timeline.live === true && t < duration;
+
+  return (
+    <Card
+      padding="none"
+      role="group"
+      aria-label={tr('playback.label')}
+      onKeyDown={onBarKeyDown}
+      className={cn('flex min-h-11 items-center gap-1 px-1', className)}
+    >
+      <Button
+        size="icon"
+        variant="ghost"
+        title={tr(playing ? 'playback.pause' : 'playback.play')}
+        onClick={() => onPlayingChange(!playing)}
+      >
+        {playing ? <Pause className="size-4" /> : <Play className="size-4" />}
+      </Button>
+      <Button
+        size="icon"
+        variant="ghost"
+        title={tr('playback.previous')}
+        onClick={() => move(previousFlowEvent(timeline, t))}
+      >
+        <SkipBack className="size-4" />
+      </Button>
+      <Button
+        size="icon"
+        variant="ghost"
+        title={tr('playback.next')}
+        onClick={() => move(nextFlowEvent(timeline, t))}
+      >
+        <SkipForward className="size-4" />
+      </Button>
+      <div className="relative mx-1 flex min-w-24 flex-1 flex-col justify-center gap-1">
+        <Slider
+          value={t}
+          min={0}
+          max={duration}
+          step={1}
+          onChange={(event) => move(Number(event.target.value))}
+          onKeyDown={onSliderKeyDown}
+          aria-label={tr('playback.label')}
+          aria-valuetext={valueText}
+        />
+        {/* The thumb's centre runs 10 px in from each end; so do the ticks. */}
+        <div aria-hidden="true" className="relative mx-2.5 h-1.5">
+          {waits.map((mark) => {
+            const end = nextFlowEvent(timeline, mark.at);
+            return (
+              <span
+                key={`wait-${mark.at}`}
+                title={mark.label}
+                data-flow-mark="wait"
+                className="text-muted-foreground absolute top-0 h-1.5 rounded-xs bg-[repeating-linear-gradient(135deg,currentColor_0_2px,transparent_2px_4px)]"
+                style={{
+                  left: `${percent(mark.at)}%`,
+                  width: `${Math.max(1, percent(end) - percent(mark.at))}%`,
+                }}
+              />
+            );
+          })}
+          {timeline.events.map((at) => (
+            <span
+              key={`event-${at}`}
+              data-flow-mark="event"
+              className="bg-muted-foreground absolute top-0 h-1.5 w-0.5 -translate-x-1/2 rounded-full"
+              style={{ left: `${percent(at)}%` }}
+            />
+          ))}
+          {failures.map((mark) => (
+            <span
+              key={`failure-${mark.at}`}
+              title={mark.label}
+              data-flow-mark="failure"
+              className="bg-destructive absolute top-0 h-1.5 w-0.5 -translate-x-1/2 rounded-full"
+              style={{ left: `${percent(mark.at)}%` }}
+            />
+          ))}
+        </div>
+      </div>
+      <span
+        aria-hidden="true"
+        className="text-muted-foreground shrink-0 px-1 text-xs tabular-nums"
+      >
+        {position}
+      </span>
+      {onSpeedChange && (
+        <>
+          <SegmentedControl
+            aria-label={tr('playback.speed')}
+            value={String(speed)}
+            onValueChange={(value) => onSpeedChange(speedOf(value))}
+            options={speedOptions}
+            className="hidden sm:inline-flex"
+          />
+          <div className="sm:hidden">
+            <Select
+              aria-label={tr('playback.speed')}
+              value={String(speed)}
+              onValueChange={(value) => onSpeedChange(speedOf(value))}
+              options={speedOptions}
+              className="h-9 w-20"
+            />
+          </div>
+        </>
+      )}
+      {timeline.live === true && (
+        <Badge variant="destructive" icon={Radio} className="shrink-0">
+          {tr('playback.live')}
+        </Badge>
+      )}
+      {behindLive && onFollowLive && (
+        <Button size="sm" variant="secondary" onClick={onFollowLive}>
+          {tr('playback.followLive')}
+        </Button>
+      )}
+    </Card>
+  );
+}
diff --git a/packages/ui/src/components/flow/playback/index.ts b/packages/ui/src/components/flow/playback/index.ts
new file mode 100644
index 0000000000..6bda2ac524
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/index.ts
@@ -0,0 +1,36 @@
+/**
+ * `@tale/ui/flow/playback` — a run on a workflow chart: the overlay and
+ * timeline types, the frame a chart draws at a moment, the timeline
+ * builder that compresses a recorded run, and the clock a host drives a
+ * replay with. The bar itself is `@tale/ui/flow/playback-bar`.
+ */
+export type {
+  FlowEdgeRunState,
+  FlowEdgeTravel,
+  FlowFrameState,
+  FlowNodeRunInfo,
+  FlowNodeSpan,
+  FlowPlayback,
+  FlowPlaybackSpeed,
+  FlowPlaybackTimeline,
+  FlowRunOverlay,
+  FlowTimelineMark,
+} from './types';
+export { FLOW_PLAYBACK_SPEEDS } from './types';
+export { flowStateAt, flowStateFromOverlay } from './derive-state';
+export {
+  buildPlaybackTimeline,
+  type BuildPlaybackTimelineOptions,
+  type FlowBuiltTimeline,
+  type FlowRealRun,
+  type FlowRealSpan,
+  type FlowRealTravel,
+  type FlowRealWait,
+} from './build-timeline';
+export {
+  FLOW_PLAYBACK_STEP_MS,
+  nextFlowEvent,
+  previousFlowEvent,
+  usePlaybackClock,
+  type FlowPlaybackClock,
+} from './use-playback-clock';
diff --git a/packages/ui/src/components/flow/playback/types.ts b/packages/ui/src/components/flow/playback/types.ts
new file mode 100644
index 0000000000..be66656873
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/types.ts
@@ -0,0 +1,129 @@
+import type { FlowNodeState } from '../node-status';
+
+/**
+ * A run on a workflow chart, two ways: an overlay (where each node stands,
+ * no time) and a playback timeline (when each node ran and when each value
+ * moved, scrubbed by the host's `t`). The canvas derives one frame state
+ * from either and draws it the same way.
+ *
+ * Playback times are milliseconds of playback, not of the run:
+ * `buildPlaybackTimeline` compresses a run's real moments into a timeline
+ * a reader can follow, and maps back to real time for the clock.
+ */
+
+/** Where one node stands in a run. */
+export interface FlowNodeRunInfo {
+  state: FlowNodeState;
+  /** The strip's right side: "1.2 s", "12 of 50 items". */
+  detail?: string;
+  /** The strip's left side in place of the state's word — why it was
+   *  skipped, the error line of a failure ("Skipped: Inbox was empty"). */
+  reason?: string;
+  /** A condition's decision: `true` took Yes. */
+  decision?: boolean;
+  /** A node that runs once per item: how many are done. */
+  items?: { done: number; total?: number; failed?: number };
+  /** A node that repeats: which pass it is on, of at most `max`. */
+  pass?: { current: number; max?: number };
+}
+
+/** A run shown without time: an old run without timings, an editor's
+ *  "last run". */
+export interface FlowRunOverlay {
+  nodes: Readonly<Record<string, FlowNodeRunInfo>>;
+  /**
+   * Which lines the run took. Left out, a line counts as travelled when
+   * its source succeeded and its target started, and as not taken when
+   * its target was skipped or its condition decided the other way.
+   */
+  edges?: Readonly<Record<string, 'travelled' | 'not-taken'>>;
+  /** The run is over: a node it never reached did not run. */
+  finished: boolean;
+}
+
+/** One stretch of a node's work on the timeline. */
+export interface FlowNodeSpan {
+  nodeId: string;
+  start: number;
+  /** Left out: still running at the end of a live timeline. */
+  end?: number;
+  outcome:
+    | 'succeeded'
+    | 'failed'
+    | 'skipped'
+    | 'stopped'
+    | 'waiting'
+    | 'not-run';
+  reason?: string;
+  detail?: string;
+  /** A condition's decision (a zero-length span when it decides). */
+  decision?: boolean;
+  /** Which item of a list this span worked on. */
+  item?: number;
+  /** Which pass of a repeat this span is. */
+  pass?: number;
+}
+
+/** A value moving along a line: it leaves the source at `start` and
+ *  arrives at `end`. */
+export interface FlowEdgeTravel {
+  edgeId: string;
+  start: number;
+  end: number;
+  item?: number;
+  /** A short peek at what moved ("12 issues"). */
+  summary?: string;
+}
+
+/** A moment worth a mark on the scrubber. */
+export interface FlowTimelineMark {
+  at: number;
+  kind: 'wait' | 'resume' | 'failure' | 'restart';
+  /** "Waited 3 h for approval". */
+  label: string;
+}
+
+export interface FlowPlaybackTimeline {
+  duration: number;
+  spans: readonly FlowNodeSpan[];
+  travels: readonly FlowEdgeTravel[];
+  marks?: readonly FlowTimelineMark[];
+  /** Every moment something starts or ends, in order: what previous and
+   *  next event step between, and where the scrubber's ticks sit. */
+  events: readonly number[];
+  /** The run is still going: the timeline grows. */
+  live?: boolean;
+}
+
+/** A run with time, at moment `t`. */
+export interface FlowPlayback {
+  timeline: FlowPlaybackTimeline;
+  t: number;
+}
+
+export type FlowEdgeRunState =
+  | 'idle'
+  | 'travelled'
+  | 'travelling'
+  | 'not-taken';
+
+/** Everything the canvas draws for a run at one moment. */
+export interface FlowFrameState {
+  nodes: Record<string, FlowNodeRunInfo>;
+  edges: Record<string, FlowEdgeRunState>;
+  /** Values on their way, and how far along (0–1). */
+  travelling: Array<{ edgeId: string; progress: number; item?: number }>;
+  /** The first node that failed, and the way the run took to it. */
+  failure?: {
+    nodeId: string;
+    pathNodes: ReadonlySet<string>;
+    pathEdges: ReadonlySet<string>;
+  };
+}
+
+/** How fast a playback runs. */
+export type FlowPlaybackSpeed = 0.5 | 1 | 2 | 4;
+
+export const FLOW_PLAYBACK_SPEEDS: readonly FlowPlaybackSpeed[] = [
+  0.5, 1, 2, 4,
+];
diff --git a/packages/ui/src/components/flow/playback/use-playback-clock.ts b/packages/ui/src/components/flow/playback/use-playback-clock.ts
new file mode 100644
index 0000000000..dfce61ff27
--- /dev/null
+++ b/packages/ui/src/components/flow/playback/use-playback-clock.ts
@@ -0,0 +1,136 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { usePrefersReducedMotion } from '../../../hooks/use-prefers-reduced-motion';
+import type { FlowPlaybackSpeed, FlowPlaybackTimeline } from './types';
+
+/** Under reduced motion, play steps from event to event this often. */
+export const FLOW_PLAYBACK_STEP_MS = 600;
+
+export interface FlowPlaybackClock {
+  /** The moment shown. */
+  t: number;
+  /** Moves to a moment; on a live timeline, stops following its end. */
+  setT: (t: number) => void;
+  playing: boolean;
+  setPlaying: (playing: boolean) => void;
+  speed: FlowPlaybackSpeed;
+  setSpeed: (speed: FlowPlaybackSpeed) => void;
+  /** A live timeline: `t` stays on its growing end. */
+  following: boolean;
+  /** Back to the live end. */
+  follow: () => void;
+}
+
+/** The first event after `t`, else the end. */
+export function nextFlowEvent(
+  timeline: FlowPlaybackTimeline,
+  t: number,
+): number {
+  return timeline.events.find((at) => at > t + 0.5) ?? timeline.duration;
+}
+
+/** The last event before `t`, else the start. */
+export function previousFlowEvent(
+  timeline: FlowPlaybackTimeline,
+  t: number,
+): number {
+  return [...timeline.events].reverse().find((at) => at < t - 0.5) ?? 0;
+}
+
+/**
+ * The clock a host drives a playback with. It opens on the end of the run
+ * (the whole story); playing from the end starts over. While it plays, `t`
+ * advances with the frames at `speed` and stops at the end. On a live
+ * timeline it follows the growing end until the reader moves `t`, and
+ * `follow()` goes back to it.
+ *
+ * Under reduced motion nothing sweeps: playing steps from event to event
+ * every 600 ms, so the states change without anything gliding.
+ */
+export function usePlaybackClock({
+  timeline,
+  live = timeline.live === true,
+}: {
+  timeline: FlowPlaybackTimeline;
+  live?: boolean;
+}): FlowPlaybackClock {
+  const reduced = usePrefersReducedMotion();
+  const [t, setTState] = useState(timeline.duration);
+  const [playing, setPlayingState] = useState(false);
+  const [speed, setSpeed] = useState<FlowPlaybackSpeed>(1);
+  const [following, setFollowing] = useState(live);
+
+  const latest = useRef({ timeline, t, speed });
+  latest.current = { timeline, t, speed };
+
+  // A live timeline grows: a follower stays on its end.
+  useEffect(() => {
+    if (live && following) setTState(timeline.duration);
+  }, [live, following, timeline.duration]);
+
+  const setT = useCallback(
+    (next: number) => {
+      const clamped = Math.min(
+        Math.max(0, next),
+        latest.current.timeline.duration,
+      );
+      setTState(clamped);
+      if (live) setFollowing(clamped >= latest.current.timeline.duration);
+    },
+    [live],
+  );
+
+  const setPlaying = useCallback((next: boolean) => {
+    if (next && latest.current.t >= latest.current.timeline.duration)
+      setTState(0);
+    setPlayingState(next);
+  }, []);
+
+  const follow = useCallback(() => {
+    setFollowing(true);
+    setTState(latest.current.timeline.duration);
+  }, []);
+
+  useEffect(() => {
+    if (!playing) return undefined;
+    if (reduced) {
+      const timer = setInterval(() => {
+        const { timeline: current, t: now } = latest.current;
+        const next = nextFlowEvent(current, now);
+        setTState(next);
+        if (next >= current.duration) setPlayingState(false);
+      }, FLOW_PLAYBACK_STEP_MS);
+      return () => clearInterval(timer);
+    }
+    let frame = 0;
+    let last: number | null = null;
+    const tick = (now: number) => {
+      const elapsed = last === null ? 0 : now - last;
+      last = now;
+      const { timeline: current, t: shown, speed: rate } = latest.current;
+      const next = Math.min(current.duration, shown + elapsed * rate);
+      latest.current = { ...latest.current, t: next };
+      setTState(next);
+      if (next >= current.duration) {
+        setPlayingState(false);
+        return;
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [playing, reduced]);
+
+  return {
+    t,
+    setT,
+    playing,
+    setPlaying,
+    speed,
+    setSpeed,
+    following,
+    follow,
+  };
+}
diff --git a/packages/ui/src/components/flow/testing/flow-fixtures.ts b/packages/ui/src/components/flow/testing/flow-fixtures.ts
index b1499f65e9..b65347195f 100644
--- a/packages/ui/src/components/flow/testing/flow-fixtures.ts
+++ b/packages/ui/src/components/flow/testing/flow-fixtures.ts
@@ -14,6 +14,8 @@ import {
   Square,
 } from 'lucide-react';
 
+import type { FlowRealRun } from '../playback/build-timeline';
+import type { FlowRunOverlay } from '../playback/types';
 import type {
   FlowEdge,
   FlowEdgeKind,
@@ -717,3 +719,246 @@ export function syntheticFlowGraph(count = 40, seed = 7): FlowGraph {
   const doc = syntheticDoc(count, seed);
   return flowGraphFromDoc(doc, [doc.at(-1)?.id ?? 's00']);
 }
+
+/** When the recorded runs below started: Thu 9 Oct 2025, 07:00 UTC. */
+const RUN_STARTED = Date.UTC(2025, 9, 9, 7, 0, 0);
+
+/**
+ * A recorded run of Triage GitHub issues that fails: Score works through
+ * four issues, one at a time, and the model refuses the third — Report
+ * never runs. Real epoch times, as a host records them.
+ */
+export function triageFailedRun(): FlowRealRun {
+  const at = (ms: number) => RUN_STARTED + ms;
+  return {
+    startedAt: at(0),
+    endedAt: at(5_000),
+    spans: [
+      {
+        nodeId: 'issues',
+        startedAt: at(50),
+        endedAt: at(1_250),
+        outcome: 'succeeded',
+        detail: '1.2 s',
+      },
+      {
+        nodeId: 'open_issues',
+        startedAt: at(1_260),
+        endedAt: at(1_290),
+        outcome: 'succeeded',
+        detail: '30 ms',
+      },
+      ...[
+        [1_300, 2_900],
+        [2_900, 4_100],
+      ].map(([from = 0, to = 0], item) => ({
+        nodeId: 'score',
+        startedAt: at(from),
+        endedAt: at(to),
+        outcome: 'succeeded' as const,
+        item,
+      })),
+      {
+        nodeId: 'score',
+        startedAt: at(4_100),
+        endedAt: at(5_000),
+        outcome: 'failed',
+        reason: 'The model provider refused the request',
+        item: 2,
+      },
+      {
+        nodeId: 'score',
+        startedAt: at(5_000),
+        endedAt: at(5_000),
+        outcome: 'not-run',
+        item: 3,
+      },
+    ],
+    travels: [
+      { edgeId: '__start>issues', at: at(0), target: 'issues' },
+      {
+        edgeId: 'issues>open_issues',
+        at: at(1_250),
+        target: 'open_issues',
+        summary: '4 issues',
+      },
+      {
+        edgeId: 'open_issues>score',
+        at: at(1_290),
+        target: 'score',
+        summary: '4 open issues',
+      },
+    ],
+  };
+}
+
+/**
+ * A recorded run of the branch fixture that succeeds: Urgent's condition
+ * says No and Normal's says Yes, so Urgent and Low are skipped; Notify
+ * fails and the run goes on; Poll repeats three times; the run waits for
+ * an approval on the way.
+ */
+export function branchRun(): FlowRealRun {
+  const at = (ms: number) => RUN_STARTED + ms;
+  const skipped = 'Skipped: the condition is false';
+  return {
+    startedAt: at(0),
+    endedAt: at(4_600),
+    spans: [
+      {
+        nodeId: 'fetch',
+        startedAt: at(10),
+        endedAt: at(400),
+        outcome: 'succeeded',
+        detail: '390 ms',
+      },
+      {
+        nodeId: 'enrich',
+        startedAt: at(410),
+        endedAt: at(900),
+        outcome: 'succeeded',
+        detail: '490 ms',
+      },
+      {
+        nodeId: 'classify',
+        startedAt: at(410),
+        endedAt: at(1_600),
+        outcome: 'succeeded',
+        detail: '1.2 s',
+      },
+      {
+        nodeId: '__gate:urgent',
+        startedAt: at(1_610),
+        endedAt: at(1_610),
+        outcome: 'succeeded',
+        decision: false,
+      },
+      {
+        nodeId: 'urgent',
+        startedAt: at(1_610),
+        endedAt: at(1_610),
+        outcome: 'skipped',
+        reason: skipped,
+      },
+      {
+        nodeId: '__gate:normal',
+        startedAt: at(1_620),
+        endedAt: at(1_620),
+        outcome: 'succeeded',
+        decision: true,
+      },
+      {
+        nodeId: 'low',
+        startedAt: at(1_620),
+        endedAt: at(1_620),
+        outcome: 'skipped',
+        reason: skipped,
+      },
+      {
+        nodeId: 'normal',
+        startedAt: at(1_630),
+        endedAt: at(2_400),
+        outcome: 'waiting',
+        reason: 'Waiting for approval',
+      },
+      {
+        nodeId: 'normal',
+        startedAt: at(2_400),
+        endedAt: at(3_000),
+        outcome: 'succeeded',
+        detail: '1.4 s',
+      },
+      {
+        nodeId: 'merge',
+        startedAt: at(3_010),
+        endedAt: at(3_100),
+        outcome: 'succeeded',
+        detail: '90 ms',
+      },
+      {
+        nodeId: 'notify',
+        startedAt: at(3_110),
+        endedAt: at(3_400),
+        outcome: 'failed',
+        reason: 'The mail server refused the message',
+      },
+      ...[1, 2, 3].map((pass) => ({
+        nodeId: 'poll',
+        startedAt: at(3_110 + (pass - 1) * 500),
+        endedAt: at(3_110 + pass * 500),
+        outcome: 'succeeded' as const,
+        pass,
+      })),
+      {
+        nodeId: '__end',
+        startedAt: at(4_600),
+        endedAt: at(4_600),
+        outcome: 'succeeded',
+        detail: 'Succeeded in 4.6 s',
+      },
+    ],
+    travels: [
+      { edgeId: '__start>fetch', at: at(0), target: 'fetch' },
+      { edgeId: 'fetch>classify', at: at(400), target: 'classify' },
+      { edgeId: 'fetch>enrich', at: at(400), target: 'enrich' },
+      {
+        edgeId: 'classify>__gate:urgent',
+        at: at(1_600),
+        target: '__gate:urgent',
+      },
+      {
+        edgeId: '__gate:urgent>__gate:normal',
+        at: at(1_610),
+        target: '__gate:normal',
+      },
+      { edgeId: '__gate:normal>normal', at: at(1_620), target: 'normal' },
+      { edgeId: 'fetch>normal', at: at(1_620), target: 'normal' },
+      { edgeId: 'normal>merge', at: at(3_000), target: 'merge' },
+      { edgeId: 'enrich>merge', at: at(3_000), target: 'merge' },
+      { edgeId: 'merge>notify', at: at(3_100), target: 'notify' },
+      { edgeId: 'merge>poll', at: at(3_100), target: 'poll' },
+      { edgeId: 'merge>__end', at: at(4_600), target: '__end' },
+      { edgeId: 'poll>__end', at: at(4_600), target: '__end' },
+    ],
+    waits: [
+      {
+        startedAt: at(1_630),
+        endedAt: at(2_400),
+        label: 'Waited 0.8 s for approval',
+      },
+    ],
+  };
+}
+
+/**
+ * The branch fixture's last run as an overlay — where each node ended,
+ * without time: what an editor shows as "last run".
+ */
+export function branchRunOverlay(): FlowRunOverlay {
+  const skipped = 'Skipped: the condition is false';
+  return {
+    finished: true,
+    nodes: {
+      __start: { state: 'succeeded', detail: 'Started 07:00 by hand' },
+      fetch: { state: 'succeeded', detail: '390 ms' },
+      enrich: { state: 'succeeded', detail: '490 ms' },
+      classify: { state: 'succeeded', detail: '1.2 s' },
+      '__gate:urgent': { state: 'succeeded', decision: false },
+      urgent: { state: 'skipped', reason: skipped },
+      '__gate:normal': { state: 'succeeded', decision: true },
+      normal: { state: 'succeeded', detail: '1.4 s' },
+      low: { state: 'skipped', reason: skipped },
+      merge: { state: 'succeeded', detail: '90 ms' },
+      notify: {
+        state: 'failed',
+        reason: 'The mail server refused the message',
+      },
+      poll: {
+        state: 'succeeded',
+        detail: '1.5 s',
+        pass: { current: 3, max: 5 },
+      },
+      __end: { state: 'succeeded', detail: 'Succeeded in 4.6 s' },
+    },
+  };
+}
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index c3c0a4268d..2e88b4c5e8 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -578,3 +578,14 @@ flow:
     empty: Noch keine Nodes
   paths:
     showAll: Alle zeigen
+  playback:
+    label: Zeitachse des Laufs
+    play: Abspielen
+    pause: Pausieren
+    previous: Vorheriges Ereignis
+    next: Nächstes Ereignis
+    speed: Wiedergabegeschwindigkeit
+    position: '{elapsed} von {total}'
+    valueText: '{position} – {events}'
+    live: Live
+    followLive: Live folgen
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index e582826583..d808eea42f 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -578,3 +578,14 @@ flow:
     empty: No nodes yet
   paths:
     showAll: Show all
+  playback:
+    label: Run timeline
+    play: Play
+    pause: Pause
+    previous: Previous event
+    next: Next event
+    speed: Playback speed
+    position: '{elapsed} of {total}'
+    valueText: '{position} — {events}'
+    live: Live
+    followLive: Follow live
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index d3292d6985..0a92f85ddb 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -578,3 +578,14 @@ flow:
     empty: Aucun nœud pour l'instant
   paths:
     showAll: Tout afficher
+  playback:
+    label: Chronologie de l'exécution
+    play: Lire
+    pause: Mettre en pause
+    previous: Événement précédent
+    next: Événement suivant
+    speed: Vitesse de lecture
+    position: '{elapsed} sur {total}'
+    valueText: '{position} – {events}'
+    live: En direct
+    followLive: Suivre en direct
diff --git a/packages/ui/src/testing/flow.ts b/packages/ui/src/testing/flow.ts
index f2cf726bae..91c461835b 100644
--- a/packages/ui/src/testing/flow.ts
+++ b/packages/ui/src/testing/flow.ts
@@ -1,11 +1,14 @@
 export {
   branchFlowGraph,
+  branchRun,
+  branchRunOverlay,
   cyclicFlowGraph,
   flowGraphFromDoc,
   inputGateFlowGraph,
   reviewPullRequestsFlowGraph,
   syntheticDoc,
   syntheticFlowGraph,
+  triageFailedRun,
   triageFlowGraph,
   triageInboxFlowGraph,
   type SyntheticDocNode,

From 235a4c542e9a9559eeaf6c891e0e053873172ae3 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 13:23:11 +0200
Subject: [PATCH 27/78] feat(ui): animate relayouts and show runs and paths on
 WorkflowCanvas

A graph that changes on screen (same layoutKey) now glides to its new
layout: what leaves shrinks out at its old place (150 ms), what stays
moves on its node wrapper's transform (300 ms, out-quint), what joins
grows in after 150 ms and new or re-routed lines fade in last at
250 ms, settled in 450 ms. The canvas draws the graph its layout was
computed for until the next one lands, so nothing vanishes before it
can leave. A live refit eases with it; the open node is brought back
into view if it moved out. Nodes changed outside this tab (changed)
ring once after their relayout. A new layoutKey, the first layout and
reduced motion play none of it.

overlay and playback put a run on the chart: each node framed and
worded by its state (a running node's top bar sweeps, a failed one
gets a red edge and its error line), conditions show how they decided,
travelled lines take the emphasis colour, lines not taken step back, a
frame counts items or passes, and a dot rides each line a value is on
(a paused Web Animation set from the host's moment; none under reduced
motion). A failed run brings the way to its first failure forward;
strips say "The run stopped here" without an error line.

paths, highlight and onHighlightChange bring parts of the chart
forward: a pointer resting on a condition or a Yes/No label lights its
paths, a node under the pointer or the keyboard its own lines, and a
host highlight wins and is announced once. Outside a highlight boxes
are dashed on a muted surface with their reason in the strip and lines
thin to 1 px; colour and width never animate, two stacked lines
crossfade. The List view says the same: state glyphs, run words first,
quiet rows dashed with their reason.
---
 packages/ui/src/components/flow/describe.ts   |  91 ++-
 .../ui/src/components/flow/flow-canvas.tsx    |  22 +-
 .../flow/flow-step-list.browser.test.tsx      |  34 +-
 .../ui/src/components/flow/flow-step-list.tsx |  37 +-
 .../components/flow/layout/geometry.test.ts   |  37 ++
 .../ui/src/components/flow/layout/geometry.ts |  36 ++
 .../components/flow/layout/use-flow-layout.ts |  31 +-
 .../flow/motion/flow-motion.test.ts           |  48 ++
 .../src/components/flow/motion/flow-motion.ts |  69 +++
 .../flow/motion/use-layout-transition.test.ts | 200 ++++++
 .../flow/motion/use-layout-transition.ts      | 254 ++++++++
 .../src/components/flow/render/entry-node.tsx |   3 +-
 .../src/components/flow/render/exit-node.tsx  |   3 +-
 .../flow/render/flow-render-context.tsx       | 202 +++++-
 .../src/components/flow/render/gate-node.tsx  |  32 +-
 .../components/flow/render/group-frame.tsx    |  31 +-
 .../src/components/flow/render/looks.test.ts  | 146 +++++
 .../ui/src/components/flow/render/looks.ts    | 118 ++++
 .../components/flow/render/pulse-layer.tsx    | 168 +++++
 .../components/flow/render/routed-edge.tsx    | 139 ++++-
 .../src/components/flow/render/step-node.tsx  |  14 +-
 .../workflow-canvas.motion.browser.test.tsx   | 265 ++++++++
 .../flow/workflow-canvas.run.browser.test.tsx | 387 ++++++++++++
 .../src/components/flow/workflow-canvas.tsx   | 573 ++++++++++++++++--
 packages/ui/src/globals.css                   |  43 ++
 packages/ui/src/i18n/messages/de.yml          |   6 +
 packages/ui/src/i18n/messages/en.yml          |   6 +
 packages/ui/src/i18n/messages/fr.yml          |   6 +
 28 files changed, 2879 insertions(+), 122 deletions(-)
 create mode 100644 packages/ui/src/components/flow/motion/flow-motion.test.ts
 create mode 100644 packages/ui/src/components/flow/motion/flow-motion.ts
 create mode 100644 packages/ui/src/components/flow/motion/use-layout-transition.test.ts
 create mode 100644 packages/ui/src/components/flow/motion/use-layout-transition.ts
 create mode 100644 packages/ui/src/components/flow/render/looks.test.ts
 create mode 100644 packages/ui/src/components/flow/render/looks.ts
 create mode 100644 packages/ui/src/components/flow/render/pulse-layer.tsx
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx

diff --git a/packages/ui/src/components/flow/describe.ts b/packages/ui/src/components/flow/describe.ts
index 50ee8e8d58..970a849698 100644
--- a/packages/ui/src/components/flow/describe.ts
+++ b/packages/ui/src/components/flow/describe.ts
@@ -1,5 +1,7 @@
 import type { IssueCounts } from '../feedback/issue-summary';
 import { flowNodeIssueText } from './node-issue-marker';
+import { FLOW_NODE_STATE } from './node-status';
+import type { FlowFrameState, FlowNodeRunInfo } from './playback/types';
 import type { FlowEdge, FlowGraph, FlowNode, FlowRow } from './types';
 
 /** Translates a key of the `flow` namespace (or of `issues`, with `ns`). */
@@ -16,7 +18,8 @@ export interface FlowWords {
   /** The accessible description: where the node sits, what it comes from
    *  and leads to, when it runs, what it reads, and the host's sentences. */
   descriptions: ReadonlyMap<string, string>;
-  /** The line along a box's foot when no run is shown. */
+  /** The line along a box's foot: what it reads, or in a run how it
+   *  went, or why it steps back from a highlight. */
   strips: ReadonlyMap<string, string>;
   /** The title of a node as other sentences name it. */
   titles: ReadonlyMap<string, string>;
@@ -44,6 +47,51 @@ export function flowNodeTitle(node: FlowNode, t: FlowTranslate): string {
   return node.label;
 }
 
+/**
+ * A node's run in words: a condition's decision, Start's and End's own
+ * line, or a step's state (or the host's reason) and its detail — "Failed
+ * · 1.2 s", "Running · 12 of 50 items". The node the run stopped at says so
+ * when the host gave no error line.
+ */
+export function flowRunText(
+  node: FlowNode,
+  info: FlowNodeRunInfo,
+  t: FlowTranslate,
+  stoppedHere = false,
+): string {
+  const state =
+    info.state === 'idle' ? '' : t(FLOW_NODE_STATE[info.state].labelKey);
+  if (node.kind === 'gate')
+    return info.decision === undefined
+      ? state
+      : t(info.decision ? 'state.decidedYes' : 'state.decidedNo');
+  if (node.kind === 'entry' || node.kind === 'exit')
+    return info.detail ?? info.reason ?? state;
+  const words =
+    info.reason ??
+    (stoppedHere && info.state === 'failed' ? t('state.failedHere') : state);
+  const detail =
+    info.detail ??
+    (info.items?.total === undefined
+      ? undefined
+      : t('group.items', { done: info.items.done, total: info.items.total })) ??
+    (info.pass?.max === undefined
+      ? undefined
+      : t('group.pass', { pass: info.pass.current, max: info.pass.max }));
+  return detail === undefined || detail === '' ? words : `${words} · ${detail}`;
+}
+
+/** A node's state in one word for its name; a condition's decision. */
+function runName(
+  node: FlowNode,
+  info: FlowNodeRunInfo,
+  t: FlowTranslate,
+): string {
+  if (node.kind === 'gate' && info.decision !== undefined)
+    return t(info.decision ? 'state.decidedYes' : 'state.decidedNo');
+  return info.state === 'idle' ? '' : t(FLOW_NODE_STATE[info.state].labelKey);
+}
+
 function rowText(row: FlowRow, t: FlowTranslate): string {
   const detail = [row.detail, row.note, row.badge?.label]
     .filter(Boolean)
@@ -64,12 +112,22 @@ export function describeFlowGraph(
     tIssues,
     list,
     issues,
+    run,
+    stoppedAt,
+    reasons,
   }: {
     t: FlowTranslate;
     /** Reads the `issues` namespace (a node's problem counts). */
     tIssues: FlowTranslate;
     list: (items: readonly string[]) => string;
     issues?: ReadonlyMap<string, IssueCounts>;
+    /** A run shown on the chart: every node says how it went. */
+    run?: FlowFrameState | null;
+    /** The node the run stopped at, in focus: without an error line its
+     *  strip says the run stopped here. */
+    stoppedAt?: string | null;
+    /** Why a node steps back from a highlight, by id: its strip says so. */
+    reasons?: Readonly<Record<string, string>>;
   },
 ): FlowWords {
   const byId = new Map(graph.nodes.map((node) => [node.id, node]));
@@ -145,11 +203,24 @@ export function describeFlowGraph(
       issues?.get(node.id) ?? NO_ISSUES,
     );
     const title = titleOf(node.id);
-    const base =
+    const plain =
       node.kind === 'gate'
         ? t('gate.name', { node: node.label, condition: node.condition })
         : title;
+    const info = run?.nodes[node.id];
+    const stateName = info ? runName(node, info, t) : '';
+    const base =
+      stateName === ''
+        ? plain
+        : t('node.rowWithDetail', { label: plain, detail: stateName });
     names.set(node.id, issueText === '' ? base : `${base} ${issueText}`);
+    const runText = info
+      ? flowRunText(node, info, t, stoppedAt === node.id)
+      : '';
+    const reason = reasons?.[node.id];
+    // The run's words, or the highlight's reason, are said once more in the
+    // description only when they add something to the name's state word.
+    const extra = [runText === stateName ? '' : runText, reason ?? ''];
 
     const parts: (string | null | undefined)[] = [
       t('node.position', { index: index + 1, count }),
@@ -157,7 +228,8 @@ export function describeFlowGraph(
     let listLines: (string | null | undefined)[] = [];
     if (node.kind === 'step') {
       const reads = readsOf(node);
-      strips.set(node.id, reads);
+      strips.set(node.id, reason ?? (runText || reads));
+      parts.push(...extra);
       parts.push(
         comesFrom(node.id),
         ...conditions(node.id),
@@ -167,12 +239,15 @@ export function describeFlowGraph(
       if (node.unreachable) parts.push(t('node.unreachable'));
       parts.push(node.description);
       listLines = [
+        runText,
+        reason,
         reads,
         ...conditions(node.id),
         leadsTo(node.id),
         node.unreachable ? t('node.unreachable') : null,
       ];
     } else if (node.kind === 'gate') {
+      parts.push(...extra);
       const out = outgoing.get(node.id) ?? [];
       const yes = out.find((edge) => edge.kind === 'branch-yes');
       const no = out.find((edge) => edge.kind === 'branch-no');
@@ -188,8 +263,8 @@ export function describeFlowGraph(
       parts.push(node.description);
     } else if (node.kind === 'entry') {
       const leads = leadsTo(node.id);
-      strips.set(node.id, leads ?? '');
-      parts.push(leads);
+      strips.set(node.id, reason ?? (runText || (leads ?? '')));
+      parts.push(...extra, leads);
       parts.push(
         node.description ??
           [
@@ -207,6 +282,7 @@ export function describeFlowGraph(
             .join('. '),
       );
       listLines = [
+        runText,
         node.triggers.length > 0
           ? section(t('node.triggers'), node.triggers, '')
           : null,
@@ -219,8 +295,8 @@ export function describeFlowGraph(
       ];
     } else {
       const from = comesFrom(node.id);
-      strips.set(node.id, from ?? '');
-      parts.push(from);
+      strips.set(node.id, reason ?? (runText || (from ?? '')));
+      parts.push(...extra, from);
       const outcomes = node.outcomes ?? [];
       parts.push(
         node.description ??
@@ -240,6 +316,7 @@ export function describeFlowGraph(
             .join('. '),
       );
       listLines = [
+        runText,
         section(
           t('node.outputs'),
           node.outputs,
diff --git a/packages/ui/src/components/flow/flow-canvas.tsx b/packages/ui/src/components/flow/flow-canvas.tsx
index f106f53e95..8e314eea63 100644
--- a/packages/ui/src/components/flow/flow-canvas.tsx
+++ b/packages/ui/src/components/flow/flow-canvas.tsx
@@ -68,7 +68,8 @@ const TOP_MARGIN = 24;
  *    keeps the graph readable (zoom 0.5 or more), else shows its top at a
  *    readable zoom, centred on its first node.
  *  - `fitKey`           — refit when it changes, while the view is still
- *    where the last fit left it (the graph was laid out again).
+ *    where the last fit left it (the graph was laid out again), easing
+ *    over `refitDuration` (a live relayout glides; a new picture jumps).
  *
  * Viewport moves ease out (quint) over the duration tokens and jump under
  * reduced motion. Everything else spreads onto `<ReactFlow>` untouched;
@@ -89,6 +90,9 @@ export interface FlowCanvasProps extends ReactFlowProps {
   fitPolicy?: FlowFitPolicy;
   /** Refit when this changes, while the view is still the fit. */
   fitKey?: unknown;
+  /** How long a refit for a new `fitKey` eases, in ms (0 under reduced
+   *  motion). @default 0 */
+  refitDuration?: number;
 }
 
 /** The view the last fit left, or `null` while a fit is under way. */
@@ -194,11 +198,13 @@ function FlowAutoFit({
   fitViewOptions,
   policy,
   fitKey,
+  refitDuration = 0,
 }: {
   memo: FitMemo;
   fitViewOptions?: FitViewOptions;
   policy: FlowFitPolicy;
   fitKey: unknown;
+  refitDuration?: number;
 }) {
   const { getViewport, getNodes, getNodesBounds } = useReactFlow();
   const fitAndRemember = useFitAndRemember(memo, policy);
@@ -208,8 +214,13 @@ function FlowAutoFit({
   // Nodes, not "nodes initialized": a canvas that gives its nodes explicit
   // sizes has no handles to measure, and that flag never turns true for it.
   const hasNodes = useStore((state) => state.nodeLookup.size > 0);
+  // The key the last fit was for: a new one eases, a resize jumps.
+  const fittedKey = useRef<{ key: unknown } | null>(null);
   useEffect(() => {
     if (!hasNodes || !width || !height) return undefined;
+    const newKey =
+      fittedKey.current !== null && fittedKey.current.key !== fitKey;
+    fittedKey.current = { key: fitKey };
     // Moved since the last fit: the view is not the fit any more.
     const fitted = memo.current;
     if (fitted !== null && !sameView(getViewport(), fitted)) return undefined;
@@ -226,7 +237,11 @@ function FlowAutoFit({
         );
         if (zoom < (fitViewOptions?.minZoom ?? minZoom)) return;
       }
-      void fitAndRemember(fitViewOptions);
+      void fitAndRemember(
+        newKey
+          ? { ...fitViewOptions, duration: refitDuration }
+          : fitViewOptions,
+      );
     });
     return () => cancelAnimationFrame(frame);
   }, [
@@ -242,6 +257,7 @@ function FlowAutoFit({
     getNodesBounds,
     fitAndRemember,
     fitViewOptions,
+    refitDuration,
   ]);
   return null;
 }
@@ -339,6 +355,7 @@ export function FlowCanvas({
   topEndActions,
   fitPolicy = 'all',
   fitKey,
+  refitDuration,
   children,
   ...flowProps
 }: FlowCanvasProps) {
@@ -361,6 +378,7 @@ export function FlowCanvas({
           fitViewOptions={flowProps.fitViewOptions}
           policy={fitPolicy}
           fitKey={fitKey}
+          refitDuration={refitDuration}
         />
       )}
       {topStartActions && (
diff --git a/packages/ui/src/components/flow/flow-step-list.browser.test.tsx b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
index a5ab562f19..623f9986b6 100644
--- a/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
+++ b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
@@ -7,7 +7,13 @@ import { userEvent } from 'vitest/browser';
 import { render, screen, within } from '@/tests/utils/render';
 
 import { FlowStepList } from './flow-step-list';
-import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+import { highlightForNodes } from './paths/highlight';
+import { flowStateFromOverlay } from './playback/derive-state';
+import {
+  branchFlowGraph,
+  branchRunOverlay,
+  triageFlowGraph,
+} from './testing/flow-fixtures';
 import type { FlowGraph } from './types';
 
 import '../../globals.css';
@@ -122,6 +128,32 @@ describe('FlowStepList', () => {
     expect(screen.getByRole('list', { name: 'Nodes' })).toBeInTheDocument();
   });
 
+  it('says how each node went in a run, and why a row steps back', () => {
+    const graph = branchFlowGraph();
+    render(
+      <FlowStepList
+        graph={graph}
+        aria-label="Nodes"
+        run={flowStateFromOverlay(graph, branchRunOverlay())}
+        highlight={{
+          ...highlightForNodes(graph, ['fetch', 'merge']),
+          reasons: { notify: 'Not on this path' },
+        }}
+      />,
+    );
+    const fetch = screen.getByRole('button', { name: 'Fetch (Succeeded)' });
+    expect(fetch).toHaveAccessibleDescription(/^Succeeded · 390 ms/);
+    expect(within(fetch).getByRole('img', { name: 'Succeeded' })).toBeVisible();
+    const notify = screen.getByRole('button', { name: 'Notify (Failed)' });
+    expect(notify).toHaveAttribute('data-flow-quiet', 'true');
+    expect(notify).toHaveAccessibleDescription(
+      /^The mail server refused the message Not on this path Reads Merge/,
+    );
+    expect(
+      screen.getByRole('button', { name: 'Fetch (Succeeded)' }),
+    ).not.toHaveAttribute('data-flow-quiet');
+  });
+
   it('says so when there is nothing to list', () => {
     render(
       <FlowStepList graph={{ nodes: [], edges: [] }} aria-label="Nodes" />,
diff --git a/packages/ui/src/components/flow/flow-step-list.tsx b/packages/ui/src/components/flow/flow-step-list.tsx
index 5b3a06c638..3a4804fcd5 100644
--- a/packages/ui/src/components/flow/flow-step-list.tsx
+++ b/packages/ui/src/components/flow/flow-step-list.tsx
@@ -19,6 +19,9 @@ import {
   FlowNodeIssueMarker,
   flowNodeIssueFrameClass,
 } from './node-issue-marker';
+import { FlowNodeStatusIcon, type FlowNodeState } from './node-status';
+import type { FlowHighlight } from './paths/highlight';
+import type { FlowFrameState } from './playback/types';
 import type { FlowGraph, FlowGroup, FlowNode } from './types';
 
 export interface FlowStepListProps {
@@ -31,6 +34,12 @@ export interface FlowStepListProps {
   issues?: ReadonlyMap<string, IssueCounts>;
   /** The region a row's button opens (an inspector), if the host has one. */
   controlsId?: string;
+  /** A run shown with the list: each row says how its node went. */
+  run?: FlowFrameState | null;
+  /** A highlight: rows outside it step back and say why. */
+  highlight?: FlowHighlight | null;
+  /** The node a failed run stopped at, in focus. */
+  stoppedAt?: string | null;
   className?: string;
 }
 
@@ -73,6 +82,9 @@ function iconOf(node: FlowNode) {
  * reads, when it runs (its condition folded in) and where it leads; members
  * of a frame sit indented under the frame's words. One Tab stop: ↑ and ↓
  * move between rows, Home and End jump, Enter or Space opens a row.
+ *
+ * With a run, each row carries its node's state glyph and says how it went
+ * first; with a highlight, a row outside it is dashed and says why.
  */
 export function FlowStepList({
   graph,
@@ -81,6 +93,9 @@ export function FlowStepList({
   onSelect,
   issues,
   controlsId,
+  run = null,
+  highlight = null,
+  stoppedAt = null,
   className,
 }: FlowStepListProps) {
   const { t } = useT('flow');
@@ -88,6 +103,14 @@ export function FlowStepList({
   const { i18n } = useTranslation();
   const locale = i18n?.resolvedLanguage ?? i18n?.language ?? 'en';
   const baseId = useId();
+  const quietRest = highlight !== null && highlight.quietRest !== false;
+  const reasons = useMemo(() => {
+    if (!quietRest || highlight?.reasons === undefined) return undefined;
+    const quiet: Record<string, string> = {};
+    for (const [id, reason] of Object.entries(highlight.reasons))
+      if (!highlight.nodes.has(id)) quiet[id] = reason;
+    return quiet;
+  }, [highlight, quietRest]);
   const words = useMemo(
     () =>
       describeFlowGraph(graph, {
@@ -95,8 +118,11 @@ export function FlowStepList({
         tIssues,
         list: flowListFormat(locale),
         issues,
+        run,
+        stoppedAt,
+        reasons,
       }),
-    [graph, t, tIssues, locale, issues],
+    [graph, t, tIssues, locale, issues, run, stoppedAt, reasons],
   );
   const items = useMemo(() => itemsOf(graph), [graph]);
   const order = useMemo(
@@ -153,6 +179,8 @@ export function FlowStepList({
       selected={selectedId === node.id}
       tabbable={tabStop === node.id}
       counts={issues?.get(node.id) ?? NO_ISSUES}
+      state={run?.nodes[node.id]?.state ?? 'idle'}
+      quiet={quietRest && !highlight?.nodes.has(node.id)}
       controlsId={controlsId}
       onActivate={() => onSelect?.(selectedId === node.id ? null : node.id)}
       onKeyDown={(event) => move(node.id, event)}
@@ -196,6 +224,8 @@ function FlowListRow({
   selected,
   tabbable,
   counts,
+  state,
+  quiet,
   controlsId,
   onActivate,
   onKeyDown,
@@ -207,6 +237,8 @@ function FlowListRow({
   selected: boolean;
   tabbable: boolean;
   counts: IssueCounts;
+  state: FlowNodeState;
+  quiet: boolean;
   controlsId?: string;
   onActivate: () => void;
   onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
@@ -230,8 +262,10 @@ function FlowListRow({
         onClick={onActivate}
         onKeyDown={onKeyDown}
         onFocus={onFocus}
+        data-flow-quiet={quiet || undefined}
         className={cn(
           'hover:bg-muted/60 flex min-h-9 w-full cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-1.5 text-left',
+          quiet && 'border-border border-dashed',
           'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none',
           flowNodeIssueFrameClass(counts),
           selected && 'bg-muted ring-ring ring-2',
@@ -254,6 +288,7 @@ function FlowListRow({
           errors={counts.errors}
           warnings={counts.warnings}
         />
+        <FlowNodeStatusIcon state={state} />
       </button>
       {lines.length > 0 && (
         <span
diff --git a/packages/ui/src/components/flow/layout/geometry.test.ts b/packages/ui/src/components/flow/layout/geometry.test.ts
index 9f4ab8cf4a..f26cd37098 100644
--- a/packages/ui/src/components/flow/layout/geometry.test.ts
+++ b/packages/ui/src/components/flow/layout/geometry.test.ts
@@ -8,6 +8,7 @@ import {
   joinSections,
   rectsOverlap,
   roundedOrthogonalPath,
+  sampleRoute,
   segmentCrossesRect,
   trimEnd,
 } from './geometry';
@@ -186,3 +187,39 @@ describe('rectangles', () => {
     ).toEqual({ x: -5, y: 0, width: 15, height: 15 });
   });
 });
+
+describe('sampleRoute', () => {
+  it('walks the route at an even step, both ends included', () => {
+    const samples = sampleRoute(
+      [
+        { x: 0, y: 0 },
+        { x: 0, y: 16 },
+        { x: 20, y: 16 },
+      ],
+      8,
+    );
+    expect(samples.map(({ x, y }) => [x, y])).toEqual([
+      [0, 0],
+      [0, 8],
+      [0, 16],
+      [8, 16],
+      [16, 16],
+      [20, 16],
+    ]);
+    expect(samples.map((sample) => sample.offset)).toEqual([
+      0,
+      8 / 36,
+      16 / 36,
+      24 / 36,
+      32 / 36,
+      1,
+    ]);
+  });
+
+  it('gives a point route its one point', () => {
+    expect(sampleRoute([{ x: 3, y: 4 }], 8)).toEqual([
+      { x: 3, y: 4, offset: 0 },
+    ]);
+    expect(sampleRoute([], 8)).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/components/flow/layout/geometry.ts b/packages/ui/src/components/flow/layout/geometry.ts
index 23caebc8d5..efd61ebd01 100644
--- a/packages/ui/src/components/flow/layout/geometry.ts
+++ b/packages/ui/src/components/flow/layout/geometry.ts
@@ -159,6 +159,42 @@ export function trimEnd(
   return out;
 }
 
+/**
+ * Points every `step` px along a route, its two ends included, each with
+ * how far along the route it lies (0–1) — keyframes for something that
+ * travels the route at an even speed.
+ */
+export function sampleRoute(
+  points: readonly FlowPoint[],
+  step: number,
+): Array<FlowPoint & { offset: number }> {
+  const first = points[0];
+  if (first === undefined) return [];
+  let total = 0;
+  for (let index = 1; index < points.length; index++)
+    total += distance(points[index - 1], points[index]);
+  if (total === 0 || step <= 0) return [{ ...first, offset: 0 }];
+  const out: Array<FlowPoint & { offset: number }> = [];
+  let walked = 0;
+  for (let index = 1; index < points.length; index++) {
+    const from = points[index - 1];
+    const to = points[index];
+    const run = distance(from, to);
+    for (let along = 0; along < run; along += step) {
+      const ratio = along / run;
+      out.push({
+        x: from.x + (to.x - from.x) * ratio,
+        y: from.y + (to.y - from.y) * ratio,
+        offset: (walked + along) / total,
+      });
+    }
+    walked += run;
+  }
+  const last = points[points.length - 1];
+  out.push({ x: last.x, y: last.y, offset: 1 });
+  return out;
+}
+
 const fmt = (value: number) => String(Math.round(value * 100) / 100);
 
 /**
diff --git a/packages/ui/src/components/flow/layout/use-flow-layout.ts b/packages/ui/src/components/flow/layout/use-flow-layout.ts
index 524eac9721..7a22732f19 100644
--- a/packages/ui/src/components/flow/layout/use-flow-layout.ts
+++ b/packages/ui/src/components/flow/layout/use-flow-layout.ts
@@ -34,6 +34,12 @@ export interface UseFlowLayoutResult {
   /** The layout before it, while the same picture changed — what a
    *  transition moves from. */
   previous: FlowLayout | null;
+  /** The graph `layout` was computed for: while a relayout is under way
+   *  it is the one before the newest, so what is drawn matches where it
+   *  is drawn. */
+  graph: FlowGraph | null;
+  /** The layout is the newest graph's (no relayout under way). */
+  settled: boolean;
   /** `failed` when the engine could not run and the graph stands in one
    *  column. */
   status: FlowLayoutStatus;
@@ -59,7 +65,8 @@ export function useFlowLayout(
     key: string | null;
     layout: FlowLayout | null;
     previous: FlowLayout | null;
-  }>({ key: null, layout: null, previous: null });
+    graph: FlowGraph | null;
+  }>({ key: null, layout: null, previous: null, graph: null });
   const [fontsLoaded, setFontsLoaded] = useState(false);
 
   useEffect(() => {
@@ -101,7 +108,12 @@ export function useFlowLayout(
     if (!samePicture) {
       const cached = flowLayoutCache.get(signature);
       if (cached) {
-        setState({ key: layoutKey, layout: cached, previous: null });
+        setState({
+          key: layoutKey,
+          layout: cached,
+          previous: null,
+          graph: latest.current.graph,
+        });
         return undefined;
       }
     }
@@ -121,6 +133,7 @@ export function useFlowLayout(
           key: layoutKey,
           layout,
           previous: samePicture ? before.layout : null,
+          graph: current,
         });
       },
       (error: unknown) => {
@@ -133,15 +146,15 @@ export function useFlowLayout(
 
   // A picture this session already laid out shows at once, without a
   // pending frame between two versions.
-  const current =
-    state.key === layoutKey
-      ? state.layout
-      : fontsLoaded
-        ? (flowLayoutCache.peek(signature) ?? null)
-        : null;
+  const ownState = state.key === layoutKey;
+  const peeked =
+    !ownState && fontsLoaded ? (flowLayoutCache.peek(signature) ?? null) : null;
+  const current = ownState ? state.layout : peeked;
   return {
     layout: current,
-    previous: state.key === layoutKey ? state.previous : null,
+    previous: ownState ? state.previous : null,
+    graph: ownState ? state.graph : peeked === null ? null : graph,
+    settled: current !== null && current.signature === signature,
     status:
       current === null
         ? 'pending'
diff --git a/packages/ui/src/components/flow/motion/flow-motion.test.ts b/packages/ui/src/components/flow/motion/flow-motion.test.ts
new file mode 100644
index 0000000000..caa0e432a7
--- /dev/null
+++ b/packages/ui/src/components/flow/motion/flow-motion.test.ts
@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { easeOutQuint, FLOW_VIEWPORT_DURATION } from '../flow-canvas';
+import {
+  FLOW_DURATION,
+  FLOW_EASE_OUT_QUINT,
+  FLOW_MOTION_CLASS,
+} from './flow-motion';
+
+const css = readFileSync(
+  join(__dirname, '..', '..', '..', 'globals.css'),
+  'utf8',
+);
+
+/** A token's value as the stylesheet declares it. */
+function token(name: string): string {
+  const match = new RegExp(`--${name}:\\s*([^;]+);`).exec(css);
+  if (match === null) throw new Error(`no --${name} in globals.css`);
+  return (match[1] ?? '').trim();
+}
+
+describe('flow motion', () => {
+  it('times script motion by the stylesheet’s duration tokens', () => {
+    for (const [name, ms] of Object.entries(FLOW_DURATION))
+      expect(token(`duration-${name}`), name).toBe(`${ms}ms`);
+    expect(token('ease-out-quint')).toBe(FLOW_EASE_OUT_QUINT);
+    // The viewport's moves are the same tokens.
+    expect(FLOW_VIEWPORT_DURATION.zoom).toBe(FLOW_DURATION.short);
+    expect(FLOW_VIEWPORT_DURATION.reveal).toBe(FLOW_DURATION.standard);
+    expect(FLOW_VIEWPORT_DURATION.fit).toBe(FLOW_DURATION.medium);
+    // The script ease ends where the curve does.
+    expect(easeOutQuint(0)).toBe(0);
+    expect(easeOutQuint(1)).toBe(1);
+  });
+
+  it('names only keyframes the stylesheet defines', () => {
+    for (const [name, className] of Object.entries(FLOW_MOTION_CLASS)) {
+      const keyframes = /animate-\[([a-z-]+)_/.exec(className)?.[1];
+      expect(keyframes, name).toBeDefined();
+      expect(css, `${name}: @keyframes ${keyframes}`).toContain(
+        `@keyframes ${keyframes} {`,
+      );
+    }
+  });
+});
diff --git a/packages/ui/src/components/flow/motion/flow-motion.ts b/packages/ui/src/components/flow/motion/flow-motion.ts
new file mode 100644
index 0000000000..d8f86668fa
--- /dev/null
+++ b/packages/ui/src/components/flow/motion/flow-motion.ts
@@ -0,0 +1,69 @@
+/**
+ * The workflow canvas's motion, in one place: the duration and ease tokens
+ * of `globals.css` (a test holds the numbers to the stylesheet) and the
+ * animation classes a live relayout puts on what enters, leaves and moves.
+ *
+ * A relayout plays in three beats: what leaves fades out (short), what
+ * stays glides to its new place (medium), what joins fades in once the
+ * glide is under way (standard, after short) and new lines last, once the
+ * boxes are nearly there (standard, after 250 ms) — so no line is ever
+ * drawn against a box still moving. Everything settles in 450 ms. Under
+ * reduced motion none of it runs: the new picture is simply there.
+ */
+
+/** The `--duration-*` tokens, in milliseconds. */
+export const FLOW_DURATION = {
+  micro: 100,
+  short: 150,
+  standard: 200,
+  medium: 300,
+  long: 400,
+} as const;
+
+/** The `--ease-out-quint` token, for motion run from script. */
+export const FLOW_EASE_OUT_QUINT = 'cubic-bezier(0.22, 1, 0.36, 1)';
+
+/** When new lines start fading in after a relayout. */
+export const FLOW_EDGE_ENTER_DELAY = 250;
+
+/** When a relayout's geometry has settled: the last line is in. */
+export const FLOW_RELAYOUT_SETTLE =
+  FLOW_EDGE_ENTER_DELAY + FLOW_DURATION.standard;
+
+/** How long a changed node's ring shows: visible through the glide, then
+ *  fading over `long`. */
+export const FLOW_RING_DELAY = FLOW_DURATION.medium;
+export const FLOW_RING_TOTAL = FLOW_RING_DELAY + FLOW_DURATION.long;
+
+/** The move of a relayout, on React Flow's node wrapper (which positions
+ *  each node with a `transform`). */
+export const FLOW_MOVE_TRANSITION =
+  'transform var(--duration-medium) var(--ease-out-quint)';
+
+/** The animation classes of each part of a relayout. */
+export const FLOW_MOTION_CLASS = {
+  /** A node or condition that joins: grows in from the exit scale. */
+  enter:
+    'animate-[flow-enter_var(--duration-standard)_var(--ease-out-quint)_var(--duration-short)_backwards]',
+  /** A node or condition that leaves: shrinks to the exit scale. */
+  exit: 'animate-[flow-exit_var(--duration-short)_var(--ease-out-quint)_forwards]',
+  /** A new or re-routed line, a resized frame: fades in last. */
+  fadeIn:
+    'animate-[fade-in_var(--duration-standard)_var(--ease-out-quint)_250ms_backwards]',
+  /** A line that is gone or re-routed, a frame that changed size. */
+  fadeOut:
+    'animate-[flow-fade-out_var(--duration-short)_var(--ease-out-quint)_forwards]',
+  /** A changed node's ring: shows through the glide, then fades. */
+  ring: 'animate-[flow-ring-out_var(--duration-long)_var(--ease-default)_var(--duration-medium)_backwards]',
+  /** A running node's top bar. */
+  sweep: 'animate-[flow-running-sweep_1.2s_linear_infinite]',
+} as const;
+
+/** A strip whose words change while a run plays: a soft settle. */
+export const FLOW_STRIP_SETTLE: {
+  keyframes: Keyframe[];
+  options: KeyframeAnimationOptions;
+} = {
+  keyframes: [{ opacity: 0.35 }, { opacity: 1 }],
+  options: { duration: FLOW_DURATION.short, easing: FLOW_EASE_OUT_QUINT },
+};
diff --git a/packages/ui/src/components/flow/motion/use-layout-transition.test.ts b/packages/ui/src/components/flow/motion/use-layout-transition.test.ts
new file mode 100644
index 0000000000..48500e1d8d
--- /dev/null
+++ b/packages/ui/src/components/flow/motion/use-layout-transition.test.ts
@@ -0,0 +1,200 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { FlowGraph, FlowLayout, FlowRect } from '../types';
+import { FLOW_DURATION, FLOW_RELAYOUT_SETTLE } from './flow-motion';
+import {
+  planFlowTransition,
+  useLayoutTransition,
+  type FlowPicture,
+} from './use-layout-transition';
+
+const rect = (x: number, y: number, width = 288, height = 88): FlowRect => ({
+  x,
+  y,
+  width,
+  height,
+});
+
+/** A three-node chain a → b → c, framed b, laid out by hand. */
+function before(): FlowPicture {
+  const graph: FlowGraph = {
+    nodes: [
+      { id: 'a', kind: 'step', label: 'A' },
+      { id: 'b', kind: 'step', label: 'B' },
+      { id: 'c', kind: 'step', label: 'C' },
+    ],
+    edges: [
+      { id: 'a>b', source: 'a', target: 'b', kind: 'data' },
+      { id: 'b>c', source: 'b', target: 'c', kind: 'data' },
+      {
+        id: 'hidden',
+        source: 'a',
+        target: 'c',
+        kind: 'order',
+        layoutOnly: true,
+      },
+    ],
+    groups: [{ id: 'each:b', kind: 'each', label: 'For each', members: ['b'] }],
+  };
+  const layout: FlowLayout = {
+    signature: 'before',
+    nodes: { a: rect(0, 0), b: rect(0, 160), c: rect(0, 320) },
+    groups: {
+      'each:b': { ...rect(-16, 120, 320, 140), header: rect(0, 124, 120, 24) },
+    },
+    edges: {
+      'a>b': {
+        points: [
+          { x: 144, y: 88 },
+          { x: 144, y: 160 },
+        ],
+      },
+      'b>c': {
+        points: [
+          { x: 144, y: 248 },
+          { x: 144, y: 320 },
+        ],
+      },
+    },
+    bounds: rect(-16, 0, 320, 408),
+    rows: [['a'], ['b'], ['c']],
+    engine: 'main',
+    ms: 1,
+  };
+  return { graph, layout };
+}
+
+/** The chain after an edit: c removed, d added beside b, a → b unchanged,
+ *  b's frame taller. */
+function after(): FlowPicture {
+  const graph: FlowGraph = {
+    nodes: [
+      { id: 'a', kind: 'step', label: 'A' },
+      { id: 'b', kind: 'step', label: 'B' },
+      { id: 'd', kind: 'step', label: 'D' },
+    ],
+    edges: [
+      { id: 'a>b', source: 'a', target: 'b', kind: 'data' },
+      { id: 'a>d', source: 'a', target: 'd', kind: 'data' },
+    ],
+    groups: [{ id: 'each:b', kind: 'each', label: 'For each', members: ['b'] }],
+  };
+  const layout: FlowLayout = {
+    signature: 'after',
+    nodes: { a: rect(0, 0), b: rect(0, 160, 288, 108), d: rect(336, 160) },
+    groups: {
+      'each:b': { ...rect(-16, 120, 320, 160), header: rect(0, 124, 120, 24) },
+    },
+    edges: {
+      'a>b': {
+        points: [
+          { x: 144, y: 88 },
+          { x: 144, y: 160 },
+        ],
+      },
+      'a>d': {
+        points: [
+          { x: 200, y: 88 },
+          { x: 200, y: 120 },
+          { x: 480, y: 120 },
+          { x: 480, y: 160 },
+        ],
+      },
+    },
+    bounds: rect(-16, 0, 640, 268),
+    rows: [['a'], ['b', 'd']],
+    engine: 'main',
+    ms: 1,
+  };
+  return { graph, layout };
+}
+
+describe('planFlowTransition', () => {
+  it('moves what stays, grows in what joins and keeps what leaves at its old place', () => {
+    const plan = planFlowTransition(before(), after());
+    expect([...plan.moving].sort()).toEqual(['a', 'b']);
+    expect([...plan.entering]).toEqual(['d']);
+    expect(plan.leaving.map(({ node }) => node.id)).toEqual(['c']);
+    expect(plan.leaving[0]?.rect).toEqual(rect(0, 320));
+  });
+
+  it('crossfades a frame that changed size, glides one that did not', () => {
+    const plan = planFlowTransition(before(), after());
+    expect([...plan.framesEntering]).toEqual(['each:b']);
+    expect(plan.framesLeaving.map(({ rect: box }) => box.height)).toEqual([
+      140,
+    ]);
+    const same = planFlowTransition(before(), {
+      ...before(),
+      layout: { ...before().layout, signature: 'moved' },
+    });
+    expect([...same.framesMoving]).toEqual(['each:b']);
+    expect(same.framesLeaving).toEqual([]);
+  });
+
+  it('fades lines out and in only when they are new, gone or re-routed', () => {
+    const plan = planFlowTransition(before(), after());
+    // a → b kept its route: it stays as it is.
+    expect(plan.edgesEntering.has('a>b')).toBe(false);
+    expect(plan.edgesEntering.has('a>d')).toBe(true);
+    expect(plan.edgesLeaving.map(({ edge }) => edge.id)).toEqual(['b>c']);
+    expect(plan.edgesLeaving[0]?.points).toEqual(
+      before().layout.edges['b>c']?.points,
+    );
+    // A layout-only line is never drawn, so it never fades.
+    expect(plan.edgesLeaving.some(({ edge }) => edge.layoutOnly)).toBe(false);
+  });
+});
+
+describe('useLayoutTransition', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('plans a live relayout, ends the exits after short and settles after 450 ms', () => {
+    const first = before();
+    const second = after();
+    const { result, rerender } = renderHook(
+      ({ picture, layoutKey }) =>
+        useLayoutTransition({ picture, layoutKey, enabled: true }),
+      { initialProps: { picture: first, layoutKey: 'doc' } },
+    );
+    expect(result.current.plan).toBeNull();
+    rerender({ picture: second, layoutKey: 'doc' });
+    expect(result.current.phase).toBe('exit');
+    expect(result.current.plan?.entering.has('d')).toBe(true);
+    act(() => {
+      vi.advanceTimersByTime(FLOW_DURATION.short);
+    });
+    expect(result.current.phase).toBe('settle');
+    act(() => {
+      vi.advanceTimersByTime(FLOW_RELAYOUT_SETTLE - FLOW_DURATION.short);
+    });
+    expect(result.current.plan).toBeNull();
+    expect(result.current.phase).toBeNull();
+  });
+
+  it('plays nothing for a new picture, the first layout or reduced motion', () => {
+    const { result, rerender } = renderHook(
+      ({ picture, layoutKey, enabled }) =>
+        useLayoutTransition({ picture, layoutKey, enabled }),
+      {
+        initialProps: {
+          picture: null as FlowPicture | null,
+          layoutKey: 'doc',
+          enabled: true,
+        },
+      },
+    );
+    rerender({ picture: before(), layoutKey: 'doc', enabled: true });
+    expect(result.current.plan).toBeNull();
+    rerender({ picture: after(), layoutKey: 'v2', enabled: true });
+    expect(result.current.plan).toBeNull();
+    rerender({ picture: before(), layoutKey: 'v2', enabled: false });
+    expect(result.current.plan).toBeNull();
+  });
+});
diff --git a/packages/ui/src/components/flow/motion/use-layout-transition.ts b/packages/ui/src/components/flow/motion/use-layout-transition.ts
new file mode 100644
index 0000000000..a8f5521a31
--- /dev/null
+++ b/packages/ui/src/components/flow/motion/use-layout-transition.ts
@@ -0,0 +1,254 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import type {
+  FlowEdge,
+  FlowGraph,
+  FlowGroup,
+  FlowLayout,
+  FlowNode,
+  FlowPoint,
+  FlowRect,
+} from '../types';
+import { FLOW_DURATION, FLOW_RELAYOUT_SETTLE } from './flow-motion';
+
+/** A chart on screen: a graph and the layout it is drawn at. */
+export interface FlowPicture {
+  graph: FlowGraph;
+  layout: FlowLayout;
+}
+
+/** A line that leaves with a relayout, drawn along its old route. */
+export interface FlowLeavingEdge {
+  edge: FlowEdge;
+  points: readonly FlowPoint[];
+  label?: FlowRect;
+}
+
+/**
+ * What a live relayout does to each part of the chart, worked out from the
+ * picture before and the picture after. Pure, so the choreography is
+ * tested without a browser.
+ */
+export interface FlowTransitionPlan {
+  /** Nodes on both pictures: they glide to their new place. */
+  moving: ReadonlySet<string>;
+  /** Nodes only on the new picture: they grow in. */
+  entering: ReadonlySet<string>;
+  /** Nodes only on the old picture, at their old place: they shrink out. */
+  leaving: ReadonlyArray<{ node: FlowNode; rect: FlowRect }>;
+  /** Frames on both pictures at the same size: they glide. */
+  framesMoving: ReadonlySet<string>;
+  /** Frames that are new or changed size: they fade in. */
+  framesEntering: ReadonlySet<string>;
+  /** Frames that are gone, or the old box of one that changed size. */
+  framesLeaving: ReadonlyArray<{
+    group: FlowGroup;
+    rect: FlowRect & { header: FlowRect };
+  }>;
+  /** Lines that are new or took another route: they fade in last. */
+  edgesEntering: ReadonlySet<string>;
+  /** Lines that are gone or took another route, along the old route. */
+  edgesLeaving: readonly FlowLeavingEdge[];
+}
+
+const samePoints = (
+  a: readonly FlowPoint[] | undefined,
+  b: readonly FlowPoint[] | undefined,
+) =>
+  a !== undefined &&
+  b !== undefined &&
+  a.length === b.length &&
+  a.every((point, index) => {
+    const other = b[index];
+    return other !== undefined && point.x === other.x && point.y === other.y;
+  });
+
+const sameSize = (a: FlowRect, b: FlowRect) =>
+  a.width === b.width && a.height === b.height;
+
+/** Which parts of the chart enter, leave or move between two pictures. */
+export function planFlowTransition(
+  from: FlowPicture,
+  to: FlowPicture,
+): FlowTransitionPlan {
+  const before = new Map(from.graph.nodes.map((node) => [node.id, node]));
+  const after = new Set(to.graph.nodes.map((node) => node.id));
+  const moving = new Set<string>();
+  const entering = new Set<string>();
+  for (const node of to.graph.nodes) {
+    if (to.layout.nodes[node.id] === undefined) continue;
+    if (before.has(node.id) && from.layout.nodes[node.id] !== undefined)
+      moving.add(node.id);
+    else entering.add(node.id);
+  }
+  const leaving: Array<{ node: FlowNode; rect: FlowRect }> = [];
+  for (const node of from.graph.nodes) {
+    const rect = from.layout.nodes[node.id];
+    if (!after.has(node.id) && rect !== undefined) leaving.push({ node, rect });
+  }
+
+  const groupsBefore = new Map(
+    (from.graph.groups ?? []).map((group) => [group.id, group]),
+  );
+  const groupsAfter = new Set((to.graph.groups ?? []).map((group) => group.id));
+  const framesMoving = new Set<string>();
+  const framesEntering = new Set<string>();
+  const framesLeaving: Array<{
+    group: FlowGroup;
+    rect: FlowRect & { header: FlowRect };
+  }> = [];
+  for (const group of to.graph.groups ?? []) {
+    const rect = to.layout.groups[group.id];
+    if (rect === undefined) continue;
+    const old = from.layout.groups[group.id];
+    const was = groupsBefore.get(group.id);
+    if (old !== undefined && was !== undefined && sameSize(old, rect))
+      framesMoving.add(group.id);
+    else {
+      framesEntering.add(group.id);
+      if (old !== undefined && was !== undefined)
+        framesLeaving.push({ group: was, rect: old });
+    }
+  }
+  for (const group of from.graph.groups ?? []) {
+    const rect = from.layout.groups[group.id];
+    if (!groupsAfter.has(group.id) && rect !== undefined)
+      framesLeaving.push({ group, rect });
+  }
+
+  const edgesBefore = new Map(
+    from.graph.edges
+      .filter((edge) => !edge.layoutOnly)
+      .map((edge) => [edge.id, edge]),
+  );
+  const edgesEntering = new Set<string>();
+  const edgesLeaving: FlowLeavingEdge[] = [];
+  const drawnAfter = new Set<string>();
+  for (const edge of to.graph.edges) {
+    if (edge.layoutOnly) continue;
+    const route = to.layout.edges[edge.id];
+    if (route === undefined) continue;
+    drawnAfter.add(edge.id);
+    const old = from.layout.edges[edge.id];
+    const was = edgesBefore.get(edge.id);
+    if (was !== undefined && samePoints(old?.points, route.points)) continue;
+    edgesEntering.add(edge.id);
+    if (was !== undefined && old !== undefined)
+      edgesLeaving.push({
+        edge: was,
+        points: old.points,
+        ...(old.label ? { label: old.label } : {}),
+      });
+  }
+  for (const [id, edge] of edgesBefore) {
+    const old = from.layout.edges[id];
+    if (drawnAfter.has(id) || old === undefined) continue;
+    edgesLeaving.push({
+      edge,
+      points: old.points,
+      ...(old.label ? { label: old.label } : {}),
+    });
+  }
+
+  return {
+    moving,
+    entering,
+    leaving,
+    framesMoving,
+    framesEntering,
+    framesLeaving,
+    edgesEntering,
+    edgesLeaving,
+  };
+}
+
+/** Where a relayout is: leaving parts still on screen, or only the glide
+ *  and the last fades left. */
+export type FlowTransitionPhase = 'exit' | 'settle';
+
+interface TransitionState {
+  picture: FlowPicture | null;
+  key: string;
+  plan: FlowTransitionPlan | null;
+  phase: FlowTransitionPhase | null;
+}
+
+/**
+ * Plays a live relayout: when the same picture (`layoutKey`) gets a new
+ * layout, it plans what enters, leaves and moves, keeps the leaving parts
+ * on screen for their exit (`short`), and holds the plan until the
+ * geometry has settled (450 ms) — then the chart is plain again. A new
+ * `layoutKey`, the first layout, or `enabled: false` (reduced motion)
+ * plays nothing. A relayout that lands mid-transition starts from where
+ * things are: CSS transitions retarget from the current transforms.
+ */
+export function useLayoutTransition({
+  picture,
+  layoutKey,
+  enabled,
+}: {
+  picture: FlowPicture | null;
+  layoutKey: string;
+  enabled: boolean;
+}): { plan: FlowTransitionPlan | null; phase: FlowTransitionPhase | null } {
+  const [state, setState] = useState<TransitionState>({
+    picture,
+    key: layoutKey,
+    plan: null,
+    phase: null,
+  });
+
+  // A new layout on screen: plan its transition while rendering it, so the
+  // first frame of the new picture already carries every class it needs.
+  let current = state;
+  if (state.picture?.layout !== picture?.layout) {
+    const live =
+      enabled &&
+      state.picture !== null &&
+      picture !== null &&
+      state.key === layoutKey;
+    const plan =
+      live && state.picture !== null && picture !== null
+        ? planFlowTransition(state.picture, picture)
+        : null;
+    current = {
+      picture,
+      key: layoutKey,
+      plan,
+      phase: plan === null ? null : 'exit',
+    };
+    setState(current);
+  } else if (state.key !== layoutKey) {
+    // Another picture that happens to share the layout: nothing plays, and
+    // the next change of this picture is a live one.
+    current = { picture, key: layoutKey, plan: null, phase: null };
+    setState(current);
+  }
+
+  const { plan } = current;
+  useEffect(() => {
+    if (plan === null) return undefined;
+    const exit = setTimeout(
+      () =>
+        setState((now) =>
+          now.plan === plan ? { ...now, phase: 'settle' } : now,
+        ),
+      FLOW_DURATION.short,
+    );
+    const settle = setTimeout(
+      () =>
+        setState((now) =>
+          now.plan === plan ? { ...now, plan: null, phase: null } : now,
+        ),
+      FLOW_RELAYOUT_SETTLE,
+    );
+    return () => {
+      clearTimeout(exit);
+      clearTimeout(settle);
+    };
+  }, [plan]);
+
+  return { plan: current.plan, phase: current.phase };
+}
diff --git a/packages/ui/src/components/flow/render/entry-node.tsx b/packages/ui/src/components/flow/render/entry-node.tsx
index 0cce3d6fe9..0e49cd0e9d 100644
--- a/packages/ui/src/components/flow/render/entry-node.tsx
+++ b/packages/ui/src/components/flow/render/entry-node.tsx
@@ -130,10 +130,11 @@ export const FlowEntryNodeView = memo(function FlowEntryNodeView({
   data,
 }: NodeProps & { data: FlowNodeData<FlowEntryNode> }) {
   const { t } = useT('flow');
-  const { node } = data;
+  const { node, phase } = data;
   return (
     <FlowNodeButton
       id={node.id}
+      phase={phase}
       className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
     >
       <span className="flex min-h-0 flex-1 flex-col px-3 pt-3">
diff --git a/packages/ui/src/components/flow/render/exit-node.tsx b/packages/ui/src/components/flow/render/exit-node.tsx
index 5acf6e7cf8..879ed53672 100644
--- a/packages/ui/src/components/flow/render/exit-node.tsx
+++ b/packages/ui/src/components/flow/render/exit-node.tsx
@@ -21,11 +21,12 @@ export const FlowExitNodeView = memo(function FlowExitNodeView({
   data,
 }: NodeProps & { data: FlowNodeData<FlowExitNode> }) {
   const { t } = useT('flow');
-  const { node } = data;
+  const { node, phase } = data;
   const outcomes = node.outcomes ?? [];
   return (
     <FlowNodeButton
       id={node.id}
+      phase={phase}
       className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
     >
       <span className="flex min-h-0 flex-1 flex-col px-3 pt-3">
diff --git a/packages/ui/src/components/flow/render/flow-render-context.tsx b/packages/ui/src/components/flow/render/flow-render-context.tsx
index 4be6929e20..1134c4632d 100644
--- a/packages/ui/src/components/flow/render/flow-render-context.tsx
+++ b/packages/ui/src/components/flow/render/flow-render-context.tsx
@@ -4,15 +4,43 @@ import { Handle, Position } from '@xyflow/react';
 import {
   createContext,
   useContext,
+  useLayoutEffect,
+  useRef,
   type FocusEvent,
   type KeyboardEvent,
   type ReactNode,
 } from 'react';
 
 import { cn } from '../../../lib/cn';
+import { ISSUE_SEVERITY_FRAME_CLASS } from '../../feedback/issue-severity';
 import type { IssueCounts } from '../../feedback/issue-summary';
 import { Tooltip } from '../../overlays/tooltip';
+import { FLOW_MOTION_CLASS, FLOW_STRIP_SETTLE } from '../motion/flow-motion';
 import { flowNodeIssueFrameClass } from '../node-issue-marker';
+import type { FlowNodeState } from '../node-status';
+
+/** How a box looks right now: its run state, and where it stands in a
+ *  highlight. */
+export interface FlowNodeLook {
+  /** `idle` while no run is shown. */
+  state: FlowNodeState;
+  /** A condition's decision in the run shown. */
+  decision?: boolean;
+  /** Outside the highlight: dashed, on a muted surface, never faded. */
+  quiet: boolean;
+  /** Inside the highlight: lifted and ringed (`error`: in the error red). */
+  highlighted: 'none' | 'default' | 'error';
+}
+
+/** How a line looks right now. */
+export interface FlowEdgeLook {
+  look: 'base' | 'quiet' | 'emphasis' | 'travelled' | 'error';
+  /** A Yes or No line in a run: whether the run took it. */
+  taken?: boolean;
+}
+
+/** A part of the chart joining or leaving with a live relayout. */
+export type FlowPhase = 'enter' | 'exit';
 
 /**
  * What the chart hands every box: kept in context rather than in React
@@ -31,9 +59,26 @@ export interface FlowRenderContextValue {
   names: ReadonlyMap<string, string>;
   descriptions: ReadonlyMap<string, string>;
   strips: ReadonlyMap<string, string>;
+  /** Run state and highlight by node id; a node not listed is plain. */
+  looks: ReadonlyMap<string, FlowNodeLook>;
+  /** By edge id; a line not listed is plain. */
+  edgeLooks: ReadonlyMap<string, FlowEdgeLook>;
+  /** The counter on a frame's header in a run ("12 of 50 items"). */
+  frameCounters: ReadonlyMap<string, string>;
+  /** Strips settle softly when their words change (a run playing on). */
+  stripSettle: boolean;
+  /** Nodes that changed outside this tab, ringed once (by `key`). */
+  ring: { ids: ReadonlySet<string>; key: string | number } | null;
+  /** Yes and No labels highlight their paths under a pointer. */
+  branchHover: boolean;
   onActivate: (id: string) => void;
   onKeyDown: (id: string, event: KeyboardEvent<HTMLButtonElement>) => void;
   onFocusNode: (id: string, event: FocusEvent<HTMLButtonElement>) => void;
+  onBlurNode: (id: string) => void;
+  /** A pointer rests on a node (`id`) or left it (`null`). */
+  onHoverNode: (id: string | null) => void;
+  /** A pointer rests on a Yes or No label, or left it (`null`). */
+  onHoverBranch: (branch: { gateId: string; decision: boolean } | null) => void;
 }
 
 const FlowRenderContext = createContext<FlowRenderContextValue | null>(null);
@@ -48,6 +93,23 @@ export function useFlowRender(): FlowRenderContextValue {
 }
 
 const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
+const PLAIN: FlowNodeLook = {
+  state: 'idle',
+  quiet: false,
+  highlighted: 'none',
+};
+
+/** The look of a node, plain when the chart has nothing to say about it. */
+export function useFlowNodeLook(id: string): FlowNodeLook {
+  return useFlowRender().looks.get(id) ?? PLAIN;
+}
+
+/** The run states that mean "it did not run here": a dashed border. */
+const PASSED_BY: ReadonlySet<FlowNodeState> = new Set([
+  'skipped',
+  'stopped',
+  'not-run',
+]);
 
 /** The id of a node's hidden description. */
 const flowDescriptionId = (baseId: string, nodeId: string) =>
@@ -65,11 +127,61 @@ const FLOW_NODE_LIFT =
 const FLOW_NODE_RING =
   'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none';
 
+/** The frame a run state draws round a box; colour is never animated. */
+const RUN_FRAME: Partial<Record<FlowNodeState, string>> = {
+  running: 'border-[hsl(var(--info-foreground))]',
+  waiting: ISSUE_SEVERITY_FRAME_CLASS.warning,
+  failed: 'border-destructive',
+};
+
+/**
+ * The marks a run state adds inside a box: a running node's top bar
+ * sweeping across (still under reduced motion), a waiting node's amber top
+ * bar, a failed node's red left edge.
+ */
+function RunChrome({ state }: { state: FlowNodeState }) {
+  if (state === 'running')
+    return (
+      <span
+        aria-hidden="true"
+        data-slot="flow-node-running"
+        className="pointer-events-none absolute inset-x-0 top-0 h-0.5 overflow-hidden rounded-t-[inherit]"
+      >
+        <span
+          className={cn(
+            'block h-full w-full bg-[hsl(var(--info-foreground))] motion-reduce:animate-none',
+            FLOW_MOTION_CLASS.sweep,
+          )}
+        />
+      </span>
+    );
+  if (state === 'waiting')
+    return (
+      <span
+        aria-hidden="true"
+        className="pointer-events-none absolute inset-x-0 top-0 h-0.5 rounded-t-[inherit] bg-amber-600 dark:bg-amber-500"
+      />
+    );
+  if (state === 'failed')
+    return (
+      <span
+        aria-hidden="true"
+        data-slot="flow-node-failed"
+        className="bg-destructive pointer-events-none absolute inset-y-0 left-0 w-1 rounded-l-[inherit]"
+      />
+    );
+  return null;
+}
+
 /**
  * A box on the chart: one real `<button>` (no control inside it), named and
  * described for a screen reader, holding the chart's roving Tab stop when it
  * is its turn. The handles are invisible stubs React Flow needs to attach
  * edges; every line is drawn from the layout's own routes.
+ *
+ * A run frames it by state, a highlight lifts it or steps it back (dashed
+ * on a muted surface — its words never fade), and a live relayout grows it
+ * in or shrinks it out (`phase`). A box on its way out is inert.
  */
 export function FlowNodeButton({
   id,
@@ -77,6 +189,7 @@ export function FlowNodeButton({
   children,
   dashed = false,
   tooltip,
+  phase,
 }: {
   id: string;
   className?: string;
@@ -84,17 +197,29 @@ export function FlowNodeButton({
   dashed?: boolean;
   /** Pointer-hover words (the full condition of a gate). */
   tooltip?: ReactNode;
+  phase?: FlowPhase;
 }) {
   const context = useFlowRender();
-  const selected = context.selectedId === id;
+  const look = context.looks.get(id) ?? PLAIN;
+  const leaving = phase === 'exit';
+  const selected = !leaving && context.selectedId === id;
   const counts = context.issues.get(id) ?? NO_ISSUES;
   const descriptionId = flowDescriptionId(context.baseId, id);
   const disclosure = context.controlsId !== undefined;
+  const ringing = !leaving && context.ring?.ids.has(id) === true;
   const button = (
     <button
       type="button"
-      data-flow-node={id}
-      tabIndex={context.tabStopId === id ? 0 : -1}
+      data-flow-node={leaving ? undefined : id}
+      data-flow-leaving={leaving ? id : undefined}
+      data-flow-state={look.state === 'idle' ? undefined : look.state}
+      data-flow-quiet={look.quiet || undefined}
+      data-flow-highlighted={
+        look.highlighted === 'none' ? undefined : look.highlighted
+      }
+      tabIndex={!leaving && context.tabStopId === id ? 0 : -1}
+      inert={leaving || undefined}
+      aria-hidden={leaving || undefined}
       aria-label={context.names.get(id)}
       aria-describedby={descriptionId}
       aria-pressed={disclosure ? undefined : selected}
@@ -103,19 +228,41 @@ export function FlowNodeButton({
       onClick={() => context.onActivate(id)}
       onKeyDown={(event) => context.onKeyDown(id, event)}
       onFocus={(event) => context.onFocusNode(id, event)}
+      onBlur={() => context.onBlurNode(id)}
+      onPointerEnter={() => context.onHoverNode(id)}
+      onPointerLeave={() => context.onHoverNode(null)}
       className={cn(
         'relative block size-full cursor-pointer text-left',
         FLOW_NODE_LIFT,
         FLOW_NODE_RING,
-        dashed && 'border-dashed',
+        (dashed || look.quiet || PASSED_BY.has(look.state)) && 'border-dashed',
         // The frame takes the worst problem's colour; the selection ring
-        // stays its own, so a picked node with a problem shows both.
+        // stays its own, so a picked node with a problem shows both. A run
+        // state's frame wins over a problem's.
         flowNodeIssueFrameClass(counts),
+        RUN_FRAME[look.state],
+        look.highlighted === 'default' && 'ring-foreground/20 shadow-md ring-1',
+        look.highlighted === 'error' && 'ring-destructive shadow-md ring-2',
         selected && 'ring-ring ring-2 ring-offset-1',
+        phase === 'enter' && FLOW_MOTION_CLASS.enter,
+        leaving && FLOW_MOTION_CLASS.exit,
         className,
+        look.quiet && 'bg-muted/40',
       )}
     >
       {children}
+      <RunChrome state={look.state} />
+      {ringing && context.ring && (
+        <span
+          key={context.ring.key}
+          aria-hidden="true"
+          data-slot="flow-node-changed"
+          className={cn(
+            'pointer-events-none absolute -inset-1 rounded-[inherit] opacity-0 ring-2 ring-[hsl(var(--info-foreground))]',
+            FLOW_MOTION_CLASS.ring,
+          )}
+        />
+      )}
     </button>
   );
   return (
@@ -126,10 +273,16 @@ export function FlowNodeButton({
         isConnectable={false}
         className="pointer-events-none! invisible!"
       />
-      {tooltip ? <Tooltip content={tooltip}>{button}</Tooltip> : button}
-      <span id={descriptionId} hidden>
-        {context.descriptions.get(id)}
-      </span>
+      {tooltip && !leaving ? (
+        <Tooltip content={tooltip}>{button}</Tooltip>
+      ) : (
+        button
+      )}
+      {!leaving && (
+        <span id={descriptionId} hidden>
+          {context.descriptions.get(id)}
+        </span>
+      )}
       <Handle
         type="source"
         position={Position.Bottom}
@@ -140,16 +293,41 @@ export function FlowNodeButton({
   );
 }
 
-/** The line along a box's foot: what it reads, or (in a run) how it went. */
+/**
+ * The line along a box's foot: what it reads, or in a run how it went
+ * ("Failed · 1.2 s"), or why it steps back from a highlight. While a run
+ * plays on, new words settle in softly; scrubbing back and reduced motion
+ * swap them at once.
+ */
 export function FlowNodeStrip({ id }: { id: string }) {
-  const { strips } = useFlowRender();
+  const { strips, stripSettle } = useFlowRender();
   const text = strips.get(id) ?? '';
+  const ref = useRef<HTMLSpanElement>(null);
+  const shown = useRef(text);
+  useLayoutEffect(() => {
+    if (shown.current === text) return undefined;
+    shown.current = text;
+    const element = ref.current;
+    if (
+      !stripSettle ||
+      element === null ||
+      typeof element.animate !== 'function'
+    )
+      return undefined;
+    const animation = element.animate(
+      FLOW_STRIP_SETTLE.keyframes,
+      FLOW_STRIP_SETTLE.options,
+    );
+    return () => animation.cancel();
+  }, [text, stripSettle]);
   return (
     <span
       data-slot="flow-node-strip"
       className="border-border text-muted-foreground flex h-7 shrink-0 items-center border-t px-3 text-xs"
     >
-      <span className="truncate">{text}</span>
+      <span ref={ref} className="truncate">
+        {text}
+      </span>
     </span>
   );
 }
diff --git a/packages/ui/src/components/flow/render/gate-node.tsx b/packages/ui/src/components/flow/render/gate-node.tsx
index 808e168e54..8408d3b1d1 100644
--- a/packages/ui/src/components/flow/render/gate-node.tsx
+++ b/packages/ui/src/components/flow/render/gate-node.tsx
@@ -1,11 +1,12 @@
 'use client';
 
 import type { NodeProps } from '@xyflow/react';
-import { Filter, Split } from 'lucide-react';
+import { Check, Filter, Minus, Split } from 'lucide-react';
 import { memo } from 'react';
 
 import { useT } from '../../../i18n/client';
 import { cn } from '../../../lib/cn';
+import { FLOW_EDGE_COLORS } from '../edge-palette';
 import { FlowNodeIssueMarker } from '../node-issue-marker';
 import type { FlowGateNode } from '../types';
 import { FlowNodeButton, useFlowRender } from './flow-render-context';
@@ -16,19 +17,23 @@ import type { FlowNodeData } from './step-node';
  * (in mono when it is the expression itself), as wide as its words need
  * (160 to 288 px). `only-if` (a filter) has one plain line out; `if-else`
  * (a split) leads to Yes on the left and No on the right. A pointer gets the
- * full condition in a tooltip; a keyboard gets it in the name.
+ * full condition in a tooltip; a keyboard gets it in the name. In a run, a
+ * chip at its end says how it decided — "Yes" with a check or "No" with a
+ * dash, in the branch's colour.
  */
 export const FlowGateNodeView = memo(function FlowGateNodeView({
   data,
 }: NodeProps & { data: FlowNodeData<FlowGateNode> }) {
   const { t } = useT('flow');
-  const { issues } = useFlowRender();
-  const { node } = data;
+  const { issues, looks } = useFlowRender();
+  const { node, phase } = data;
   const Icon = node.mode === 'if-else' ? Split : Filter;
   const counts = issues.get(node.id);
+  const decision = looks.get(node.id)?.decision;
   return (
     <FlowNodeButton
       id={node.id}
+      phase={phase}
       tooltip={
         <span className="flex max-w-xs flex-col gap-0.5">
           <span className="font-medium">
@@ -59,6 +64,25 @@ export const FlowGateNodeView = memo(function FlowGateNodeView({
           warnings={counts.warnings}
         />
       )}
+      {decision !== undefined && (
+        <span
+          aria-hidden="true"
+          data-slot="flow-gate-decision"
+          className="inline-flex h-5 shrink-0 items-center gap-0.5 text-xs font-medium"
+          style={{
+            color: decision
+              ? FLOW_EDGE_COLORS.positive
+              : FLOW_EDGE_COLORS.negative,
+          }}
+        >
+          {decision ? (
+            <Check className="size-3" />
+          ) : (
+            <Minus className="size-3" />
+          )}
+          {t(decision ? 'branch.yes' : 'branch.no')}
+        </span>
+      )}
     </FlowNodeButton>
   );
 });
diff --git a/packages/ui/src/components/flow/render/group-frame.tsx b/packages/ui/src/components/flow/render/group-frame.tsx
index dc1a288f6d..c53a868788 100644
--- a/packages/ui/src/components/flow/render/group-frame.tsx
+++ b/packages/ui/src/components/flow/render/group-frame.tsx
@@ -4,9 +4,12 @@ import type { NodeProps } from '@xyflow/react';
 import { RefreshCw, Repeat } from 'lucide-react';
 import { memo } from 'react';
 
+import { cn } from '../../../lib/cn';
 import { FLOW_EDGE_COLORS, FLOW_EDGE_DASH } from '../edge-palette';
 import { roundedOrthogonalPath } from '../layout/geometry';
+import { FLOW_MOTION_CLASS } from '../motion/flow-motion';
 import type { FlowGroup, FlowRect } from '../types';
+import { useFlowRender, type FlowPhase } from './flow-render-context';
 
 export interface FlowFrameData extends Record<string, unknown> {
   group: FlowGroup;
@@ -15,6 +18,9 @@ export interface FlowFrameData extends Record<string, unknown> {
   /** The members' boxes, relative to the frame (where a repeat's loop
    *  arc runs). */
   members: readonly FlowRect[];
+  /** Joining (a new or resized frame fades in) or leaving with a live
+   *  relayout. */
+  phase?: FlowPhase;
 }
 
 /** How far a repeat's loop arc stands off its node's right side. */
@@ -26,19 +32,27 @@ const ARC_OFFSET = 20;
  * host's words in its header. Decoration only — every member's description
  * says the same — so it is hidden from assistive technology and never
  * takes a pointer. A repeat draws its loop as a dashed arc in its right
- * gutter, from the node's foot back to its head.
+ * gutter, from the node's foot back to its head. In a run, a counter in
+ * its top-right corner says how far it got ("12 of 50 items", "Pass 3 of
+ * 5"); the member's strip says the same.
  */
 export const FlowGroupFrameView = memo(function FlowGroupFrameView({
   data,
 }: NodeProps & { data: FlowFrameData }) {
-  const { group, header, members } = data;
+  const { group, header, members, phase } = data;
+  const { frameCounters } = useFlowRender();
+  const counter = phase === 'exit' ? undefined : frameCounters.get(group.id);
   const Icon = group.kind === 'repeat' ? RefreshCw : Repeat;
   const member = members[0];
   return (
     <div
       aria-hidden="true"
-      data-flow-frame={group.id}
-      className="border-border bg-muted/30 pointer-events-none relative size-full rounded-xl border border-dashed"
+      data-flow-frame={phase === 'exit' ? undefined : group.id}
+      className={cn(
+        'border-border bg-muted/30 pointer-events-none relative size-full rounded-xl border border-dashed',
+        phase === 'enter' && FLOW_MOTION_CLASS.fadeIn,
+        phase === 'exit' && FLOW_MOTION_CLASS.fadeOut,
+      )}
     >
       <div
         data-slot="flow-frame-header"
@@ -53,6 +67,15 @@ export const FlowGroupFrameView = memo(function FlowGroupFrameView({
         <Icon className="size-3.5 shrink-0" />
         <span className="truncate">{group.label}</span>
       </div>
+      {counter && (
+        <span
+          data-slot="flow-frame-counter"
+          className="bg-background text-foreground border-border absolute right-2 inline-flex h-5 items-center rounded-full border px-2 text-xs font-medium tabular-nums"
+          style={{ top: header.y + (header.height - 20) / 2 }}
+        >
+          {counter}
+        </span>
+      )}
       {group.kind === 'repeat' && member && (
         <svg className="absolute inset-0 size-full overflow-visible">
           <path
diff --git a/packages/ui/src/components/flow/render/looks.test.ts b/packages/ui/src/components/flow/render/looks.test.ts
new file mode 100644
index 0000000000..61bf41d354
--- /dev/null
+++ b/packages/ui/src/components/flow/render/looks.test.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+
+import type { FlowTranslate } from '../describe';
+import { flowRunText } from '../describe';
+import { highlightForIncident, highlightForNodes } from '../paths/highlight';
+import { flowStateFromOverlay } from '../playback/derive-state';
+import {
+  branchFlowGraph,
+  branchRunOverlay,
+  triageFlowGraph,
+} from '../testing/flow-fixtures';
+import { flowFrameCounters, flowLooks, looksSignature } from './looks';
+
+/** Echoes the key and its values, so the test reads what was asked for. */
+const t: FlowTranslate = (key, options) =>
+  options === undefined
+    ? key
+    : `${key}(${Object.entries(options)
+        .map(([name, value]) => `${name}=${String(value)}`)
+        .join(', ')})`;
+
+describe('flowLooks', () => {
+  it('leaves a chart with nothing to say plain', () => {
+    const { nodes, edges } = flowLooks({
+      graph: triageFlowGraph(),
+      run: null,
+      primary: null,
+      incident: null,
+    });
+    expect(nodes.size).toBe(0);
+    expect(edges.size).toBe(0);
+  });
+
+  it('steps back from everything outside a highlight, and rings what is in it', () => {
+    const graph = branchFlowGraph();
+    const { nodes, edges } = flowLooks({
+      graph,
+      run: null,
+      primary: highlightForNodes(graph, ['fetch', 'classify'], {
+        tone: 'error',
+      }),
+      incident: null,
+    });
+    expect(nodes.get('fetch')).toEqual({
+      state: 'idle',
+      quiet: false,
+      highlighted: 'error',
+    });
+    expect(nodes.get('merge')?.quiet).toBe(true);
+    expect(edges.get('fetch>classify')).toEqual({ look: 'emphasis' });
+    expect(edges.get('merge>notify')).toEqual({ look: 'quiet' });
+  });
+
+  it('brings a node’s own lines forward without quieting anything', () => {
+    const graph = triageFlowGraph();
+    const { nodes, edges } = flowLooks({
+      graph,
+      run: null,
+      primary: null,
+      incident: highlightForIncident(graph, 'score'),
+    });
+    expect(nodes.size).toBe(0);
+    expect(edges.get('open_issues>score')).toEqual({ look: 'emphasis' });
+    expect(edges.get('issues>open_issues')).toBeUndefined();
+  });
+
+  it('draws a run: travelled lines, red into the failure, branches taken or not', () => {
+    const graph = branchFlowGraph();
+    const run = flowStateFromOverlay(graph, branchRunOverlay());
+    const { nodes, edges } = flowLooks({
+      graph,
+      run,
+      primary: null,
+      incident: null,
+    });
+    expect(nodes.get('urgent')?.state).toBe('skipped');
+    expect(nodes.get('__gate:urgent')?.decision).toBe(false);
+    expect(edges.get('fetch>classify')).toEqual({ look: 'travelled' });
+    expect(edges.get('merge>notify')).toEqual({ look: 'error' });
+    expect(edges.get('__gate:urgent>urgent')).toEqual({
+      look: 'quiet',
+      taken: false,
+    });
+    expect(edges.get('__gate:normal>normal')).toEqual({
+      look: 'travelled',
+      taken: true,
+    });
+  });
+
+  it('does not ring a failure’s way, whose boxes wear their run frames', () => {
+    const graph = branchFlowGraph();
+    const run = flowStateFromOverlay(graph, branchRunOverlay());
+    const failure = run.failure;
+    if (failure === undefined) throw new Error('no failure');
+    const { nodes } = flowLooks({
+      graph,
+      run,
+      primary: { nodes: failure.pathNodes, edges: failure.pathEdges },
+      incident: null,
+      ringPrimary: false,
+    });
+    expect(nodes.get('merge')?.highlighted).toBe('none');
+    expect(nodes.get('urgent')?.quiet).toBe(true);
+  });
+});
+
+describe('flowFrameCounters and flowRunText', () => {
+  it('counts passes on a frame in a run', () => {
+    const graph = branchFlowGraph();
+    const counters = flowFrameCounters(
+      graph,
+      flowStateFromOverlay(graph, branchRunOverlay()),
+      t,
+    );
+    expect(counters.get('repeat:poll')).toBe('group.pass(pass=3, max=5)');
+    expect(flowFrameCounters(graph, null, t).size).toBe(0);
+  });
+
+  it('words a step’s run: the reason or the state, then the detail', () => {
+    const graph = branchFlowGraph();
+    const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+    const fetch = byId.get('fetch');
+    const gate = byId.get('__gate:urgent');
+    if (fetch === undefined || gate === undefined) throw new Error('fixture');
+    expect(flowRunText(fetch, { state: 'succeeded', detail: '1.2 s' }, t)).toBe(
+      'state.succeeded · 1.2 s',
+    );
+    expect(flowRunText(fetch, { state: 'failed' }, t, true)).toBe(
+      'state.failedHere',
+    );
+    expect(
+      flowRunText(fetch, { state: 'running', items: { done: 2, total: 5 } }, t),
+    ).toBe('state.running · group.items(done=2, total=5)');
+    expect(flowRunText(gate, { state: 'succeeded', decision: true }, t)).toBe(
+      'state.decidedYes',
+    );
+  });
+
+  it('keeps a signature that changes with the looks', () => {
+    const a = new Map([['x', { look: 'quiet' }]]);
+    const b = new Map([['x', { look: 'quiet' }]]);
+    const c = new Map([['x', { look: 'emphasis' }]]);
+    expect(looksSignature(a)).toBe(looksSignature(b));
+    expect(looksSignature(a)).not.toBe(looksSignature(c));
+  });
+});
diff --git a/packages/ui/src/components/flow/render/looks.ts b/packages/ui/src/components/flow/render/looks.ts
new file mode 100644
index 0000000000..52ecbd7ea0
--- /dev/null
+++ b/packages/ui/src/components/flow/render/looks.ts
@@ -0,0 +1,118 @@
+import type { FlowTranslate } from '../describe';
+import type { FlowHighlight } from '../paths/highlight';
+import type { FlowFrameState } from '../playback/types';
+import type { FlowGraph } from '../types';
+import type { FlowEdgeLook, FlowNodeLook } from './flow-render-context';
+
+/**
+ * How every box and line of a chart looks, from the run shown and the
+ * highlights on it. Pure: a browser test checks the picture, this checks
+ * the rules.
+ *
+ *  - `primary` is the highlight that quiets the rest: a host's path, a
+ *    condition a pointer rests on, or a failed run's way to its failure.
+ *    Inside it, boxes are lifted and ringed (unless `ringPrimary` is off,
+ *    as for a failure, whose boxes already wear their run frames) and lines
+ *    stand out; outside it, boxes step back and lines thin.
+ *  - `incident` only brings a node's own lines forward (a pointer or the
+ *    keyboard on it) and quiets nothing.
+ *  - In a run, a line the run took is drawn in the emphasis colour (red
+ *    into the node it failed at), a line it did not take steps back.
+ */
+export function flowLooks({
+  graph,
+  run,
+  primary,
+  incident,
+  ringPrimary = true,
+}: {
+  graph: FlowGraph;
+  run: FlowFrameState | null;
+  primary: FlowHighlight | null;
+  incident: FlowHighlight | null;
+  ringPrimary?: boolean;
+}): {
+  nodes: Map<string, FlowNodeLook>;
+  edges: Map<string, FlowEdgeLook>;
+} {
+  const quietRest = primary !== null && primary.quietRest !== false;
+  const nodes = new Map<string, FlowNodeLook>();
+  for (const node of graph.nodes) {
+    const info = run?.nodes[node.id];
+    const inside = primary?.nodes.has(node.id) === true;
+    const look: FlowNodeLook = {
+      state: info?.state ?? 'idle',
+      quiet: quietRest && !inside,
+      highlighted:
+        quietRest && inside && ringPrimary
+          ? primary?.tone === 'error'
+            ? 'error'
+            : 'default'
+          : 'none',
+    };
+    if (info?.decision !== undefined) look.decision = info.decision;
+    if (look.state !== 'idle' || look.quiet || look.highlighted !== 'none')
+      nodes.set(node.id, look);
+  }
+
+  const edges = new Map<string, FlowEdgeLook>();
+  const failedAt = run?.failure?.nodeId;
+  for (const edge of graph.edges) {
+    if (edge.layoutOnly) continue;
+    const state = run?.edges[edge.id];
+    const forward =
+      primary?.edges.has(edge.id) === true ||
+      incident?.edges.has(edge.id) === true;
+    let look: FlowEdgeLook['look'];
+    if (quietRest && !forward) look = 'quiet';
+    else if (state === 'not-taken') look = 'quiet';
+    else if (state === 'travelled' || state === 'travelling')
+      look =
+        failedAt !== undefined && edge.target === failedAt
+          ? 'error'
+          : 'travelled';
+    else if (forward) look = 'emphasis';
+    else look = 'base';
+    const branch = edge.kind === 'branch-yes' || edge.kind === 'branch-no';
+    const taken =
+      !branch || state === undefined || state === 'idle'
+        ? undefined
+        : state !== 'not-taken';
+    if (look !== 'base' || taken !== undefined)
+      edges.set(edge.id, taken === undefined ? { look } : { look, taken });
+  }
+  return { nodes, edges };
+}
+
+/** The counter on each frame's header in a run: items or passes done. */
+export function flowFrameCounters(
+  graph: FlowGraph,
+  run: FlowFrameState | null,
+  t: FlowTranslate,
+): Map<string, string> {
+  const counters = new Map<string, string>();
+  if (run === null) return counters;
+  for (const group of graph.groups ?? []) {
+    const member = group.members[0];
+    const info = member === undefined ? undefined : run.nodes[member];
+    if (info?.items?.total !== undefined)
+      counters.set(
+        group.id,
+        t('group.items', { done: info.items.done, total: info.items.total }),
+      );
+    else if (info?.pass?.max !== undefined)
+      counters.set(
+        group.id,
+        t('group.pass', { pass: info.pass.current, max: info.pass.max }),
+      );
+  }
+  return counters;
+}
+
+/** A string that changes exactly when a look map does, to keep its
+ *  identity between frames of a playback where nothing changed. */
+export function looksSignature(
+  map: ReadonlyMap<string, object | string>,
+): string {
+  return JSON.stringify([...map]);
+}
diff --git a/packages/ui/src/components/flow/render/pulse-layer.tsx b/packages/ui/src/components/flow/render/pulse-layer.tsx
new file mode 100644
index 0000000000..272820e993
--- /dev/null
+++ b/packages/ui/src/components/flow/render/pulse-layer.tsx
@@ -0,0 +1,168 @@
+'use client';
+
+import { ViewportPortal } from '@xyflow/react';
+import { memo, useLayoutEffect, useRef } from 'react';
+
+import { FLOW_EDGE_CORNER_RADIUS } from '../edge-palette';
+import { roundedOrthogonalPath, sampleRoute } from '../layout/geometry';
+import type { FlowLayout, FlowPoint } from '../types';
+
+/** One playback "second" of a pulse: its animation runs paused, and its
+ *  `currentTime` is the travel's progress times this. */
+export const FLOW_PULSE_DURATION = 1_000;
+
+/** How far apart the pulse's keyframes sit along its route. */
+const SAMPLE_STEP = 8;
+/** Half the dot, so its centre rides the line. */
+const DOT_HALF = 4;
+
+/**
+ * Keyframe points every 8 px along the route the canvas draws (rounded
+ * corners included), read from an SVG path when the page can measure one,
+ * else along the route's straight segments.
+ */
+function pulsePoints(
+  points: readonly FlowPoint[],
+): Array<FlowPoint & { offset: number }> {
+  if (typeof document !== 'undefined') {
+    try {
+      const path = document.createElementNS(
+        'http://www.w3.org/2000/svg',
+        'path',
+      );
+      path.setAttribute(
+        'd',
+        roundedOrthogonalPath(points, FLOW_EDGE_CORNER_RADIUS),
+      );
+      const total = path.getTotalLength();
+      if (total > 0) {
+        const out: Array<FlowPoint & { offset: number }> = [];
+        for (let along = 0; along < total; along += SAMPLE_STEP) {
+          const point = path.getPointAtLength(along);
+          out.push({ x: point.x, y: point.y, offset: along / total });
+        }
+        const end = path.getPointAtLength(total);
+        out.push({ x: end.x, y: end.y, offset: 1 });
+        return out;
+      }
+    } catch (error) {
+      console.warn(
+        'Flow pulse could not measure its route; following its segments',
+        error,
+      );
+    }
+  }
+  return sampleRoute(points, SAMPLE_STEP);
+}
+
+/**
+ * A value on its way: an 8 px dot riding its line. The motion is a Web
+ * Animation created paused — the host's time sets its `currentTime`, so
+ * playing, scrubbing and stepping are the same thing, and a dot is exactly
+ * where the travel's progress says. It fades in over the first 8 % and
+ * dissolves into the box it reaches over the last 8 %.
+ */
+const FlowPulse = memo(function FlowPulse({
+  edgeId,
+  points,
+  progress,
+}: {
+  edgeId: string;
+  points: readonly FlowPoint[];
+  progress: number;
+}) {
+  const moveRef = useRef<HTMLSpanElement>(null);
+  const dotRef = useRef<HTMLSpanElement>(null);
+  const animations = useRef<Animation[]>([]);
+  const progressRef = useRef(progress);
+  progressRef.current = progress;
+
+  useLayoutEffect(() => {
+    const move = moveRef.current;
+    const dot = dotRef.current;
+    if (move === null || dot === null || typeof move.animate !== 'function')
+      return undefined;
+    const samples = pulsePoints(points);
+    const travel = move.animate(
+      samples.map(({ x, y, offset }) => ({
+        transform: `translate(${x - DOT_HALF}px, ${y - DOT_HALF}px)`,
+        offset,
+      })),
+      { duration: FLOW_PULSE_DURATION, fill: 'both', easing: 'linear' },
+    );
+    const fade = dot.animate(
+      [
+        { opacity: 0, offset: 0 },
+        { opacity: 1, offset: 0.08 },
+        { opacity: 1, offset: 0.92 },
+        { opacity: 0, offset: 1 },
+      ],
+      { duration: FLOW_PULSE_DURATION, fill: 'both' },
+    );
+    travel.pause();
+    fade.pause();
+    animations.current = [travel, fade];
+    for (const animation of animations.current)
+      animation.currentTime = progressRef.current * FLOW_PULSE_DURATION;
+    return () => {
+      travel.cancel();
+      fade.cancel();
+      animations.current = [];
+    };
+  }, [points]);
+
+  useLayoutEffect(() => {
+    for (const animation of animations.current)
+      animation.currentTime = progress * FLOW_PULSE_DURATION;
+  }, [progress]);
+
+  return (
+    <span
+      ref={moveRef}
+      aria-hidden="true"
+      data-flow-pulse={edgeId}
+      className="pointer-events-none absolute top-0 left-0"
+    >
+      <span
+        ref={dotRef}
+        className="block size-2 rounded-full bg-[hsl(var(--info-foreground))] ring-4 ring-[hsl(var(--info-foreground)/0.25)]"
+      />
+    </span>
+  );
+});
+
+/**
+ * The values moving through a run at the moment shown: one dot per
+ * active travel, drawn in the chart's own coordinates. Under reduced
+ * motion there are none — the lines switch to travelled when a value
+ * arrives, and the states tell the story.
+ */
+export function FlowPulseLayer({
+  travelling,
+  layout,
+}: {
+  travelling: ReadonlyArray<{
+    edgeId: string;
+    progress: number;
+    item?: number;
+  }>;
+  layout: FlowLayout;
+}) {
+  if (travelling.length === 0) return null;
+  return (
+    <ViewportPortal>
+      {travelling.map(({ edgeId, progress, item }) => {
+        const route = layout.edges[edgeId];
+        if (route === undefined) return null;
+        return (
+          <FlowPulse
+            key={`${edgeId}:${item ?? ''}`}
+            edgeId={edgeId}
+            points={route.points}
+            progress={progress}
+          />
+        );
+      })}
+    </ViewportPortal>
+  );
+}
diff --git a/packages/ui/src/components/flow/render/routed-edge.tsx b/packages/ui/src/components/flow/render/routed-edge.tsx
index 5326f7a912..53d064de3b 100644
--- a/packages/ui/src/components/flow/render/routed-edge.tsx
+++ b/packages/ui/src/components/flow/render/routed-edge.tsx
@@ -1,8 +1,10 @@
 'use client';
 
 import { EdgeLabelRenderer, type EdgeProps } from '@xyflow/react';
+import { Check, Minus } from 'lucide-react';
 import { memo } from 'react';
 
+import { cn } from '../../../lib/cn';
 import {
   FLOW_EDGE_ARROW,
   FLOW_EDGE_COLORS,
@@ -10,10 +12,17 @@ import {
   FLOW_EDGE_STROKE,
   flowEdgeDash,
   flowEdgeTone,
+  type FlowEdgeTone,
 } from '../edge-palette';
 import { roundedOrthogonalPath, trimEnd } from '../layout/geometry';
+import { FLOW_MOTION_CLASS } from '../motion/flow-motion';
 import type { FlowEdge, FlowPoint, FlowRect } from '../types';
 import { flowArrowId } from './edge-markers';
+import {
+  useFlowRender,
+  type FlowEdgeLook,
+  type FlowPhase,
+} from './flow-render-context';
 
 export interface FlowRoutedEdgeData extends Record<string, unknown> {
   edge: FlowEdge;
@@ -21,6 +30,8 @@ export interface FlowRoutedEdgeData extends Record<string, unknown> {
   label?: { text: string; rect: FlowRect };
   /** Prefix of the canvas's arrowhead ids. */
   baseId: string;
+  /** Joining or leaving with a live relayout. */
+  phase?: FlowPhase;
 }
 
 /**
@@ -50,36 +61,109 @@ export function flowEdgePaths(points: readonly FlowPoint[]): {
 /** Pointer room round a line, wider than the line itself. */
 const HIT_WIDTH = 12;
 
+const PLAIN: FlowEdgeLook = { look: 'base' };
+
+/** The colour and width of a line in a look. A Yes or No line keeps its
+ *  hue when it stands out, so the branch stays readable. */
+function strokeOf(
+  edge: FlowEdge,
+  look: FlowEdgeLook['look'],
+): { tone: FlowEdgeTone; width: number } {
+  const own = flowEdgeTone(edge.kind);
+  const branch = own === 'positive' || own === 'negative';
+  switch (look) {
+    case 'quiet':
+      return { tone: own, width: FLOW_EDGE_STROKE.quiet };
+    case 'emphasis':
+      return {
+        tone: branch ? own : 'emphasis',
+        width: FLOW_EDGE_STROKE.emphasis,
+      };
+    case 'travelled':
+      return { tone: branch ? own : 'emphasis', width: FLOW_EDGE_STROKE.base };
+    case 'error':
+      return { tone: 'error', width: FLOW_EDGE_STROKE.base };
+    default:
+      return { tone: own, width: FLOW_EDGE_STROKE.base };
+  }
+}
+
+const FADE =
+  'transition-opacity duration-[var(--duration-short)] ease-[var(--ease-out-quint)]';
+
 /**
  * An edge drawn along the route the layout gave it — orthogonal, corners
  * rounded at 8 px — never along React Flow's own handle-to-handle curve,
  * which ignored the boxes in its way. The kind sets the line: a `data`
  * edge solid, `order` dashed, `completion` dotted, `branch-yes` green and
  * `branch-no` amber with a "Yes" / "No" pill at the layout's label box.
- * Hidden from assistive technology: the nodes say what the lines mean.
+ *
+ * A highlight or a run changes how it looks — thinner when it steps back,
+ * thicker when it stands out, the emphasis colour once a run travelled it,
+ * red into the node a run failed at — and the change crossfades two
+ * stacked lines (colour and width never animate). Hidden from assistive
+ * technology: the nodes say what the lines mean.
  */
 export const FlowRoutedEdgeView = memo(function FlowRoutedEdgeView({
   data,
 }: EdgeProps & { data: FlowRoutedEdgeData }) {
-  const { edge, points, label, baseId } = data;
-  const tone = flowEdgeTone(edge.kind);
-  const color = FLOW_EDGE_COLORS[tone];
+  const { edge, points, label, baseId, phase } = data;
+  const context = useFlowRender();
+  const leaving = phase === 'exit';
+  const { look, taken } = leaving
+    ? PLAIN
+    : (context.edgeLooks.get(edge.id) ?? PLAIN);
+  const rest = strokeOf(edge, 'base');
+  const now = strokeOf(edge, look === 'base' ? 'quiet' : look);
+  const dash = flowEdgeDash(edge.kind);
+  const cap = edge.kind === 'completion' ? 'round' : 'butt';
   const { full, stroke } = flowEdgePaths(points);
+  const branchGate =
+    edge.kind === 'branch-yes' || edge.kind === 'branch-no'
+      ? edge.source
+      : null;
+  const hoverable = branchGate !== null && context.branchHover && !leaving;
   return (
-    <>
+    <g
+      data-flow-edge-group={leaving ? undefined : edge.id}
+      data-flow-edge-leaving={leaving ? edge.id : undefined}
+      className={cn(
+        phase === 'enter' && FLOW_MOTION_CLASS.fadeIn,
+        leaving && FLOW_MOTION_CLASS.fadeOut,
+      )}
+    >
       <path
         d={stroke}
         fill="none"
-        data-flow-edge={edge.id}
+        data-flow-edge={leaving ? undefined : edge.id}
         data-kind={edge.kind}
-        className="react-flow__edge-path"
-        strokeWidth={FLOW_EDGE_STROKE.base}
-        strokeDasharray={flowEdgeDash(edge.kind)}
-        strokeLinecap={edge.kind === 'completion' ? 'round' : 'butt'}
-        markerEnd={`url(#${flowArrowId(baseId, tone)})`}
-        style={{ stroke: color }}
+        data-look={look}
+        className={cn('react-flow__edge-path', FADE)}
+        strokeWidth={rest.width}
+        strokeDasharray={dash}
+        strokeLinecap={cap}
+        markerEnd={`url(#${flowArrowId(baseId, rest.tone)})`}
+        style={{
+          stroke: FLOW_EDGE_COLORS[rest.tone],
+          opacity: look === 'base' ? 1 : 0,
+        }}
+      />
+      <path
+        d={stroke}
+        fill="none"
+        aria-hidden="true"
+        data-flow-edge-state={leaving ? undefined : edge.id}
+        className={FADE}
+        strokeWidth={now.width}
+        strokeDasharray={dash}
+        strokeLinecap={cap}
+        markerEnd={`url(#${flowArrowId(baseId, now.tone)})`}
+        style={{
+          stroke: FLOW_EDGE_COLORS[now.tone],
+          opacity: look === 'base' ? 0 : 1,
+        }}
       />
-      {edge.detail && (
+      {edge.detail && !leaving && (
         <path
           d={full}
           fill="none"
@@ -94,19 +178,40 @@ export const FlowRoutedEdgeView = memo(function FlowRoutedEdgeView({
         <EdgeLabelRenderer>
           <div
             aria-hidden="true"
-            data-flow-edge-label={edge.id}
-            className="bg-background pointer-events-none absolute flex items-center justify-center rounded-full text-xs leading-4 font-medium"
+            data-flow-edge-label={leaving ? undefined : edge.id}
+            data-taken={taken === undefined ? undefined : String(taken)}
+            onPointerEnter={
+              hoverable && branchGate !== null
+                ? () =>
+                    context.onHoverBranch({
+                      gateId: branchGate,
+                      decision: edge.kind === 'branch-yes',
+                    })
+                : undefined
+            }
+            onPointerLeave={
+              hoverable ? () => context.onHoverBranch(null) : undefined
+            }
+            className={cn(
+              'bg-background absolute flex items-center justify-center gap-0.5 rounded-full text-xs leading-4',
+              hoverable ? 'nopan pointer-events-auto' : 'pointer-events-none',
+              taken === false ? 'font-normal' : 'font-medium',
+              phase === 'enter' && FLOW_MOTION_CLASS.fadeIn,
+              leaving && FLOW_MOTION_CLASS.fadeOut,
+            )}
             style={{
               width: label.rect.width,
               height: label.rect.height,
               transform: `translate(${label.rect.x}px, ${label.rect.y}px)`,
-              color,
+              color: FLOW_EDGE_COLORS[rest.tone],
             }}
           >
+            {taken === true && <Check className="size-3 shrink-0" />}
+            {taken === false && <Minus className="size-3 shrink-0" />}
             {label.text}
           </div>
         </EdgeLabelRenderer>
       )}
-    </>
+    </g>
   );
 });
diff --git a/packages/ui/src/components/flow/render/step-node.tsx b/packages/ui/src/components/flow/render/step-node.tsx
index 8a1e3a9369..d22504fb6a 100644
--- a/packages/ui/src/components/flow/render/step-node.tsx
+++ b/packages/ui/src/components/flow/render/step-node.tsx
@@ -9,16 +9,20 @@ import { cn } from '../../../lib/cn';
 import { ISSUE_SEVERITY_CHIP_CLASS } from '../../feedback/issue-severity';
 import { SKELETON_PULSE } from '../../feedback/skeleton';
 import { FlowNodeIssueMarker } from '../node-issue-marker';
+import { FlowNodeStatusIcon } from '../node-status';
 import type { FlowChip, FlowIcon, FlowStepNode } from '../types';
 import {
   FlowNodeButton,
   FlowNodeStrip,
   useFlowRender,
+  type FlowPhase,
 } from './flow-render-context';
 
 /** The data React Flow carries for a box. */
 export interface FlowNodeData<T> extends Record<string, unknown> {
   node: T;
+  /** Joining or leaving with a live relayout. */
+  phase?: FlowPhase;
 }
 
 const CHIP_TONE: Record<NonNullable<FlowChip['tone']>, string> = {
@@ -44,7 +48,8 @@ function FlowChipPill({ chip }: { chip: FlowChip }) {
   );
 }
 
-/** The title row every box shares: icon tile, title, glyphs, problems. */
+/** The title row every box shares: icon tile, title, glyphs, problems and,
+ *  in a run, the state's glyph. */
 export function FlowNodeTitleRow({
   id,
   icon: Icon,
@@ -56,8 +61,9 @@ export function FlowNodeTitleRow({
   title: string;
   trailing?: ReactNode;
 }) {
-  const { issues } = useFlowRender();
+  const { issues, looks } = useFlowRender();
   const counts = issues.get(id);
+  const state = looks.get(id)?.state ?? 'idle';
   return (
     <span className="flex h-5 items-center gap-2">
       <span className="bg-muted text-muted-foreground flex size-5 shrink-0 items-center justify-center rounded-md">
@@ -74,6 +80,7 @@ export function FlowNodeTitleRow({
             warnings={counts.warnings}
           />
         )}
+        <FlowNodeStatusIcon state={state} className="size-3.5" />
       </span>
     </span>
   );
@@ -89,7 +96,7 @@ export const FlowStepNodeView = memo(function FlowStepNodeView({
   data,
 }: NodeProps & { data: FlowNodeData<FlowStepNode> }) {
   const { t } = useT('flow');
-  const { node } = data;
+  const { node, phase } = data;
   const chips = node.chips ?? [];
   const shown = chips.slice(0, 2);
   const hidden = chips.length - shown.length;
@@ -97,6 +104,7 @@ export const FlowStepNodeView = memo(function FlowStepNodeView({
   return (
     <FlowNodeButton
       id={node.id}
+      phase={phase}
       dashed={node.conditional === true || node.unreachable === true}
       className="bg-card text-card-foreground border-border flex flex-col rounded-lg border shadow-sm"
     >
diff --git a/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
new file mode 100644
index 0000000000..2597aa42df
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
@@ -0,0 +1,265 @@
+import { viewportAtRest } from '@tale/ui/testing/flow';
+import { cleanup } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cdp, page } from 'vitest/browser';
+
+import { render, waitFor } from '@/tests/utils/render';
+
+import { triageFlowGraph } from './testing/flow-fixtures';
+import type { FlowGraph, FlowLayout } from './types';
+import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
+
+import '../../globals.css';
+
+afterEach(async () => {
+  cleanup();
+  window.localStorage.removeItem('tale:flow-view');
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+});
+
+/** Triage with a step `tag` added after Report: a graph this session has
+ *  not laid out before. */
+function withStep(tag: string, base = triageFlowGraph()): FlowGraph {
+  const id = `probe_${tag}`;
+  return {
+    ...base,
+    nodes: [
+      ...base.nodes.slice(0, -1),
+      { id, kind: 'step', label: `Probe ${tag}`, typeLabel: 'Transform' },
+      ...base.nodes.slice(-1),
+    ],
+    edges: [
+      ...base.edges,
+      { id: `report>${id}`, source: 'report', target: id, kind: 'data' },
+      { id: `${id}>__end`, source: id, target: '__end', kind: 'completion' },
+    ],
+  };
+}
+
+/** Renders a canvas whose graph the test swaps, and counts its layouts. */
+async function renderLive(
+  graph: FlowGraph,
+  props: Partial<WorkflowCanvasProps> = {},
+) {
+  await page.viewport(1280, 1400);
+  const layouts: FlowLayout[] = [];
+  const view = render(
+    <div style={{ width: 1100, height: 1300 }}>
+      <WorkflowCanvas
+        graph={graph}
+        aria-label="Triage"
+        layoutKey="triage"
+        fitPolicy="all"
+        onLayout={(layout) => layouts.push(layout)}
+        {...props}
+      />
+    </div>,
+  );
+  await waitFor(() => expect(layouts.length).toBeGreaterThan(0), {
+    timeout: 20_000,
+  });
+  await waitFor(() =>
+    expect(
+      view.container.querySelectorAll('path[data-flow-edge]'),
+    ).toHaveLength(graph.edges.filter((edge) => !edge.layoutOnly).length),
+  );
+  await viewportAtRest();
+  const swap = (next: FlowGraph, more: Partial<WorkflowCanvasProps> = {}) =>
+    view.rerender(
+      <div style={{ width: 1100, height: 1300 }}>
+        <WorkflowCanvas
+          graph={next}
+          aria-label="Triage"
+          layoutKey="triage"
+          fitPolicy="all"
+          onLayout={(layout) => layouts.push(layout)}
+          {...props}
+          {...more}
+        />
+      </div>,
+    );
+  return { ...view, layouts, swap };
+}
+
+const chart = (container: HTMLElement) => {
+  const element = container.querySelector<HTMLElement>('[data-flow-engine]');
+  if (element === null) throw new Error('no chart');
+  return element;
+};
+const wrapper = (container: HTMLElement, id: string) =>
+  container.querySelector<HTMLElement>(
+    `.react-flow__node[data-id="${CSS.escape(id)}"]`,
+  );
+
+describe('WorkflowCanvas live relayout', () => {
+  it('glides what stays, grows in what joins and fades new lines in last', async () => {
+    const { container, layouts, swap } = await renderLive(triageFlowGraph());
+    const next = withStep('glide');
+    swap(next);
+    await waitFor(() => expect(layouts).toHaveLength(2), { timeout: 20_000 });
+    await waitFor(() =>
+      expect(chart(container)).toHaveAttribute('data-flow-transition', 'move'),
+    );
+
+    // Every node that stays carries the move: 300 ms, out-quint.
+    const issues = getComputedStyle(wrapper(container, 'issues') as Element);
+    expect(issues.transitionProperty).toBe('transform');
+    expect(issues.transitionDuration).toBe('0.3s');
+    expect(issues.transitionTimingFunction).toBe(
+      'cubic-bezier(0.22, 1, 0.36, 1)',
+    );
+
+    // The new node grows in once the glide is under way.
+    const probe = await waitFor(() => {
+      const button = container.querySelector('[data-flow-node="probe_glide"]');
+      if (button === null) throw new Error('not drawn yet');
+      return getComputedStyle(button);
+    });
+    expect(probe.animationName).toBe('flow-enter');
+    expect(probe.animationDuration).toBe('0.2s');
+    expect(probe.animationDelay).toBe('0.15s');
+
+    // Its lines fade in last, once the boxes are nearly there.
+    const line = await waitFor(() => {
+      const group = container.querySelector(
+        '[data-flow-edge-group="report>probe_glide"]',
+      );
+      if (group === null) throw new Error('not drawn yet');
+      return getComputedStyle(group);
+    });
+    expect(line.animationName).toBe('fade-in');
+    expect(line.animationDelay).toBe('0.25s');
+
+    // Settled after 450 ms: plain again, nothing moves on a later pan.
+    await waitFor(
+      () =>
+        expect(chart(container)).not.toHaveAttribute('data-flow-transition'),
+      { timeout: 2_000 },
+    );
+    expect(
+      getComputedStyle(wrapper(container, 'issues') as Element)
+        .transitionProperty,
+    ).not.toBe('transform');
+  });
+
+  it('shrinks a removed node out at its old place, then lets it go', async () => {
+    const start = withStep('leave');
+    const { container, layouts, swap } = await renderLive(start);
+    swap(triageFlowGraph());
+    await waitFor(() => expect(layouts).toHaveLength(2), { timeout: 20_000 });
+    const leaving = await waitFor(() => {
+      const button = container.querySelector(
+        '[data-flow-leaving="probe_leave"]',
+      );
+      if (button === null) throw new Error('not leaving yet');
+      return button;
+    });
+    expect(getComputedStyle(leaving).animationName).toBe('flow-exit');
+    expect(leaving).toHaveAttribute('aria-hidden', 'true');
+    expect(leaving.hasAttribute('inert')).toBe(true);
+    // Its lines fade out along their old routes.
+    expect(
+      container.querySelector('[data-flow-edge-leaving="report>probe_leave"]'),
+    ).not.toBeNull();
+    await waitFor(
+      () =>
+        expect(
+          container.querySelector('[data-flow-leaving="probe_leave"]'),
+        ).toBeNull(),
+      { timeout: 2_000 },
+    );
+  });
+
+  it('rings nodes changed outside this tab once, and only then', async () => {
+    const { container, layouts, swap } = await renderLive(triageFlowGraph(), {
+      changed: { ids: new Set(['report']), key: 0 },
+    });
+    // The key the canvas opened with is never rung.
+    expect(
+      container.querySelector('[data-slot="flow-node-changed"]'),
+    ).toBeNull();
+    swap(withStep('ring'), {
+      changed: { ids: new Set(['probe_ring', 'report']), key: 1 },
+    });
+    await waitFor(() => expect(layouts).toHaveLength(2), { timeout: 20_000 });
+    const ring = await waitFor(() => {
+      const element = container.querySelector(
+        '[data-flow-node="report"] [data-slot="flow-node-changed"]',
+      );
+      if (element === null) throw new Error('no ring yet');
+      return element;
+    });
+    const style = getComputedStyle(ring);
+    expect(style.animationName).toBe('flow-ring-out');
+    expect(style.animationDelay).toBe('0.3s');
+    expect(style.animationDuration).toBe('0.4s');
+    await waitFor(
+      () =>
+        expect(
+          container.querySelector('[data-slot="flow-node-changed"]'),
+        ).toBeNull(),
+      { timeout: 2_000 },
+    );
+  });
+
+  it('lays a new picture out afresh, without gliding', async () => {
+    const { container, layouts, swap } = await renderLive(triageFlowGraph());
+    swap(withStep('fresh'), { layoutKey: 'another-version' });
+    await waitFor(() => expect(layouts).toHaveLength(2), { timeout: 20_000 });
+    await waitFor(() =>
+      expect(
+        container.querySelector('[data-flow-node="probe_fresh"]'),
+      ).not.toBeNull(),
+    );
+    expect(chart(container)).not.toHaveAttribute('data-flow-transition');
+    expect(
+      getComputedStyle(wrapper(container, 'issues') as Element)
+        .transitionProperty,
+    ).not.toBe('transform');
+    expect(
+      getComputedStyle(
+        container.querySelector('[data-flow-node="probe_fresh"]') as Element,
+      ).animationName,
+    ).not.toBe('flow-enter');
+  });
+
+  it('jumps to the new layout under reduced motion: no animation, no ring', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const { container, layouts, swap } = await renderLive(withStep('calm'));
+    swap(triageFlowGraph(), {
+      changed: { ids: new Set(['report']), key: 'calm' },
+    });
+    await waitFor(() => expect(layouts).toHaveLength(2), { timeout: 20_000 });
+    await waitFor(() =>
+      expect(
+        container.querySelector('[data-flow-node="probe_calm"]'),
+      ).toBeNull(),
+    );
+    expect(chart(container)).not.toHaveAttribute('data-flow-transition');
+    expect(container.querySelector('[data-flow-leaving]')).toBeNull();
+    expect(
+      container.querySelector('[data-slot="flow-node-changed"]'),
+    ).toBeNull();
+    // Nothing animates: no transition on a node, no running animation.
+    expect(
+      getComputedStyle(wrapper(container, 'issues') as Element)
+        .transitionProperty,
+    ).not.toBe('transform');
+    const running = document
+      .getAnimations()
+      .filter(
+        (animation) =>
+          animation.playState === 'running' &&
+          Number(animation.effect?.getComputedTiming().duration) > 1,
+      );
+    expect(running).toEqual([]);
+    // Every box is at its final place at once.
+    const final = layouts.at(-1);
+    const report = wrapper(container, 'report');
+    expect(report?.style.transform).toBe(
+      `translate(${final?.nodes.report?.x}px, ${final?.nodes.report?.y}px)`,
+    );
+  });
+});
diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
new file mode 100644
index 0000000000..162cd7f045
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -0,0 +1,387 @@
+import { viewportAtRest } from '@tale/ui/testing/flow';
+import { cleanup } from '@testing-library/react';
+import axe from 'axe-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cdp, page, userEvent } from 'vitest/browser';
+
+import { ratioAgainst } from '@/tests/utils/contrast';
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { highlightForNodes, type FlowPath } from './paths/highlight';
+import { buildPlaybackTimeline } from './playback/build-timeline';
+import { flowStateAt } from './playback/derive-state';
+import type { FlowPlaybackTimeline } from './playback/types';
+import { FLOW_PULSE_DURATION } from './render/pulse-layer';
+import {
+  branchFlowGraph,
+  branchRunOverlay,
+  triageFailedRun,
+  triageFlowGraph,
+} from './testing/flow-fixtures';
+import type { FlowGraph, FlowLayout } from './types';
+import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
+
+import '../../globals.css';
+
+afterEach(async () => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  window.localStorage.removeItem('tale:flow-view');
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+});
+
+const BRANCH_PATHS: FlowPath[] = [
+  {
+    id: 'urgent',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      'urgent',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': true },
+  },
+  {
+    id: 'normal',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      '__gate:normal',
+      'normal',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': true },
+  },
+  {
+    id: 'low',
+    nodes: [
+      'fetch',
+      'classify',
+      '__gate:urgent',
+      '__gate:normal',
+      'low',
+      'enrich',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': false },
+  },
+];
+
+function Canvas(props: Partial<WorkflowCanvasProps> & { graph: FlowGraph }) {
+  return (
+    <div style={{ width: 1100, height: 1500 }}>
+      <WorkflowCanvas
+        aria-label="Workflow"
+        layoutKey={`run-${props.graph.nodes.length}`}
+        fitPolicy="all"
+        {...props}
+      />
+    </div>
+  );
+}
+
+/** Renders and resolves once the layout and every line are on the page. */
+async function renderRun(
+  props: Partial<WorkflowCanvasProps> & { graph: FlowGraph },
+) {
+  await page.viewport(1280, 1600);
+  let layout: FlowLayout | null = null;
+  const view = render(
+    <Canvas
+      {...props}
+      onLayout={(next) => {
+        layout = next;
+      }}
+    />,
+  );
+  await waitFor(
+    () => {
+      if (layout === null) throw new Error('not laid out yet');
+    },
+    { timeout: 20_000 },
+  );
+  await waitFor(() =>
+    expect(
+      view.container.querySelectorAll('path[data-flow-edge]'),
+    ).toHaveLength(props.graph.edges.filter((edge) => !edge.layoutOnly).length),
+  );
+  await viewportAtRest();
+  return {
+    ...view,
+    layout: layout as unknown as FlowLayout,
+    rerun: (more: Partial<WorkflowCanvasProps>) =>
+      view.rerender(<Canvas {...props} {...more} />),
+  };
+}
+
+const node = (id: string) =>
+  document.querySelector<HTMLElement>(`[data-flow-node="${CSS.escape(id)}"]`);
+const strip = (id: string) =>
+  node(id)?.querySelector('[data-slot="flow-node-strip"]')?.textContent;
+const look = (id: string) =>
+  document
+    .querySelector(`path[data-flow-edge="${CSS.escape(id)}"]`)
+    ?.getAttribute('data-look');
+
+describe('WorkflowCanvas with a run', () => {
+  it('draws the state of every node at the playback moment, as flowStateAt says', async () => {
+    const graph = triageFlowGraph();
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const travel = timeline.travels.find(
+      (candidate) => candidate.edgeId === 'issues>open_issues',
+    );
+    if (travel === undefined) throw new Error('no travel');
+    const t = travel.start + (travel.end - travel.start) * 0.25;
+    await renderRun({ graph, playback: { timeline, t } });
+    const frame = flowStateAt(graph, timeline, t);
+    for (const each of graph.nodes)
+      expect(node(each.id)?.getAttribute('data-flow-state'), each.id).toBe(
+        frame.nodes[each.id]?.state,
+      );
+    expect(strip('issues')).toBe('Succeeded · 1.2 s');
+    expect(
+      screen.getByRole('button', { name: /^Issues \(Succeeded\)/ }),
+    ).toBeInTheDocument();
+
+    // One dot rides the line a value is on, a quarter of the way along.
+    const pulses = document.querySelectorAll('[data-flow-pulse]');
+    expect(pulses).toHaveLength(1);
+    expect(pulses[0]).toHaveAttribute('data-flow-pulse', 'issues>open_issues');
+    const animation = pulses[0]?.getAnimations()[0];
+    expect(animation?.playState).toBe('paused');
+    expect(Number(animation?.currentTime)).toBeCloseTo(
+      0.25 * FLOW_PULSE_DURATION,
+      0,
+    );
+  });
+
+  it('moves the dot with the moment, and scrubbing back resets the states', async () => {
+    const graph = triageFlowGraph();
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const travel = timeline.travels.find(
+      (candidate) => candidate.edgeId === 'issues>open_issues',
+    );
+    if (travel === undefined) throw new Error('no travel');
+    const at = (share: number) =>
+      travel.start + (travel.end - travel.start) * share;
+    const { rerun } = await renderRun({
+      graph,
+      playback: { timeline, t: at(0.25) },
+    });
+    rerun({ playback: { timeline, t: at(0.75) } });
+    await waitFor(() =>
+      expect(
+        Number(
+          document.querySelector('[data-flow-pulse]')?.getAnimations()[0]
+            ?.currentTime,
+        ),
+      ).toBeCloseTo(0.75 * FLOW_PULSE_DURATION, 0),
+    );
+    rerun({ playback: { timeline, t: 30 } });
+    await waitFor(() =>
+      expect(node('issues')).toHaveAttribute('data-flow-state', 'pending'),
+    );
+    expect(
+      document.querySelector('[data-flow-pulse="issues>open_issues"]'),
+    ).toBeNull();
+  });
+
+  it('draws no dots under reduced motion: the lines say when a value arrived', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const graph = triageFlowGraph();
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const travel = timeline.travels[1];
+    const t = travel ? (travel.start + travel.end) / 2 : 0;
+    await renderRun({ graph, playback: { timeline, t } });
+    expect(document.querySelectorAll('[data-flow-pulse]')).toHaveLength(0);
+    expect(look('__start>issues')).toBe('travelled');
+  });
+
+  it('brings a failed run’s way to its failure forward', async () => {
+    const graph = triageFlowGraph();
+    const timeline: FlowPlaybackTimeline =
+      buildPlaybackTimeline(triageFailedRun());
+    const { rerun } = await renderRun({
+      graph,
+      playback: { timeline, t: timeline.duration },
+    });
+    expect(node('score')).toHaveAttribute('data-flow-state', 'failed');
+    expect(strip('score')).toBe(
+      'The model provider refused the request · 4 of 4 items',
+    );
+    expect(look('open_issues>score')).toBe('error');
+    expect(look('issues>open_issues')).toBe('travelled');
+    // Off the way there: stepped back, dashed, words kept.
+    expect(node('report')).toHaveAttribute('data-flow-quiet', 'true');
+    expect(look('score>report')).toBe('quiet');
+    expect(node('__end')).toHaveAttribute('data-flow-state', 'failed');
+    // The frame counts the items.
+    expect(
+      document.querySelector('[data-slot="flow-frame-counter"]')?.textContent,
+    ).toBe('4 of 4 items');
+
+    rerun({
+      playback: { timeline, t: timeline.duration },
+      focusFailure: false,
+    });
+    await waitFor(() =>
+      expect(node('report')).not.toHaveAttribute('data-flow-quiet'),
+    );
+  });
+
+  it('says the run stopped here when the host gave no error line', async () => {
+    const graph = triageFlowGraph();
+    await renderRun({
+      graph,
+      overlay: {
+        finished: true,
+        nodes: {
+          issues: { state: 'succeeded' },
+          open_issues: { state: 'succeeded' },
+          score: { state: 'failed' },
+        },
+      },
+    });
+    expect(strip('score')).toBe('The run stopped here');
+    expect(strip('report')).toBe('Not run');
+  });
+
+  it('shows how each condition decided, and quiets the branch not taken', async () => {
+    await renderRun({ graph: branchFlowGraph(), overlay: branchRunOverlay() });
+    const decision = node('__gate:urgent')?.querySelector(
+      '[data-slot="flow-gate-decision"]',
+    );
+    expect(decision?.textContent).toBe('No');
+    expect(look('__gate:urgent>urgent')).toBe('quiet');
+    const labels = Array.from(
+      document.querySelectorAll<HTMLElement>('[data-flow-edge-label]'),
+    );
+    expect(
+      labels.filter((label) => label.dataset.taken === 'true'),
+    ).toHaveLength(2);
+    expect(
+      labels.filter((label) => label.dataset.taken === 'false'),
+    ).toHaveLength(2);
+    expect(node('urgent')).toHaveAttribute('data-flow-state', 'skipped');
+    expect(strip('urgent')).toBe('Skipped: the condition is false');
+    expect(
+      screen.getByRole('button', {
+        name: /^Condition for Urgent: urgent of Classify is true \(Condition was false\)/,
+      }),
+    ).toBeInTheDocument();
+    expect(
+      document.querySelector('[data-slot="flow-frame-counter"]')?.textContent,
+    ).toBe('Pass 3 of 5');
+  });
+});
+
+describe('WorkflowCanvas highlights', () => {
+  it('highlights the paths through No when a pointer rests on its label', async () => {
+    const onHighlightChange = vi.fn();
+    await renderRun({
+      graph: branchFlowGraph(),
+      paths: BRANCH_PATHS,
+      onHighlightChange,
+    });
+    const no = Array.from(
+      document.querySelectorAll<HTMLElement>('[data-flow-edge-label]'),
+    ).find(
+      (label) => label.dataset.flowEdgeLabel === '__gate:urgent>__gate:normal',
+    );
+    if (no === undefined) throw new Error('no No label');
+    await userEvent.hover(no);
+    await waitFor(() => expect(look('__gate:urgent>urgent')).toBe('quiet'));
+    expect(look('__gate:urgent>__gate:normal')).toBe('emphasis');
+    expect(node('urgent')).toHaveAttribute('data-flow-quiet', 'true');
+    expect(node('normal')).toHaveAttribute('data-flow-highlighted', 'default');
+    expect(node('low')).toHaveAttribute('data-flow-highlighted', 'default');
+    expect(onHighlightChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({ nodes: expect.any(Set) }),
+    );
+    await userEvent.unhover(no);
+    await waitFor(() => expect(look('__gate:urgent>urgent')).toBe('base'));
+    expect(onHighlightChange).toHaveBeenLastCalledWith(null);
+  });
+
+  it('brings a node’s own lines forward under the pointer, quieting nothing', async () => {
+    await renderRun({ graph: triageFlowGraph() });
+    await userEvent.hover(screen.getByRole('button', { name: 'Open issues' }));
+    await waitFor(() => expect(look('issues>open_issues')).toBe('emphasis'));
+    expect(look('open_issues>score')).toBe('emphasis');
+    expect(look('score>report')).toBe('base');
+    expect(document.querySelector('[data-flow-quiet]')).toBeNull();
+  });
+
+  it('shows a host highlight with its reasons, and says it once', async () => {
+    const graph = branchFlowGraph();
+    const highlight = {
+      ...highlightForNodes(graph, ['fetch', 'classify'], { tone: 'error' }),
+      reasons: { merge: 'Not on this path' },
+      announcement: 'Showing the nodes that end a run',
+    };
+    const { rerun } = await renderRun({ graph, highlight });
+    expect(node('fetch')).toHaveAttribute('data-flow-highlighted', 'error');
+    expect(strip('merge')).toBe('Not on this path');
+    const status = document.querySelector('[data-slot="flow-announcer"]');
+    await waitFor(() =>
+      expect(status).toHaveTextContent('Showing the nodes that end a run'),
+    );
+    rerun({ highlight: { ...highlight } });
+    expect(status?.querySelectorAll('span')).toHaveLength(1);
+    rerun({ highlight: null });
+    await waitFor(() =>
+      expect(node('fetch')).not.toHaveAttribute('data-flow-highlighted'),
+    );
+  });
+
+  it.each(['light', 'dark'])(
+    'keeps quiet lines and every strip readable, and passes axe (%s)',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      const { container } = await renderRun({
+        graph: branchFlowGraph(),
+        overlay: branchRunOverlay(),
+      });
+      const result = await axe.run(container, {
+        runOnly: [
+          'color-contrast',
+          'aria-allowed-attr',
+          'aria-valid-attr-value',
+          'button-name',
+          'nested-interactive',
+        ],
+      });
+      expect(result.violations).toEqual([]);
+      const pane = container.querySelector('.react-flow__pane');
+      if (pane === null) throw new Error('no pane');
+      for (const path of container.querySelectorAll<SVGPathElement>(
+        'path[data-flow-edge-state]',
+      )) {
+        if (getComputedStyle(path).opacity === '0') continue;
+        expect(
+          ratioAgainst(pane, getComputedStyle(path).stroke),
+          `${theme} ${path.getAttribute('data-flow-edge-state')}`,
+        ).toBeGreaterThanOrEqual(3);
+      }
+      for (const element of container.querySelectorAll(
+        '[data-slot="flow-node-strip"], [data-slot="flow-gate-decision"], [data-slot="flow-frame-counter"]',
+      ))
+        expect(
+          ratioAgainst(element, getComputedStyle(element).color),
+          `${theme} ${element.textContent}`,
+        ).toBeGreaterThanOrEqual(4.5);
+    },
+  );
+});
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
index 6a785e06c8..879a031646 100644
--- a/packages/ui/src/components/flow/workflow-canvas.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -46,6 +46,26 @@ import {
   flowTabStop,
 } from './interaction/navigation';
 import { useFlowLayout } from './layout/use-flow-layout';
+import {
+  FLOW_DURATION,
+  FLOW_MOVE_TRANSITION,
+  FLOW_RING_TOTAL,
+} from './motion/flow-motion';
+import {
+  useLayoutTransition,
+  type FlowPicture,
+  type FlowTransitionPhase,
+  type FlowTransitionPlan,
+} from './motion/use-layout-transition';
+import {
+  highlightForBranch,
+  highlightForIncident,
+  sameFlowHighlight,
+  type FlowHighlight,
+  type FlowPath,
+} from './paths/highlight';
+import { flowStateAt, flowStateFromOverlay } from './playback/derive-state';
+import type { FlowPlayback, FlowRunOverlay } from './playback/types';
 import { FlowEdgeMarkers } from './render/edge-markers';
 import { FlowEntryNodeView } from './render/entry-node';
 import { FlowExitNodeView } from './render/exit-node';
@@ -55,6 +75,8 @@ import {
 } from './render/flow-render-context';
 import { FlowGateNodeView } from './render/gate-node';
 import { FlowGroupFrameView, type FlowFrameData } from './render/group-frame';
+import { flowFrameCounters, flowLooks, looksSignature } from './render/looks';
+import { FlowPulseLayer } from './render/pulse-layer';
 import {
   FlowRoutedEdgeView,
   type FlowRoutedEdgeData,
@@ -70,7 +92,7 @@ export interface WorkflowCanvasProps {
   'aria-label': string;
   /** What the graph is a picture of; a change is another picture (laid
    *  out afresh, swapped in with a fade), the same key with a changed graph
-   *  a live relayout. */
+   *  a live relayout (it glides to its new layout). */
   layoutKey: string;
   selectedId?: string | null;
   onSelect?: (id: string | null) => void;
@@ -81,6 +103,29 @@ export interface WorkflowCanvasProps {
   /** The region a node's button opens (an inspector): nodes then say
    *  whether it is open (`aria-expanded`) instead of `aria-pressed`. */
   controlsId?: string;
+  /** A run shown without time: where each node ended. */
+  overlay?: FlowRunOverlay;
+  /** A run with time, at the host's moment `t`; wins over `overlay`. */
+  playback?: FlowPlayback;
+  /**
+   * When a run failed, bring the way it took to the first failure
+   * forward and step back from the rest, until a highlight takes over.
+   * @default true
+   */
+  focusFailure?: boolean;
+  /** The possible paths: a pointer resting on a condition or on a Yes or
+   *  No label then highlights the paths through it. An empty list (the
+   *  host could not list them) highlights what lies below the branch. */
+  paths?: readonly FlowPath[];
+  /** The host's highlight (a pinned path, the nodes that end a run when
+   *  they fail). It wins over the canvas's own; `null` leaves the
+   *  canvas's own hover and focus highlights. */
+  highlight?: FlowHighlight | null;
+  /** The canvas's own highlight changed (a pointer or the keyboard). */
+  onHighlightChange?: (highlight: FlowHighlight | null) => void;
+  /** Nodes that changed outside this tab (another window, a coding
+   *  agent): ringed once when `key` changes, after their relayout. */
+  changed?: { ids: ReadonlySet<string>; key: string | number };
   /** Controlled view; the built-in chart/list toggle is hidden. */
   view?: FlowView;
   onViewChange?: (view: FlowView) => void;
@@ -126,9 +171,14 @@ const TOUCH_HINT_KEY = 'tale:flow-touch-hint';
 const REVEAL_MARGIN = 24;
 /** How long the two-finger hint stays. */
 const TOUCH_HINT_MS = 1_500;
+/** How long a pointer rests on a condition or a branch before its paths
+ *  light up: passing over on the way elsewhere lights nothing. */
+const HOVER_INTENT_MS = 150;
 
 /** The frame node behind a group's members. */
 const frameNodeId = (groupId: string) => `__frame:${groupId}`;
+/** A part leaving with a relayout, beside the one that replaces it. */
+const leavingId = (id: string) => `${id}~exit`;
 
 /**
  * How far to move the span `[start, end]` so it shows inside `[min, max]`:
@@ -162,38 +212,98 @@ const relative = (rect: FlowRect, origin: FlowRect): FlowRect => ({
   height: rect.height,
 });
 
-/** React Flow's nodes for a layout: frames behind, boxes on top. */
-function toFlowNodes(graph: FlowGraph, layout: FlowLayout): Node[] {
+/**
+ * The graph to draw on `layout`: the one it was laid out for, each node,
+ * line and frame in its newest words. While a relayout is under way a
+ * removed node stays where it was (it leaves with the new layout) and a new
+ * one waits for its place.
+ */
+function shownGraph(graph: FlowGraph, laidOut: FlowGraph | null): FlowGraph {
+  if (laidOut === null || laidOut === graph) return graph;
+  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+  const edges = new Map(graph.edges.map((edge) => [edge.id, edge]));
+  const groups = new Map(
+    (graph.groups ?? []).map((group) => [group.id, group]),
+  );
+  return {
+    nodes: laidOut.nodes.map((node) => nodes.get(node.id) ?? node),
+    edges: laidOut.edges.map((edge) => edges.get(edge.id) ?? edge),
+    groups: (laidOut.groups ?? []).map(
+      (group) => groups.get(group.id) ?? group,
+    ),
+  };
+}
+
+/** React Flow's nodes for a layout: frames behind, boxes on top, and while
+ *  a relayout plays, what leaves at its old place. */
+function toFlowNodes(
+  graph: FlowGraph,
+  layout: FlowLayout,
+  plan: FlowTransitionPlan | null,
+  phase: FlowTransitionPhase | null,
+): Node[] {
   const nodes: Node[] = [];
+  const glide = (moving: boolean): Record<string, string> =>
+    plan !== null && moving ? { transition: FLOW_MOVE_TRANSITION } : {};
+  const frameNode = (
+    id: string,
+    data: FlowFrameData,
+    rect: FlowRect,
+    style: Record<string, string>,
+  ): Node => ({
+    id,
+    type: 'frame',
+    position: { x: rect.x, y: rect.y },
+    width: rect.width,
+    height: rect.height,
+    zIndex: -1,
+    selectable: false,
+    focusable: false,
+    draggable: false,
+    style: { pointerEvents: 'none', ...style },
+    domAttributes: { 'aria-roledescription': undefined },
+    data,
+  });
+  if (plan !== null && phase === 'exit')
+    for (const { group, rect } of plan.framesLeaving)
+      nodes.push(
+        frameNode(
+          leavingId(frameNodeId(group.id)),
+          {
+            group,
+            header: relative(rect.header, rect),
+            members: [],
+            phase: 'exit',
+          },
+          rect,
+          {},
+        ),
+      );
   for (const group of graph.groups ?? []) {
     const frame = layout.groups[group.id];
     if (frame === undefined) continue;
-    const data: FlowFrameData = {
-      group,
-      header: relative(frame.header, frame),
-      members: group.members.flatMap((id) => {
-        const rect = layout.nodes[id];
-        return rect ? [relative(rect, frame)] : [];
-      }),
-    };
-    nodes.push({
-      id: frameNodeId(group.id),
-      type: 'frame',
-      position: { x: frame.x, y: frame.y },
-      width: frame.width,
-      height: frame.height,
-      zIndex: -1,
-      selectable: false,
-      focusable: false,
-      draggable: false,
-      style: { pointerEvents: 'none' },
-      domAttributes: { 'aria-roledescription': undefined },
-      data,
-    });
+    const entering = plan?.framesEntering.has(group.id) === true;
+    nodes.push(
+      frameNode(
+        frameNodeId(group.id),
+        {
+          group,
+          header: relative(frame.header, frame),
+          members: group.members.flatMap((id) => {
+            const rect = layout.nodes[id];
+            return rect ? [relative(rect, frame)] : [];
+          }),
+          ...(entering ? { phase: 'enter' as const } : {}),
+        },
+        frame,
+        glide(plan?.framesMoving.has(group.id) === true),
+      ),
+    );
   }
   for (const node of graph.nodes) {
     const rect = layout.nodes[node.id];
     if (rect === undefined) continue;
+    const entering = plan?.entering.has(node.id) === true;
     nodes.push({
       id: node.id,
       type: node.kind,
@@ -205,11 +315,29 @@ function toFlowNodes(graph: FlowGraph, layout: FlowLayout): Node[] {
       draggable: false,
       // React Flow turns pointer events off on a node that is neither
       // selectable nor draggable; the box is a real button and needs them.
-      style: { pointerEvents: 'all' },
+      style: {
+        pointerEvents: 'all',
+        ...glide(plan?.moving.has(node.id) === true),
+      },
       domAttributes: { 'aria-roledescription': undefined },
-      data: { node },
+      data: entering ? { node, phase: 'enter' } : { node },
     });
   }
+  if (plan !== null && phase === 'exit')
+    for (const { node, rect } of plan.leaving)
+      nodes.push({
+        id: node.id,
+        type: node.kind,
+        position: { x: rect.x, y: rect.y },
+        width: rect.width,
+        height: rect.height,
+        selectable: false,
+        focusable: false,
+        draggable: false,
+        style: { pointerEvents: 'none' },
+        domAttributes: { 'aria-roledescription': undefined },
+        data: { node, phase: 'exit' },
+      });
   return nodes;
 }
 
@@ -218,8 +346,22 @@ function toFlowEdges(
   layout: FlowLayout,
   baseId: string,
   labelOf: (edge: FlowEdge) => string | undefined,
+  plan: FlowTransitionPlan | null,
+  phase: FlowTransitionPhase | null,
 ): Edge[] {
   const edges: Edge[] = [];
+  const edgeOf = (id: string, edge: FlowEdge, data: FlowRoutedEdgeData) => ({
+    id,
+    source: edge.source,
+    target: edge.target,
+    type: 'routed',
+    selectable: false,
+    focusable: false,
+    // The nodes say what the lines mean; the lines stay out of the
+    // accessibility tree (React Flow names each in English).
+    domAttributes: { 'aria-hidden': true as const },
+    data,
+  });
   for (const edge of graph.edges) {
     if (edge.layoutOnly) continue;
     const route = layout.edges[edge.id];
@@ -230,28 +372,49 @@ function toFlowEdges(
     )
       continue;
     const text = labelOf(edge);
-    const data: FlowRoutedEdgeData = {
-      edge,
-      points: route.points,
-      baseId,
-      ...(text && route.label ? { label: { text, rect: route.label } } : {}),
-    };
-    edges.push({
-      id: edge.id,
-      source: edge.source,
-      target: edge.target,
-      type: 'routed',
-      selectable: false,
-      focusable: false,
-      // The nodes say what the lines mean; the lines stay out of the
-      // accessibility tree (React Flow names each in English).
-      domAttributes: { 'aria-hidden': true },
-      data,
-    });
+    edges.push(
+      edgeOf(edge.id, edge, {
+        edge,
+        points: route.points,
+        baseId,
+        ...(text && route.label ? { label: { text, rect: route.label } } : {}),
+        ...(plan?.edgesEntering.has(edge.id) ? { phase: 'enter' } : {}),
+      }),
+    );
+  }
+  if (plan !== null && phase === 'exit') {
+    const present = new Set([
+      ...graph.nodes
+        .filter((node) => layout.nodes[node.id] !== undefined)
+        .map((node) => node.id),
+      ...plan.leaving.map(({ node }) => node.id),
+    ]);
+    for (const { edge, points, label } of plan.edgesLeaving) {
+      if (!present.has(edge.source) || !present.has(edge.target)) continue;
+      const text = labelOf(edge);
+      edges.push(
+        edgeOf(leavingId(edge.id), edge, {
+          edge,
+          points,
+          baseId,
+          ...(text && label ? { label: { text, rect: label } } : {}),
+          phase: 'exit',
+        }),
+      );
+    }
   }
   return edges;
 }
 
+/** Keeps the value from the last render while its signature is the same,
+ *  so a playback frame that changed nothing re-renders nothing. */
+function useStable<T>(value: T, signature: string): T {
+  const kept = useRef<{ value: T; signature: string } | null>(null);
+  if (kept.current === null || kept.current.signature !== signature)
+    kept.current = { value, signature };
+  return kept.current.value;
+}
+
 /** A column of placeholder boxes in the real frame while the first layout
  *  is computed. */
 function ArrangingSkeleton({ label }: { label: string }) {
@@ -282,6 +445,13 @@ function WorkflowCanvasInner({
   revealId = null,
   issues = NO_ISSUES,
   controlsId,
+  overlay,
+  playback,
+  focusFailure = true,
+  paths,
+  highlight,
+  onHighlightChange,
+  changed,
   view: controlledView,
   onViewChange,
   framed = false,
@@ -344,7 +514,22 @@ function WorkflowCanvasInner({
           : undefined,
     [t],
   );
-  const { layout, status } = useFlowLayout(graph, { layoutKey, edgeLabel });
+  const {
+    layout,
+    status,
+    graph: laidOut,
+    settled,
+  } = useFlowLayout(graph, { layoutKey, edgeLabel });
+  const shown = useMemo(() => shownGraph(graph, laidOut), [graph, laidOut]);
+  const picture = useMemo<FlowPicture | null>(
+    () => (layout === null ? null : { graph: shown, layout }),
+    [shown, layout],
+  );
+  const { plan, phase } = useLayoutTransition({
+    picture,
+    layoutKey,
+    enabled: !reduced,
+  });
 
   // Once per layout, whatever the identity of the host's callback.
   const onLayoutRef = useRef(onLayout);
@@ -353,29 +538,116 @@ function WorkflowCanvasInner({
     if (layout) onLayoutRef.current?.(layout);
   }, [layout]);
 
-  const words = useMemo(
+  // The run shown, at the host's moment.
+  const run = useMemo(
+    () =>
+      playback
+        ? flowStateAt(shown, playback.timeline, playback.t)
+        : overlay
+          ? flowStateFromOverlay(shown, overlay)
+          : null,
+    [shown, playback, overlay],
+  );
+
+  // The canvas's own highlight: a pointer or the keyboard on a node (its
+  // lines only), or a pointer resting on a condition or a branch (its
+  // paths). A host's highlight wins; a failed run's way to its failure
+  // stands in when nothing else is shown.
+  const [own, setOwnState] = useState<FlowHighlight | null>(null);
+  const ownRef = useRef(own);
+  ownRef.current = own;
+  const onHighlightChangeRef = useRef(onHighlightChange);
+  onHighlightChangeRef.current = onHighlightChange;
+  const setOwn = useCallback((next: FlowHighlight | null) => {
+    if (sameFlowHighlight(ownRef.current, next)) return;
+    ownRef.current = next;
+    setOwnState(next);
+    onHighlightChangeRef.current?.(next);
+  }, []);
+  const failure =
+    focusFailure && run?.failure !== undefined ? run.failure : null;
+  const failureHighlight = useMemo<FlowHighlight | null>(
     () =>
-      describeFlowGraph(graph, {
+      failure === null
+        ? null
+        : { nodes: failure.pathNodes, edges: failure.pathEdges },
+    [failure],
+  );
+  const ownPath = own !== null && own.quietRest !== false ? own : null;
+  const incident = own !== null && own.quietRest === false ? own : null;
+  const primary = highlight ?? ownPath ?? failureHighlight;
+  // Why each node outside the host's highlight steps back.
+  const reasons = useMemo(() => {
+    if (primary?.reasons === undefined) return undefined;
+    const quiet: Record<string, string> = {};
+    for (const [id, reason] of Object.entries(primary.reasons))
+      if (!primary.nodes.has(id)) quiet[id] = reason;
+    return quiet;
+  }, [primary]);
+
+  const computedWords = useMemo(
+    () =>
+      describeFlowGraph(shown, {
         t,
         tIssues,
         list: flowListFormat(locale),
         issues,
+        run,
+        stoppedAt: failure?.nodeId ?? null,
+        reasons,
+      }),
+    [shown, t, tIssues, locale, issues, run, failure, reasons],
+  );
+  const words = useStable(
+    computedWords,
+    JSON.stringify([
+      [...computedWords.names],
+      [...computedWords.descriptions],
+      [...computedWords.strips],
+    ]),
+  );
+
+  const computedLooks = useMemo(
+    () =>
+      flowLooks({
+        graph: shown,
+        run,
+        primary,
+        incident,
+        ringPrimary: primary !== failureHighlight,
       }),
-    [graph, t, tIssues, locale, issues],
+    [shown, run, primary, incident, failureHighlight],
+  );
+  const looks = useStable(
+    computedLooks.nodes,
+    looksSignature(computedLooks.nodes),
+  );
+  const edgeLooks = useStable(
+    computedLooks.edges,
+    looksSignature(computedLooks.edges),
+  );
+  const computedCounters = useMemo(
+    () => flowFrameCounters(shown, run, t),
+    [shown, run, t],
+  );
+  const frameCounters = useStable(
+    computedCounters,
+    looksSignature(computedCounters),
   );
 
   const nodes = useMemo(
-    () => (layout ? toFlowNodes(graph, layout) : []),
-    [graph, layout],
+    () => (layout ? toFlowNodes(shown, layout, plan, phase) : []),
+    [shown, layout, plan, phase],
   );
   const edges = useMemo(
-    () => (layout ? toFlowEdges(graph, layout, baseId, edgeLabel) : []),
-    [graph, layout, baseId, edgeLabel],
+    () =>
+      layout ? toFlowEdges(shown, layout, baseId, edgeLabel, plan, phase) : [],
+    [shown, layout, baseId, edgeLabel, plan, phase],
   );
 
   const frameRef = useRef<HTMLDivElement>(null);
   const [lastFocused, setLastFocused] = useState<string | null>(null);
-  const tabStopId = flowTabStop(graph, selectedId, lastFocused);
+  const tabStopId = flowTabStop(shown, selectedId, lastFocused);
 
   const buttonOf = useCallback(
     (id: string) =>
@@ -419,6 +691,97 @@ function WorkflowCanvasInner({
     return () => cancelAnimationFrame(frame);
   }, [revealId, layout, view, reveal]);
 
+  // Once a relayout has settled, the open node is brought back into view
+  // if it moved out of it (a refit already shows it).
+  const settling = useRef(false);
+  useEffect(() => {
+    if (plan !== null) {
+      settling.current = true;
+      return undefined;
+    }
+    if (!settling.current) return undefined;
+    settling.current = false;
+    if (selectedId === null || view !== 'chart') return undefined;
+    const frame = requestAnimationFrame(() => reveal(selectedId));
+    return () => cancelAnimationFrame(frame);
+  }, [plan, selectedId, view, reveal]);
+
+  // While a run plays, the node it reaches is followed into view, as long
+  // as the reader has not moved the view themselves.
+  const following = useRef(true);
+  const playing = playback !== undefined;
+  useEffect(() => {
+    following.current = true;
+  }, [layoutKey, playing]);
+  // One string per set of running nodes: a new frame of the same set says
+  // nothing new.
+  const runningKey =
+    playback && run
+      ? Object.entries(run.nodes)
+          .filter(([, info]) => info.state === 'running')
+          .map(([id]) => id)
+          .join('\n')
+      : '';
+  const lastRunning = useRef<readonly string[]>([]);
+  useEffect(() => {
+    const ids = runningKey === '' ? [] : runningKey.split('\n');
+    const fresh = ids.find((id) => !lastRunning.current.includes(id));
+    lastRunning.current = ids;
+    if (fresh === undefined || !following.current || view !== 'chart')
+      return undefined;
+    const frame = requestAnimationFrame(() => reveal(fresh));
+    return () => cancelAnimationFrame(frame);
+  }, [runningKey, view, reveal]);
+
+  // Strips settle softly while a run plays on; going back swaps them.
+  const playbackT = playback?.t ?? null;
+  const [clock, setClock] = useState<{ t: number | null; forward: boolean }>({
+    t: playbackT,
+    forward: false,
+  });
+  if (clock.t !== playbackT)
+    setClock({
+      t: playbackT,
+      forward: playbackT !== null && clock.t !== null && playbackT > clock.t,
+    });
+  const forward = clock.forward;
+
+  // A change made outside this tab rings its nodes once, after their
+  // relayout. The key the canvas opens with is never rung.
+  const rungKey = useRef(changed?.key);
+  const [ring, setRing] = useState<FlowRenderContextValue['ring']>(null);
+  useEffect(() => {
+    if (changed === undefined || !settled || layout === null) return;
+    if (rungKey.current === changed.key) return;
+    rungKey.current = changed.key;
+    if (!reduced) setRing({ ids: changed.ids, key: changed.key });
+  }, [changed, settled, layout, reduced]);
+  useEffect(() => {
+    if (ring === null) return undefined;
+    const timer = setTimeout(() => setRing(null), FLOW_RING_TOTAL);
+    return () => clearTimeout(timer);
+  }, [ring]);
+
+  // A host's highlight says what it shows, once, politely.
+  const [spoken, setSpoken] = useState({ text: '', serial: 0 });
+  const lastSpoken = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    const text = highlight?.announcement;
+    if (text === lastSpoken.current) return;
+    lastSpoken.current = text;
+    if (text === undefined || text === '') return;
+    setSpoken((previous) => ({ text, serial: previous.serial + 1 }));
+  }, [highlight]);
+
+  const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  useEffect(() => () => clearTimeout(hoverTimer.current), []);
+  const nodeKind = useCallback(
+    (id: string) => shown.nodes.find((node) => node.id === id)?.kind,
+    [shown],
+  );
+
   const context = useMemo<FlowRenderContextValue>(
     () => ({
       baseId,
@@ -429,12 +792,18 @@ function WorkflowCanvasInner({
       names: words.names,
       descriptions: words.descriptions,
       strips: words.strips,
+      looks,
+      edgeLooks,
+      frameCounters,
+      stripSettle: forward && !reduced,
+      ring,
+      branchHover: paths !== undefined,
       onActivate: (id) => onSelect?.(selectedId === id ? null : id),
       onKeyDown: (id, event: KeyboardEvent<HTMLButtonElement>) => {
         const key = FLOW_NAVIGATION_KEYS[event.key];
         if (key === undefined || layout === null) return;
         event.preventDefault();
-        const next = flowNeighbour(graph, layout, id, key);
+        const next = flowNeighbour(shown, layout, id, key);
         // The canvas pans the box into view itself; the browser's own
         // scroll-into-view would shift the clipped frame instead.
         if (next !== null) buttonOf(next)?.focus({ preventScroll: true });
@@ -444,7 +813,44 @@ function WorkflowCanvasInner({
         // A mouse press focuses the button too, and panning then would drag
         // the box out from under the pointer mid-click — follow keyboard
         // focus only.
-        if (event.currentTarget.matches(':focus-visible')) reveal(id);
+        if (event.currentTarget.matches(':focus-visible')) {
+          reveal(id);
+          // The keyboard brings a node's own lines forward; a condition's
+          // paths are the Paths list's to show, so tabbing never flickers.
+          setOwn(highlightForIncident(shown, id));
+        }
+      },
+      onBlurNode: () => {
+        if (ownRef.current?.quietRest === false) setOwn(null);
+      },
+      onHoverNode: (id) => {
+        clearTimeout(hoverTimer.current);
+        if (id === null) {
+          setOwn(null);
+          return;
+        }
+        if (nodeKind(id) === 'gate' && paths !== undefined) {
+          hoverTimer.current = setTimeout(
+            () => setOwn(highlightForBranch(shown, paths, id)),
+            HOVER_INTENT_MS,
+          );
+          return;
+        }
+        setOwn(highlightForIncident(shown, id));
+      },
+      onHoverBranch: (branch) => {
+        clearTimeout(hoverTimer.current);
+        if (branch === null || paths === undefined) {
+          setOwn(null);
+          return;
+        }
+        hoverTimer.current = setTimeout(
+          () =>
+            setOwn(
+              highlightForBranch(shown, paths, branch.gateId, branch.decision),
+            ),
+          HOVER_INTENT_MS,
+        );
       },
     }),
     [
@@ -454,11 +860,20 @@ function WorkflowCanvasInner({
       controlsId,
       issues,
       words,
+      looks,
+      edgeLooks,
+      frameCounters,
+      forward,
+      reduced,
+      ring,
+      paths,
       onSelect,
       layout,
-      graph,
+      shown,
       buttonOf,
       reveal,
+      setOwn,
+      nodeKind,
     ],
   );
 
@@ -502,6 +917,20 @@ function WorkflowCanvasInner({
       </Button>
     ) : null;
 
+  const announcer = (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      className="sr-only"
+      data-slot="flow-announcer"
+    >
+      {spoken.text === '' ? null : (
+        <span key={spoken.serial}>{spoken.text}</span>
+      )}
+    </div>
+  );
+
   if (graph.nodes.length === 0 && empty !== undefined) {
     return <div className={cn('flex h-full flex-col', className)}>{empty}</div>;
   }
@@ -514,6 +943,7 @@ function WorkflowCanvasInner({
   return (
     <div className={cn('flex h-full min-h-0 flex-col', className)}>
       {notice}
+      {announcer}
       {view === 'list' ? (
         <div ref={swapRef} className={cn(frameClass, 'overflow-y-auto')}>
           <div className="flex items-center gap-1 px-3 pt-3">
@@ -530,6 +960,9 @@ function WorkflowCanvasInner({
             onSelect={onSelect}
             issues={issues}
             controlsId={controlsId}
+            run={run}
+            highlight={primary}
+            stoppedAt={failure?.nodeId ?? null}
           />
         </div>
       ) : (
@@ -541,6 +974,7 @@ function WorkflowCanvasInner({
           aria-describedby={helpId}
           aria-busy={layout === null}
           data-flow-engine={layout?.engine}
+          data-flow-transition={plan === null ? undefined : 'move'}
           className={frameClass}
           onTouchMove={onTouchMove}
         >
@@ -563,6 +997,7 @@ function WorkflowCanvasInner({
                   edgeTypes={EDGE_TYPES}
                   fitPolicy={fitPolicy}
                   fitKey={layout.signature}
+                  refitDuration={plan === null ? 0 : FLOW_DURATION.medium}
                   minZoom={0.25}
                   maxZoom={1.5}
                   // Every box is a real button holding the chart's one Tab
@@ -576,6 +1011,10 @@ function WorkflowCanvasInner({
                   panOnDrag={!pageScroll}
                   preventScrolling={!pageScroll}
                   zoomOnScroll={!pageScroll}
+                  onMoveStart={(event) => {
+                    // The reader moved the view: stop following the run.
+                    if (event !== null) following.current = false;
+                  }}
                   onPaneClick={() => {
                     if (selectedId !== null) onSelect?.(null);
                   }}
@@ -592,7 +1031,14 @@ function WorkflowCanvasInner({
                       </>
                     ) : undefined
                   }
-                />
+                >
+                  {run !== null && !reduced && (
+                    <FlowPulseLayer
+                      travelling={run.travelling}
+                      layout={layout}
+                    />
+                  )}
+                </FlowCanvas>
               </FlowRenderProvider>
             </div>
           )}
@@ -624,12 +1070,19 @@ function WorkflowCanvasInner({
  * below, every step from its own words, conditions as pills with Yes and
  * No, frames round iterating steps, and lines along routes that never cross
  * a box. Nobody places a node — the same graph always draws the same
- * picture, and a graph that changes on screen keeps every row in order.
+ * picture, and a graph that changes on screen glides to its new layout
+ * keeping every row in order.
+ *
+ * A run shows on it as an overlay (where each node ended) or a playback
+ * (the host's moment `t`, values travelling the lines); a failed run brings
+ * the way to its failure forward. Paths and highlights bring parts of the
+ * chart forward and step back from the rest — dashed, never faded.
  *
  * The chart is one Tab stop: arrows follow the lines and the rows, Home and
  * End jump to Start and End, Enter or Space opens a node. The List view
  * says the same as text. Layout runs in a worker; until the first one
- * lands the frame shows a skeleton column, then the chart fades in.
+ * lands the frame shows a skeleton column, then the chart fades in. Under
+ * reduced motion nothing glides, rings or travels.
  */
 export function WorkflowCanvas(props: WorkflowCanvasProps) {
   return (
diff --git a/packages/ui/src/globals.css b/packages/ui/src/globals.css
index 2454c411a5..20b8fa154f 100644
--- a/packages/ui/src/globals.css
+++ b/packages/ui/src/globals.css
@@ -813,6 +813,49 @@
   animation: row-enter 0.2s ease-out;
 }
 
+/* Workflow canvas motion (components/flow/motion/flow-motion.ts names the
+   timings; every one is skipped under reduced motion). A node that joins a
+   relaid chart grows in from the exit scale, one that leaves shrinks back
+   to it, a re-routed line fades out, a changed node's ring fades away, and
+   a running node's top bar sweeps across. Opacity and transform only. */
+@keyframes flow-enter {
+  from {
+    opacity: 0;
+    transform: scale(var(--scale-exit));
+  }
+}
+
+@keyframes flow-exit {
+  to {
+    opacity: 0;
+    transform: scale(var(--scale-exit));
+  }
+}
+
+@keyframes flow-fade-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes flow-ring-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes flow-running-sweep {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(100%);
+  }
+}
+
 /* Structured message sections (chat / agent output rendering). */
 .structured-conclusion {
   border-left: 2px solid hsl(var(--primary));
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index 2e88b4c5e8..f34f8bc7e4 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -558,6 +558,9 @@ flow:
   branch:
     'yes': Ja
     'no': Nein
+  group:
+    items: '{done} von {total, plural, one {# Element} other {# Elementen}}'
+    pass: Durchgang {pass} von {max}
   relation:
     comesFrom: Kommt von {list}
     leadsTo: Führt zu {list}
@@ -572,6 +575,9 @@ flow:
     skipped: Übersprungen
     stopped: Hier gestoppt
     notRun: Nicht ausgeführt
+    decidedYes: Bedingung traf zu
+    decidedNo: Bedingung traf nicht zu
+    failedHere: Der Lauf endete hier
   list:
     label: Nodes
     reads: Liest {list}
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index d808eea42f..e7c5d75794 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -558,6 +558,9 @@ flow:
   branch:
     'yes': 'Yes'
     'no': 'No'
+  group:
+    items: '{done} of {total, plural, one {# item} other {# items}}'
+    pass: Pass {pass} of {max}
   relation:
     comesFrom: Comes from {list}
     leadsTo: Leads to {list}
@@ -572,6 +575,9 @@ flow:
     skipped: Skipped
     stopped: Stopped here
     notRun: Not run
+    decidedYes: Condition was true
+    decidedNo: Condition was false
+    failedHere: The run stopped here
   list:
     label: Nodes
     reads: Reads {list}
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 0a92f85ddb..8de97c7837 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -558,6 +558,9 @@ flow:
   branch:
     'yes': Oui
     'no': Non
+  group:
+    items: '{done} sur {total, plural, one {# élément} other {# éléments}}'
+    pass: Passage {pass} sur {max}
   relation:
     comesFrom: Vient de {list}
     leadsTo: Mène à {list}
@@ -572,6 +575,9 @@ flow:
     skipped: Ignoré
     stopped: Arrêté ici
     notRun: Non exécuté
+    decidedYes: La condition était vraie
+    decidedNo: La condition était fausse
+    failedHere: L'exécution s'est arrêtée ici
   list:
     label: Nœuds
     reads: Lit {list}

From 06bdaaa46a3820c527a71dc3e6207efc8af4044f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:11:44 +0200
Subject: [PATCH 28/78] docs(ui): guide workflow paths and playback with live
 demos

Guides for the possible-paths list and run playback, the canvas guide's overlay and relayout sections, four live demos (static overlay, possible paths, playback with its bar, live relayout) and the matching stories.
---
 .../flow/workflow-canvas.stories.tsx          | 200 +++++++++++++++
 services/ui-docs/app/content/frontmatter.json |  14 +
 .../ui-docs/app/demos/flow/live-relayout.tsx  | 141 ++++++++++
 services/ui-docs/app/demos/flow/playback.tsx  | 241 ++++++++++++++++++
 .../ui-docs/app/demos/flow/possible-paths.tsx | 224 ++++++++++++++++
 .../ui-docs/app/demos/flow/static-overlay.tsx | 152 +++++++++++
 .../content/components/workflow-canvas.md     |  33 +++
 .../content/components/workflow-paths.md      | 105 ++++++++
 .../content/components/workflow-playback.md   |  92 +++++++
 services/ui-docs/content/nav.json             |   2 +
 services/ui-docs/content/published.json       |   2 +
 11 files changed, 1206 insertions(+)
 create mode 100644 services/ui-docs/app/demos/flow/live-relayout.tsx
 create mode 100644 services/ui-docs/app/demos/flow/playback.tsx
 create mode 100644 services/ui-docs/app/demos/flow/possible-paths.tsx
 create mode 100644 services/ui-docs/app/demos/flow/static-overlay.tsx
 create mode 100644 services/ui-docs/content/components/workflow-paths.md
 create mode 100644 services/ui-docs/content/components/workflow-playback.md

diff --git a/packages/ui/src/components/flow/workflow-canvas.stories.tsx b/packages/ui/src/components/flow/workflow-canvas.stories.tsx
index 0838cd9d30..7f587da548 100644
--- a/packages/ui/src/components/flow/workflow-canvas.stories.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.stories.tsx
@@ -2,11 +2,23 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
 
 import { TooltipProvider } from '../overlays/tooltip';
+import { FlowPathList } from './flow-path-list';
 import { FlowStepList } from './flow-step-list';
+import {
+  highlightForNodes,
+  highlightForPaths,
+  type FlowPath,
+} from './paths/highlight';
+import { buildPlaybackTimeline } from './playback/build-timeline';
+import { FlowPlaybackBar } from './playback/flow-playback-bar';
+import { usePlaybackClock } from './playback/use-playback-clock';
 import {
   branchFlowGraph,
+  branchRun,
+  branchRunOverlay,
   reviewPullRequestsFlowGraph,
   syntheticFlowGraph,
+  triageFailedRun,
   triageFlowGraph,
   triageInboxFlowGraph,
 } from './testing/flow-fixtures';
@@ -123,3 +135,191 @@ export const ListView: Story = {
     </div>
   ),
 };
+
+/** Where a finished run ended: decisions, a skipped branch, a failure in
+ *  focus, a repeat's passes. */
+export const RunOverlay: Story = {
+  render: () => (
+    <Selectable
+      graph={branchFlowGraph()}
+      overlay={branchRunOverlay()}
+      height={900}
+    />
+  ),
+};
+
+const TRIAGE_TIMELINE = buildPlaybackTimeline(triageFailedRun());
+
+function Replay() {
+  const clock = usePlaybackClock({ timeline: TRIAGE_TIMELINE });
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      <div style={{ height: 720 }}>
+        <WorkflowCanvas
+          graph={triageFlowGraph()}
+          aria-label="Triage GitHub issues, a run"
+          layoutKey="story-replay"
+          framed
+          playback={{ timeline: TRIAGE_TIMELINE, t: clock.t }}
+        />
+      </div>
+      <FlowPlaybackBar
+        timeline={TRIAGE_TIMELINE}
+        t={clock.t}
+        onTChange={clock.setT}
+        playing={clock.playing}
+        onPlayingChange={clock.setPlaying}
+        speed={clock.speed}
+        onSpeedChange={clock.setSpeed}
+      />
+    </div>
+  );
+}
+
+/** A failed run replayed: values travel the lines, Score fails on its
+ *  third issue. */
+export const Playback: Story = {
+  render: () => <Replay />,
+};
+
+const BRANCH_TIMELINE = buildPlaybackTimeline(branchRun());
+
+/** A wait, a skipped branch and a repeat, replayed. */
+export const PlaybackWithWait: Story = {
+  render: function PlaybackWithWait() {
+    const timeline = BRANCH_TIMELINE;
+    const clock = usePlaybackClock({ timeline });
+    return (
+      <div className="flex flex-col gap-2 p-4">
+        <div style={{ height: 900 }}>
+          <WorkflowCanvas
+            graph={branchFlowGraph()}
+            aria-label="Route a ticket, a run"
+            layoutKey="story-wait"
+            framed
+            playback={{ timeline, t: clock.t }}
+          />
+        </div>
+        <FlowPlaybackBar
+          timeline={timeline}
+          t={clock.t}
+          onTChange={clock.setT}
+          playing={clock.playing}
+          onPlayingChange={clock.setPlaying}
+        />
+      </div>
+    );
+  },
+};
+
+const BRANCH_PATHS: FlowPath[] = [
+  {
+    id: 'urgent',
+    label: 'Path 1',
+    nodes: [
+      'fetch',
+      'classify',
+      'enrich',
+      '__gate:urgent',
+      'urgent',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': true },
+  },
+  {
+    id: 'normal',
+    label: 'Path 2',
+    nodes: [
+      'fetch',
+      'classify',
+      'enrich',
+      '__gate:urgent',
+      '__gate:normal',
+      'normal',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': true },
+  },
+  {
+    id: 'low',
+    label: 'Path 3',
+    nodes: [
+      'fetch',
+      'classify',
+      'enrich',
+      '__gate:urgent',
+      '__gate:normal',
+      'low',
+      'merge',
+      'notify',
+      'poll',
+    ],
+    decisions: { 'when:urgent': false, 'when:normal': false },
+  },
+];
+
+/** The paths beside the chart: point at one to preview it, Enter pins. */
+export const Paths: Story = {
+  render: function Paths() {
+    const graph = branchFlowGraph();
+    const [preview, setPreview] = useState<string | null>(null);
+    const [pinned, setPinned] = useState<string | null>(null);
+    const shown = pinned ?? preview;
+    const path = BRANCH_PATHS.find((candidate) => candidate.id === shown);
+    const highlight =
+      shown === 'halts'
+        ? highlightForNodes(graph, ['fetch', 'classify', 'merge'], {
+            tone: 'error',
+          })
+        : path
+          ? highlightForPaths(graph, [path])
+          : null;
+    return (
+      <div className="flex gap-3 p-4">
+        <div className="border-border w-64 shrink-0 rounded-lg border py-2">
+          <FlowPathList
+            aria-label="Paths a run can take"
+            sections={[
+              {
+                id: 'paths',
+                rows: BRANCH_PATHS.map((each) => ({
+                  id: each.id,
+                  title: each.label ?? each.id,
+                })),
+              },
+              {
+                id: 'halt',
+                title: 'Ends the run when it fails',
+                rows: [
+                  {
+                    id: 'halts',
+                    title: 'Fetch, Classify, Merge',
+                    pinnable: false,
+                  },
+                ],
+              },
+            ]}
+            previewId={preview}
+            pinnedId={pinned}
+            onPreview={setPreview}
+            onPin={setPinned}
+          />
+        </div>
+        <div style={{ height: 900 }} className="min-w-0 flex-1">
+          <WorkflowCanvas
+            graph={graph}
+            aria-label="Route a ticket"
+            layoutKey="story-paths"
+            framed
+            paths={BRANCH_PATHS}
+            highlight={highlight}
+          />
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/services/ui-docs/app/content/frontmatter.json b/services/ui-docs/app/content/frontmatter.json
index 1145e3830a..e13ec197b5 100644
--- a/services/ui-docs/app/content/frontmatter.json
+++ b/services/ui-docs/app/content/frontmatter.json
@@ -118,6 +118,20 @@
       "description": "Draw a workflow from its data with an automatic layout, lines that route round every box, a keyboard path through it and a List view that says the same in text."
     }
   },
+  "components/workflow-paths": {
+    "slug": "components/workflow-paths",
+    "frontmatter": {
+      "title": "Workflow paths",
+      "description": "Show every way a run can go through a workflow, preview and pin one path at a time, and point out the nodes that end a run when they fail."
+    }
+  },
+  "components/workflow-playback": {
+    "slug": "components/workflow-playback",
+    "frontmatter": {
+      "title": "Workflow playback",
+      "description": "Show how a run went on a workflow chart, and replay it with values travelling the lines, a scrubber and the failure in focus."
+    }
+  },
   "foundations/accessibility": {
     "slug": "foundations/accessibility",
     "frontmatter": {
diff --git a/services/ui-docs/app/demos/flow/live-relayout.tsx b/services/ui-docs/app/demos/flow/live-relayout.tsx
new file mode 100644
index 0000000000..03652dc3b2
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/live-relayout.tsx
@@ -0,0 +1,141 @@
+import { Button } from '@tale/ui/button';
+import type {
+  FlowEdge,
+  FlowGraph,
+  FlowIcon,
+  FlowNode,
+  FlowStepNode,
+} from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Braces, Mail, Sparkles } from 'lucide-react';
+import { useState } from 'react';
+
+const step = (
+  id: string,
+  label: string,
+  typeLabel: string,
+  icon: FlowIcon = typeLabel === 'Transform' ? Braces : Sparkles,
+): FlowStepNode => ({ id, kind: 'step', label, typeLabel, icon });
+
+const edge = (
+  source: string,
+  target: string,
+  kind: FlowEdge['kind'] = 'data',
+): FlowEdge => ({ id: `${source}>${target}`, source, target, kind });
+
+const START: FlowNode = {
+  id: '__start',
+  kind: 'entry',
+  triggers: [],
+  inputs: [{ id: 'ticket', label: 'ticket', detail: 'an object', code: true }],
+};
+const END: FlowNode = {
+  id: '__end',
+  kind: 'exit',
+  outputs: [{ id: 'reply', label: 'The output of Reply' }],
+};
+
+// Three versions of one workflow, as a coding agent might save them. The
+// layoutKey stays the same, so the canvas glides from one to the next.
+const VERSIONS: FlowGraph[] = [
+  {
+    nodes: [
+      START,
+      step('fetch', 'Fetch', 'HTTP · Get'),
+      step('reply', 'Reply', 'Language model'),
+      END,
+    ],
+    edges: [
+      edge('__start', 'fetch', 'entry'),
+      edge('fetch', 'reply'),
+      edge('reply', '__end', 'exit'),
+    ],
+  },
+  {
+    nodes: [
+      START,
+      step('fetch', 'Fetch', 'HTTP · Get'),
+      step('classify', 'Classify', 'Language model'),
+      step('reply', 'Reply', 'Language model'),
+      END,
+    ],
+    edges: [
+      edge('__start', 'fetch', 'entry'),
+      edge('fetch', 'classify'),
+      edge('fetch', 'reply'),
+      edge('classify', 'reply'),
+      edge('reply', '__end', 'exit'),
+    ],
+  },
+  {
+    nodes: [
+      START,
+      step('fetch', 'Fetch', 'HTTP · Get'),
+      step('classify', 'Classify', 'Language model'),
+      step('reply', 'Reply', 'Language model'),
+      step('notify', 'Notify', 'Email · Send', Mail),
+      END,
+    ],
+    edges: [
+      edge('__start', 'fetch', 'entry'),
+      edge('fetch', 'classify'),
+      edge('fetch', 'reply'),
+      edge('classify', 'reply'),
+      edge('classify', 'notify'),
+      edge('reply', '__end', 'exit'),
+      edge('notify', '__end', 'completion'),
+    ],
+  },
+];
+
+/** The nodes a version adds or rewires, ringed once when it arrives. */
+const CHANGED: ReadonlySet<string>[] = [
+  new Set(['reply']),
+  new Set(['classify', 'reply']),
+  new Set(['notify']),
+];
+
+export default function FlowLiveRelayoutDemo() {
+  const [version, setVersion] = useState(0);
+  const [selected, setSelected] = useState<string | null>(null);
+  const graph = VERSIONS[version] ?? VERSIONS[0];
+  return (
+    <div className="flex w-full flex-col gap-3">
+      <div className="flex flex-wrap gap-2">
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={version === VERSIONS.length - 1}
+          onClick={() => setVersion((at) => at + 1)}
+        >
+          Save the next version
+        </Button>
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={version === 0}
+          onClick={() => setVersion((at) => at - 1)}
+        >
+          Go back a version
+        </Button>
+      </div>
+      <div className="h-[32rem]">
+        <WorkflowCanvas
+          graph={graph}
+          aria-label="Answer a ticket"
+          layoutKey="answer-a-ticket"
+          framed
+          selectedId={selected}
+          onSelect={setSelected}
+          changed={{
+            ids: CHANGED[version] ?? new Set(),
+            key: version,
+          }}
+        />
+      </div>
+      <p className="text-muted-foreground text-sm" aria-live="polite">
+        Version {version + 1} of {VERSIONS.length}
+      </p>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/playback.tsx b/services/ui-docs/app/demos/flow/playback.tsx
new file mode 100644
index 0000000000..ac4ca57269
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/playback.tsx
@@ -0,0 +1,241 @@
+import {
+  buildPlaybackTimeline,
+  flowStateAt,
+  usePlaybackClock,
+  type FlowRealRun,
+} from '@tale/ui/flow/playback';
+import { FlowPlaybackBar, formatFlowClock } from '@tale/ui/flow/playback-bar';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Braces, MessageSquare, Send, Sparkles } from 'lucide-react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    {
+      id: '__start',
+      kind: 'entry',
+      triggers: [],
+      inputs: [
+        { id: 'ticket', label: 'ticket', detail: 'an object', code: true },
+      ],
+    },
+    {
+      id: 'fetch',
+      kind: 'step',
+      label: 'Fetch',
+      icon: Send,
+      typeLabel: 'HTTP · Get',
+    },
+    {
+      id: 'classify',
+      kind: 'step',
+      label: 'Classify',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'fetch', label: 'Fetch' }],
+    },
+    {
+      id: '__gate:escalate',
+      kind: 'gate',
+      label: 'Escalate',
+      mode: 'if-else',
+      condition: 'the priority of Classify is "urgent"',
+    },
+    {
+      id: 'escalate',
+      kind: 'step',
+      label: 'Escalate',
+      icon: MessageSquare,
+      typeLabel: 'Slack · Send message',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'answer',
+      kind: 'step',
+      label: 'Answer',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'log',
+      kind: 'step',
+      label: 'Log',
+      icon: Braces,
+      typeLabel: 'Transform',
+      reads: [
+        { id: 'escalate', label: 'Escalate' },
+        { id: 'answer', label: 'Answer' },
+      ],
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'log', label: 'The output of Log' }],
+    },
+  ],
+  edges: [
+    { id: 's>fetch', source: '__start', target: 'fetch', kind: 'entry' },
+    { id: 'fetch>classify', source: 'fetch', target: 'classify', kind: 'data' },
+    {
+      id: 'classify>gate',
+      source: 'classify',
+      target: '__gate:escalate',
+      kind: 'order',
+    },
+    {
+      id: 'gate>escalate',
+      source: '__gate:escalate',
+      target: 'escalate',
+      kind: 'branch-yes',
+    },
+    {
+      id: 'classify>escalate',
+      source: 'classify',
+      target: 'escalate',
+      kind: 'data',
+    },
+    {
+      id: 'gate>answer',
+      source: '__gate:escalate',
+      target: 'answer',
+      kind: 'branch-no',
+    },
+    {
+      id: 'classify>answer',
+      source: 'classify',
+      target: 'answer',
+      kind: 'data',
+    },
+    { id: 'escalate>log', source: 'escalate', target: 'log', kind: 'data' },
+    { id: 'answer>log', source: 'answer', target: 'log', kind: 'data' },
+    { id: 'log>end', source: 'log', target: '__end', kind: 'exit' },
+  ],
+};
+
+const START = Date.UTC(2025, 9, 9, 7, 0, 0);
+const at = (ms: number) => START + ms;
+const APPROVED = 3 * 60 * 60 * 1000;
+const skipped = 'Skipped: the condition is false';
+
+// A run as a host records it, in real time: Answer waits three hours for
+// an approval, then Log fails.
+const RUN: FlowRealRun = {
+  startedAt: at(0),
+  endedAt: at(APPROVED + 3_300),
+  spans: [
+    {
+      nodeId: 'fetch',
+      startedAt: at(20),
+      endedAt: at(420),
+      outcome: 'succeeded',
+      detail: '0.4 s',
+    },
+    {
+      nodeId: 'classify',
+      startedAt: at(430),
+      endedAt: at(1_830),
+      outcome: 'succeeded',
+      detail: '1.4 s',
+    },
+    {
+      nodeId: '__gate:escalate',
+      startedAt: at(1_840),
+      endedAt: at(1_840),
+      outcome: 'succeeded',
+      decision: false,
+    },
+    {
+      nodeId: 'escalate',
+      startedAt: at(1_840),
+      endedAt: at(1_840),
+      outcome: 'skipped',
+      reason: skipped,
+    },
+    {
+      nodeId: 'answer',
+      startedAt: at(1_850),
+      endedAt: at(APPROVED),
+      outcome: 'waiting',
+      reason: 'Waiting for approval',
+    },
+    {
+      nodeId: 'answer',
+      startedAt: at(APPROVED),
+      endedAt: at(APPROVED + 2_400),
+      outcome: 'succeeded',
+      detail: '2.4 s',
+    },
+    {
+      nodeId: 'log',
+      startedAt: at(APPROVED + 2_410),
+      endedAt: at(APPROVED + 3_300),
+      outcome: 'failed',
+      reason: 'The log service did not answer',
+    },
+  ],
+  travels: [
+    { edgeId: 's>fetch', at: at(0), target: 'fetch' },
+    {
+      edgeId: 'fetch>classify',
+      at: at(420),
+      target: 'classify',
+      summary: 'the ticket',
+    },
+    { edgeId: 'classify>gate', at: at(1_830), target: '__gate:escalate' },
+    { edgeId: 'gate>answer', at: at(1_840), target: 'answer' },
+    { edgeId: 'classify>answer', at: at(1_840), target: 'answer' },
+    { edgeId: 'answer>log', at: at(APPROVED + 2_400), target: 'log' },
+  ],
+  waits: [
+    {
+      startedAt: at(1_850),
+      endedAt: at(APPROVED),
+      label: 'Waited 3 h for approval',
+    },
+  ],
+};
+
+const TIMELINE = buildPlaybackTimeline(RUN);
+
+export default function FlowPlaybackDemo() {
+  const clock = usePlaybackClock({ timeline: TIMELINE });
+  // What is happening at the moment shown, for the scrubber's spoken value.
+  const frame = flowStateAt(GRAPH, TIMELINE, clock.t);
+  const activity = GRAPH.nodes
+    .flatMap((node) => {
+      const state = frame.nodes[node.id]?.state;
+      return node.kind === 'step' &&
+        (state === 'running' || state === 'waiting')
+        ? [`${node.label} ${state}`]
+        : [];
+    })
+    .join(', ');
+  return (
+    <div className="flex w-full flex-col gap-2">
+      <div className="h-[32rem]">
+        <WorkflowCanvas
+          graph={GRAPH}
+          aria-label="Answer a ticket, a run"
+          layoutKey="playback"
+          framed
+          playback={{ timeline: TIMELINE, t: clock.t }}
+        />
+      </div>
+      <FlowPlaybackBar
+        timeline={TIMELINE}
+        t={clock.t}
+        onTChange={clock.setT}
+        playing={clock.playing}
+        onPlayingChange={clock.setPlaying}
+        speed={clock.speed}
+        onSpeedChange={clock.setSpeed}
+        activity={activity}
+        // The clock shows how long the run really took, waits included.
+        formatTime={(t) => formatFlowClock(TIMELINE.toReal(t) - RUN.startedAt)}
+      />
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/possible-paths.tsx b/services/ui-docs/app/demos/flow/possible-paths.tsx
new file mode 100644
index 0000000000..4e2dc5ca92
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/possible-paths.tsx
@@ -0,0 +1,224 @@
+import {
+  FlowPathList,
+  type FlowPathListSection,
+} from '@tale/ui/flow/flow-path-list';
+import {
+  highlightForNodes,
+  highlightForPaths,
+  type FlowHighlight,
+  type FlowPath,
+} from '@tale/ui/flow/paths';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Braces, MessageSquare, Send, Sparkles } from 'lucide-react';
+import { useMemo, useState } from 'react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    {
+      id: '__start',
+      kind: 'entry',
+      triggers: [],
+      inputs: [
+        { id: 'ticket', label: 'ticket', detail: 'an object', code: true },
+      ],
+    },
+    {
+      id: 'fetch',
+      kind: 'step',
+      label: 'Fetch',
+      icon: Send,
+      typeLabel: 'HTTP · Get',
+    },
+    {
+      id: 'classify',
+      kind: 'step',
+      label: 'Classify',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'fetch', label: 'Fetch' }],
+    },
+    {
+      id: '__gate:escalate',
+      kind: 'gate',
+      label: 'Escalate',
+      mode: 'if-else',
+      condition: 'the priority of Classify is "urgent"',
+      decisionKey: 'when:escalate',
+    },
+    {
+      id: 'escalate',
+      kind: 'step',
+      label: 'Escalate',
+      icon: MessageSquare,
+      typeLabel: 'Slack · Send message',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'answer',
+      kind: 'step',
+      label: 'Answer',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'log',
+      kind: 'step',
+      label: 'Log',
+      icon: Braces,
+      typeLabel: 'Transform',
+      chips: [{ id: 'onError', label: 'Continues on error', tone: 'error' }],
+      description: 'If it fails, the run goes on without it.',
+      reads: [
+        { id: 'escalate', label: 'Escalate' },
+        { id: 'answer', label: 'Answer' },
+      ],
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'log', label: 'The output of Log' }],
+    },
+  ],
+  edges: [
+    { id: 's>fetch', source: '__start', target: 'fetch', kind: 'entry' },
+    { id: 'fetch>classify', source: 'fetch', target: 'classify', kind: 'data' },
+    {
+      id: 'classify>gate',
+      source: 'classify',
+      target: '__gate:escalate',
+      kind: 'order',
+    },
+    {
+      id: 'gate>escalate',
+      source: '__gate:escalate',
+      target: 'escalate',
+      kind: 'branch-yes',
+    },
+    {
+      id: 'classify>escalate',
+      source: 'classify',
+      target: 'escalate',
+      kind: 'data',
+    },
+    {
+      id: 'gate>answer',
+      source: '__gate:escalate',
+      target: 'answer',
+      kind: 'branch-no',
+    },
+    {
+      id: 'classify>answer',
+      source: 'classify',
+      target: 'answer',
+      kind: 'data',
+    },
+    { id: 'escalate>log', source: 'escalate', target: 'log', kind: 'data' },
+    { id: 'answer>log', source: 'answer', target: 'log', kind: 'data' },
+    { id: 'log>end', source: 'log', target: '__end', kind: 'exit' },
+  ],
+};
+
+// A host works these out from its own analysis of the workflow.
+const PATHS: FlowPath[] = [
+  {
+    id: 'p1',
+    label: 'Path 1',
+    nodes: ['fetch', 'classify', '__gate:escalate', 'escalate', 'log'],
+    decisions: { 'when:escalate': true },
+  },
+  {
+    id: 'p2',
+    label: 'Path 2',
+    nodes: ['fetch', 'classify', '__gate:escalate', 'answer', 'log'],
+    decisions: { 'when:escalate': false },
+  },
+];
+// Every node whose failure ends the run; Log lets the run go on.
+const HALTS = ['fetch', 'classify', 'escalate', 'answer'];
+
+const SECTIONS: FlowPathListSection[] = [
+  {
+    id: 'paths',
+    rows: [
+      {
+        id: 'p1',
+        title: 'Path 1',
+        meta: '4 of 5 nodes run',
+        clauses: [{ id: 'escalate', label: 'Escalate: Yes', tone: 'positive' }],
+      },
+      {
+        id: 'p2',
+        title: 'Path 2',
+        meta: '4 of 5 nodes run',
+        clauses: [{ id: 'escalate', label: 'Escalate: No', tone: 'negative' }],
+      },
+    ],
+  },
+  {
+    id: 'halts',
+    title: 'Ends the run when it fails',
+    rows: HALTS.map((id) => ({
+      id: `halt:${id}`,
+      title: GRAPH.nodes.find((node) => node.id === id)?.label ?? id,
+      pinnable: false,
+    })),
+  },
+];
+
+/** The highlight a row shows: its path, with why the rest steps back, or
+ *  every node that ends a run when it fails. */
+function highlightOf(id: string | null): FlowHighlight | null {
+  if (id === null) return null;
+  if (id.startsWith('halt:'))
+    return highlightForNodes(GRAPH, HALTS, { tone: 'error' });
+  const path = PATHS.find((candidate) => candidate.id === id);
+  if (path === undefined) return null;
+  const highlight = highlightForPaths(GRAPH, [path]);
+  const reasons: Record<string, string> = {};
+  for (const node of GRAPH.nodes)
+    if (!highlight.nodes.has(node.id))
+      reasons[node.id] = `Not on ${path.label ?? 'this path'}`;
+  return { ...highlight, reasons };
+}
+
+export default function FlowPossiblePathsDemo() {
+  const [preview, setPreview] = useState<string | null>(null);
+  const [pinned, setPinned] = useState<string | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const highlight = useMemo(
+    () => highlightOf(pinned ?? preview),
+    [pinned, preview],
+  );
+  return (
+    <div className="flex w-full flex-col gap-3 md:flex-row">
+      <div className="border-border w-full shrink-0 rounded-lg border py-2 md:w-64">
+        <FlowPathList
+          sections={SECTIONS}
+          aria-label="Paths a run can take"
+          previewId={preview}
+          pinnedId={pinned}
+          onPreview={setPreview}
+          onPin={setPinned}
+          onActivate={(id) => setSelected(id.replace('halt:', ''))}
+          announce={(row) => `Showing ${row.title}`}
+        />
+      </div>
+      <div className="h-[34rem] min-w-0 flex-1">
+        <WorkflowCanvas
+          graph={GRAPH}
+          aria-label="Answer a ticket"
+          layoutKey="possible-paths"
+          framed
+          paths={PATHS}
+          highlight={highlight}
+          selectedId={selected}
+          onSelect={setSelected}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/services/ui-docs/app/demos/flow/static-overlay.tsx b/services/ui-docs/app/demos/flow/static-overlay.tsx
new file mode 100644
index 0000000000..6233dd3cda
--- /dev/null
+++ b/services/ui-docs/app/demos/flow/static-overlay.tsx
@@ -0,0 +1,152 @@
+import type { FlowRunOverlay } from '@tale/ui/flow/playback';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { Switch } from '@tale/ui/switch';
+import { Braces, MessageSquare, Send, Sparkles } from 'lucide-react';
+import { useState } from 'react';
+
+const GRAPH: FlowGraph = {
+  nodes: [
+    {
+      id: '__start',
+      kind: 'entry',
+      triggers: [],
+      inputs: [
+        { id: 'ticket', label: 'ticket', detail: 'an object', code: true },
+      ],
+    },
+    {
+      id: 'fetch',
+      kind: 'step',
+      label: 'Fetch',
+      icon: Send,
+      typeLabel: 'HTTP · Get',
+    },
+    {
+      id: 'classify',
+      kind: 'step',
+      label: 'Classify',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'fetch', label: 'Fetch' }],
+    },
+    {
+      id: '__gate:escalate',
+      kind: 'gate',
+      label: 'Escalate',
+      mode: 'if-else',
+      condition: 'the priority of Classify is "urgent"',
+    },
+    {
+      id: 'escalate',
+      kind: 'step',
+      label: 'Escalate',
+      icon: MessageSquare,
+      typeLabel: 'Slack · Send message',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'answer',
+      kind: 'step',
+      label: 'Answer',
+      icon: Sparkles,
+      typeLabel: 'Language model',
+      reads: [{ id: 'classify', label: 'Classify' }],
+      conditional: true,
+    },
+    {
+      id: 'log',
+      kind: 'step',
+      label: 'Log',
+      icon: Braces,
+      typeLabel: 'Transform',
+      reads: [
+        { id: 'escalate', label: 'Escalate' },
+        { id: 'answer', label: 'Answer' },
+      ],
+    },
+    {
+      id: '__end',
+      kind: 'exit',
+      outputs: [{ id: 'log', label: 'The output of Log' }],
+    },
+  ],
+  edges: [
+    { id: 's>fetch', source: '__start', target: 'fetch', kind: 'entry' },
+    { id: 'fetch>classify', source: 'fetch', target: 'classify', kind: 'data' },
+    {
+      id: 'classify>gate',
+      source: 'classify',
+      target: '__gate:escalate',
+      kind: 'order',
+    },
+    {
+      id: 'gate>escalate',
+      source: '__gate:escalate',
+      target: 'escalate',
+      kind: 'branch-yes',
+    },
+    {
+      id: 'classify>escalate',
+      source: 'classify',
+      target: 'escalate',
+      kind: 'data',
+    },
+    {
+      id: 'gate>answer',
+      source: '__gate:escalate',
+      target: 'answer',
+      kind: 'branch-no',
+    },
+    {
+      id: 'classify>answer',
+      source: 'classify',
+      target: 'answer',
+      kind: 'data',
+    },
+    { id: 'escalate>log', source: 'escalate', target: 'log', kind: 'data' },
+    { id: 'answer>log', source: 'answer', target: 'log', kind: 'data' },
+    { id: 'log>end', source: 'log', target: '__end', kind: 'exit' },
+  ],
+};
+
+// Where each node of a finished run ended, as a host reads it from the
+// run's record. Lines are left out: the canvas works out which ones the
+// run took from where their two ends stand.
+const LAST_RUN: FlowRunOverlay = {
+  finished: true,
+  nodes: {
+    __start: { state: 'succeeded', detail: 'Started 07:00 by hand' },
+    fetch: { state: 'succeeded', detail: '0.4 s' },
+    classify: { state: 'succeeded', detail: '1.4 s' },
+    '__gate:escalate': { state: 'succeeded', decision: false },
+    escalate: { state: 'skipped', reason: 'Skipped: the condition is false' },
+    answer: { state: 'succeeded', detail: '2.4 s' },
+    log: { state: 'failed', reason: 'The log service did not answer' },
+    __end: { state: 'failed', detail: 'Failed at Log' },
+  },
+};
+
+export default function FlowStaticOverlayDemo() {
+  const [focus, setFocus] = useState(true);
+  return (
+    <div className="flex w-full flex-col gap-3">
+      <Switch
+        label="Bring the way to the failure forward"
+        checked={focus}
+        onCheckedChange={setFocus}
+      />
+      <div className="h-[34rem]">
+        <WorkflowCanvas
+          graph={GRAPH}
+          aria-label="Answer a ticket, last run"
+          layoutKey="static-overlay"
+          framed
+          overlay={LAST_RUN}
+          focusFailure={focus}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/services/ui-docs/content/components/workflow-canvas.md b/services/ui-docs/content/components/workflow-canvas.md
index 5f08823f32..b1d9a5049a 100644
--- a/services/ui-docs/content/components/workflow-canvas.md
+++ b/services/ui-docs/content/components/workflow-canvas.md
@@ -32,6 +32,27 @@ Every node is drawn from its data. A step shows its `icon`, `label` and `typeLab
 
 `layoutKey` names what the picture shows, such as a document and the version on screen. When the same key gets a changed graph, the canvas lays it out again and keeps each row in its order, so no box swaps sides with its neighbour. A new key is another picture: it is laid out afresh and fades in.
 
+## Watch it change
+
+<Demo name="flow/live-relayout" />
+
+Save the next version to see the chart glide to its new layout. A graph that changes under the same `layoutKey`, such as a version a coding agent saved or a field edit that adds a reference, moves in three beats:
+
+| What | Moves | Timing |
+| --- | --- | --- |
+| A node, condition or frame that leaves | Shrinks out at its old place | 150 ms |
+| A line that leaves or takes another route | Fades out along its old route | 150 ms |
+| A node, condition or frame that stays | Glides to its new place | 300 ms, from the start |
+| A node or condition that joins | Grows in | 200 ms, after 150 ms |
+| A frame that changed size | Fades out, then in at its new size | 150 ms, then 200 ms after 250 ms |
+| A line that joins or takes another route | Fades in | 200 ms, after 250 ms |
+
+The chart has settled 450 ms after the new layout lands, and no line is drawn against a box that is still moving. The motion uses the duration tokens and the out-quint ease, and only transform and opacity. If the view was still where the fit left it, it eases to the new fit; otherwise the open node is brought back into view if it moved out. A change that arrives while a glide is under way starts from where everything is.
+
+Pass `changed` with the ids of the nodes that changed outside this tab, such as a version saved in another window, and a new `key`. Those nodes show a ring that fades out once the glide is done. Leave out your reader's own edits: a field they just changed never rings. The key the canvas opens with is never rung.
+
+Under reduced motion none of this plays: the new layout is simply there, and nothing rings.
+
 ## Follow the lines
 
 <Demo name="flow/routed-edges" />
@@ -80,6 +101,12 @@ The List view says the same as the chart in text. `FlowStepList` renders an orde
 
 Inside `WorkflowCanvas`, **Show as list** in the corner switches to this view and **Show as chart** switches back. The choice is stored in the browser under `tale:flow-view`. On a screen narrower than 24rem the list is the default. Pass `view` and `onViewChange` to control it yourself; the built-in button then goes away.
 
+## Show a run or a path
+
+Pass a run as `overlay` (where each node ended) or `playback` (a moment of a replay) to frame each node by its state and draw the lines the run took. A failed run brings the way to its first failure forward. See [Workflow playback](/docs/components/workflow-playback).
+
+Pass `paths` and `highlight` to bring one path, one branch or a set of nodes forward and step back from the rest. See [Workflow paths](/docs/components/workflow-paths).
+
 ## Use the keyboard
 
 The chart is one Tab stop: the selected node, else the node focused last, else Start. From there:
@@ -120,6 +147,12 @@ Viewport moves ease out over the duration tokens: zoom 150 ms, reveal 200 ms, re
 | `revealId` | `string \| null` | — | Brings this node into view. |
 | `issues` | `ReadonlyMap<string, IssueCounts>` | — | Problem counts by node id. |
 | `controlsId` | `string` | — | The panel a node opens. |
+| `overlay` | `FlowRunOverlay` | — | A run without time: where each node ended. |
+| `playback` | `{ timeline, t }` | — | A run at moment `t`; wins over `overlay`. |
+| `focusFailure` | `boolean` | `true` | Brings a failed run's way to its failure forward. |
+| `paths` | `FlowPath[]` | — | Lets a pointer on a condition or a Yes/No label highlight its paths. |
+| `highlight` / `onHighlightChange` | `FlowHighlight \| null` | — | Your highlight wins over the canvas's own; the callback reports the canvas's own. |
+| `changed` | `{ ids, key }` | — | Nodes changed outside this tab, ringed once when `key` changes. |
 | `view` / `onViewChange` | `'chart' \| 'list'` | stored choice | Controls the view. |
 | `framed` | `boolean` | `false` | A bordered frame for a page. |
 | `touchPolicy` | `'pan' \| 'page-scroll'` | `framed ? 'page-scroll' : 'pan'` | What one finger does on a touch screen. |
diff --git a/services/ui-docs/content/components/workflow-paths.md b/services/ui-docs/content/components/workflow-paths.md
new file mode 100644
index 0000000000..ca6856f077
--- /dev/null
+++ b/services/ui-docs/content/components/workflow-paths.md
@@ -0,0 +1,105 @@
+---
+title: Workflow paths
+description: Show every way a run can go through a workflow, preview and pin one path at a time, and point out the nodes that end a run when they fail.
+---
+
+A workflow with conditions can run in more than one way. `FlowPath` describes one of those ways as plain data, the highlight helpers turn one or more paths into what the canvas brings forward, and `FlowPathList` is the list a reader explores them with. The reader points at a path, pins it, and the chart steps back from everything that does not run on it.
+
+```tsx
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import { FlowPathList } from '@tale/ui/flow/flow-path-list';
+import {
+  highlightForPaths,
+  highlightForBranch,
+  highlightForNodes,
+  type FlowPath,
+  type FlowHighlight,
+} from '@tale/ui/flow/paths';
+```
+
+## Explore the paths
+
+<Demo name="flow/possible-paths" />
+
+Point at a path in the list to preview it on the chart, and press Enter or click to pin it. Press Escape or **Show all** to unpin. Point at a row under **Ends the run when it fails** to ring those nodes in red, and choose one to open it. Rest the pointer on the condition, or on its **Yes** or **No** label, to see the paths through it.
+
+## Describe the paths
+
+Your host works the paths out from its own analysis of the workflow. Each `FlowPath` lists the steps and conditions that run on it and how each condition decided:
+
+```ts
+const path: FlowPath = {
+  id: 'p2',
+  label: 'Path 2',
+  nodes: ['fetch', 'classify', '__gate:escalate', 'answer', 'log'],
+  decisions: { 'when:escalate': false },
+};
+```
+
+`decisions` is keyed by each gate's `decisionKey`, or by its id when it has none. `true` takes **Yes** and `false` takes **No**. Start and End are on every path, so leave them out.
+
+| Helper | Brings forward |
+| --- | --- |
+| `highlightForPaths(graph, paths)` | Every node on any of the paths, Start and End, and every line a run on one of them follows. A **Yes** or **No** line counts only on a path where its condition decided that way. |
+| `highlightForBranch(graph, paths, gateId, decision?)` | The paths that consult the condition, only those where it decided `decision` when you give it. With no paths, the condition and everything below the branch's target. |
+| `highlightForNodes(graph, ids, { tone })` | A set of nodes and the lines between them. `tone: 'error'` rings them in the error red. |
+| `highlightForIncident(graph, id)` | A node's own lines, without quieting anything. |
+
+## Show a highlight on the canvas
+
+Pass a `FlowHighlight` as `highlight`. Inside it, boxes are lifted and ringed and lines stand out at 2.5 px. Outside it, boxes step back: a dashed border on a muted surface, with their words at full contrast. Lines thin to 1 px and keep their colour and dash, so a quiet line still reads at 3:1. Colour and width never animate; two stacked lines crossfade their opacity over 150 ms. Under reduced motion the change is instant.
+
+Give `reasons` to say why a node steps back, such as "Not on Path 2" or "Skipped: Inbox was empty". The reason replaces the node's strip and joins its accessible description. Give `announcement` to have the canvas say the highlight once in a polite live region. Set `quietRest: false` to bring things forward without quieting the rest.
+
+Your `highlight` wins over the canvas's own. Pass `null` to leave the canvas's own highlights:
+
+- A pointer or keyboard focus on a node brings its own lines forward and quiets nothing, so tabbing through the chart never flickers.
+- With `paths`, a pointer that rests 150 ms on a condition, or on a **Yes** or **No** label, highlights the paths through it. Pass an empty list when your analysis gave up (too many conditions to list every path); the branch then highlights what lies below its target.
+
+`onHighlightChange` reports the canvas's own highlight as it changes, so a list beside the chart can follow it.
+
+## List the paths
+
+`FlowPathList` renders the paths, and anything else the reader can point at, in sections:
+
+```tsx
+<FlowPathList
+  sections={[
+    { id: 'paths', rows: [{ id: 'p1', title: 'Path 1', meta: '4 of 5 nodes run', clauses: [{ id: 'e', label: 'Escalate: Yes', tone: 'positive' }] }] },
+    { id: 'halts', title: 'Ends the run when it fails', rows: [{ id: 'fetch', title: 'Fetch', pinnable: false }] },
+  ]}
+  aria-label="Paths a run can take"
+  previewId={preview}
+  pinnedId={pinned}
+  onPreview={setPreview}
+  onPin={setPinned}
+  onActivate={openNode}
+  announce={(row) => `Showing ${row.title}`}
+/>
+```
+
+Pointing at a row or focusing it calls `onPreview`. Enter, Space or a click calls `onPin` with the row's id, and again with `null` to unpin. A row with `pinnable: false` calls `onActivate` instead. A clause shows its words with a tone dot, so the tone never speaks alone.
+
+Place the list in a panel that stays open while the reader clicks the chart, not in a popover that closes on the first click elsewhere. Show the highlight of the pinned row, else of the previewed one.
+
+## Use the keyboard
+
+The list is one Tab stop across all its sections. ↓ and ↑ move between rows, Home and End jump to the first and last. Enter or Space pins or opens a row. Escape unpins, and a screen reader hears your `announce` words once for each pin.
+
+While a path is pinned, the list claims Escape, so inside a sheet the first Escape unpins and the next one closes the sheet. The chart itself highlights only a node's own lines on keyboard focus; the list is how a keyboard reaches a single path.
+
+## Props
+
+`FlowPathList`:
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `sections` | `{ id, title?, description?, rows, footer? }[]` | Rows in order; one Tab stop across all of them. |
+| `previewId` / `onPreview` | `string \| null` | The row a pointer or focus is on. |
+| `pinnedId` / `onPin` | `string \| null` | The pinned row; `onPin(null)` unpins. |
+| `onActivate` | `(id) => void` | A row with `pinnable: false` was chosen. |
+| `announce` | `(row) => string` | Said once when a row is pinned. |
+| `aria-label` | `string` | Names the list. |
+| `empty` | `ReactNode` | Shown when no section has a row. |
+
+On `WorkflowCanvas`, see [Workflow canvas](/docs/components/workflow-canvas#props) for `paths`, `highlight` and `onHighlightChange`.
diff --git a/services/ui-docs/content/components/workflow-playback.md b/services/ui-docs/content/components/workflow-playback.md
new file mode 100644
index 0000000000..0cd3647d32
--- /dev/null
+++ b/services/ui-docs/content/components/workflow-playback.md
@@ -0,0 +1,92 @@
+---
+title: Workflow playback
+description: Show how a run went on a workflow chart, and replay it with values travelling the lines, a scrubber and the failure in focus.
+---
+
+`WorkflowCanvas` shows a run two ways. An overlay says where each node ended, with no time. A playback replays the run: your host owns the moment `t`, the canvas draws the run at that moment, and dots carry values along the lines. Both bring a failed run's way to its first failure forward.
+
+```tsx
+import { WorkflowCanvas } from '@tale/ui/flow/workflow-canvas';
+import {
+  buildPlaybackTimeline,
+  flowStateAt,
+  usePlaybackClock,
+  type FlowRunOverlay,
+} from '@tale/ui/flow/playback';
+import { FlowPlaybackBar } from '@tale/ui/flow/playback-bar';
+```
+
+## Show where a run ended
+
+<Demo name="flow/static-overlay" />
+
+Pass a `FlowRunOverlay` as `overlay`: each node's `state`, and optionally a `detail` such as "1.4 s", a `reason` such as the error line, a condition's `decision`, the `items` of a node that runs once per item, and the `pass` of one that repeats. Set `finished` when the run is over, so a node it never reached reads as not run.
+
+Leave `edges` out to let the canvas work out the lines. A line counts as travelled when its source succeeded and its target started, and as not taken when its condition decided the other way or its target was skipped.
+
+| State | The box |
+| --- | --- |
+| Running | Blue frame and a top bar that sweeps across, still under reduced motion |
+| Waiting | Amber frame and top bar |
+| Succeeded | Plain |
+| Failed | Red frame and left edge; the strip shows the error line |
+| Skipped, stopped, not run | Dashed border |
+
+Each box shows its state's glyph and says its state in its name, such as "Classify (Succeeded)". Its strip says the reason or the state, then the detail: "Succeeded · 1.4 s". A condition shows a **Yes** or **No** chip; the branch it took gets a check, the other a dash and a thin line. A frame counts "12 of 50 items" or "Pass 3 of 5". No text is ever faded.
+
+When the run failed, the canvas brings forward the way the run took to the first failure and steps back from the rest. The line into the failed node turns red. Without an error line, the failed node's strip says "The run stopped here". Set `focusFailure={false}` to show the run without the focus. A `highlight` you pass wins over it.
+
+## Replay a run
+
+<Demo name="flow/playback" />
+
+Press **Play**, drag the scrubber, or step between events. The answer waits three hours for an approval; the replay shows that wait as a hatched band and moves on.
+
+1. Record the run in real time: each node's spans with `startedAt` and `endedAt`, each moment a value left a node (`travels`, with the `target` it goes to), and each wait.
+2. Build the timeline once with `buildPlaybackTimeline(run)`.
+3. Drive it with `usePlaybackClock({ timeline })` and pass `playback={{ timeline, t }}` to the canvas.
+4. Put `FlowPlaybackBar` under the canvas, fed by the same clock.
+
+`buildPlaybackTimeline` compresses real time piece by piece. The stretch between two moments plays for its real length, but at least `minStepMs` (240 ms) and at most `maxGapMs` (1.2 s), and each value gets `travelMs` (320 ms) to reach its target before the target starts. A long wait becomes a `wait` mark with your words; a failure becomes a `failure` mark. `toReal(t)` and `fromReal(ms)` map between playback and real time, so the bar can show how long the run really took.
+
+`flowStateAt(graph, timeline, t)` is the frame the canvas draws. Use it to say what is happening for the scrubber's spoken value (`activity`), or to drive the List view.
+
+## Watch the values travel
+
+While a value is on its way, an 8 px dot rides its line. Its motion is a Web Animation created paused: every change of `t` sets its `currentTime`, so playing, scrubbing and stepping are the same operation. It fades in over the first 8 % of the line and dissolves into the box it reaches. Strips settle softly when their words change while the run plays forward; scrubbing back swaps them at once.
+
+While the run plays, the canvas follows the node it reaches into view, until the reader moves the view.
+
+Under reduced motion there are no dots: a line switches to travelled when its value arrives. **Play** steps from event to event every 600 ms instead of sweeping.
+
+## Control the replay
+
+`usePlaybackClock` opens on the end of the run, which shows the whole story. Playing from the end starts over. On a live timeline it follows the growing end until the reader moves `t`, and `follow()` returns to it.
+
+`FlowPlaybackBar` holds play or pause, previous and next event, a scrubber with a tick for each event, the time and the speed. The speed is a segmented control, folded into a menu on a phone. A live run shows **Live**, and **Follow live** while the reader is behind its end. The play button's name says what it does next.
+
+| Key | Does |
+| --- | --- |
+| Space | Plays or pauses, anywhere on the bar except a button |
+| ← / → | Moves the scrubber by 1 % |
+| Page Down / Page Up | Moves it by 10 % |
+| Home / End | Jumps to the start or the end |
+| `[` / `]` | Steps to the previous or next event |
+
+The scrubber is named "Run timeline" and says where it is, such as "00:42 of 03:10 — Classify running", from `formatTime` and your `activity` words.
+
+## Props
+
+`FlowPlaybackBar`:
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `timeline` | `FlowPlaybackTimeline` | From `buildPlaybackTimeline`. |
+| `t` / `onTChange` | `number` | The moment shown, in playback ms. |
+| `playing` / `onPlayingChange` | `boolean` | |
+| `speed` / `onSpeedChange` | `0.5 \| 1 \| 2 \| 4` | The speed control shows only with `onSpeedChange`. |
+| `formatTime` | `(t) => string` | Defaults to playback time as `mm:ss`; pass `formatFlowClock(toReal(t) - startedAt)` for real time. |
+| `activity` | `string` | What happens at `t`, for the scrubber's spoken value. |
+| `onFollowLive` | `() => void` | Shows **Follow live** on a live run. |
+
+On `WorkflowCanvas`, see [Workflow canvas](/docs/components/workflow-canvas#props) for `overlay`, `playback` and `focusFailure`.
diff --git a/services/ui-docs/content/nav.json b/services/ui-docs/content/nav.json
index 2dedb5daab..9ae7f7553f 100644
--- a/services/ui-docs/content/nav.json
+++ b/services/ui-docs/content/nav.json
@@ -30,6 +30,8 @@
         "components/issue-list",
         "components/flow-node-issues",
         "components/workflow-canvas",
+        "components/workflow-paths",
+        "components/workflow-playback",
         "components/field-issues",
         "components/recurrence-picker",
         "components/schedule-occurrence-list",
diff --git a/services/ui-docs/content/published.json b/services/ui-docs/content/published.json
index 6098792c95..34eda8c699 100644
--- a/services/ui-docs/content/published.json
+++ b/services/ui-docs/content/published.json
@@ -18,6 +18,8 @@
     "components/time-field",
     "components/toast",
     "components/workflow-canvas",
+    "components/workflow-paths",
+    "components/workflow-playback",
     "foundations/accessibility",
     "foundations/colors",
     "foundations/icons",

From 7cec08ed2d3e29897f5e0b1df222a268e0b0282f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:36:17 +0200
Subject: [PATCH 29/78] fix(ui): unpin a flow path from Show all and show every
 path again

Escape only unpinned from a path row. With focus on Show all, the
list's Escape claim kept a sheet around it open and nothing unpinned,
so the key did nothing. Escape now unpins from Show all as well and
hands focus back to the row that was pinned.

Unpinning, with Escape or Show all, also ends the preview, so the chart
shows every path again. Before, focus landed back on the pinned row and
previewed its path, so Show all went on showing that one path. The row
keeps the focus without previewing; the next arrow key previews as
usual.
---
 .../flow/flow-path-list.browser.test.tsx      | 55 ++++++++++++++++++
 .../ui/src/components/flow/flow-path-list.tsx | 57 ++++++++++++++-----
 .../content/components/workflow-paths.md      |  4 +-
 3 files changed, 102 insertions(+), 14 deletions(-)

diff --git a/packages/ui/src/components/flow/flow-path-list.browser.test.tsx b/packages/ui/src/components/flow/flow-path-list.browser.test.tsx
index 476449f106..3974a9d90f 100644
--- a/packages/ui/src/components/flow/flow-path-list.browser.test.tsx
+++ b/packages/ui/src/components/flow/flow-path-list.browser.test.tsx
@@ -6,6 +6,7 @@ import { userEvent } from 'vitest/browser';
 
 import { render, screen, waitFor } from '@/tests/utils/render';
 
+import { Sheet } from '../overlays/sheet';
 import {
   FlowPathList,
   type FlowPathListProps,
@@ -116,12 +117,19 @@ describe('FlowPathList', () => {
       document.querySelector('[data-slot="flow-path-list"]'),
     ).toHaveAttribute('data-claims-escape');
 
+    // Unpinning shows every path again: the preview ends with the pin,
+    // and focus stays where it was.
     await userEvent.keyboard('{Escape}');
     expect(onPin).toHaveBeenLastCalledWith(null);
     expect(row(/^Path 2/)).toHaveAttribute('aria-pressed', 'false');
+    expect(screen.getByTestId('preview')).toHaveTextContent('none');
+    expect(document.activeElement).toBe(row(/^Path 2/));
     expect(
       document.querySelector('[data-slot="flow-path-list"]'),
     ).not.toHaveAttribute('data-claims-escape');
+    // The next arrow key previews again.
+    await userEvent.keyboard('{ArrowUp}');
+    expect(screen.getByTestId('preview')).toHaveTextContent('p1');
 
     await userEvent.click(row(/^Path 1/));
     await waitFor(() => expect(status).toHaveTextContent('Showing Path 1'));
@@ -129,6 +137,53 @@ describe('FlowPathList', () => {
     expect(onPin).toHaveBeenLastCalledWith(null);
     expect(screen.queryByRole('button', { name: 'Show all' })).toBeNull();
     expect(document.activeElement).toBe(row(/^Path 1/));
+    expect(screen.getByTestId('preview')).toHaveTextContent('none');
+  });
+
+  it('unpins with Escape from Show all and returns focus to the row', async () => {
+    const onPin = vi.fn();
+    render(<Harness onPin={onPin} />);
+    await userEvent.click(row(/^Path 2/));
+    await userEvent.tab();
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Show all' }),
+    );
+    await userEvent.keyboard('{Escape}');
+    expect(onPin).toHaveBeenLastCalledWith(null);
+    expect(document.activeElement).toBe(row(/^Path 2/));
+    expect(screen.getByTestId('preview')).toHaveTextContent('none');
+  });
+
+  it('takes the first Escape in a sheet to unpin, and the next closes it', async () => {
+    function InSheet() {
+      const [open, setOpen] = useState(true);
+      return (
+        <>
+          <p>{open ? 'sheet open' : 'sheet closed'}</p>
+          <Sheet
+            open={open}
+            onOpenChange={setOpen}
+            title="Paths"
+            description="Every way a run can go"
+            side="bottom"
+          >
+            <Harness />
+          </Sheet>
+        </>
+      );
+    }
+    render(<InSheet />);
+    await userEvent.click(
+      await screen.findByRole('button', { name: /^Path 2/ }),
+    );
+    expect(row(/^Path 2/)).toHaveAttribute('aria-pressed', 'true');
+    await userEvent.keyboard('{Escape}');
+    expect(row(/^Path 2/)).toHaveAttribute('aria-pressed', 'false');
+    expect(screen.getByText('sheet open')).toBeInTheDocument();
+    await userEvent.keyboard('{Escape}');
+    await waitFor(() =>
+      expect(screen.getByText('sheet closed')).toBeInTheDocument(),
+    );
   });
 
   it('activates a row that is not a path instead of pinning it', async () => {
diff --git a/packages/ui/src/components/flow/flow-path-list.tsx b/packages/ui/src/components/flow/flow-path-list.tsx
index 9660d1241a..c0845e5601 100644
--- a/packages/ui/src/components/flow/flow-path-list.tsx
+++ b/packages/ui/src/components/flow/flow-path-list.tsx
@@ -5,6 +5,7 @@ import {
   useCallback,
   useEffect,
   useId,
+  useMemo,
   useRef,
   useState,
   type KeyboardEvent,
@@ -90,6 +91,11 @@ const CLAUSE_DOT: Record<NonNullable<FlowPathClause['tone']>, string> = {
  * Home and End jump. Pinning says so once in a polite live region, in the
  * host's words. While a path is pinned the list claims Escape, so the
  * first Escape inside a sheet unpins and only the next one closes it.
+ *
+ * Unpinning — Escape anywhere in the list, or **Show all** — ends the
+ * preview too, so the chart shows every path again; focus stays on (or
+ * returns to) the row that was pinned without previewing it, and the next
+ * arrow key previews as usual.
  */
 export function FlowPathList({
   sections,
@@ -105,9 +111,15 @@ export function FlowPathList({
 }: FlowPathListProps) {
   const { t } = useT('flow');
   const baseId = useId();
-  const rows = sections.flatMap((section) => section.rows);
+  const rows = useMemo(
+    () => sections.flatMap((section) => section.rows),
+    [sections],
+  );
   const ids = rows.map((row) => row.id);
   const buttons = useRef(new Map<string, HTMLButtonElement>());
+  // A row focused by the list itself after an unpin: it keeps the focus
+  // without previewing its path again.
+  const quietFocus = useRef<string | null>(null);
   const [focusedId, setFocusedId] = useState<string | null>(null);
   const [spoken, setSpoken] = useState({ text: '', serial: 0 });
 
@@ -133,8 +145,10 @@ export function FlowPathList({
     setSpoken((previous) => ({ text, serial: previous.serial + 1 }));
   }, [pinnedId, announce, rows]);
 
-  const focusRow = useCallback((id: string) => {
+  const focusRow = useCallback((id: string, preview = true) => {
+    if (!preview) quietFocus.current = id;
     buttons.current.get(id)?.focus();
+    quietFocus.current = null;
   }, []);
 
   const choose = (row: FlowPathListRow) => {
@@ -142,10 +156,34 @@ export function FlowPathList({
     else onPin?.(pinnedId === row.id ? null : row.id);
   };
 
+  /** Back to every path: no pin, no preview. `refocus` returns focus to
+   *  the row that was pinned (from **Show all**, which then goes away). */
+  const unpin = (refocus: boolean) => {
+    if (pinnedId === null) return;
+    onPin?.(null);
+    onPreview?.(null);
+    if (refocus) focusRow(pinnedId, false);
+  };
+
+  // Escape unpins from anywhere in the list — a row, or Show all, which
+  // then hands focus back to the row — and the claim keeps a sheet round
+  // the list from closing on that same press.
+  const onEscape = (
+    event: KeyboardEvent<HTMLButtonElement>,
+    refocus: boolean,
+  ): boolean => {
+    if (event.key !== 'Escape' || pinnedId === null) return false;
+    event.preventDefault();
+    event.stopPropagation();
+    unpin(refocus);
+    return true;
+  };
+
   const onRowKeyDown = (
     event: KeyboardEvent<HTMLButtonElement>,
     index: number,
   ) => {
+    if (onEscape(event, false)) return;
     let next: string | undefined;
     switch (event.key) {
       case 'ArrowDown':
@@ -160,12 +198,6 @@ export function FlowPathList({
       case 'End':
         next = ids.at(-1);
         break;
-      case 'Escape':
-        if (pinnedId === null) return;
-        event.preventDefault();
-        event.stopPropagation();
-        onPin?.(null);
-        return;
       default:
         return;
     }
@@ -249,7 +281,8 @@ export function FlowPathList({
                           onKeyDown={(event) => onRowKeyDown(event, at)}
                           onFocus={() => {
                             setFocusedId(row.id);
-                            onPreview?.(row.id);
+                            if (quietFocus.current !== row.id)
+                              onPreview?.(row.id);
                           }}
                           onBlur={(event) => {
                             // Leaving the list ends the preview; moving
@@ -328,10 +361,8 @@ export function FlowPathList({
           <Button
             size="sm"
             variant="secondary"
-            onClick={() => {
-              onPin?.(null);
-              focusRow(pinnedId);
-            }}
+            onClick={() => unpin(true)}
+            onKeyDown={(event) => onEscape(event, true)}
           >
             {t('paths.showAll')}
           </Button>
diff --git a/services/ui-docs/content/components/workflow-paths.md b/services/ui-docs/content/components/workflow-paths.md
index ca6856f077..b9d71679d8 100644
--- a/services/ui-docs/content/components/workflow-paths.md
+++ b/services/ui-docs/content/components/workflow-paths.md
@@ -84,7 +84,9 @@ Place the list in a panel that stays open while the reader clicks the chart, not
 
 ## Use the keyboard
 
-The list is one Tab stop across all its sections. ↓ and ↑ move between rows, Home and End jump to the first and last. Enter or Space pins or opens a row. Escape unpins, and a screen reader hears your `announce` words once for each pin.
+The list is one Tab stop across all its sections. ↓ and ↑ move between rows, Home and End jump to the first and last. Enter or Space pins or opens a row. Escape unpins from a row or from **Show all**, and a screen reader hears your `announce` words once for each pin.
+
+Unpinning ends the preview too (`onPreview(null)`), so the chart shows every path again. Focus stays on the row that was pinned, or returns to it from **Show all**, without previewing it; the next arrow key previews as usual.
 
 While a path is pinned, the list claims Escape, so inside a sheet the first Escape unpins and the next one closes the sheet. The chart itself highlights only a node's own lines on keyboard focus; the list is how a keyboard reaches a single path.
 

From 52c815ff29328a95661b6de4daf729c9fd360759 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:36:37 +0200
Subject: [PATCH 30/78] fix(ui): replay a run's details, waits and dots as they
 happened

A replayed step showed its recorded detail, such as its 1.2 s duration,
while it was still running at the moment shown. A span's detail now
shows once the replay reaches the span's end. A span still open on a
live run shows its detail at once, because there the host's words
describe the present.

A wait's hatched band on the scrubber ran only to the next event, so
work going on during the wait cut it short. buildPlaybackTimeline now
gives a wait mark its end, and the bar draws the band to it. A wait
still open has no end, and its band runs to the end of the timeline.

Two values travelling one line at once, or two marks at the same
moment, no longer share a React key, so each keeps its own dot or tick.
---
 .../flow/playback/build-timeline.test.ts           | 14 +++++++++++++-
 .../src/components/flow/playback/build-timeline.ts |  1 +
 .../components/flow/playback/derive-state.test.ts  |  7 ++++++-
 .../src/components/flow/playback/derive-state.ts   |  6 +++++-
 .../playback/flow-playback-bar.browser.test.tsx    | 12 ++++++++++--
 .../components/flow/playback/flow-playback-bar.tsx | 11 ++++++-----
 packages/ui/src/components/flow/playback/types.ts  |  4 ++++
 .../ui/src/components/flow/render/pulse-layer.tsx  |  8 +++++++-
 .../content/components/workflow-playback.md        |  4 ++--
 9 files changed, 54 insertions(+), 13 deletions(-)

diff --git a/packages/ui/src/components/flow/playback/build-timeline.test.ts b/packages/ui/src/components/flow/playback/build-timeline.test.ts
index 2ca55ea23e..1961c060c0 100644
--- a/packages/ui/src/components/flow/playback/build-timeline.test.ts
+++ b/packages/ui/src/components/flow/playback/build-timeline.test.ts
@@ -49,9 +49,21 @@ describe('buildPlaybackTimeline', () => {
   });
 
   it('marks a long wait with its real words and a failure with its reason', () => {
-    const timeline = buildPlaybackTimeline(branchRun());
+    const run = branchRun();
+    const timeline = buildPlaybackTimeline(run);
     const wait = timeline.marks?.find((mark) => mark.kind === 'wait');
     expect(wait?.label).toBe('Waited 0.8 s for approval');
+    // The band runs from where the wait began to where it ended.
+    const real = run.waits?.[0];
+    expect(wait?.at).toBe(timeline.fromReal(real?.startedAt ?? 0));
+    expect(wait?.end).toBe(timeline.fromReal(real?.endedAt ?? 0));
+    // A wait still open has no end yet.
+    const open = buildPlaybackTimeline({
+      ...run,
+      endedAt: undefined,
+      waits: [{ startedAt: real?.startedAt ?? 0, label: 'Waiting' }],
+    }).marks?.find((mark) => mark.kind === 'wait');
+    expect(open?.end).toBeUndefined();
     const failure = buildPlaybackTimeline(triageFailedRun()).marks?.find(
       (mark) => mark.kind === 'failure',
     );
diff --git a/packages/ui/src/components/flow/playback/build-timeline.ts b/packages/ui/src/components/flow/playback/build-timeline.ts
index e4187d9522..3bf17856dc 100644
--- a/packages/ui/src/components/flow/playback/build-timeline.ts
+++ b/packages/ui/src/components/flow/playback/build-timeline.ts
@@ -169,6 +169,7 @@ export function buildPlaybackTimeline(
   for (const wait of run.waits ?? [])
     marks.push({
       at: fromReal(wait.startedAt),
+      ...(wait.endedAt === undefined ? {} : { end: fromReal(wait.endedAt) }),
       kind: 'wait',
       label: wait.label,
     });
diff --git a/packages/ui/src/components/flow/playback/derive-state.test.ts b/packages/ui/src/components/flow/playback/derive-state.test.ts
index 0d42e0518a..8a9d22e9c1 100644
--- a/packages/ui/src/components/flow/playback/derive-state.test.ts
+++ b/packages/ui/src/components/flow/playback/derive-state.test.ts
@@ -25,12 +25,14 @@ describe('flowStateAt', () => {
     expect(before.nodes.issues?.state).toBe('pending');
     expect(before.nodes.__end?.state).toBe('pending');
 
+    // What a step came to ("1.2 s") shows once the replay gets there.
     const fetching = flowStateAt(graph, timeline, real(600));
     expect(fetching.nodes.issues?.state).toBe('running');
-    expect(fetching.nodes.issues?.detail).toBe('1.2 s');
+    expect(fetching.nodes.issues?.detail).toBeUndefined();
 
     const done = flowStateAt(graph, timeline, real(1_255));
     expect(done.nodes.issues?.state).toBe('succeeded');
+    expect(done.nodes.issues?.detail).toBe('1.2 s');
   });
 
   it('counts the items of a node that runs once per item, and fails with an item', () => {
@@ -132,10 +134,13 @@ describe('flowStateAt', () => {
           startedAt: run.startedAt + 4_100,
           outcome: 'succeeded',
           item: 2,
+          detail: 'Scoring the third issue',
         }),
     });
     const now = flowStateAt(graph, live, live.duration);
     expect(now.nodes.score?.state).toBe('running');
+    // A span still open says what it is doing now, in the host's words.
+    expect(now.nodes.score?.detail).toBe('Scoring the third issue');
     // The run is not over: a live list has no known length yet.
     expect(now.nodes.score?.items).toEqual({ done: 2 });
     expect(now.nodes.report?.state).toBe('pending');
diff --git a/packages/ui/src/components/flow/playback/derive-state.ts b/packages/ui/src/components/flow/playback/derive-state.ts
index a06a7dc336..28290444c7 100644
--- a/packages/ui/src/components/flow/playback/derive-state.ts
+++ b/packages/ui/src/components/flow/playback/derive-state.ts
@@ -105,7 +105,11 @@ function stateFromSpans(
       : undefined;
   const words = failing ?? latest;
   if (words.reason !== undefined) info.reason = words.reason;
-  if (words.detail !== undefined) info.detail = words.detail;
+  // A recorded span's detail ("1.2 s") is what it came to: shown once the
+  // replay reaches its end, never while it still plays. A live span with
+  // no end yet carries the host's words for now.
+  if (words.detail !== undefined && (words.end === undefined || words.end <= t))
+    info.detail = words.detail;
   const decided = [...started]
     .reverse()
     .find((span) => span.decision !== undefined);
diff --git a/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx b/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
index 7d7c18dfca..a4075f6239 100644
--- a/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
+++ b/packages/ui/src/components/flow/playback/flow-playback-bar.browser.test.tsx
@@ -91,8 +91,16 @@ describe('FlowPlaybackBar', () => {
     expect(shownT()).toBe(Math.round(first));
     await userEvent.keyboard('{End}');
     expect(shownT()).toBe(Math.round(timeline.duration));
-    // The wait shows as a band.
-    expect(document.querySelector('[data-flow-mark="wait"]')).not.toBeNull();
+    // The wait shows as a band, from where it began to where it ended.
+    const band = document.querySelector<HTMLElement>('[data-flow-mark="wait"]');
+    const wait = timeline.marks?.find((mark) => mark.kind === 'wait');
+    if (band === null || wait?.end === undefined) throw new Error('no wait');
+    const share = (at: number) => (at / timeline.duration) * 100;
+    expect(parseFloat(band.style.left)).toBeCloseTo(share(wait.at), 3);
+    expect(parseFloat(band.style.width)).toBeCloseTo(
+      share(wait.end) - share(wait.at),
+      3,
+    );
   });
 
   it('plays with Space and the button, whose name says what it does', async () => {
diff --git a/packages/ui/src/components/flow/playback/flow-playback-bar.tsx b/packages/ui/src/components/flow/playback/flow-playback-bar.tsx
index be85fcb94c..e5130c86f2 100644
--- a/packages/ui/src/components/flow/playback/flow-playback-bar.tsx
+++ b/packages/ui/src/components/flow/playback/flow-playback-bar.tsx
@@ -201,11 +201,12 @@ export function FlowPlaybackBar({
         />
         {/* The thumb's centre runs 10 px in from each end; so do the ticks. */}
         <div aria-hidden="true" className="relative mx-2.5 h-1.5">
-          {waits.map((mark) => {
-            const end = nextFlowEvent(timeline, mark.at);
+          {waits.map((mark, index) => {
+            // A wait still open runs to the end of what has been recorded.
+            const end = mark.end ?? duration;
             return (
               <span
-                key={`wait-${mark.at}`}
+                key={`wait-${index}`}
                 title={mark.label}
                 data-flow-mark="wait"
                 className="text-muted-foreground absolute top-0 h-1.5 rounded-xs bg-[repeating-linear-gradient(135deg,currentColor_0_2px,transparent_2px_4px)]"
@@ -224,9 +225,9 @@ export function FlowPlaybackBar({
               style={{ left: `${percent(at)}%` }}
             />
           ))}
-          {failures.map((mark) => (
+          {failures.map((mark, index) => (
             <span
-              key={`failure-${mark.at}`}
+              key={`failure-${index}`}
               title={mark.label}
               data-flow-mark="failure"
               className="bg-destructive absolute top-0 h-1.5 w-0.5 -translate-x-1/2 rounded-full"
diff --git a/packages/ui/src/components/flow/playback/types.ts b/packages/ui/src/components/flow/playback/types.ts
index be66656873..f937a8fd10 100644
--- a/packages/ui/src/components/flow/playback/types.ts
+++ b/packages/ui/src/components/flow/playback/types.ts
@@ -78,6 +78,10 @@ export interface FlowEdgeTravel {
 /** A moment worth a mark on the scrubber. */
 export interface FlowTimelineMark {
   at: number;
+  /** Where a wait ended; the scrubber draws it as a band from `at` to
+   *  here. Left out on a wait, the run is still waiting: the band runs to
+   *  the end of the timeline. */
+  end?: number;
   kind: 'wait' | 'resume' | 'failure' | 'restart';
   /** "Waited 3 h for approval". */
   label: string;
diff --git a/packages/ui/src/components/flow/render/pulse-layer.tsx b/packages/ui/src/components/flow/render/pulse-layer.tsx
index 272820e993..e16d55e609 100644
--- a/packages/ui/src/components/flow/render/pulse-layer.tsx
+++ b/packages/ui/src/components/flow/render/pulse-layer.tsx
@@ -149,14 +149,20 @@ export function FlowPulseLayer({
   layout: FlowLayout;
 }) {
   if (travelling.length === 0) return null;
+  // Two values can be on one line at once (items of a list, passes of a
+  // repeat): each keeps its own dot.
+  const seen = new Map<string, number>();
   return (
     <ViewportPortal>
       {travelling.map(({ edgeId, progress, item }) => {
         const route = layout.edges[edgeId];
         if (route === undefined) return null;
+        const base = `${edgeId}:${item ?? ''}`;
+        const nth = seen.get(base) ?? 0;
+        seen.set(base, nth + 1);
         return (
           <FlowPulse
-            key={`${edgeId}:${item ?? ''}`}
+            key={`${base}:${nth}`}
             edgeId={edgeId}
             points={route.points}
             progress={progress}
diff --git a/services/ui-docs/content/components/workflow-playback.md b/services/ui-docs/content/components/workflow-playback.md
index 0cd3647d32..fc0d4dea32 100644
--- a/services/ui-docs/content/components/workflow-playback.md
+++ b/services/ui-docs/content/components/workflow-playback.md
@@ -42,12 +42,12 @@ When the run failed, the canvas brings forward the way the run took to the first
 
 Press **Play**, drag the scrubber, or step between events. The answer waits three hours for an approval; the replay shows that wait as a hatched band and moves on.
 
-1. Record the run in real time: each node's spans with `startedAt` and `endedAt`, each moment a value left a node (`travels`, with the `target` it goes to), and each wait.
+1. Record the run in real time: each node's spans with `startedAt` and `endedAt`, each moment a value left a node (`travels`, with the `target` it goes to), and each wait. A span's `detail`, such as its duration, shows once the replay reaches the span's end; a span still open on a live run shows its `detail` at once.
 2. Build the timeline once with `buildPlaybackTimeline(run)`.
 3. Drive it with `usePlaybackClock({ timeline })` and pass `playback={{ timeline, t }}` to the canvas.
 4. Put `FlowPlaybackBar` under the canvas, fed by the same clock.
 
-`buildPlaybackTimeline` compresses real time piece by piece. The stretch between two moments plays for its real length, but at least `minStepMs` (240 ms) and at most `maxGapMs` (1.2 s), and each value gets `travelMs` (320 ms) to reach its target before the target starts. A long wait becomes a `wait` mark with your words; a failure becomes a `failure` mark. `toReal(t)` and `fromReal(ms)` map between playback and real time, so the bar can show how long the run really took.
+`buildPlaybackTimeline` compresses real time piece by piece. The stretch between two moments plays for its real length, but at least `minStepMs` (240 ms) and at most `maxGapMs` (1.2 s), and each value gets `travelMs` (320 ms) to reach its target before the target starts. A long wait becomes a `wait` mark with your words and its `end`, drawn as a band on the scrubber; a wait still open has no `end` yet and its band runs to the end of the timeline. A failure becomes a `failure` mark. `toReal(t)` and `fromReal(ms)` map between playback and real time, so the bar can show how long the run really took.
 
 `flowStateAt(graph, timeline, t)` is the frame the canvas draws. Use it to say what is happening for the scrubber's spoken value (`activity`), or to drive the List view.
 

From fd3f8a969dcd47e1e1d2bae41ea61b89628cd7cc Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:36:53 +0200
Subject: [PATCH 31/78] test(ui): measure the flow canvas's run and highlight
 motion

The motion table had rows no test measured. The browser tests now
check four of them:
- a highlight's two stacked lines crossfade on opacity for 150 ms with
  the out-quint ease;
- a running node's top bar sweeps for 1.2 s, linear and endless, and
  holds still under reduced motion;
- a strip settles from 0.35 to full opacity over 150 ms while a run
  plays forward;
- the strip swaps at once when scrubbing back or under reduced motion.

A unit test ties the waits in script to the class delays: new lines
fade in after 250 ms, a relayout settles at 450 ms, and the ring fades
from 300 ms and is gone at 700 ms.
---
 .../flow/motion/flow-motion.test.ts           |  20 ++++
 .../flow/workflow-canvas.run.browser.test.tsx | 101 ++++++++++++++++++
 2 files changed, 121 insertions(+)

diff --git a/packages/ui/src/components/flow/motion/flow-motion.test.ts b/packages/ui/src/components/flow/motion/flow-motion.test.ts
index caa0e432a7..3bd0a2a7fd 100644
--- a/packages/ui/src/components/flow/motion/flow-motion.test.ts
+++ b/packages/ui/src/components/flow/motion/flow-motion.test.ts
@@ -7,7 +7,11 @@ import { easeOutQuint, FLOW_VIEWPORT_DURATION } from '../flow-canvas';
 import {
   FLOW_DURATION,
   FLOW_EASE_OUT_QUINT,
+  FLOW_EDGE_ENTER_DELAY,
   FLOW_MOTION_CLASS,
+  FLOW_RELAYOUT_SETTLE,
+  FLOW_RING_DELAY,
+  FLOW_RING_TOTAL,
 } from './flow-motion';
 
 const css = readFileSync(
@@ -36,6 +40,22 @@ describe('flow motion', () => {
     expect(easeOutQuint(1)).toBe(1);
   });
 
+  it('waits in script exactly as long as the classes delay', () => {
+    // New lines fade in last; the relayout has settled once they are in.
+    expect(FLOW_MOTION_CLASS.fadeIn).toContain(`_${FLOW_EDGE_ENTER_DELAY}ms_`);
+    expect(FLOW_RELAYOUT_SETTLE).toBe(450);
+    // The ring shows through the glide, then fades: gone at 700 ms.
+    expect(FLOW_RING_DELAY).toBe(FLOW_DURATION.medium);
+    expect(FLOW_MOTION_CLASS.ring).toContain(
+      '_var(--duration-long)_var(--ease-default)_var(--duration-medium)_',
+    );
+    expect(FLOW_RING_TOTAL).toBe(700);
+    // A node joins once the glide is under way.
+    expect(FLOW_MOTION_CLASS.enter).toContain(
+      '_var(--duration-standard)_var(--ease-out-quint)_var(--duration-short)_',
+    );
+  });
+
   it('names only keyframes the stylesheet defines', () => {
     for (const [name, className] of Object.entries(FLOW_MOTION_CLASS)) {
       const keyframes = /animate-\[([a-z-]+)_/.exec(className)?.[1];
diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
index 162cd7f045..61cf21a349 100644
--- a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -7,6 +7,7 @@ import { cdp, page, userEvent } from 'vitest/browser';
 import { ratioAgainst } from '@/tests/utils/contrast';
 import { render, screen, waitFor } from '@/tests/utils/render';
 
+import { FLOW_STRIP_SETTLE } from './motion/flow-motion';
 import { highlightForNodes, type FlowPath } from './paths/highlight';
 import { buildPlaybackTimeline } from './playback/build-timeline';
 import { flowStateAt } from './playback/derive-state';
@@ -287,6 +288,92 @@ describe('WorkflowCanvas with a run', () => {
   });
 });
 
+describe('WorkflowCanvas run motion', () => {
+  /** The strip settles the canvas asked the browser for. */
+  const settles = (spy: { mock: { calls: unknown[][] } }) =>
+    spy.mock.calls.filter(
+      ([keyframes]) =>
+        JSON.stringify(keyframes) ===
+        JSON.stringify(FLOW_STRIP_SETTLE.keyframes),
+    );
+
+  it('sweeps a running node’s top bar, and holds it still under reduced motion', async () => {
+    const overlay = {
+      finished: false,
+      nodes: { issues: { state: 'running' as const } },
+    };
+    const { unmount } = await renderRun({ graph: triageFlowGraph(), overlay });
+    const bar = () =>
+      node('issues')?.querySelector('[data-slot="flow-node-running"] > span');
+    let style = getComputedStyle(bar() as Element);
+    expect(style.animationName).toBe('flow-running-sweep');
+    expect(style.animationDuration).toBe('1.2s');
+    expect(style.animationTimingFunction).toBe('linear');
+    expect(style.animationIterationCount).toBe('infinite');
+    unmount();
+
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    await renderRun({ graph: triageFlowGraph(), overlay });
+    style = getComputedStyle(bar() as Element);
+    // Still there, still blue — it only stops moving.
+    expect(style.animationName).toBe('none');
+    expect(bar()).toBeVisible();
+  });
+
+  it('settles a strip softly as the run plays on, and swaps it when scrubbing back', async () => {
+    const graph = triageFlowGraph();
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const issues = timeline.spans.find((span) => span.nodeId === 'issues');
+    if (issues?.end === undefined) throw new Error('no issues span');
+    const running = (issues.start + issues.end) / 2;
+    const { rerun } = await renderRun({
+      graph,
+      playback: { timeline, t: running },
+    });
+    expect(strip('issues')).toBe('Running');
+    const animate = vi.spyOn(Element.prototype, 'animate');
+    try {
+      rerun({ playback: { timeline, t: issues.end + 1 } });
+      await waitFor(() => expect(strip('issues')).toBe('Succeeded · 1.2 s'));
+      const forward = settles(animate);
+      expect(forward.length).toBeGreaterThan(0);
+      expect(forward[0]?.[1]).toEqual(FLOW_STRIP_SETTLE.options);
+      expect(FLOW_STRIP_SETTLE.options.duration).toBe(150);
+
+      animate.mockClear();
+      rerun({ playback: { timeline, t: running } });
+      await waitFor(() => expect(strip('issues')).toBe('Running'));
+      expect(settles(animate)).toEqual([]);
+    } finally {
+      animate.mockRestore();
+    }
+  });
+
+  it('swaps strips at once under reduced motion', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const graph = triageFlowGraph();
+    const timeline = buildPlaybackTimeline(triageFailedRun());
+    const issues = timeline.spans.find((span) => span.nodeId === 'issues');
+    if (issues?.end === undefined) throw new Error('no issues span');
+    const { rerun } = await renderRun({
+      graph,
+      playback: { timeline, t: (issues.start + issues.end) / 2 },
+    });
+    const animate = vi.spyOn(Element.prototype, 'animate');
+    try {
+      rerun({ playback: { timeline, t: issues.end + 1 } });
+      await waitFor(() => expect(strip('issues')).toBe('Succeeded · 1.2 s'));
+      expect(settles(animate)).toEqual([]);
+    } finally {
+      animate.mockRestore();
+    }
+  });
+});
+
 describe('WorkflowCanvas highlights', () => {
   it('highlights the paths through No when a pointer rests on its label', async () => {
     const onHighlightChange = vi.fn();
@@ -322,6 +409,20 @@ describe('WorkflowCanvas highlights', () => {
     expect(look('open_issues>score')).toBe('emphasis');
     expect(look('score>report')).toBe('base');
     expect(document.querySelector('[data-flow-quiet]')).toBeNull();
+    // The two stacked lines crossfade: opacity only, short, out-quint.
+    for (const selector of [
+      'path[data-flow-edge="issues>open_issues"]',
+      'path[data-flow-edge-state="issues>open_issues"]',
+    ]) {
+      const style = getComputedStyle(
+        document.querySelector(selector) as Element,
+      );
+      expect(style.transitionProperty, selector).toBe('opacity');
+      expect(style.transitionDuration, selector).toBe('0.15s');
+      expect(style.transitionTimingFunction, selector).toBe(
+        'cubic-bezier(0.22, 1, 0.36, 1)',
+      );
+    }
   });
 
   it('shows a host highlight with its reasons, and says it once', async () => {

From 95b431ec592781a9bfb6a0ad5b7b50d383658bc6 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:37:03 +0200
Subject: [PATCH 32/78] refactor(ui): drop the flow node look hook nothing uses

---
 .../ui/src/components/flow/render/flow-render-context.tsx    | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/packages/ui/src/components/flow/render/flow-render-context.tsx b/packages/ui/src/components/flow/render/flow-render-context.tsx
index 1134c4632d..44cdd67633 100644
--- a/packages/ui/src/components/flow/render/flow-render-context.tsx
+++ b/packages/ui/src/components/flow/render/flow-render-context.tsx
@@ -99,11 +99,6 @@ const PLAIN: FlowNodeLook = {
   highlighted: 'none',
 };
 
-/** The look of a node, plain when the chart has nothing to say about it. */
-export function useFlowNodeLook(id: string): FlowNodeLook {
-  return useFlowRender().looks.get(id) ?? PLAIN;
-}
-
 /** The run states that mean "it did not run here": a dashed border. */
 const PASSED_BY: ReadonlySet<FlowNodeState> = new Set([
   'skipped',

From 67ae13c54a5f2e5cf45dda6b058c9ec57bfd1952 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:37:12 +0200
Subject: [PATCH 33/78] docs(ui): list the flow paths and playback entry points

---
 packages/ui/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/README.md b/packages/ui/README.md
index f86c741eaa..e7e2de89fc 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -19,7 +19,7 @@ and stories live together under `src/components/<family>/`.
 | Layout and navigation | `page-layout`, `adaptive-header`, `sub-panel`, `header-breadcrumbs`, `tab-navigation` |
 | Dialogs and feedback | `dialog/form-dialog`, `dialog/delete-dialog`, `toaster`, `use-toast`, `use-retry-focus` |
 | Problems a check found | `issue-list`, `issue-summary`, `issue-severity`, `field-issue-messages`, `issue-focus`, `flow/node-issue-marker` |
-| Editing and diagrams | `editor`, `wizard/*`, `catalog/*`, `filters/*`, `flow/workflow-canvas`, `flow/flow-step-list`, `flow/layout`, `flow/*` |
+| Editing and diagrams | `editor`, `wizard/*`, `catalog/*`, `filters/*`, `flow/workflow-canvas`, `flow/flow-step-list`, `flow/flow-path-list`, `flow/paths`, `flow/playback`, `flow/playback-bar`, `flow/layout`, `flow/*` |
 | Documentation sites | `docs/docs-layout`, `docs/docs-header`, `docs/docs-article`, `docs/docs-not-found`, `docs/page-actions`, `search/static-index/*` |
 | Shared infrastructure | `i18n/*`, `markdown/*`, `seo/*`, `server`, `monitoring/*`, `theme`, `testing/*` |
 | Large custom collections | `use-virtual-list`; [windowing and focus guidance](https://ui.tale.dev/docs/patterns/list-page#bound-a-custom-collections-rendering) |

From 2e532670451642a92a1b791a0f55ac37e450f7ca Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:40:12 +0200
Subject: [PATCH 34/78] test(ui): cover a relayout mid-transition and following
 a run

Two motion rows had no test. A relayout that lands while another is
still playing must plan from the picture on screen and run on its own
timers; a unit test now checks that the leaving and joining parts come
from the picture on screen and that the first relayout's timers no
longer end the second early.

While a run plays, the canvas follows the node it reaches into view. A
browser test now checks that it follows only until the reader moves
the view: after a wheel zoom, a node starting below the fold leaves the
view where the reader put it.
---
 .../flow/motion/use-layout-transition.test.ts | 32 +++++++++
 .../flow/workflow-canvas.run.browser.test.tsx | 70 +++++++++++++++++++
 2 files changed, 102 insertions(+)

diff --git a/packages/ui/src/components/flow/motion/use-layout-transition.test.ts b/packages/ui/src/components/flow/motion/use-layout-transition.test.ts
index 48500e1d8d..ff4283ba8c 100644
--- a/packages/ui/src/components/flow/motion/use-layout-transition.test.ts
+++ b/packages/ui/src/components/flow/motion/use-layout-transition.test.ts
@@ -178,6 +178,38 @@ describe('useLayoutTransition', () => {
     expect(result.current.phase).toBeNull();
   });
 
+  it('starts a relayout that lands mid-transition from the picture on screen, on its own clock', () => {
+    const { result, rerender } = renderHook(
+      ({ picture }) =>
+        useLayoutTransition({ picture, layoutKey: 'doc', enabled: true }),
+      { initialProps: { picture: before() } },
+    );
+    rerender({ picture: after() });
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    // Back to the chain while d is still growing in: d leaves, c joins.
+    rerender({ picture: before() });
+    expect(result.current.phase).toBe('exit');
+    expect(result.current.plan?.entering.has('c')).toBe(true);
+    expect(result.current.plan?.leaving.map(({ node }) => node.id)).toEqual([
+      'd',
+    ]);
+    // The first relayout's timers no longer count.
+    act(() => {
+      vi.advanceTimersByTime(FLOW_DURATION.short - 100);
+    });
+    expect(result.current.phase).toBe('exit');
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current.phase).toBe('settle');
+    act(() => {
+      vi.advanceTimersByTime(FLOW_RELAYOUT_SETTLE - FLOW_DURATION.short);
+    });
+    expect(result.current.plan).toBeNull();
+  });
+
   it('plays nothing for a new picture, the first layout or reduced motion', () => {
     const { result, rerender } = renderHook(
       ({ picture, layoutKey, enabled }) =>
diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
index 61cf21a349..869d530b1e 100644
--- a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -351,6 +351,76 @@ describe('WorkflowCanvas run motion', () => {
     }
   });
 
+  it('follows the node a run reaches into view, until the reader moves the view', async () => {
+    await page.viewport(1280, 900);
+    // Report runs from 400 to 900: below the fold of a small frame.
+    const timeline: FlowPlaybackTimeline = {
+      duration: 1_000,
+      spans: [{ nodeId: 'report', start: 400, end: 900, outcome: 'succeeded' }],
+      travels: [],
+      events: [400, 900],
+    };
+    const Small = ({ t }: { t: number }) => (
+      <div data-testid="small" style={{ width: 600, height: 320 }}>
+        <WorkflowCanvas
+          graph={triageFlowGraph()}
+          aria-label="Workflow"
+          layoutKey="follow"
+          fitPolicy="auto"
+          playback={{ timeline, t }}
+        />
+      </div>
+    );
+    const inside = (id: string) => {
+      const frame = screen.getByTestId('small').getBoundingClientRect();
+      const box = node(id)?.getBoundingClientRect();
+      return (
+        box !== undefined &&
+        box.top >= frame.top - 1 &&
+        box.bottom <= frame.bottom + 1
+      );
+    };
+    const opened = async () => {
+      const view = render(<Small t={0} />);
+      await waitFor(() => expect(node('report')).not.toBeNull(), {
+        timeout: 20_000,
+      });
+      await viewportAtRest();
+      expect(inside('report')).toBe(false);
+      return view;
+    };
+    const first = await opened();
+    first.rerender(<Small t={500} />);
+    await waitFor(() => expect(inside('report')).toBe(true));
+    await viewportAtRest();
+    first.unmount();
+
+    // The same run opened again: the reader zooms in on Start, and the run
+    // no longer pulls the view away.
+    const { rerender } = await opened();
+    const pane = document.querySelector('.react-flow__pane');
+    if (pane === null) throw new Error('no pane');
+    const at = node('__start')?.getBoundingClientRect();
+    pane.dispatchEvent(
+      new WheelEvent('wheel', {
+        deltaY: -120,
+        clientX: (at?.left ?? 0) + 20,
+        clientY: (at?.top ?? 0) + 20,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    await viewportAtRest();
+    const moved = await viewportAtRest();
+    rerender(<Small t={500} />);
+    await waitFor(() =>
+      expect(node('report')).toHaveAttribute('data-flow-state', 'running'),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    expect(await viewportAtRest()).toBe(moved);
+    expect(inside('report')).toBe(false);
+  });
+
   it('swaps strips at once under reduced motion', async () => {
     await cdp().send('Emulation.setEmulatedMedia', {
       features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],

From a179d0698e18ff858612577c1bedc76acaaa0cfa Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 16:42:25 +0200
Subject: [PATCH 35/78] fix(ui): keep a frame's run counter beside its words,
 not over them

In a run, a frame's counter ("4 of 4 items") sat at the frame's right
edge on top of its header. A long header such as "For each item of
issues of Open issues" ran under the chip and lost its end without an
ellipsis. The header and the counter now share one row: the words keep
the box the layout gave them and end in an ellipsis before the counter
when the two do not fit side by side.
---
 .../components/flow/render/group-frame.tsx    | 40 ++++++++++---------
 .../flow/workflow-canvas.run.browser.test.tsx | 11 +++--
 2 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/packages/ui/src/components/flow/render/group-frame.tsx b/packages/ui/src/components/flow/render/group-frame.tsx
index c53a868788..f13ce4fdf2 100644
--- a/packages/ui/src/components/flow/render/group-frame.tsx
+++ b/packages/ui/src/components/flow/render/group-frame.tsx
@@ -54,28 +54,30 @@ export const FlowGroupFrameView = memo(function FlowGroupFrameView({
         phase === 'exit' && FLOW_MOTION_CLASS.fadeOut,
       )}
     >
+      {/* One row: the header's words in the box the layout kept for them,
+          and in a run the counter at the frame's right edge. A long label
+          ends in an ellipsis before the counter, never under it. */}
       <div
-        data-slot="flow-frame-header"
-        className="text-muted-foreground absolute flex items-center gap-1.5 px-1 text-xs leading-4 font-medium"
-        style={{
-          left: header.x,
-          top: header.y,
-          width: header.width,
-          height: header.height,
-        }}
+        className="absolute right-2 flex items-center gap-2"
+        style={{ left: header.x, top: header.y, height: header.height }}
       >
-        <Icon className="size-3.5 shrink-0" />
-        <span className="truncate">{group.label}</span>
-      </div>
-      {counter && (
-        <span
-          data-slot="flow-frame-counter"
-          className="bg-background text-foreground border-border absolute right-2 inline-flex h-5 items-center rounded-full border px-2 text-xs font-medium tabular-nums"
-          style={{ top: header.y + (header.height - 20) / 2 }}
+        <div
+          data-slot="flow-frame-header"
+          className="text-muted-foreground flex min-w-0 items-center gap-1.5 px-1 text-xs leading-4 font-medium"
+          style={{ width: header.width }}
         >
-          {counter}
-        </span>
-      )}
+          <Icon className="size-3.5 shrink-0" />
+          <span className="truncate">{group.label}</span>
+        </div>
+        {counter && (
+          <span
+            data-slot="flow-frame-counter"
+            className="bg-background text-foreground border-border ml-auto inline-flex h-5 shrink-0 items-center rounded-full border px-2 text-xs font-medium whitespace-nowrap tabular-nums"
+          >
+            {counter}
+          </span>
+        )}
+      </div>
       {group.kind === 'repeat' && member && (
         <svg className="absolute inset-0 size-full overflow-visible">
           <path
diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
index 869d530b1e..c4c7f00058 100644
--- a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -228,10 +228,13 @@ describe('WorkflowCanvas with a run', () => {
     expect(node('report')).toHaveAttribute('data-flow-quiet', 'true');
     expect(look('score>report')).toBe('quiet');
     expect(node('__end')).toHaveAttribute('data-flow-state', 'failed');
-    // The frame counts the items.
-    expect(
-      document.querySelector('[data-slot="flow-frame-counter"]')?.textContent,
-    ).toBe('4 of 4 items');
+    // The frame counts the items, beside its words, never over them.
+    const counter = document.querySelector('[data-slot="flow-frame-counter"]');
+    expect(counter?.textContent).toBe('4 of 4 items');
+    const header = document.querySelector('[data-slot="flow-frame-header"]');
+    expect(header?.getBoundingClientRect().right).toBeLessThanOrEqual(
+      (counter?.getBoundingClientRect().left ?? 0) + 0.5,
+    );
 
     rerun({
       playback: { timeline, t: timeline.duration },

From 9157675895a06ec0133550ab4c559f2ff04a3ea7 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:37:35 +0200
Subject: [PATCH 36/78] feat(platform): ask the draft check for its analysis
 and shapes

The editor's draft check now asks the validate route for `detail:
['analysis', 'types']` and reads both through zod at the boundary: the
part of the analysis the canvas uses (why a node can fail, which nodes
end a run, whether the result may be empty) and the inferred shapes of
the run input, each node's output and the result. A shape nests at most
16 levels before the rest reads as "anything".

Each part is read on its own: one in a shape this build does not read is
dropped with a warning, and the issues still stand.
---
 .../hooks/use-automation-validation.test.tsx  |  28 ++++
 .../hooks/use-automation-validation.ts        |  26 ++-
 .../lib/backend/automation-validation.test.ts | 152 ++++++++++++++++++
 .../app/lib/backend/automation-validation.ts  |  49 +++++-
 .../lib/shared/schemas/automation-issues.ts   | 133 ++++++++++++++-
 5 files changed, 377 insertions(+), 11 deletions(-)
 create mode 100644 services/platform/app/lib/backend/automation-validation.test.ts

diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
index 0b3db1e1b8..7a7a22c1ec 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
@@ -111,6 +111,34 @@ describe('useAutomationValidation', () => {
     );
   });
 
+  it('asks for the analysis and the shapes, and keeps them with the result', async () => {
+    const analysis = {
+      nodes: {},
+      paths: { count: 1, truncated: false, halts: [] },
+      output: { reads: [], maybeEmpty: false },
+    };
+    const types = {
+      inputs: {},
+      nodes: { reply: { output: { type: 'string' } } },
+      output: {},
+    };
+    validate.mockResolvedValue({ ...answer(), analysis, types });
+    const { result } = renderValidation({
+      document: doc('Hi'),
+      isDraft: false,
+      enabled: true,
+    });
+    await waitFor(() => expect(result.current.status).toBe('ready'));
+    expect(validate).toHaveBeenCalledWith(
+      'org-1',
+      'support/triage',
+      doc('Hi'),
+      expect.objectContaining({ detail: ['analysis', 'types'] }),
+    );
+    expect(result.current.analysis).toEqual(analysis);
+    expect(result.current.types).toEqual(types);
+  });
+
   it('waits for a pause in the edits and checks the newest draft only', async () => {
     vi.useFakeTimers({ shouldAdvanceTime: true });
     validate.mockResolvedValue(answer());
diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.ts b/services/platform/app/features/automations/hooks/use-automation-validation.ts
index 23a17a1b1e..ca8938ac6a 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.ts
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.ts
@@ -9,10 +9,17 @@ import {
 import { useCallback, useMemo, useRef } from 'react';
 
 import { runAdapted } from '@/app/lib/backend/adapters';
-import { validateAutomationDraft } from '@/app/lib/backend/automation-validation';
+import {
+  validateAutomationDraft,
+  type DraftCheck,
+  type ValidationDetail,
+} from '@/app/lib/backend/automation-validation';
 import { backendKey } from '@/app/lib/backend/query-keys';
 import type { Automation } from '@/lib/engine/core/types';
-import type { ValidationAnswer } from '@/lib/shared/schemas/automation-issues';
+import type {
+  AnalysisView,
+  TypesView,
+} from '@/lib/shared/schemas/automation-issues';
 import { stableStringify } from '@/lib/shared/utils/stable-stringify';
 
 import { withIssueIds, type AutomationIssue } from '../lib/issues';
@@ -137,13 +144,23 @@ export interface AutomationValidation {
   currentHash: string | null;
   /** Why the last check failed, when it did. */
   failure?: unknown;
+  /** The last result's analysis: why each node can fail, what the result
+   * may leave empty — of the document on screen when `ready`. */
+  analysis: AnalysisView | null;
+  /** The last result's inferred shapes: the run input, each node's output,
+   * the result. */
+  types: TypesView | null;
 }
 
 interface Settled {
   hash: string;
-  answer: ValidationAnswer;
+  answer: DraftCheck;
 }
 
+/** What every check asks for beside the issues: the canvas words why a
+ * node can fail and shows what each node returns. */
+const DETAIL: readonly ValidationDetail[] = ['analysis', 'types'];
+
 const NO_ISSUES: AutomationIssue[] = [];
 
 /**
@@ -197,6 +214,7 @@ export function useAutomationValidation({
         runAdapted(() =>
           validateAutomationDraft(organizationId, automationSlug, target, {
             signal: bounded,
+            detail: DETAIL,
           }),
         ),
       ),
@@ -244,5 +262,7 @@ export function useAutomationValidation({
     settledFor: settled?.hash ?? null,
     currentHash,
     ...(status === 'failed' && { failure: query.error }),
+    analysis: settled?.answer.analysis ?? null,
+    types: settled?.answer.types ?? null,
   };
 }
diff --git a/services/platform/app/lib/backend/automation-validation.test.ts b/services/platform/app/lib/backend/automation-validation.test.ts
new file mode 100644
index 0000000000..7e3c86b780
--- /dev/null
+++ b/services/platform/app/lib/backend/automation-validation.test.ts
@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { MAX_SHAPE_DEPTH } from '@/lib/shared/schemas/automation-issues';
+
+import { validateAutomationDraft } from './automation-validation';
+
+/**
+ * The draft check at its boundary: what the editor asks for beside the
+ * issues, and how each part of the answer is read on its own — a malformed
+ * analysis or shape tree is dropped with a warning, never the issues.
+ */
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const ISSUE = {
+  level: 'error',
+  code: 'REF_UNKNOWN_NODE',
+  message: 'nodes.nope does not exist',
+  at: { pointer: '/nodes/0/prompt' },
+};
+
+const ANALYSIS = {
+  version: 1,
+  nodes: { a: { failureReasons: ['code'], reachable: true } },
+  paths: {
+    atoms: [],
+    success: [],
+    count: 1,
+    truncated: false,
+    halts: [{ nodeId: 'a', reasons: ['code'] }],
+  },
+  output: { reads: ['a'], maybeEmpty: false },
+};
+
+const TYPES = {
+  inputs: { type: 'object', properties: {} },
+  nodes: {
+    a: {
+      output: {
+        type: 'object',
+        properties: { count: { type: 'number' } },
+        required: ['count'],
+        'x-origin': 'inferred',
+      },
+      ts: '{ count: number }',
+      origin: 'inferred',
+    },
+  },
+  output: { type: 'object', properties: { count: { type: 'number' } } },
+};
+
+let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+function answerWith(body: unknown) {
+  fetchSpy.mockImplementation(async () => jsonResponse(body));
+}
+
+beforeEach(() => {
+  window.__ENV__ = { BASE_PATH: '' };
+  fetchSpy = vi.spyOn(window, 'fetch');
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete window.__ENV__;
+});
+
+describe('validateAutomationDraft', () => {
+  it('asks for the detail it names and reads the analysis and the shapes', async () => {
+    answerWith({
+      valid: false,
+      errors: [ISSUE],
+      warnings: [],
+      analysis: ANALYSIS,
+      types: TYPES,
+    });
+    const check = await validateAutomationDraft(
+      'org-1',
+      'support/triage',
+      { name: 'x', nodes: [] },
+      { detail: ['analysis', 'types'] },
+    );
+    const init = fetchSpy.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      detail: ['analysis', 'types'],
+    });
+    expect(check.errors).toEqual([expect.objectContaining(ISSUE)]);
+    expect(check.analysis).toEqual({
+      nodes: { a: { failureReasons: ['code'] } },
+      paths: {
+        count: 1,
+        truncated: false,
+        halts: [{ nodeId: 'a', reasons: ['code'] }],
+      },
+      output: { reads: ['a'], maybeEmpty: false },
+    });
+    expect(check.types?.nodes.a?.output).toEqual(TYPES.nodes.a.output);
+  });
+
+  it('drops a malformed shape tree with a warning and keeps the issues', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    answerWith({
+      valid: false,
+      errors: [ISSUE],
+      warnings: [],
+      types: { ...TYPES, nodes: { a: { output: { properties: 'nope' } } } },
+    });
+    const check = await validateAutomationDraft('org-1', 'x', {});
+    expect(check.types).toBeUndefined();
+    expect(check.errors).toHaveLength(1);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('types'),
+      expect.anything(),
+    );
+  });
+
+  it('reads a shape deeper than the cap as anything, instead of recursing on', async () => {
+    let deep: Record<string, unknown> = { type: 'string' };
+    for (let i = 0; i < MAX_SHAPE_DEPTH + 4; i++) {
+      deep = { type: 'array', items: deep };
+    }
+    answerWith({
+      valid: true,
+      errors: [],
+      warnings: [],
+      types: { ...TYPES, output: deep },
+    });
+    const check = await validateAutomationDraft('org-1', 'x', {});
+    let at: unknown = check.types?.output;
+    let depth = 0;
+    while (typeof at === 'object' && at !== null && 'items' in at) {
+      at = (at as { items: unknown }).items;
+      depth++;
+    }
+    expect(depth).toBe(MAX_SHAPE_DEPTH);
+    expect(at).toEqual({});
+  });
+
+  it('answers without detail when none was asked for', async () => {
+    answerWith({ valid: true, errors: [], warnings: [] });
+    const check = await validateAutomationDraft('org-1', 'x', {});
+    const init = fetchSpy.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({ detail: [] });
+    expect(check).toEqual({ valid: true, errors: [], warnings: [] });
+  });
+});
diff --git a/services/platform/app/lib/backend/automation-validation.ts b/services/platform/app/lib/backend/automation-validation.ts
index a7bc846404..be26616cc0 100644
--- a/services/platform/app/lib/backend/automation-validation.ts
+++ b/services/platform/app/lib/backend/automation-validation.ts
@@ -5,8 +5,14 @@
  * the automation editor checks a draft.
  */
 
+import type { ZodType } from 'zod';
+
 import {
+  analysisSchema,
+  typesSchema,
   validationAnswerSchema,
+  type AnalysisView,
+  type TypesView,
   type ValidationAnswer,
 } from '@/lib/shared/schemas/automation-issues';
 
@@ -16,13 +22,42 @@ import { namePath } from './automations';
 /** What a draft check answers beside the issues (`detail` of the route). */
 export type ValidationDetail = 'analysis' | 'types';
 
+/** A check's answer: the issues, and what it was asked for beside them
+ * when it answered that in a shape this build reads. */
+export type DraftCheck = ValidationAnswer & {
+  analysis?: AnalysisView;
+  types?: TypesView;
+};
+
+/** One detail of an answer, read on its own: a malformed one is left out
+ * with a warning, and the issues still stand. */
+function detailOf<T>(
+  body: unknown,
+  key: ValidationDetail,
+  schema: ZodType<T>,
+): T | undefined {
+  if (typeof body !== 'object' || body === null || !(key in body)) {
+    return undefined;
+  }
+  const value: unknown = Reflect.get(body, key);
+  if (value === undefined || value === null) return undefined;
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  console.warn(
+    `[automations] the draft check answered its ${key} in a shape this app does not read`,
+    parsed.error.issues,
+  );
+  return undefined;
+}
+
 /**
  * Check a draft without saving it: the problems the engine finds, split into
  * errors and warnings. Reads only — nothing is written or audited — and is
  * author-gated like a save. The answer is parsed at this boundary; one in a
  * shape this build does not read is a failed check, never a cast. `detail`
- * names what to answer beside the issues; the editor reads none of it yet,
- * so the default asks for nothing more.
+ * names what to answer beside the issues (nothing more by default); each
+ * part is read on its own, so a malformed part is dropped, never the
+ * issues.
  *
  * Throws the transport's errors as they are; callers that show a refusal's
  * words normalize them through `runAdapted` like every adapted read.
@@ -35,7 +70,7 @@ export async function validateAutomationDraft(
     signal?: AbortSignal;
     detail?: readonly ValidationDetail[];
   } = {},
-): Promise<ValidationAnswer> {
+): Promise<DraftCheck> {
   const body = await backendFetch<unknown>(
     `/automations/${namePath(name)}/validate`,
     {
@@ -52,5 +87,11 @@ export async function validateAutomationDraft(
     );
     throw new Error('The draft check answered in an unreadable shape.');
   }
-  return parsed.data;
+  const analysis = detailOf(body, 'analysis', analysisSchema);
+  const types = detailOf(body, 'types', typesSchema);
+  return {
+    ...parsed.data,
+    ...(analysis !== undefined && { analysis }),
+    ...(types !== undefined && { types }),
+  };
 }
diff --git a/services/platform/lib/shared/schemas/automation-issues.ts b/services/platform/lib/shared/schemas/automation-issues.ts
index f33eef55c6..fbf760d650 100644
--- a/services/platform/lib/shared/schemas/automation-issues.ts
+++ b/services/platform/lib/shared/schemas/automation-issues.ts
@@ -7,10 +7,14 @@
  * The engine's own `Issue` (`lib/engine/core/types.ts`) is the source of
  * truth; this schema reads what the editor uses of it, so a malformed or
  * foreign answer is refused at the boundary instead of travelling into the
- * Problems panel as a cast. Fields the editor does not read (`related`, the
- * analysis and the inferred types) are left out and stripped. A code is any
- * string: a newer server's code still reads, as a problem this build has no
- * words for.
+ * Problems panel as a cast. Fields the editor does not read (`related`, most
+ * of the analysis) are left out and stripped. A code is any string: a newer
+ * server's code still reads, as a problem this build has no words for.
+ *
+ * Beside the issues, a check may answer the part of its analysis the canvas
+ * reads (why a node can fail, what the result may leave empty) and the
+ * inferred shapes of the run input, every node's output and the result. Each
+ * is read on its own: a malformed one is dropped, never the issues with it.
  */
 
 import { z } from 'zod';
@@ -51,6 +55,127 @@ export const validationAnswerSchema = z.object({
 
 export type ValidationAnswer = z.infer<typeof validationAnswerSchema>;
 
+/** The part of the check's analysis the canvas reads. A failure reason is
+ * any string: a newer server's reason reads as no words, not a refusal. */
+export const analysisSchema = z.object({
+  nodes: z.record(
+    z.string(),
+    z.object({ failureReasons: z.array(z.string()) }),
+  ),
+  paths: z.object({
+    count: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+    halts: z.array(
+      z.object({ nodeId: z.string(), reasons: z.array(z.string()) }),
+    ),
+  }),
+  output: z.object({ reads: z.array(z.string()), maybeEmpty: z.boolean() }),
+});
+
+export type AnalysisView = z.infer<typeof analysisSchema>;
+
+/** A JSON value, as `enum` and `const` hold them. */
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.string(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+  ]),
+);
+
+/** An inferred shape (the engine's `Shape`, a JSON Schema subset). */
+export interface WireShape {
+  type?:
+    | 'object'
+    | 'array'
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'null';
+  properties?: Record<string, WireShape>;
+  required?: string[];
+  additionalProperties?: boolean | WireShape;
+  items?: WireShape;
+  anyOf?: WireShape[];
+  enum?: JsonValue[];
+  const?: JsonValue;
+  description?: string;
+  'x-origin'?: 'declared' | 'signature' | 'inferred' | 'fixed' | 'child';
+}
+
+/** Shapes nest this deep before the rest reads as "anything": a
+ * pathological answer cannot make the parse recurse without end. */
+export const MAX_SHAPE_DEPTH = 16;
+
+const shapeAt = new Map<number, z.ZodType<WireShape>>();
+
+function shapeSchemaAt(depth: number): z.ZodType<WireShape> {
+  const known = shapeAt.get(depth);
+  if (known !== undefined) return known;
+  const schema: z.ZodType<WireShape> =
+    depth >= MAX_SHAPE_DEPTH
+      ? z.unknown().transform((): WireShape => ({}))
+      : z.lazy(() => {
+          const inner = shapeSchemaAt(depth + 1);
+          return z.object({
+            type: z
+              .enum([
+                'object',
+                'array',
+                'string',
+                'number',
+                'integer',
+                'boolean',
+                'null',
+              ])
+              .optional(),
+            properties: z.record(z.string(), inner).optional(),
+            required: z.array(z.string()).optional(),
+            additionalProperties: z.union([z.boolean(), inner]).optional(),
+            items: inner.optional(),
+            anyOf: z.array(inner).optional(),
+            enum: z.array(jsonValueSchema).optional(),
+            const: jsonValueSchema.optional(),
+            description: z.string().optional(),
+            'x-origin': z
+              .enum(['declared', 'signature', 'inferred', 'fixed', 'child'])
+              .optional(),
+          });
+        });
+  shapeAt.set(depth, schema);
+  return schema;
+}
+
+const shapeSchema = shapeSchemaAt(0);
+
+/** The inferred shapes: the run input, each node's output, the result. */
+export const typesSchema = z.object({
+  inputs: shapeSchema,
+  nodes: z.record(
+    z.string(),
+    z.object({
+      output: shapeSchema,
+      item: shapeSchema.optional(),
+      input: shapeSchema.optional(),
+    }),
+  ),
+  output: shapeSchema,
+});
+
+export type TypesView = z.infer<typeof typesSchema>;
+
 /** What a refused save or deploy carries beside its sentence. */
 export const refusalIssuesSchema = z.object({
   errors: z.array(issueSchema).optional(),

From b808c80c454b5671bae730f63b5f5c8fa3823ce8 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:37:56 +0200
Subject: [PATCH 37/78] refactor(platform): share the cron field's schedule
 words

`cronPatternText` turns a recognised schedule into the words the Cron
field shows under it ("Every day at 07:00"), so the canvas's Start can
say the same words without a second copy.
---
 .../automations/hooks/use-cron-preview.ts     | 27 ++++++----------
 .../features/automations/lib/cron-preview.ts  | 31 +++++++++++++++++++
 2 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/services/platform/app/features/automations/hooks/use-cron-preview.ts b/services/platform/app/features/automations/hooks/use-cron-preview.ts
index de8e45a322..552e15ffa0 100644
--- a/services/platform/app/features/automations/hooks/use-cron-preview.ts
+++ b/services/platform/app/features/automations/hooks/use-cron-preview.ts
@@ -3,7 +3,11 @@ import { useMemo } from 'react';
 
 import { useT } from '@/lib/i18n/client';
 
-import { type CronPreview, previewCronExpression } from '../lib/cron-preview';
+import {
+  cronPatternText,
+  type CronPreview,
+  previewCronExpression,
+} from '../lib/cron-preview';
 
 /**
  * The words under a Cron field — one hook for every surface that takes a
@@ -44,22 +48,11 @@ export function useCronPreview(
         : t('trigger.cronInvalidReason', { reason: preview.reason })
       : undefined;
 
-  const pattern = useMemo(() => {
-    if (preview.kind !== 'ok') return undefined;
-    if (preview.pattern?.type === 'everyMinutes') {
-      return t('trigger.cronEveryMinutes', { n: preview.pattern.n });
-    }
-    if (preview.pattern?.type === 'everyHours') {
-      return t('trigger.cronEveryHours', { n: preview.pattern.n });
-    }
-    if (preview.pattern?.type === 'dailyAt') {
-      const { hour, minute } = preview.pattern;
-      const hh = String(hour).padStart(2, '0');
-      const mm = String(minute).padStart(2, '0');
-      return t('trigger.cronDailyAt', { time: `${hh}:${mm}` });
-    }
-    return undefined;
-  }, [preview, t]);
+  const pattern = useMemo(
+    () =>
+      preview.kind === 'ok' ? cronPatternText(preview.pattern, t) : undefined,
+    [preview, t],
+  );
 
   const description = useMemo(() => {
     if (!active) return undefined;
diff --git a/services/platform/app/features/automations/lib/cron-preview.ts b/services/platform/app/features/automations/lib/cron-preview.ts
index 50f20740c3..6225d02fed 100644
--- a/services/platform/app/features/automations/lib/cron-preview.ts
+++ b/services/platform/app/features/automations/lib/cron-preview.ts
@@ -121,6 +121,37 @@ export function previewCronExpression(
   }
 }
 
+/** The translate function of the session's language, bound to the
+ *  `automations` namespace. */
+export type CronTranslate = (
+  key: string,
+  options?: Record<string, unknown>,
+) => string;
+
+/**
+ * A recognised schedule in words ("Every 5 minutes", "Every day at 07:00"),
+ * or undefined for a shape the preview does not name — one wording for the
+ * Cron field's hint and the Start of the canvas.
+ */
+export function cronPatternText(
+  pattern: Extract<CronPreview, { kind: 'ok' }>['pattern'],
+  t: CronTranslate,
+): string | undefined {
+  if (pattern === null) return undefined;
+  switch (pattern.type) {
+    case 'everyMinutes':
+      return t('trigger.cronEveryMinutes', { n: pattern.n });
+    case 'everyHours':
+      return t('trigger.cronEveryHours', { n: pattern.n });
+    default: {
+      // `dailyAt`: one time of day.
+      const hh = String(pattern.hour).padStart(2, '0');
+      const mm = String(pattern.minute).padStart(2, '0');
+      return t('trigger.cronDailyAt', { time: `${hh}:${mm}` });
+    }
+  }
+}
+
 /**
  * Whether `timezone` names a zone `Intl` resolves — the check the bind
  * makes (`wallClockIn` throws on an unknown zone), so a surface can refuse

From 85ab3be866ecc02e7d06a28645dc0557585219d5 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:38:05 +0200
Subject: [PATCH 38/78] fix(platform): draw run states with the canvas's glyphs
 and colours

The run badges and the step timeline's icons now read their glyph and
colour from `@tale/ui/flow/node-status`, the vocabulary the canvas draws
node states with. Settled and skipped states were slate-400 icons at
2.6:1 on a white page; every glyph now reaches 3:1, and a running node
spins only where motion is welcome. A node whose server stopped keeps a
still glyph of its own, and the page keeps its own words.
---
 .../components/run-status-badge.test.tsx      | 34 ++++++--
 .../components/run-status-badge.tsx           | 82 +++++++++----------
 .../app/features/automations/lib/run-view.ts  | 24 ++++++
 3 files changed, 90 insertions(+), 50 deletions(-)

diff --git a/services/platform/app/features/automations/components/run-status-badge.test.tsx b/services/platform/app/features/automations/components/run-status-badge.test.tsx
index 2646991d87..51141d7ec7 100644
--- a/services/platform/app/features/automations/components/run-status-badge.test.tsx
+++ b/services/platform/app/features/automations/components/run-status-badge.test.tsx
@@ -29,14 +29,18 @@ describe('run status icons', () => {
     expect(container.querySelector('svg')).not.toHaveClass('animate-spin');
   });
 
+  // A node spins only where motion is welcome: the canvas's own glyph, which
+  // stands still under reduced motion.
   it('spins a running node badge but leaves settled ones still', () => {
     const running = render(<RunStatusBadge status="running" />);
-    expect(running.container.querySelector('svg')).toHaveClass('animate-spin');
+    expect(running.container.querySelector('svg')).toHaveClass(
+      'motion-safe:animate-spin',
+    );
     running.unmount();
 
     const settled = render(<RunStatusBadge status="ok" />);
     expect(settled.container.querySelector('svg')).not.toHaveClass(
-      'animate-spin',
+      'motion-safe:animate-spin',
     );
   });
 
@@ -44,16 +48,32 @@ describe('run status icons', () => {
     render(<NodeStatusIcon status="running" />);
     // The status word stays readable to a screen reader — that label IS the icon.
     const icon = screen.getByRole('img', { name: 'Running now' });
-    expect(icon).toHaveClass('animate-spin');
-    expect(icon).toHaveClass('motion-reduce:animate-none');
+    expect(icon.querySelector('svg')).toHaveClass('motion-safe:animate-spin');
   });
 
   it('leaves a settled icon-only node still', () => {
     render(<NodeStatusIcon status="ok" />);
-    expect(screen.getByRole('img', { name: 'Ran' })).not.toHaveClass(
-      'animate-spin',
+    const icon = screen.getByRole('img', { name: 'Ran' });
+    expect(icon.querySelector('svg')).not.toHaveClass(
+      'motion-safe:animate-spin',
     );
   });
+
+  // The canvas's glyphs and colours: none of them the slate-400 that read
+  // 2.6:1 on a white page.
+  it.each([
+    ['ok', 'lucide-circle-check'],
+    ['error', 'lucide-circle-x'],
+    ['skipped', 'lucide-circle-minus'],
+    ['not_run', 'lucide-circle-dashed'],
+    ['stopped', 'lucide-ban'],
+    ['pending', 'lucide-clock'],
+  ] as const)('draws %s with the canvas glyph', (status, glyph) => {
+    render(<NodeStatusIcon status={status} />);
+    const svg = screen.getByRole('img').querySelector('svg');
+    expect(svg).toHaveClass(glyph);
+    expect(svg?.getAttribute('class')).not.toMatch(/slate-400/);
+  });
 });
 
 describe('an interrupted run', () => {
@@ -82,7 +102,7 @@ describe('an interrupted run', () => {
 
 describe('the node a run is on, when nobody is running it', () => {
   it.each([
-    ['waiting', 'Waiting here', 'lucide-clock'],
+    ['waiting', 'Waiting here', 'lucide-hourglass'],
     ['interrupted', 'Interrupted here', 'lucide-refresh-cw'],
   ] as const)('reads %s in words, with a still icon', (status, word, icon) => {
     const { container } = render(<RunStatusBadge status={status} />);
diff --git a/services/platform/app/features/automations/components/run-status-badge.tsx b/services/platform/app/features/automations/components/run-status-badge.tsx
index 17a6da033c..ea7ded8e5b 100644
--- a/services/platform/app/features/automations/components/run-status-badge.tsx
+++ b/services/platform/app/features/automations/components/run-status-badge.tsx
@@ -2,13 +2,12 @@
 
 import { Badge } from '@tale/ui/badge';
 import { cn } from '@tale/ui/cn';
+import { FLOW_NODE_STATE } from '@tale/ui/flow/node-status';
 import {
   Ban,
   CheckCircle2,
-  CircleDashed,
   Clock,
   Loader2,
-  MinusCircle,
   RefreshCw,
   XCircle,
 } from 'lucide-react';
@@ -16,10 +15,14 @@ import type * as React from 'react';
 
 import { useT } from '@/lib/i18n/client';
 
-import type { NodeRunStatus, RunStatus } from '../lib/run-view';
+import {
+  flowNodeState,
+  type NodeRunStatus,
+  type RunStatus,
+} from '../lib/run-view';
 
 type BadgeVariant = 'green' | 'destructive' | 'yellow' | 'blue' | 'slate';
-type StatusIcon = React.ComponentType<React.ComponentProps<typeof Loader2>>;
+type StatusIcon = React.ComponentType<{ className?: string }>;
 
 /** `Badge` hardcodes the icon className, so spinning must live on the icon. */
 function RunningIcon({
@@ -84,31 +87,33 @@ export function RunBadge({
 }
 
 /**
- * What a run did to one node. `pending` means the run has not reached the node
- * yet; the engine's `not_run` means it finished without ever reaching it;
- * `stopped` means the run was stopped while on it; `waiting` means it waits
- * there for a person; `interrupted` means its server stopped while on it —
- * different facts, so they read differently, and only a node something is
- * working on spins.
+ * What a run did to one node, in the canvas's own vocabulary
+ * (`@tale/ui/flow/node-status`): the same glyph and colour as the node's box
+ * and its row in the List view, every glyph colour at 3:1 or better. The
+ * words stay this page's own — "Ran", "Never reached", "Not reached yet" —
+ * because they tell apart facts the canvas's shorter words merge. A node
+ * whose server stopped keeps a still glyph of its own: nothing works on it
+ * until another server takes it over, so nothing spins.
  */
-const NODE_STATUS_STYLE: Record<
-  NodeRunStatus,
-  { variant: BadgeVariant; icon: StatusIcon }
-> = {
-  ok: { variant: 'green', icon: CheckCircle2 },
-  skipped: { variant: 'slate', icon: MinusCircle },
-  error: { variant: 'destructive', icon: XCircle },
-  not_run: { variant: 'slate', icon: CircleDashed },
-  pending: { variant: 'blue', icon: Clock },
-  running: { variant: 'blue', icon: RunningIcon },
-  waiting: { variant: 'yellow', icon: Clock },
-  interrupted: { variant: 'blue', icon: RefreshCw },
-  stopped: { variant: 'slate', icon: Ban },
-};
+function nodeStatusLook(status: NodeRunStatus): {
+  variant: BadgeVariant;
+  icon: StatusIcon;
+  iconClass: string;
+} {
+  if (status === 'interrupted') {
+    return {
+      variant: 'blue',
+      icon: RefreshCw,
+      iconClass: 'text-[hsl(var(--info-foreground))]',
+    };
+  }
+  const { badge, icon, iconClass } = FLOW_NODE_STATE[flowNodeState(status)];
+  return { variant: badge, icon, iconClass };
+}
 
 export function RunStatusBadge({ status }: { status: NodeRunStatus }) {
   const { t } = useT('automations');
-  const { variant, icon } = NODE_STATUS_STYLE[status];
+  const { variant, icon } = nodeStatusLook(status);
   return (
     <Badge variant={variant} icon={icon}>
       {t(`runs.nodeStatus.${status}`)}
@@ -116,16 +121,6 @@ export function RunStatusBadge({ status }: { status: NodeRunStatus }) {
   );
 }
 
-/** The badge palette, as icon-only foreground colours — for surfaces too
- * dense for a badge per row. */
-const NODE_STATUS_ICON_COLOR: Record<BadgeVariant, string> = {
-  green: 'text-green-600',
-  destructive: 'text-destructive',
-  yellow: 'text-yellow-600',
-  blue: 'text-blue-600',
-  slate: 'text-slate-400',
-};
-
 /**
  * The same node-status vocabulary as {@link RunStatusBadge}, compressed to its
  * icon — the step timeline shows one per row, where a full badge would drown
@@ -139,16 +134,17 @@ export function NodeStatusIcon({
   className?: string;
 }) {
   const { t } = useT('automations');
-  const { variant, icon: Icon } = NODE_STATUS_STYLE[status];
+  const { icon: Icon, iconClass } = nodeStatusLook(status);
   return (
-    <Icon
+    <span
       role="img"
       aria-label={t(`runs.nodeStatus.${status}`)}
-      className={cn(
-        'size-4 shrink-0',
-        NODE_STATUS_ICON_COLOR[variant],
-        className,
-      )}
-    />
+      className="inline-flex"
+    >
+      <Icon
+        aria-hidden="true"
+        className={cn('size-4 shrink-0', iconClass, className)}
+      />
+    </span>
   );
 }
diff --git a/services/platform/app/features/automations/lib/run-view.ts b/services/platform/app/features/automations/lib/run-view.ts
index b8428230e6..88bcdfa624 100644
--- a/services/platform/app/features/automations/lib/run-view.ts
+++ b/services/platform/app/features/automations/lib/run-view.ts
@@ -13,6 +13,8 @@
  * every one, in the order it happened.
  */
 
+import type { FlowShownState } from '@tale/ui/flow/node-status';
+
 import type { RunWaitingFor } from '@/app/lib/backend/contract/automations';
 import type { Effect, NodeStatus, NodeTrace } from '@/lib/engine/core/types';
 
@@ -129,6 +131,28 @@ export type NodeRunStatus =
   | 'interrupted'
   | 'stopped';
 
+/**
+ * The package's state for a node's status in a run — one icon and colour
+ * vocabulary for the canvas, the step list and the badges. A node whose
+ * server stopped (`interrupted`) is not being worked on, so it does not
+ * spin: it waits to be picked up again, like a node not reached yet.
+ */
+export function flowNodeState(status: NodeRunStatus): FlowShownState {
+  return FLOW_NODE_STATE_OF[status];
+}
+
+const FLOW_NODE_STATE_OF: Readonly<Record<NodeRunStatus, FlowShownState>> = {
+  ok: 'succeeded',
+  error: 'failed',
+  skipped: 'skipped',
+  not_run: 'not-run',
+  stopped: 'stopped',
+  running: 'running',
+  waiting: 'waiting',
+  pending: 'pending',
+  interrupted: 'pending',
+};
+
 /** What the node a live run's cursor names reads as. */
 export type CursorNodeStatus = Extract<
   NodeRunStatus,

From fd9f674a59e598dd33f49f4552a2b41dd265c801 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:38:18 +0200
Subject: [PATCH 39/78] fix(ui): keep the host's toolbar in the flow canvas's
 List view

The List view dropped the bottom toolbar a host hands `WorkflowCanvas`.
On a phone narrower than 24rem the list is the default view, so the
host's verbs (an editor's Test run and Problems) had no way in. The
toolbar now sits at the foot of the list, clear of the mobile nav.
---
 .../src/components/flow/workflow-canvas.browser.test.tsx | 5 ++++-
 packages/ui/src/components/flow/workflow-canvas.tsx      | 9 +++++++++
 services/ui-docs/content/components/workflow-canvas.md   | 2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
index 8bada3f104..00dd9cc702 100644
--- a/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.browser.test.tsx
@@ -414,7 +414,7 @@ describe('WorkflowCanvas', () => {
     }
   });
 
-  it("keeps the host's corner controls in a controlled List view", async () => {
+  it("keeps the host's corner controls and toolbar in a controlled List view", async () => {
     const onLayout = vi.fn();
     render(
       <WorkflowCanvas
@@ -424,6 +424,7 @@ describe('WorkflowCanvas', () => {
         view="list"
         topStart={<button type="button">Canvas, List or Source</button>}
         topEnd={<button type="button">Paths</button>}
+        toolbar={<button type="button">Save</button>}
         onLayout={onLayout}
       />,
     );
@@ -434,6 +435,8 @@ describe('WorkflowCanvas', () => {
       screen.getByRole('button', { name: 'Canvas, List or Source' }),
     ).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Paths' })).toBeInTheDocument();
+    // The bottom toolbar too: on a phone the list is the default view.
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument();
     // A controlled view hides the built-in toggle.
     expect(screen.queryByRole('button', { name: 'Show as chart' })).toBeNull();
   });
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
index 879a031646..70f685b678 100644
--- a/packages/ui/src/components/flow/workflow-canvas.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -964,6 +964,15 @@ function WorkflowCanvasInner({
             highlight={primary}
             stoppedAt={failure?.nodeId ?? null}
           />
+          {/* The host's verbs stay with the List view: on a phone, where
+              the list is the default, they are the only way to reach them. */}
+          {toolbar && (
+            <div className="sticky bottom-0 flex justify-center px-3 pt-2 pb-[max(1rem,var(--mobile-nav-clearance-live,0px))]">
+              <div className="ring-border bg-background flex w-max max-w-full items-center gap-2 rounded-lg p-1 shadow-sm ring-1">
+                {toolbar}
+              </div>
+            </div>
+          )}
         </div>
       ) : (
         <div
diff --git a/services/ui-docs/content/components/workflow-canvas.md b/services/ui-docs/content/components/workflow-canvas.md
index b1d9a5049a..8bf4022938 100644
--- a/services/ui-docs/content/components/workflow-canvas.md
+++ b/services/ui-docs/content/components/workflow-canvas.md
@@ -128,7 +128,7 @@ When the button opens a panel, pass that panel's id as `controlsId`: each node t
 
 Viewport moves ease out over the duration tokens: zoom 150 ms, reveal 200 ms, reset 300 ms. Under reduced motion they jump. `framed` draws a bordered frame for a page; on a touch screen one finger then scrolls the page and two move the chart, and the first one-finger drag says so once. Set `touchPolicy` to choose either behaviour yourself.
 
-`topStart`, `topEnd`, `toolbar` and `cornerActions` place your own controls. `legend` adds a **Legend** button that explains the marks your chart uses in your words. `notice` sits above the chart and `empty` replaces it when the graph has no nodes.
+`topStart`, `topEnd`, `toolbar` and `cornerActions` place your own controls. The List view keeps `topStart` and `topEnd` above the list and `toolbar` at its foot, so a phone that opens on the list still reaches them. `legend` adds a **Legend** button that explains the marks your chart uses in your words. `notice` sits above the chart and `empty` replaces it when the graph has no nodes.
 
 ## Lay out without the canvas
 

From 36f7576e6bce990250252a9783959fa419adbcc8 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:39:03 +0200
Subject: [PATCH 40/78] feat(platform): draw automations with Start, End,
 conditions and paths

The editor and the run page now draw every automation through
`@tale/ui`'s WorkflowCanvas, laid out by ELK from the references alone:
nobody places a node, and `ui.positions` is never read.

- `toFlowGraph` turns a document into the canvas's graph: Start with its
  triggers in words and the fields each run receives; End with what a
  run returns and the three ways a run ends; a condition above each node
  that has a `when`, in words when it reads as words, with an `elseOf`
  partner hanging from it as No; one frame per iterating node; data,
  order, entry, exit and completion lines.
- Node faces name the connector and the action in the reader's language,
  what the node returns once the draft check says, what it reads, and
  the marks for writes, questions, unpinned models and "Continues on
  error".
- Paths lists every way a successful run can go and the nodes that end a
  run when they fail: a panel under the view switch on a wide screen, a
  sheet and a pill on a narrow one. Pointing at a path previews it,
  picking it pins it, and End says what it leaves empty.
- Canvas | List switch and the open node live in the link (`?view=`,
  `?node=`); the last-run eye, Paths and "Edit with your coding agent"
  sit top right, the coding agent is also an empty automation's action.
- A version saved elsewhere while no draft is open glides in, rings what
  changed and says "Now showing v6."; under a draft a notice offers it.
- The run page frames its canvas, lays the run over it and opens a
  failed run on its failure.
- Problems are counted on conditions, Start and End too.

`automation-node.tsx`, `readPositions` and `rankNodes` are gone, and so
is the platform's own `@xyflow/react` dependency.
---
 bun.lock                                      |   1 -
 .../automation-canvas.browser.test.tsx        | 368 ++++++++++
 .../components/automation-canvas.test.tsx     | 378 +++++++---
 .../components/automation-canvas.tsx          | 581 +++++++--------
 .../automation-editor.browser.test.tsx        | 225 +++++-
 .../components/automation-editor.test.tsx     | 260 ++++++-
 .../components/automation-editor.tsx          | 426 +++++++++--
 .../components/automation-node.test.tsx       | 289 --------
 .../components/automation-node.tsx            | 256 -------
 .../components/automation-paths.tsx           | 207 ++++++
 .../components/coding-agent-entry.test.tsx    |  93 +++
 .../components/coding-agent-entry.tsx         | 111 +++
 .../components/run-detail.test.tsx            |  96 ++-
 .../automations/components/run-detail.tsx     |  81 ++-
 .../automations/hooks/use-canvas-flow.ts      | 131 ++++
 .../hooks/use-deselect-on-escape.ts           |  23 +-
 .../automations/lib/condition-text.test.ts    | 177 +++++
 .../automations/lib/condition-text.ts         | 557 +++++++++++++++
 .../features/automations/lib/document.test.ts |  17 +-
 .../app/features/automations/lib/document.ts  |  28 +-
 .../automations/lib/editor-search.test.ts     |  42 ++
 .../features/automations/lib/editor-search.ts |  16 +-
 .../automations/lib/flow-graph.test.ts        | 475 +++++++++++++
 .../features/automations/lib/flow-graph.ts    | 672 ++++++++++++++++++
 .../app/features/automations/lib/flow-ids.ts  |  35 +
 .../features/automations/lib/graph.test.ts    |  68 +-
 .../app/features/automations/lib/graph.ts     |  81 +--
 .../features/automations/lib/issues.test.ts   |  41 ++
 .../app/features/automations/lib/issues.ts    |  38 +-
 .../automations/lib/node-face.test.ts         | 233 ++++++
 .../app/features/automations/lib/node-face.ts | 295 ++++++++
 .../features/automations/lib/paths.test.ts    | 211 ++++++
 .../app/features/automations/lib/paths.ts     | 304 ++++++++
 .../automations/lib/run-overlay.test.ts       | 171 +++++
 .../features/automations/lib/run-overlay.ts   | 139 ++++
 .../automations/lib/trigger-summary.test.ts   | 106 +++
 .../automations/lib/trigger-summary.ts        | 206 ++++++
 .../automations/$automationSlug/editor.tsx    |  33 +-
 .../automations/$automationSlug/editor.tsx    |  31 +-
 .../platform/messages/de-CH/automations.yml   |   3 +
 services/platform/messages/de/automations.yml | 154 +++-
 services/platform/messages/en/automations.yml | 152 +++-
 services/platform/messages/fr/automations.yml | 154 +++-
 services/platform/package.json                |   1 -
 .../tests/docs-screenshots/manifest.ts        |   8 +-
 .../tests/manual/suites/automations.md        |   7 +-
 services/platform/vitest.config.ts            |   3 +
 47 files changed, 6684 insertions(+), 1300 deletions(-)
 create mode 100644 services/platform/app/features/automations/components/automation-canvas.browser.test.tsx
 delete mode 100644 services/platform/app/features/automations/components/automation-node.test.tsx
 delete mode 100644 services/platform/app/features/automations/components/automation-node.tsx
 create mode 100644 services/platform/app/features/automations/components/automation-paths.tsx
 create mode 100644 services/platform/app/features/automations/components/coding-agent-entry.test.tsx
 create mode 100644 services/platform/app/features/automations/components/coding-agent-entry.tsx
 create mode 100644 services/platform/app/features/automations/hooks/use-canvas-flow.ts
 create mode 100644 services/platform/app/features/automations/lib/condition-text.test.ts
 create mode 100644 services/platform/app/features/automations/lib/condition-text.ts
 create mode 100644 services/platform/app/features/automations/lib/editor-search.test.ts
 create mode 100644 services/platform/app/features/automations/lib/flow-graph.test.ts
 create mode 100644 services/platform/app/features/automations/lib/flow-graph.ts
 create mode 100644 services/platform/app/features/automations/lib/flow-ids.ts
 create mode 100644 services/platform/app/features/automations/lib/node-face.test.ts
 create mode 100644 services/platform/app/features/automations/lib/node-face.ts
 create mode 100644 services/platform/app/features/automations/lib/paths.test.ts
 create mode 100644 services/platform/app/features/automations/lib/paths.ts
 create mode 100644 services/platform/app/features/automations/lib/run-overlay.test.ts
 create mode 100644 services/platform/app/features/automations/lib/run-overlay.ts
 create mode 100644 services/platform/app/features/automations/lib/trigger-summary.test.ts
 create mode 100644 services/platform/app/features/automations/lib/trigger-summary.ts

diff --git a/bun.lock b/bun.lock
index dc8d9b593c..37d86b7750 100644
--- a/bun.lock
+++ b/bun.lock
@@ -322,7 +322,6 @@
         "@tanstack/react-router": "1.168.10",
         "@tanstack/react-table": "8.21.3",
         "@xmldom/xmldom": "0.8.15",
-        "@xyflow/react": "12.10.2",
         "acorn": "8.18.0",
         "ajv": "8.20.0",
         "aws4fetch": "^1.0.20",
diff --git a/services/platform/app/features/automations/components/automation-canvas.browser.test.tsx b/services/platform/app/features/automations/components/automation-canvas.browser.test.tsx
new file mode 100644
index 0000000000..4898506f26
--- /dev/null
+++ b/services/platform/app/features/automations/components/automation-canvas.browser.test.tsx
@@ -0,0 +1,368 @@
+import '@testing-library/jest-dom/vitest';
+import type { FlowLayout, FlowRect } from '@tale/ui/flow/types';
+import {
+  assertLabelsClear,
+  assertRoutesAxisAligned,
+  edgeBoxCrossings,
+  flowRowOrderFlips,
+  viewportAtRest,
+} from '@tale/ui/testing/flow';
+import axe from 'axe-core';
+import { useState } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cdp, page, userEvent } from 'vitest/browser';
+
+import type { Automation } from '@/lib/engine/core/types';
+import { i18n } from '@/lib/i18n/i18n';
+import { cleanup, render, screen, waitFor, within } from '@/tests/utils/render';
+
+import githubTriage from '../../../../../../configs/platform/custom/automations/github/triage-issues/workflow.yml';
+import gmailTriage from '../../../../../../configs/platform/custom/automations/gmail/triage-inbox/workflow.yml';
+import { mergeNodeTypes } from '../hooks/backend';
+import { nodeCatalogView } from '../lib/node-face';
+import { AutomationCanvas } from './automation-canvas';
+
+import '@/app/globals.css';
+
+/**
+ * The automation canvas in a real browser, on the automations Tale ships:
+ * the document becomes a graph in the reader's words, `@tale/ui` lays it
+ * out and draws it. Here the shipped documents themselves are measured —
+ * their own words size the boxes, conditions and labels — so a line that
+ * runs through a box, a label over a line, or a row that swaps sides on an
+ * edit shows up here first.
+ */
+
+afterEach(async () => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  window.localStorage.removeItem('tale:flow-view');
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+});
+
+const CATALOG = nodeCatalogView(
+  mergeNodeTypes([
+    {
+      type: 'github.list_issues',
+      kind: 'connector',
+      description: 'List issues',
+      allowedFields: ['input'],
+      requiredFields: [],
+      outputKind: 'structured',
+      connector: 'github',
+      title: 'List issues',
+    },
+  ]),
+  [{ name: 'github', displayName: 'GitHub' }],
+);
+
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a shipped v1 pack, parsed at build time; the engine's corpus test validates it
+const TRIAGE = githubTriage as Automation;
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- as above
+const INBOX = gmailTriage as Automation;
+
+function Harness({
+  automation,
+  layoutKey = 'triage:latest',
+  onLayout,
+  changed,
+}: {
+  automation: Automation;
+  layoutKey?: string;
+  onLayout: (layout: FlowLayout) => void;
+  changed?: { ids: ReadonlySet<string>; key: string | number };
+}) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div>
+      <button type="button">Before the canvas</button>
+      <div style={{ width: 1180, height: 1500 }}>
+        <AutomationCanvas
+          automation={automation}
+          layoutKey={layoutKey}
+          catalog={CATALOG}
+          selectedId={selected}
+          onSelect={setSelected}
+          inspectorId="inspector"
+          onLayout={onLayout}
+          {...(changed !== undefined && { changed })}
+        />
+      </div>
+      <p data-testid="selected">{selected ?? ''}</p>
+    </div>
+  );
+}
+
+/** Renders a document and waits until it is laid out, drawn and at rest. */
+async function renderLaidOut(automation: Automation) {
+  await page.viewport(1280, 1600);
+  const layouts: FlowLayout[] = [];
+  const onLayout = (layout: FlowLayout) => layouts.push(layout);
+  const view = render(<Harness automation={automation} onLayout={onLayout} />);
+  await expectLaidOut(view.container, layouts, 1);
+  const rerender = (
+    next: Automation,
+    changed?: { ids: ReadonlySet<string>; key: string | number },
+  ) =>
+    view.rerender(
+      <Harness
+        automation={next}
+        onLayout={onLayout}
+        {...(changed !== undefined && { changed })}
+      />,
+    );
+  return { ...view, layouts, rerender };
+}
+
+/** The chart is done: `count` layouts landed, the frame is no longer busy,
+ *  every drawn line is on the page and the view has come to rest. */
+async function expectLaidOut(
+  container: HTMLElement,
+  layouts: readonly FlowLayout[],
+  count: number,
+) {
+  await waitFor(() => expect(layouts.length).toBeGreaterThanOrEqual(count), {
+    timeout: 20_000,
+  });
+  const chart = await waitFor(() => {
+    const element = container.querySelector('[data-flow-engine]');
+    if (element === null) throw new Error('no chart yet');
+    return element;
+  });
+  await waitFor(() => expect(chart).toHaveAttribute('aria-busy', 'false'));
+  const layout = layouts.at(-1);
+  await waitFor(
+    () =>
+      expect(
+        container.querySelectorAll('path[data-flow-edge]').length,
+      ).toBeGreaterThanOrEqual(Object.keys(layout?.edges ?? {}).length - 2),
+    { timeout: 10_000 },
+  );
+  await viewportAtRest(container);
+  return chart;
+}
+
+/** The view's translate and scale, from React Flow's viewport element. */
+function viewTransform(container: HTMLElement) {
+  const viewport = container.querySelector<HTMLElement>(
+    '.react-flow__viewport',
+  );
+  const match = /translate\(([-\d.]+)px, ([-\d.]+)px\) scale\(([-\d.]+)\)/.exec(
+    viewport?.style.transform ?? '',
+  );
+  if (match === null) throw new Error('no viewport transform');
+  return { x: Number(match[1]), y: Number(match[2]), zoom: Number(match[3]) };
+}
+
+/** Every box the page draws (nodes, conditions, Start, End and frame
+ *  headers), mapped back to the layout's coordinates. */
+function renderedBoxes(container: HTMLElement) {
+  const pane = container.querySelector('.react-flow')?.getBoundingClientRect();
+  if (pane === undefined) throw new Error('no pane');
+  const { x, y, zoom } = viewTransform(container);
+  const toFlow = (rect: DOMRect): FlowRect => ({
+    x: (rect.left - pane.left - x) / zoom,
+    y: (rect.top - pane.top - y) / zoom,
+    width: rect.width / zoom,
+    height: rect.height / zoom,
+  });
+  const boxes: Array<{ id: string; rect: FlowRect }> = [];
+  for (const button of container.querySelectorAll<HTMLElement>(
+    '[data-flow-node]',
+  )) {
+    boxes.push({
+      id: button.dataset.flowNode ?? '',
+      rect: toFlow(button.getBoundingClientRect()),
+    });
+  }
+  container
+    .querySelectorAll<HTMLElement>('[data-slot="flow-frame-header"]')
+    .forEach((header, index) => {
+      boxes.push({
+        id: `header:${index}`,
+        rect: toFlow(header.getBoundingClientRect()),
+      });
+    });
+  return boxes;
+}
+
+describe('AutomationCanvas in Chromium', () => {
+  it('draws Triage GitHub issues with Start above, End below and no line through a box', async () => {
+    const { container, layouts } = await renderLaidOut(TRIAGE);
+    const layout = layouts.at(-1) as FlowLayout;
+    const boxes = renderedBoxes(container);
+    expect(edgeBoxCrossings(layout.edges, boxes)).toEqual([]);
+    assertRoutesAxisAligned(layout);
+    assertLabelsClear(layout);
+
+    const rectOf = (id: string) => {
+      const box = boxes.find((candidate) => candidate.id === id);
+      if (box === undefined) throw new Error(`no box ${id}`);
+      return box.rect;
+    };
+    const start = rectOf('__start');
+    const end = rectOf('__end');
+    for (const id of TRIAGE.nodes.map((node) => node.id)) {
+      const box = rectOf(id);
+      expect(box.y, `${id} below Start`).toBeGreaterThan(
+        start.y + start.height,
+      );
+      expect(box.y + box.height, `${id} above End`).toBeLessThan(end.y);
+    }
+    // Score walks the issues in a frame of its own, named in words.
+    expect(
+      container.querySelector('[data-slot="flow-frame-header"]'),
+    ).toHaveTextContent('For each item of issues of Open issues');
+    // Start says what a run receives; End what it returns.
+    expect(
+      screen.getByRole('button', { name: /^Start/ }),
+    ).toHaveAccessibleDescription(/owner/);
+    expect(screen.getByRole('button', { name: /^End/ })).toBeVisible();
+  });
+
+  it.each(['en', 'de', 'fr'])(
+    'keeps the condition and its labels clear of every line in %s',
+    async (locale) => {
+      const previous = i18n.language;
+      await i18n.changeLanguage(locale);
+      try {
+        const { container, layouts } = await renderLaidOut(INBOX);
+        const layout = layouts.at(-1) as FlowLayout;
+        expect(
+          edgeBoxCrossings(layout.edges, renderedBoxes(container)),
+        ).toEqual([]);
+        assertLabelsClear(layout);
+        // The condition reads as words, above Triage.
+        const gate = container.querySelector<HTMLElement>(
+          '[data-flow-node="__gate:triage"]',
+        );
+        const triage = container.querySelector<HTMLElement>(
+          '[data-flow-node="triage"]',
+        );
+        if (gate === null || triage === null) throw new Error('no gate');
+        expect(gate.getBoundingClientRect().bottom).toBeLessThan(
+          triage.getBoundingClientRect().top,
+        );
+        expect(gate).not.toHaveTextContent('{{');
+      } finally {
+        cleanup();
+        await i18n.changeLanguage(previous);
+      }
+    },
+  );
+
+  it('is one Tab stop: Start first, the arrows follow the lines, Enter opens', async () => {
+    await renderLaidOut(TRIAGE);
+    screen.getByRole('button', { name: 'Before the canvas' }).focus();
+    await userEvent.keyboard('{Tab}');
+    const start = screen.getByRole('button', { name: /^Start/ });
+    await waitFor(() => expect(start).toHaveFocus());
+    await userEvent.keyboard('{ArrowDown}');
+    const issues = screen.getByRole('button', { name: /^Issues/ });
+    await waitFor(() => expect(issues).toHaveFocus());
+    // Each box says what it is and what it reads.
+    expect(issues).toHaveAccessibleDescription(
+      /run input \(owner, repo, limit\)/,
+    );
+    await userEvent.keyboard('{Enter}');
+    expect(screen.getByTestId('selected')).toHaveTextContent('issues');
+    await userEvent.keyboard('{End}');
+    await waitFor(() =>
+      expect(screen.getByRole('button', { name: /^End/ })).toHaveFocus(),
+    );
+  });
+
+  it('glides to a structural edit without swapping any row', async () => {
+    const { container, layouts, rerender } = await renderLaidOut(TRIAGE);
+    rerender({
+      ...TRIAGE,
+      nodes: [
+        ...TRIAGE.nodes,
+        {
+          id: 'archive',
+          type: 'transform',
+          input: { report: '{{ nodes.report.output }}' },
+          code: 'return input.report;',
+        },
+      ],
+    });
+    await waitFor(() => expect(layouts.length).toBe(2), { timeout: 20_000 });
+    const chart = container.querySelector('[data-flow-engine]');
+    await waitFor(() =>
+      expect(chart).toHaveAttribute('data-flow-transition', 'move'),
+    );
+    const [before, after] = layouts as [FlowLayout, FlowLayout];
+    expect(flowRowOrderFlips(before, after)).toEqual([]);
+    const issues = container.querySelector<HTMLElement>(
+      '.react-flow__node[data-id="issues"]',
+    );
+    expect(getComputedStyle(issues as Element).transitionDuration).toBe('0.3s');
+    await waitFor(
+      () => expect(chart).not.toHaveAttribute('data-flow-transition'),
+      { timeout: 2_000 },
+    );
+    expect(
+      container.querySelector('[data-flow-node="archive"]'),
+    ).not.toBeNull();
+  });
+
+  it('jumps to an edit made elsewhere under reduced motion, without a ring', async () => {
+    await cdp().send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+    });
+    const { container, layouts, rerender } = await renderLaidOut(TRIAGE);
+    const nodes = TRIAGE.nodes.slice(0, -1);
+    rerender({ ...TRIAGE, nodes }, { ids: new Set(['score']), key: 3 });
+    await waitFor(() => expect(layouts.length).toBe(2), { timeout: 20_000 });
+    await waitFor(() =>
+      expect(container.querySelector('[data-flow-node="report"]')).toBeNull(),
+    );
+    const chart = container.querySelector('[data-flow-engine]');
+    expect(chart).not.toHaveAttribute('data-flow-transition');
+    expect(
+      container.querySelector('[data-slot="flow-node-changed"]'),
+    ).toBeNull();
+  });
+
+  it.each(['light', 'dark'])(
+    'reads at AA in %s with a path pinned from the Paths panel',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      const { container } = await renderLaidOut(INBOX);
+      await userEvent.click(screen.getByRole('button', { name: /paths$/ }));
+      const panel = await screen.findByRole('region', {
+        name: 'Possible paths',
+      });
+      const [first] = within(
+        within(panel).getByRole('group', { name: 'Possible paths' }),
+      ).getAllByRole('button');
+      if (first === undefined) throw new Error('No path rows');
+      await userEvent.click(first);
+      await waitFor(() =>
+        expect(first).toHaveAttribute('aria-pressed', 'true'),
+      );
+      // Colours are judged at rest.
+      await Promise.all(
+        document
+          .getAnimations()
+          .filter(
+            (animation) =>
+              animation.effect?.getComputedTiming().endTime !== Infinity,
+          )
+          .map((animation) => animation.finished),
+      );
+      const chart = container.querySelector('[data-flow-engine]');
+      if (!(chart instanceof HTMLElement)) throw new Error('no chart');
+      const result = await axe.run(chart, {
+        runOnly: [
+          'color-contrast',
+          'aria-allowed-attr',
+          'aria-valid-attr-value',
+          'button-name',
+          'nested-interactive',
+        ],
+      });
+      expect(result.violations).toEqual([]);
+    },
+  );
+});
diff --git a/services/platform/app/features/automations/components/automation-canvas.test.tsx b/services/platform/app/features/automations/components/automation-canvas.test.tsx
index 3611075eda..548dd6175c 100644
--- a/services/platform/app/features/automations/components/automation-canvas.test.tsx
+++ b/services/platform/app/features/automations/components/automation-canvas.test.tsx
@@ -1,106 +1,320 @@
-import { describe, expect, it, vi } from 'vitest';
+import type { FlowLegendEntry } from '@tale/ui/flow/flow-legend';
+import type { FlowHighlight } from '@tale/ui/flow/paths';
+import type { FlowRunOverlay } from '@tale/ui/flow/playback';
+import type { FlowGraph } from '@tale/ui/flow/types';
+import type { ReactNode } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { fireEvent, render, screen } from '@/tests/utils/render';
-
-import { buildGraph } from '../lib/graph';
-import { AutomationCanvas } from './automation-canvas';
+import type { Automation } from '@/lib/engine/core/types';
+import { checkAccessibility } from '@/tests/utils/a11y';
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@/tests/utils/render';
 
 /**
- * The canvas switches every React Flow interaction model off and puts a real
- * button inside each node box instead. React Flow answers that combination by
- * rendering node wrappers with `pointer-events: none` — which once made every
- * box unreachable by mouse while the keyboard path kept working. These tests
- * pin the repaired contract: the wrapper hands pointer events back, and a
- * plain click on a box selects it (or clears the selection if it was already
- * the selected box). (jsdom's synthetic clicks do not honour
- * pointer-events, so the style assertion is the load-bearing one.)
+ * The platform's half of the canvas: it turns the document into the graph
+ * `@tale/ui`'s `WorkflowCanvas` draws, and puts the paths, the legend, the
+ * run and the page's own controls around it. The package's own tests hold
+ * the drawing (layout, routes, keyboard, motion); jsdom performs no layout,
+ * so here a stand-in canvas shows what it was handed.
  */
 
-const graph = buildGraph({
-  name: 'order-report',
+const shown = vi.hoisted(() => ({
+  props: null as null | {
+    graph: FlowGraph;
+    'aria-label': string;
+    layoutKey: string;
+    controlsId?: string;
+    highlight?: FlowHighlight | null;
+    overlay?: FlowRunOverlay;
+    legend?: readonly FlowLegendEntry[];
+    paths?: readonly unknown[];
+  },
+  compact: false,
+}));
+
+vi.mock('@tale/ui/flow/workflow-canvas', () => ({
+  WorkflowCanvas: (props: {
+    graph: FlowGraph;
+    'aria-label': string;
+    layoutKey: string;
+    onSelect?: (id: string | null) => void;
+    topStart?: ReactNode;
+    topEnd?: ReactNode;
+    notice?: ReactNode;
+    highlight?: FlowHighlight | null;
+  }) => {
+    shown.props = props;
+    return (
+      <div>
+        {props.notice}
+        <div data-testid="top-start">{props.topStart}</div>
+        <div data-testid="top-end">{props.topEnd}</div>
+        <div role="group" aria-label={props['aria-label']}>
+          {props.graph.nodes.map((node) => (
+            <button
+              key={node.id}
+              type="button"
+              data-dashed={
+                props.highlight?.nodes.has(node.id) === false ? 'quiet' : ''
+              }
+              onClick={() => props.onSelect?.(node.id)}
+            >
+              {`${node.kind} ${node.label ?? node.id}`}
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  },
+}));
+
+vi.mock('@tale/ui/use-media-query', () => ({
+  useMediaQuery: () => shown.compact,
+}));
+
+import { nodeCatalogView } from '../lib/node-face';
+import { AutomationCanvas } from './automation-canvas';
+
+const CATALOG = nodeCatalogView([]);
+
+/** Two ways to run: Triage only when the inbox has mail. */
+const TRIAGE: Automation = {
+  name: 'triage-inbox',
   nodes: [
-    { id: 'calc', type: 'transform', input: { expr: '1 + 1' } },
+    { id: 'inbox', type: 'transform', code: 'return [];' },
     {
-      id: 'summary',
+      id: 'triage',
       type: 'llm',
-      when: '{{ nodes.calc.output.count > 0 }}',
-      input: { prompt: '{{ nodes.calc.output }}' },
+      when: '{{ nodes.inbox.output.length > 0 }}',
+      prompt: '{{ nodes.inbox.output }}',
     },
   ],
-});
+};
 
-/** Every node placed, so the canvas renders without waiting for auto-layout. */
-const positions = {
-  calc: { x: 0, y: 0 },
-  summary: { x: 0, y: 200 },
+function renderCanvas(
+  automation: Automation = TRIAGE,
+  extra: Partial<Parameters<typeof AutomationCanvas>[0]> = {},
+) {
+  const onSelect = vi.fn();
+  const utils = render(
+    <AutomationCanvas
+      automation={automation}
+      layoutKey="triage-inbox:latest"
+      catalog={CATALOG}
+      selectedId={null}
+      onSelect={onSelect}
+      inspectorId="inspector"
+      {...extra}
+    />,
+  );
+  return { ...utils, onSelect };
+}
+
+const props = () => {
+  if (shown.props === null) throw new Error('The canvas was not drawn');
+  return shown.props;
 };
 
+beforeEach(() => {
+  shown.props = null;
+  shown.compact = false;
+});
+
 describe('AutomationCanvas', () => {
-  it('hands pointer events back to every node box', () => {
-    const { container } = render(
-      <AutomationCanvas
-        graph={graph}
-        positions={positions}
-        selectedNodeId={null}
-        onSelectNode={vi.fn()}
-        inspectorId="inspector"
-      />,
-    );
-    const wrappers =
-      container.querySelectorAll<HTMLElement>('.react-flow__node');
-    expect(wrappers).toHaveLength(2);
-    for (const wrapper of wrappers) {
-      expect(wrapper.style.pointerEvents).toBe('all');
-    }
+  it('draws the document with Start, its condition in words and End', () => {
+    renderCanvas();
+    const { graph } = props();
+    expect(graph.nodes.map((node) => `${node.kind}:${node.id}`)).toEqual([
+      'entry:__start',
+      'step:inbox',
+      'gate:__gate:triage',
+      'step:triage',
+      'exit:__end',
+    ]);
+    const gate = graph.nodes.find((node) => node.kind === 'gate');
+    expect(gate).toMatchObject({
+      condition: 'the output of Inbox is not empty',
+    });
+    expect(props()['aria-label']).toBe('Automation canvas');
+    expect(props().controlsId).toBe('inspector');
+    expect(props().layoutKey).toBe('triage-inbox:latest');
   });
 
-  it('selects a node with a plain click on its box', () => {
-    const onSelectNode = vi.fn();
-    render(
-      <AutomationCanvas
-        graph={graph}
-        positions={positions}
-        selectedNodeId={null}
-        onSelectNode={onSelectNode}
-        inspectorId="inspector"
-      />,
-    );
-    // fireEvent, not user-event: a full pointer sequence bubbles mousedown
-    // into React Flow's d3-zoom pane handler, which dereferences the event's
-    // `view` — null on jsdom's synthetic events.
-    fireEvent.click(screen.getByRole('button', { name: /^calc/i }));
-    expect(onSelectNode).toHaveBeenCalledWith('calc');
+  it('opens a box the reader picks', async () => {
+    const { user, onSelect } = renderCanvas();
+    await user.click(screen.getByRole('button', { name: 'step Triage' }));
+    expect(onSelect).toHaveBeenCalledWith('triage');
+  });
+
+  it('says in the legend what every line and box means', () => {
+    renderCanvas();
+    expect(props().legend?.map((entry) => entry.label)).toEqual([
+      'Solid line: reads the output of the node above',
+      'Dashed line: runs after it, without reading its output',
+      'Condition: decides whether the node below runs',
+      'Yes: runs when the condition holds',
+      "No: runs when the condition doesn't hold",
+      'Dotted line: the run ends after this node',
+      "Dashed box: may not run, or didn't run",
+      'Frame: runs once per item, or repeats',
+    ]);
   });
 
-  it('clears the selection when the selected box is clicked again', () => {
-    const onSelectNode = vi.fn();
-    render(
-      <AutomationCanvas
-        graph={graph}
-        positions={positions}
-        selectedNodeId="calc"
-        onSelectNode={onSelectNode}
-        inspectorId="inspector"
-      />,
+  it('asks a coding agent for nodes when the version has none', () => {
+    renderCanvas(
+      { name: 'empty', nodes: [] },
+      {
+        emptyAction: <button type="button">Edit with your coding agent</button>,
+      },
     );
-    fireEvent.click(screen.getByRole('button', { name: /^calc/i }));
-    expect(onSelectNode).toHaveBeenCalledWith(null);
+    expect(shown.props).toBeNull();
+    expect(screen.getByText('This version has no nodes')).toBeVisible();
+    expect(
+      screen.getByText(
+        'An automation does its work in nodes. Ask your coding agent to add them.',
+      ),
+    ).toBeVisible();
+    expect(
+      screen.getByRole('button', { name: 'Edit with your coding agent' }),
+    ).toBeVisible();
+  });
+
+  it('warns about a cycle and lists no paths', () => {
+    renderCanvas({
+      name: 'loop',
+      nodes: [
+        {
+          id: 'a',
+          type: 'transform',
+          input: { v: '{{ nodes.b.output }}' },
+          code: 'return 1;',
+        },
+        {
+          id: 'b',
+          type: 'transform',
+          input: { v: '{{ nodes.a.output }}' },
+          code: 'return 1;',
+        },
+      ],
+    });
+    expect(
+      screen.getByText('These nodes reference each other in a circle'),
+    ).toBeVisible();
+    expect(screen.queryByRole('button', { name: /paths?$/ })).toBeNull();
+    // Start and End are still there to read.
+    expect(screen.getByRole('button', { name: 'entry __start' })).toBeVisible();
   });
 
-  it('clears the selection when the pane is clicked', () => {
-    const onSelectNode = vi.fn();
-    const { container } = render(
-      <AutomationCanvas
-        graph={graph}
-        positions={positions}
-        selectedNodeId="calc"
-        onSelectNode={onSelectNode}
-        inspectorId="inspector"
-      />,
+  it('lays a run over the boxes', () => {
+    renderCanvas(TRIAGE, {
+      run: {
+        statusByNode: new Map([
+          ['inbox', 'ok'],
+          ['triage', 'error'],
+        ]),
+        projection: { byNode: new Map(), effects: [], trace: [] },
+        status: 'failed',
+      },
+    });
+    expect(props().overlay?.nodes.triage).toEqual({ state: 'failed' });
+    expect(props().overlay?.finished).toBe(true);
+  });
+});
+
+describe('AutomationCanvas paths', () => {
+  it('lists the paths in a panel beside the chart and lights one up', async () => {
+    const { user } = renderCanvas();
+    const button = within(screen.getByTestId('top-end')).getByRole('button', {
+      name: '2 paths',
+    });
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    await user.click(button);
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+
+    const panel = screen.getByRole('region', { name: 'Possible paths' });
+    expect(button).toHaveAttribute('aria-controls', panel.id);
+    // The panel sits under the view switch, inside the canvas.
+    expect(within(screen.getByTestId('top-start')).getByRole('region')).toBe(
+      panel,
     );
-    const pane = container.querySelector('.react-flow__pane');
-    expect(pane).not.toBeNull();
-    fireEvent.click(pane as Element);
-    expect(onSelectNode).toHaveBeenCalledWith(null);
+
+    const paths = within(panel).getByRole('group', { name: 'Possible paths' });
+    const [first] = within(paths).getAllByRole('button');
+    if (first === undefined) throw new Error('No path rows');
+    await user.click(first);
+    await waitFor(() => expect(first).toHaveAttribute('aria-pressed', 'true'));
+    const highlight = props().highlight;
+    expect(highlight?.announcement).toMatch(/^Showing path 1: /);
+    expect(highlight?.nodes.has('triage')).toBe(true);
+
+    // Closing the panel keeps what is pinned on the chart.
+    await user.click(within(panel).getByRole('button', { name: 'Close' }));
+    expect(screen.queryByRole('region', { name: 'Possible paths' })).toBeNull();
+    expect(props().highlight?.nodes.has('triage')).toBe(true);
+  });
+
+  it('pins a path from a sheet on a narrow screen and leaves a pill to undo it', async () => {
+    shown.compact = true;
+    const { user } = renderCanvas();
+    await user.click(screen.getByRole('button', { name: '2 paths' }));
+    const sheet = await screen.findByRole('dialog', { name: 'Possible paths' });
+    const [first] = within(
+      within(sheet).getByRole('group', { name: 'Possible paths' }),
+    ).getAllByRole('button');
+    if (first === undefined) throw new Error('No path rows');
+    await user.click(first);
+
+    // The sheet closes on the pin (jsdom never ends its slide-out, so it
+    // stays mounted, closed).
+    await waitFor(() => expect(sheet).toHaveAttribute('data-state', 'closed'));
+    const pill = within(screen.getByTestId('top-start'));
+    expect(pill.getByText(/^Path 1 · /)).toBeVisible();
+    // `hidden` and a plain click: the never-ended slide-out leaves the page
+    // aria-hidden and without pointer events in jsdom; a browser lifts both
+    // once the sheet is gone.
+    act(() => {
+      fireEvent.click(
+        pill.getByRole('button', { name: 'Show all', hidden: true }),
+      );
+    });
+    expect(props().highlight).toBeNull();
+    expect(screen.queryByText(/^Path 1 · /)).toBeNull();
+  });
+
+  it('forgets a pinned path when another picture is shown', async () => {
+    const { user, rerender } = renderCanvas();
+    await user.click(screen.getByRole('button', { name: '2 paths' }));
+    const [first] = within(
+      screen.getByRole('group', { name: 'Possible paths' }),
+    ).getAllByRole('button');
+    if (first === undefined) throw new Error('No path rows');
+    await user.click(first);
+    await waitFor(() => expect(props().highlight).not.toBeNull());
+
+    act(() => {
+      rerender(
+        <AutomationCanvas
+          automation={TRIAGE}
+          layoutKey="triage-inbox:2"
+          catalog={CATALOG}
+          selectedId={null}
+          onSelect={vi.fn()}
+          inspectorId="inspector"
+        />,
+      );
+    });
+    await waitFor(() => expect(props().highlight).toBeNull());
+  });
+
+  it('passes an axe audit with the Paths panel open', async () => {
+    const { user, container } = renderCanvas();
+    await user.click(screen.getByRole('button', { name: '2 paths' }));
+    await checkAccessibility(container);
   });
 });
diff --git a/services/platform/app/features/automations/components/automation-canvas.tsx b/services/platform/app/features/automations/components/automation-canvas.tsx
index 66f84b91ab..101c5bb2ec 100644
--- a/services/platform/app/features/automations/components/automation-canvas.tsx
+++ b/services/platform/app/features/automations/components/automation-canvas.tsx
@@ -1,342 +1,343 @@
 'use client';
 
 import { Alert } from '@tale/ui/alert';
-import { cn } from '@tale/ui/cn';
 import { EmptyState } from '@tale/ui/empty-state';
-import {
-  FLOW_EDGE_COLORS,
-  FLOW_EDGE_MARKER_SIZE,
-  FLOW_EDGE_STROKE_WIDTH,
-} from '@tale/ui/flow/edge-palette';
-import { FlowCanvas } from '@tale/ui/flow/flow-canvas';
-import { useElkLayout } from '@tale/ui/flow/use-elk-layout';
+import type { FlowLegendEntry } from '@tale/ui/flow/flow-legend';
+import type { FlowHighlight } from '@tale/ui/flow/paths';
+import type { FlowLayout, FlowRow } from '@tale/ui/flow/types';
+import { WorkflowCanvas, type FlowView } from '@tale/ui/flow/workflow-canvas';
 import type { IssueCounts } from '@tale/ui/issue-summary';
-import {
-  MarkerType,
-  Position,
-  ReactFlowProvider,
-  useReactFlow,
-  type Edge,
-  type Node,
-} from '@xyflow/react';
-import { AlertTriangle, Workflow } from 'lucide-react';
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  type CSSProperties,
-  type ReactNode,
-} from 'react';
+import { useMediaQuery } from '@tale/ui/use-media-query';
+import { AlertTriangle, Hand, Workflow } from 'lucide-react';
+import { useEffect, useId, useMemo, useState, type ReactNode } from 'react';
 
+import type { Automation } from '@/lib/engine/core/types';
 import { useT } from '@/lib/i18n/client';
+import type {
+  AnalysisView,
+  TypesView,
+} from '@/lib/shared/schemas/automation-issues';
 
-import { automationNodeElement } from '../hooks/use-deselect-on-escape';
-import type { NodePosition } from '../lib/document';
-import type { AutomationGraph } from '../lib/graph';
-import type { NodeRunStatus } from '../lib/run-view';
+import { useCanvasFlow } from '../hooks/use-canvas-flow';
+import type { NodeCatalogView, ReturnsSource } from '../lib/node-face';
+import { runOverlay } from '../lib/run-overlay';
+import type { NodeRunStatus, RunProjection, RunStatus } from '../lib/run-view';
+import { AUTOMATION_WORKBENCH_COMPACT_QUERY } from '../lib/workbench';
 import {
-  AutomationNode,
-  CanvasNodeProvider,
-  type AutomationNodeData,
-  type CanvasNodeContextValue,
-} from './automation-node';
+  AutomationPathsButton,
+  AutomationPathsPanel,
+  AutomationPathsPill,
+  AutomationPathsSheet,
+} from './automation-paths';
 
-/** The box every node renders at. Fixed so the layout engine and the DOM
- * agree, and so a long node id cannot reflow the graph. */
-const NODE_WIDTH = 300;
-const NODE_HEIGHT = 116;
-
-/** React Flow requires a stable node-type map; an inline object remounts every
- * node on each render. */
-const NODE_TYPES = { automation: AutomationNode };
-
-/** React Flow computes `pointer-events: none` on a node wrapper that is
- * neither selectable nor draggable and has no flow-level mouse handlers —
- * which is every node here, because this canvas turns React Flow's own
- * interaction models off in favour of the real button inside each box. The
- * per-node style spreads after that computed value, handing pointer events
- * back so the button is clickable at all. */
-const NODE_STYLE: CSSProperties = { pointerEvents: 'all' };
+/** A run laid over the canvas. */
+export interface CanvasRun {
+  statusByNode: ReadonlyMap<string, NodeRunStatus>;
+  projection: RunProjection;
+  status: RunStatus;
+  /** Who or what started it, for Start's strip. */
+  startedBy?: string;
+}
 
 export interface AutomationCanvasProps {
-  graph: AutomationGraph;
-  /** Hand-placed positions from the document's canvas metadata. Nodes without
-   * one are laid out automatically. */
-  positions: Record<string, NodePosition>;
-  selectedNodeId: string | null;
-  onSelectNode: (nodeId: string | null) => void;
-  /** Id of the inspector region a node button expands. */
+  /** The document on screen. */
+  automation: Automation;
+  /** What the canvas is a picture of: the automation and the version on
+   *  screen. The same key with a changed document glides to its new
+   *  layout; a new key is another picture. */
+  layoutKey: string;
+  catalog: NodeCatalogView;
+  modelLabel?: (id: string) => string | undefined;
+  /** Start's trigger rows; by hand, the API or MCP when left out. */
+  triggers?: readonly FlowRow[];
+  /** What the draft check answered, when the reader may have one. */
+  check?: {
+    status: ReturnsSource['status'];
+    analysis: AnalysisView | null;
+    types: TypesView | null;
+  };
+  /** Why a trigger's runs are refused, said on Start. */
+  startNotice?: string | null;
+  /** Problems per box: a node, its condition, Start or End. */
+  issueCounts?: ReadonlyMap<string, IssueCounts>;
+  /** The open box: a node, a condition, Start or End. */
+  selectedId: string | null;
+  onSelect: (id: string | null) => void;
+  /** Id of the inspector region a box opens. */
   inspectorId: string;
-  runStatusByNode?: ReadonlyMap<string, NodeRunStatus>;
-  /** Problems the editor's check found, by node id — marked on each box. */
-  issueCountsByNode?: ReadonlyMap<string, IssueCounts>;
+  run?: CanvasRun;
+  /** Bring this box into view. */
+  revealId?: string | null;
+  /** Nodes another window or a coding agent changed, ringed once. */
+  changed?: { ids: ReadonlySet<string>; key: string | number };
   /**
-   * Draw the canvas as a bordered, rounded frame (a run's page, where it sits
-   * in the page inset). The Editor tab's edge-to-edge workbench turns it off:
-   * there the canvas meets the tab strip, the window and the inspector at
-   * their own borders.
+   * Draw the canvas as a bordered frame (a run's page). The Editor tab's
+   * edge-to-edge workbench turns it off.
    * @default true
    */
   framed?: boolean;
-  /** Mobile editor actions, kept inside the canvas toolbar. */
-  centerActions?: ReactNode;
+  view?: FlowView;
+  onViewChange?: (view: FlowView) => void;
+  /** The top-left corner (the view switch). */
+  topStart?: ReactNode;
+  /** Verbs after Paths in the top-right corner. */
+  topEnd?: ReactNode;
+  /** The bottom-centre toolbar. */
+  toolbar?: ReactNode;
+  /** The main action of an automation with no nodes yet. */
+  emptyAction?: ReactNode;
+  /** Each layout once it is on the page (tests measure it). */
+  onLayout?: (layout: FlowLayout) => void;
 }
 
-const EMPTY_STATUSES: ReadonlyMap<string, NodeRunStatus> = new Map();
-const NO_ISSUE_COUNTS: ReadonlyMap<string, IssueCounts> = new Map();
-
-/** Room left between a box brought into view and the frame's edge. */
-const REVEAL_MARGIN = 24;
+const NO_CHECK: NonNullable<AutomationCanvasProps['check']> = {
+  status: 'off',
+  analysis: null,
+  types: null,
+};
 
 /**
- * How far to move the span `[start, end]` so it shows inside `[min, max]`:
- * nothing when it already does, otherwise the least shift that leaves the
- * margin — aligned to its start when the span is longer than the room.
+ * The automation canvas: the document, drawn by `@tale/ui`'s
+ * `WorkflowCanvas` and laid out by it — nobody places a node, and a
+ * document's stored positions are never read.
+ *
+ * Start says what starts a run and what it receives; End what a successful
+ * run returns and how a run ends; each condition sits above its node in
+ * words, with Yes and No when an `elseOf` partner hangs from it. The Paths
+ * list shows every way a run can go and lights one up on the chart. A run
+ * lays its outcome over every box.
  */
-function revealShift(
-  start: number,
-  end: number,
-  min: number,
-  max: number,
-): number {
-  if (start >= min && end <= max) return 0;
-  const lo = min + REVEAL_MARGIN;
-  const hi = max - REVEAL_MARGIN;
-  if (end - start > hi - lo) return lo - start;
-  if (end > hi) return hi - end;
-  return lo - start;
-}
-
-function CanvasInner({
-  graph,
-  positions,
-  selectedNodeId,
-  onSelectNode,
+export function AutomationCanvas({
+  automation,
+  layoutKey,
+  catalog,
+  modelLabel,
+  triggers,
+  check = NO_CHECK,
+  startNotice,
+  issueCounts,
+  selectedId,
+  onSelect,
   inspectorId,
-  runStatusByNode = EMPTY_STATUSES,
-  issueCountsByNode = NO_ISSUE_COUNTS,
+  run,
+  revealId,
+  changed,
   framed = true,
-  centerActions,
+  view,
+  onViewChange,
+  topStart,
+  topEnd,
+  toolbar,
+  emptyAction,
+  onLayout,
 }: AutomationCanvasProps) {
   const { t } = useT('automations');
-  const { getViewport, setViewport } = useReactFlow();
+  const compact = useMediaQuery(AUTOMATION_WORKBENCH_COMPACT_QUERY);
+  const panelId = useId();
+  const manualOnly = useMemo<readonly FlowRow[]>(
+    () => [
+      { id: 'trigger:manual', icon: Hand, label: t('canvas.start.manual') },
+    ],
+    [t],
+  );
+  const [pathsOpen, setPathsOpen] = useState(false);
+  const [previewId, setPreviewId] = useState<string | null>(null);
+  const [pinnedId, setPinnedId] = useState<string | null>(null);
 
-  const incomingByNode = useMemo(() => {
-    const grouped = new Map<string, typeof graph.edges>();
-    for (const edge of graph.edges) {
-      const bucket = grouped.get(edge.target);
-      if (bucket) bucket.push(edge);
-      else grouped.set(edge.target, [edge]);
-    }
-    return grouped;
-  }, [graph.edges]);
+  const flow = useCanvasFlow({
+    automation,
+    catalog,
+    ...(modelLabel !== undefined && { modelLabel }),
+    triggers: triggers ?? manualOnly,
+    check,
+    ...(startNotice !== undefined && { startNotice }),
+    pinnedPath: pinnedId,
+  });
+  const { graph, paths, hasCycle } = flow;
 
-  // Nodes are handed to React Flow in EXECUTION order, so Tab walks the graph
-  // the way the engine runs it — DOM order is the tab order, and this canvas
-  // switches React Flow's own focus handling off in favour of a real button
-  // inside every box.
-  const baseNodes = useMemo<Node[]>(
-    () =>
-      graph.nodes.map((node) => {
-        const data: AutomationNodeData = { node };
-        return {
-          id: node.id,
-          type: 'automation',
-          position: positions[node.id] ?? { x: 0, y: 0 },
-          width: NODE_WIDTH,
-          height: NODE_HEIGHT,
-          sourcePosition: Position.Bottom,
-          targetPosition: Position.Top,
-          style: NODE_STYLE,
-          data,
-        };
-      }),
-    [graph.nodes, positions],
-  );
+  // A path that is no longer there (the document changed, another
+  // picture) is no longer shown.
+  const pinnedInfo = pinnedId === null ? undefined : paths?.rows.get(pinnedId);
+  useEffect(() => {
+    if (pinnedId !== null && pinnedInfo === undefined) setPinnedId(null);
+  }, [pinnedId, pinnedInfo]);
+  useEffect(() => {
+    setPinnedId(null);
+    setPreviewId(null);
+  }, [layoutKey]);
 
-  const flowEdges = useMemo<Edge[]>(
+  const shownRow = pinnedId ?? previewId;
+  const highlight = useMemo<FlowHighlight | null>(
     () =>
-      graph.edges.map((edge) => ({
-        id: edge.id,
-        source: edge.source,
-        target: edge.target,
-        type: 'smoothstep',
-        // One colour for every derived edge: the reference kind is carried by
-        // the LINE STYLE, so colour keeps its single documented meaning. A
-        // control reference only orders two nodes, so it is drawn dashed.
-        style: {
-          stroke: FLOW_EDGE_COLORS.flow,
-          strokeWidth: FLOW_EDGE_STROKE_WIDTH,
-          ...(edge.kind === 'control' && { strokeDasharray: '6 4' }),
-        },
-        markerEnd: {
-          type: MarkerType.ArrowClosed,
-          width: FLOW_EDGE_MARKER_SIZE,
-          height: FLOW_EDGE_MARKER_SIZE,
-          color: FLOW_EDGE_COLORS.flow,
-        },
-        ariaLabel:
-          edge.kind === 'data'
-            ? t('canvas.edge.data', {
-                source: edge.source,
-                target: edge.target,
-              })
-            : t('canvas.edge.control', {
-                source: edge.source,
-                target: edge.target,
-              }),
-      })),
-    [graph.edges, t],
+      shownRow === null || paths === null
+        ? null
+        : paths.highlightFor(shownRow, shownRow === pinnedId),
+    [shownRow, pinnedId, paths],
   );
 
-  // Auto-layout runs only for a document that has not placed every node.
-  // Handing the shared layout engine an empty list is its documented no-op, so
-  // a fully placed document never loads it at all.
-  const needsLayout = graph.nodes.some((node) => !positions[node.id]);
-  const { nodes: laidOut, isLayouting } = useElkLayout(
-    needsLayout ? baseNodes : [],
-    needsLayout ? flowEdges : [],
-  );
-
-  const nodes = needsLayout ? laidOut : baseNodes;
-
-  // Bring a node's box fully into the frame with the least pan, at the zoom
-  // the author chose. Measured on the page, so it holds even right after the
-  // frame changed size — React Flow only learns its new size a frame later.
-  const frameRef = useRef<HTMLDivElement>(null);
-  const revealNode = useCallback(
-    (nodeId: string) => {
-      const frame = frameRef.current;
-      const box = frame === null ? null : automationNodeElement(nodeId, frame);
-      if (frame === null || box === null) return;
-      const bounds = frame.getBoundingClientRect();
-      const rect = box.getBoundingClientRect();
-      const dx = revealShift(rect.left, rect.right, bounds.left, bounds.right);
-      const dy = revealShift(rect.top, rect.bottom, bounds.top, bounds.bottom);
-      if (dx === 0 && dy === 0) return;
-      const viewport = getViewport();
-      // The pan resolves when the animation ends and there is nothing to do
-      // afterwards, so it is not awaited.
-      void setViewport(
-        { x: viewport.x + dx, y: viewport.y + dy, zoom: viewport.zoom },
-        { duration: 200 },
-      );
-    },
-    [getViewport, setViewport],
+  const overlay = useMemo(
+    () =>
+      run === undefined
+        ? undefined
+        : runOverlay({
+            graph,
+            statusByNode: run.statusByNode,
+            projection: run.projection,
+            status: run.status,
+            t,
+            ...(run.startedBy !== undefined && { startedBy: run.startedBy }),
+          }),
+    [run, graph, t],
   );
 
-  // A keyboard user tabbing through the graph must see the box that just
-  // took focus — without the viewport jumping scale, or moving at all when
-  // the box is already in sight.
-  const onFocusNode = revealNode;
-
-  // Picking a node opens the inspector beside the canvas and narrows it; a
-  // picked box the inspector now covers pans back into view.
-  useEffect(() => {
-    if (selectedNodeId !== null) revealNode(selectedNodeId);
-  }, [selectedNodeId, revealNode]);
-
-  const canvasContext = useMemo<CanvasNodeContextValue>(
-    () => ({
-      selectedNodeId,
-      inspectorId,
-      onSelect: onSelectNode,
-      onFocusNode,
-      runStatusByNode,
-      incomingByNode,
-      issueCountsByNode,
-    }),
-    [
-      selectedNodeId,
-      inspectorId,
-      onSelectNode,
-      onFocusNode,
-      runStatusByNode,
-      incomingByNode,
-      issueCountsByNode,
+  const legend = useMemo<FlowLegendEntry[]>(
+    () => [
+      { id: 'data', swatch: { edge: 'data' }, label: t('canvas.legend.data') },
+      {
+        id: 'control',
+        swatch: { edge: 'order' },
+        label: t('canvas.legend.control'),
+      },
+      { id: 'gate', swatch: { node: 'gate' }, label: t('canvas.legend.gate') },
+      {
+        id: 'yes',
+        swatch: { edge: 'branch-yes' },
+        label: t('canvas.legend.yes'),
+      },
+      { id: 'no', swatch: { edge: 'branch-no' }, label: t('canvas.legend.no') },
+      {
+        id: 'completion',
+        swatch: { edge: 'completion' },
+        label: t('canvas.legend.completion'),
+      },
+      {
+        id: 'conditional',
+        swatch: { node: 'dashed' },
+        label: t('canvas.legend.conditional'),
+      },
+      { id: 'loop', swatch: { node: 'frame' }, label: t('canvas.legend.loop') },
     ],
+    [t],
   );
 
-  if (graph.nodes.length === 0) {
+  const hasSteps = graph.nodes.some((node) => node.kind === 'step');
+  if (!hasSteps) {
     return (
       <EmptyState
         icon={Workflow}
         title={t('canvas.empty.title')}
         description={t('canvas.empty.description')}
-        action={centerActions}
+        action={emptyAction}
       />
     );
   }
 
+  const listProps =
+    paths === null
+      ? null
+      : {
+          paths,
+          previewId,
+          pinnedId,
+          onPreview: setPreviewId,
+          onPin: setPinnedId,
+          onActivate: (nodeId: string) => onSelect(nodeId),
+        };
+
+  const panel =
+    listProps !== null && pathsOpen && !compact ? (
+      <AutomationPathsPanel
+        id={panelId}
+        onClose={() => {
+          setPathsOpen(false);
+          setPreviewId(null);
+        }}
+        {...listProps}
+      />
+    ) : null;
+  const pill =
+    compact && pinnedInfo !== undefined ? (
+      <AutomationPathsPill
+        info={pinnedInfo}
+        onShowAll={() => {
+          setPinnedId(null);
+          setPreviewId(null);
+        }}
+      />
+    ) : null;
+  const corner =
+    panel !== null || pill !== null ? (
+      <div className="flex flex-col items-start gap-2">
+        {topStart}
+        {pill}
+        {panel}
+      </div>
+    ) : (
+      topStart
+    );
+
   return (
-    <CanvasNodeProvider value={canvasContext}>
-      {graph.hasCycle && (
-        <Alert
-          variant="warning"
-          icon={AlertTriangle}
-          title={t('canvas.cycle.title')}
-          description={t('canvas.cycle.description')}
-          // Unframed, the canvas has no inset of its own: the warning keeps
-          // the page's instead of running into the edges.
-          className={framed ? 'mb-3' : 'm-4 mb-0'}
-        />
-      )}
-      <div
-        ref={frameRef}
-        // A definite height at mount matters: React Flow measures its frame
-        // once, and a `flex-1` box inside a scrolling column can start at
-        // zero — which paints an empty canvas that never re-fits.
-        className={cn(
-          'relative h-full flex-1 overflow-hidden',
-          // Framed, the canvas sits in a scrolling page and needs a height of
-          // its own. Unframed (the Editor tab), the workbench row already
-          // holds it at 24rem or more, and the Problems dock under it may
-          // take part of that row — the canvas keeps at least 12rem.
-          framed ? 'border-border min-h-[24rem] rounded-lg border' : 'min-h-48',
-        )}
-        role="group"
+    <>
+      <WorkflowCanvas
+        graph={graph}
         aria-label={t('canvas.ariaLabel')}
-        aria-busy={isLayouting}
-      >
-        <FlowCanvas
-          centerActions={centerActions}
-          nodes={nodes}
-          edges={flowEdges}
-          nodeTypes={NODE_TYPES}
-          // Every node box owns a real button, so React Flow must not add a
-          // second tab stop around it or bind arrow keys that would fight the
-          // page's own scrolling.
-          nodesFocusable={false}
-          edgesFocusable={false}
-          disableKeyboardA11y
-          nodesDraggable={false}
-          nodesConnectable={false}
-          elementsSelectable={false}
-          onPaneClick={() => {
-            onSelectNode(null);
+        layoutKey={layoutKey}
+        selectedId={selectedId}
+        onSelect={onSelect}
+        controlsId={inspectorId}
+        {...(revealId !== undefined && { revealId })}
+        {...(issueCounts !== undefined && { issues: issueCounts })}
+        {...(overlay !== undefined && { overlay })}
+        {...(paths !== null && { paths: paths.flowPaths })}
+        highlight={highlight}
+        {...(changed !== undefined && { changed })}
+        {...(view !== undefined && { view })}
+        {...(onViewChange !== undefined && { onViewChange })}
+        framed={framed}
+        topStart={corner}
+        topEnd={
+          <>
+            {paths !== null && (
+              <AutomationPathsButton
+                count={paths.count}
+                open={pathsOpen}
+                controls={pathsOpen && !compact ? panelId : undefined}
+                onToggle={() => {
+                  setPathsOpen((open) => !open);
+                  setPreviewId(null);
+                }}
+              />
+            )}
+            {topEnd}
+          </>
+        }
+        toolbar={toolbar}
+        legend={legend}
+        {...(onLayout !== undefined && { onLayout })}
+        notice={
+          hasCycle ? (
+            <Alert
+              variant="warning"
+              icon={AlertTriangle}
+              title={t('canvas.cycle.title')}
+              description={t('canvas.cycle.description')}
+              // Unframed, the canvas has no inset of its own: the warning
+              // keeps the page's instead of running into the edges.
+              className={framed ? 'mb-3' : 'm-4 mb-0'}
+            />
+          ) : undefined
+        }
+      />
+      {listProps !== null && compact && (
+        <AutomationPathsSheet
+          open={pathsOpen}
+          onOpenChange={(open) => {
+            setPathsOpen(open);
+            if (!open) setPreviewId(null);
           }}
-          fitView
-          backgroundProps={{ gap: 16 }}
+          {...listProps}
         />
-      </div>
-    </CanvasNodeProvider>
-  );
-}
-
-/**
- * The automation canvas: the document, drawn.
- *
- * Nodes come from the document in execution order and edges are DERIVED from
- * the `{{ nodes.<id>.output }}` references between them — the canvas keeps no
- * graph of its own, so what it draws is exactly what the engine will run.
- * Positions come from the document's canvas metadata when an author placed
- * them, and from the shared layout engine when they did not.
- */
-export function AutomationCanvas(props: AutomationCanvasProps) {
-  return (
-    <ReactFlowProvider>
-      <CanvasInner {...props} />
-    </ReactFlowProvider>
+      )}
+    </>
   );
 }
diff --git a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
index afc46c0f47..64bec4401b 100644
--- a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
@@ -43,6 +43,7 @@ const { automation, check } = vi.hoisted(() => {
     type: string;
     code: string;
     input?: Record<string, string>;
+    when?: string;
   }[] = [
     { id: 'pulls', type: 'transform', code: 'return { items: [] };' },
     {
@@ -58,17 +59,12 @@ const { automation, check } = vi.hoisted(() => {
       code: 'return { text: "" };',
     },
   ];
-  // Every node placed, so the canvas never waits on the layout engine.
-  const positions: Record<string, { x: number; y: number }> = {
-    pulls: { x: 0, y: 0 },
-    diff: { x: 0, y: 196 },
-    summary: { x: 0, y: 392 },
-  };
+  // The canvas lays every document out itself (ELK, in a worker); nothing
+  // is placed by hand.
   return {
     automation: {
       name: 'pr-digest',
       nodes,
-      ui: { positions },
       deployedVersion: 1 as number | undefined,
     },
     /** What the draft check answers: nothing, unless a test plants a problem. */
@@ -139,6 +135,7 @@ vi.mock('@/app/features/projects/hooks/queries', async (importOriginal) => ({
     typeof import('@/app/features/projects/hooks/queries')
   >()),
   useProjects: () => ({ projects: [], isLoading: false }),
+  useProjectHarnesses: () => ({ data: { harnesses: [], models: [] } }),
 }));
 
 vi.mock('../hooks/queries', async (importOriginal) => ({
@@ -178,6 +175,7 @@ vi.mock('../hooks/queries', async (importOriginal) => ({
   }),
   useAutomationRuns: () => ({ data: [] }),
   useAutomationProjects: () => ({ data: [] }),
+  useAutomationTriggers: () => ({ data: [] }),
   useNodeTypeCatalog: () => ({ data: undefined, isError: false }),
 }));
 
@@ -341,13 +339,40 @@ function scrollContainerOf(element: Element) {
  * A real pointer click: React Flow's pane reads the event's window on
  * mousedown, which a synthesized event does not carry. */
 async function selectNode(id: string) {
+  await expectLaidOut();
   await userEvent.click(
     await screen.findByRole('button', { name: new RegExp(`^${id}`, 'i') }),
   );
   await screen.findByRole('textbox', { name: 'Code' });
 }
 
+/** The chart is drawn: the canvas laid the document out (in a worker, the
+ * first time a while), the frame is no longer busy and the view has come to
+ * rest. */
+async function expectLaidOut() {
+  const canvas = await screen.findByRole(
+    'group',
+    { name: 'Automation canvas' },
+    { timeout: 20_000 },
+  );
+  await vi.waitFor(() => expect(canvas).toHaveAttribute('aria-busy', 'false'), {
+    timeout: 20_000,
+  });
+  await viewportAtRest(canvas);
+  return canvas;
+}
+
+/** The canvas as it is shown: the chart, or the List view that stands in
+ * for it on a narrow screen. */
+function canvasView() {
+  return (
+    screen.queryByRole('group', { name: 'Automation canvas' }) ??
+    screen.getByRole('list', { name: 'Automation canvas' })
+  );
+}
+
 async function expectWholeCanvas() {
+  await expectLaidOut();
   for (const name of ZOOM_CONTROLS) {
     const control = await screen.findByRole('button', { name });
     expect(unclippedShare(control), name).toBeCloseTo(1, 2);
@@ -416,11 +441,8 @@ describe('automation editor workbench in Chromium', () => {
       expect(bounds.bottom).toBeLessThanOrEqual(
         strip.getBoundingClientRect().bottom,
       );
-      expect(
-        screen
-          .getByRole('group', { name: 'Automation canvas' })
-          .contains(picker),
-      ).toBe(false);
+      // Narrower than 24rem the List view stands in for the chart.
+      expect(canvasView().contains(picker)).toBe(false);
       await userEvent.click(picker);
       const history = await screen.findByRole('dialog', { name: 'Versions' });
       expect(history.getBoundingClientRect().left).toBeGreaterThanOrEqual(0);
@@ -472,7 +494,7 @@ describe('automation editor workbench in Chromium', () => {
       await screen.findByText('General settings');
       await userEvent.click(screen.getByRole('button', { name: 'Version' }));
       await userEvent.click(await screen.findByRole('radio', { name: /^v1/ }));
-      await screen.findByRole('group', { name: 'Automation canvas' });
+      await vi.waitFor(() => canvasView());
       expect(screen.getByRole('button', { name: 'Version' })).toHaveTextContent(
         'v1',
       );
@@ -658,18 +680,44 @@ describe('automation editor workbench in Chromium', () => {
   it('pans a picked box back into view when the inspector narrows the canvas', async () => {
     await page.viewport(1280, 800);
     const { nodes } = automation;
-    const { positions } = automation.ui;
-    // A box fitted against the canvas's right edge: the inspector's column
-    // opens right over where it was drawn.
+    // Six nodes that read nothing make the chart as wide as the canvas
+    // once it is fitted: the right-most box sits against the canvas's
+    // right edge, where the inspector's column opens.
     automation.nodes = [
       ...nodes,
-      { id: 'archive', type: 'transform', code: 'return {};' },
+      ...['archive', 'backup', 'cleanup', 'digest', 'export'].map((id) => ({
+        id,
+        type: 'transform',
+        code: 'return {};',
+      })),
     ];
-    automation.ui.positions = { ...positions, archive: { x: 1600, y: 0 } };
     try {
       renderEditorTab();
       const canvas = await expectWholeCanvas();
-      const box = await screen.findByRole('button', { name: /^archive/i });
+      const roots = [
+        'pulls',
+        'archive',
+        'backup',
+        'cleanup',
+        'digest',
+        'export',
+      ];
+      const boxes = await Promise.all(
+        roots.map((id) =>
+          screen.findByRole('button', { name: new RegExp(`^${id}`, 'i') }),
+        ),
+      );
+      const box = boxes.reduce((right, candidate) =>
+        candidate.getBoundingClientRect().right >
+        right.getBoundingClientRect().right
+          ? candidate
+          : right,
+      );
+      // The inspector's column is 22rem wide.
+      const inspectorWidth = 22 * 16;
+      expect(box.getBoundingClientRect().right).toBeGreaterThan(
+        canvas.getBoundingClientRect().right - inspectorWidth,
+      );
       await userEvent.click(box);
       await screen.findByRole('textbox', { name: 'Code' });
       await expect
@@ -683,21 +731,18 @@ describe('automation editor workbench in Chromium', () => {
       // frame before the 200ms pan ends: measure where the view comes to rest.
       await viewportAtRest(canvas);
 
-      // Closing hands the width back without moving the graph: focus returns
-      // to the box, which is already in sight.
-      const settled = box.getBoundingClientRect();
+      // Closing hands the width back: focus returns to the box, and the
+      // view — still the canvas's own fit, nobody moved it — follows the
+      // canvas back to its full width with the box in sight.
       await userEvent.keyboard('{Escape}');
       await expect.poll(() => document.activeElement).toBe(box);
-      // A pan that must not come has no event to await: the pause gives one
-      // time to show. A runner too slow to draw it in time can only miss it,
-      // never fail a graph that holds still.
-      await new Promise((resolve) => setTimeout(resolve, 400));
+      await viewportAtRest(canvas);
+      const frame = canvas.getBoundingClientRect();
       const after = box.getBoundingClientRect();
-      expect(after.left).toBeCloseTo(settled.left, 0);
-      expect(after.top).toBeCloseTo(settled.top, 0);
+      expect(after.left).toBeGreaterThanOrEqual(frame.left - 1);
+      expect(after.right).toBeLessThanOrEqual(frame.right + 1);
     } finally {
       automation.nodes = nodes;
-      automation.ui.positions = positions;
     }
   });
 
@@ -869,3 +914,125 @@ describe('automation editor workbench in Chromium', () => {
     expect(save).toHaveAccessibleDescription('Fix 1 error to save');
   });
 });
+
+describe('automation editor paths in Chromium', () => {
+  /** Summary runs only when the diff has text: two ways a run can go. */
+  async function withCondition(test: () => Promise<void>) {
+    const { nodes } = automation;
+    automation.nodes = nodes.map((node) =>
+      node.id === 'summary'
+        ? { ...node, when: '{{ nodes.diff.output.text !== "" }}' }
+        : node,
+    );
+    try {
+      await test();
+    } finally {
+      automation.nodes = nodes;
+    }
+  }
+
+  it('lists the paths in a panel under the view switch that stays open while a node is picked', async () =>
+    withCondition(async () => {
+      await page.viewport(1280, 800);
+      renderEditorTab();
+      const canvas = await expectWholeCanvas();
+      const button = screen.getByRole('button', { name: '2 paths' });
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+      await userEvent.click(button);
+      const panel = await screen.findByRole('region', {
+        name: 'Possible paths',
+      });
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+      expect(button).toHaveAttribute('aria-controls', panel.id);
+      // Under the view switch, inside the canvas's top-left corner.
+      const viewSwitch = screen.getByRole('radiogroup', { name: 'View' });
+      const panelBox = panel.getBoundingClientRect();
+      const canvasBox = canvas.getBoundingClientRect();
+      expect(panelBox.top).toBeGreaterThanOrEqual(
+        viewSwitch.getBoundingClientRect().bottom,
+      );
+      expect(panelBox.left).toBeGreaterThanOrEqual(canvasBox.left);
+      expect(panelBox.bottom).toBeLessThanOrEqual(canvasBox.bottom);
+
+      const row = within(panel).getByRole('button', { name: /^Path 2/ });
+      await userEvent.click(row);
+      expect(row).toHaveAttribute('aria-pressed', 'true');
+      // Not a popover: picking a node leaves the list open. (The panel
+      // names Pulls too, as a node that ends a run when it fails: the box
+      // is picked by its own mark.)
+      const pulls = canvas.querySelector<HTMLElement>(
+        '[data-flow-node="pulls"]',
+      );
+      if (pulls === null) throw new Error('no Pulls box');
+      await userEvent.click(pulls);
+      await screen.findByRole('textbox', { name: 'Code' });
+      expect(
+        screen.getByRole('region', { name: 'Possible paths' }),
+      ).toBeVisible();
+      expect(row).toHaveAttribute('aria-pressed', 'true');
+
+      await userEvent.click(
+        within(panel).getByRole('button', { name: 'Close' }),
+      );
+      await vi.waitFor(() =>
+        expect(
+          screen.queryByRole('region', { name: 'Possible paths' }),
+        ).toBeNull(),
+      );
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    }));
+
+  it('opens the List view on a 375px phone, pins a path from a sheet and leaves a pill to undo it', async () =>
+    withCondition(async () => {
+      await page.viewport(375, 812);
+      renderEditorTab();
+      // Narrower than 24rem, the chart is too small to read: the List view
+      // says the same, and the view switch says which one is shown.
+      await screen.findByRole('list', { name: 'Automation canvas' });
+      expect(screen.getByRole('radio', { name: 'List' })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+      await userEvent.click(screen.getByRole('button', { name: '2 paths' }));
+      const sheet = await screen.findByRole('dialog', {
+        name: 'Possible paths',
+      });
+      await userEvent.click(
+        within(sheet).getByRole('button', { name: /^Path 2/ }),
+      );
+      await vi.waitFor(() =>
+        expect(
+          screen.queryByRole('dialog', { name: 'Possible paths' }),
+        ).toBeNull(),
+      );
+      const pill = await screen.findByText(/^Path 2 · /);
+      expect(pill).toBeVisible();
+      await userEvent.click(screen.getByRole('button', { name: 'Show all' }));
+      await vi.waitFor(() =>
+        expect(screen.queryByText(/^Path 2 · /)).toBeNull(),
+      );
+    }));
+
+  it.each([375, 390])(
+    'keeps every canvas verb at least 24px on a %ipx phone',
+    async (width) =>
+      withCondition(async () => {
+        await page.viewport(width, 812);
+        renderEditorTab();
+        await screen.findByRole('button', { name: 'Test run' });
+        const verbs = [
+          screen.getByRole('radio', { name: 'Canvas' }),
+          screen.getByRole('radio', { name: 'List' }),
+          screen.getByRole('button', { name: '2 paths' }),
+          screen.getByRole('button', { name: 'Edit with your coding agent' }),
+          screen.getByRole('button', { name: 'Test run' }),
+        ];
+        for (const verb of verbs) {
+          const box = verb.getBoundingClientRect();
+          expect(box.width, verb.textContent ?? '').toBeGreaterThanOrEqual(24);
+          expect(box.height, verb.textContent ?? '').toBeGreaterThanOrEqual(24);
+          expect(box.right).toBeLessThanOrEqual(width);
+        }
+      }),
+  );
+});
diff --git a/services/platform/app/features/automations/components/automation-editor.test.tsx b/services/platform/app/features/automations/components/automation-editor.test.tsx
index c3ed675267..cc08f4fd4e 100644
--- a/services/platform/app/features/automations/components/automation-editor.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.test.tsx
@@ -124,6 +124,7 @@ vi.mock('../hooks/use-automation-validation', () => ({
     };
   },
   useInvalidateAutomationValidation: () => invalidateValidation,
+  VALIDATION_DEBOUNCE_MS: 400,
 }));
 
 // `EditorActions` owns every piece of save feedback and reaches for the
@@ -246,6 +247,7 @@ vi.mock('../hooks/queries', async (importOriginal) => {
     useAutomationRuns: () => ({ data: runsData }),
     useAutomationProjects: () => ({ data: projectsData.bound }),
     useNodeTypeCatalog: () => ({ data: undefined, isError: false }),
+    useAutomationTriggers: () => ({ data: [] }),
   };
 });
 
@@ -279,36 +281,73 @@ vi.mock('@tanstack/react-router', async () => {
   };
 });
 
-// The canvas is a React Flow viewport and jsdom performs no layout; the page
-// only needs it to hand a node to the inspector, so the stub offers that.
+// The canvas is a laid-out chart and jsdom performs no layout; the page only
+// needs it to hand a box to the inspector and to carry the page's own
+// controls in its corners, so the stub offers that.
 vi.mock('./automation-canvas', () => ({
   AutomationCanvas: ({
-    graph,
-    onSelectNode,
+    automation,
+    layoutKey,
+    onSelect,
     inspectorId,
-    runStatusByNode,
+    run,
+    changed,
+    view,
+    topStart,
+    topEnd,
+    toolbar,
   }: {
-    graph: { nodes: readonly { id: string }[] };
-    onSelectNode: (nodeId: string | null) => void;
+    automation: { nodes: readonly { id: string; when?: string }[] };
+    layoutKey: string;
+    onSelect: (id: string | null) => void;
     inspectorId: string;
-    runStatusByNode?: ReadonlyMap<string, string>;
+    run?: { statusByNode: ReadonlyMap<string, string> };
+    changed?: { ids: ReadonlySet<string>; key: string | number };
+    view?: string;
+    topStart?: React.ReactNode;
+    topEnd?: React.ReactNode;
+    toolbar?: React.ReactNode;
   }) => (
-    <div data-testid="canvas" data-inspector-id={inspectorId}>
-      {graph.nodes.map((node) => (
+    <div
+      data-testid="canvas"
+      data-inspector-id={inspectorId}
+      data-layout-key={layoutKey}
+      data-view={view}
+      data-changed={
+        changed === undefined ? undefined : [...changed.ids].sort().join(',')
+      }
+    >
+      <div data-testid="canvas-top-start">{topStart}</div>
+      <div data-testid="canvas-top-end">{topEnd}</div>
+      {automation.nodes.map((node) => (
         <button
           key={node.id}
           type="button"
           onClick={() => {
-            onSelectNode(node.id);
+            onSelect(node.id);
           }}
-          data-run-status={runStatusByNode?.get(node.id)}
+          data-run-status={run?.statusByNode.get(node.id)}
         >
           {`select ${node.id}`}
         </button>
       ))}
-      <button type="button" onClick={() => onSelectNode(null)}>
+      {automation.nodes
+        .filter((node) => node.when !== undefined)
+        .map((node) => (
+          <button
+            key={`gate-${node.id}`}
+            type="button"
+            onClick={() => {
+              onSelect(`__gate:${node.id}`);
+            }}
+          >
+            {`select the condition of ${node.id}`}
+          </button>
+        ))}
+      <button type="button" onClick={() => onSelect(null)}>
         deselect
       </button>
+      {toolbar}
     </div>
   ),
 }));
@@ -388,6 +427,22 @@ const saveButton = () => screen.getByRole('button', { name: 'Save' });
 const discardButton = () => screen.getByRole('button', { name: 'Discard' });
 const whenField = () => screen.getByRole('textbox', { name: 'When' });
 const versionPicker = () => screen.getByRole('button', { name: 'Version' });
+/** The live region that counts problems; the canvas has one of its own. */
+const issueAnnouncer = () => {
+  const region = screen
+    .getAllByRole('status')
+    .find((element) => element.dataset.slot === 'issue-announcer');
+  if (region === undefined) throw new Error('No problems announcer');
+  return region;
+};
+/** The live region that says what changed on the canvas. */
+const canvasAnnouncer = () => {
+  const region = screen
+    .getAllByRole('status')
+    .find((element) => element.dataset.slot === 'canvas-announcer');
+  if (region === undefined) throw new Error('No canvas announcer');
+  return region;
+};
 
 /** Select the one node and edit a field every node type accepts. */
 async function editTheNode(user: ReturnType<typeof renderPage>['user']) {
@@ -1012,9 +1067,12 @@ describe('AutomationEditor', () => {
       startedAt: 1_700_000_200_000,
     });
     const { user } = renderPage();
-    const hide = screen.getByRole('button', { name: 'Hide last run' });
+    // Among the canvas's own verbs, in its top-right corner.
+    const hide = within(screen.getByTestId('canvas-top-end')).getByRole(
+      'button',
+      { name: 'Hide last run' },
+    );
     expect(hide).toHaveAttribute('aria-pressed', 'true');
-    expect(hide.closest('.absolute')).not.toBeNull();
     expect(
       screen.queryByRole('link', { name: 'Open the last run' }),
     ).toBeNull();
@@ -1830,9 +1888,7 @@ describe('AutomationEditor problems', () => {
     // The server's errors hold Save until the draft changes.
     expect(saveButton()).toHaveAttribute('aria-disabled', 'true');
     await waitFor(() =>
-      expect(screen.getByRole('status')).toHaveTextContent(
-        'Saving was refused. 1 error',
-      ),
+      expect(issueAnnouncer()).toHaveTextContent('Saving was refused. 1 error'),
     );
   });
 
@@ -1857,7 +1913,7 @@ describe('AutomationEditor problems', () => {
 
   it('says a draft check only when its counts change', async () => {
     const { user } = renderPage();
-    const status = () => screen.getByRole('status');
+    const status = issueAnnouncer;
     // The stored version had no problems: a clean draft is no news.
     await editTheNode(user);
     await user.type(whenField(), 'y');
@@ -1913,7 +1969,7 @@ describe('AutomationEditor problems', () => {
     const { user } = renderPage();
     await user.click(screen.getByRole('button', { name: 'Deploy v3' }));
     await waitFor(() =>
-      expect(screen.getByRole('status')).toHaveTextContent(/^1 error$/),
+      expect(issueAnnouncer()).toHaveTextContent(/^1 error$/),
     );
   });
 
@@ -1953,7 +2009,7 @@ describe('AutomationEditor problems', () => {
       screen.getByRole('region', { name: 'Problems' }),
     ).getByRole('button', { name: /Error:/ });
     expect(row).toHaveAttribute('aria-disabled', 'true');
-    expect(row).toHaveAccessibleDescription(/can't be edited here/);
+    expect(row).toHaveAccessibleDescription(/with your coding agent/);
   });
 
   it('checks nothing and shows no Problems for a member', () => {
@@ -1970,3 +2026,165 @@ describe('AutomationEditor problems', () => {
     await checkAccessibility(container);
   });
 });
+
+describe('AutomationEditor canvas', () => {
+  const twoNodes = {
+    name: 'billing/dunning',
+    nodes: [
+      { id: 'summary', type: 'llm', prompt: 'One sentence, please.' },
+      {
+        id: 'notify',
+        type: 'transform',
+        when: '{{ nodes.summary.output !== null }}',
+        input: { text: '{{ nodes.summary.output }}' },
+        code: 'return input.text;',
+      },
+    ],
+  };
+
+  it('follows a version saved elsewhere, rings what changed and says so', async () => {
+    const { user, rerender } = renderPage();
+    await user.click(screen.getByRole('button', { name: 'select summary' }));
+    expect(screen.getByTestId('canvas')).toHaveAttribute(
+      'data-layout-key',
+      'billing/dunning:latest',
+    );
+
+    // A coding agent saves v4: Summary changed, Notify is new.
+    state.version = 4;
+    state.document = {
+      ...twoNodes,
+      nodes: [
+        { id: 'summary', type: 'llm', prompt: 'Two sentences, please.' },
+        ...twoNodes.nodes.slice(1),
+      ],
+    };
+    rerender(page());
+
+    await waitFor(() =>
+      expect(canvasAnnouncer()).toHaveTextContent('Now showing v4.'),
+    );
+    const canvas = screen.getByTestId('canvas');
+    // The same picture, glided to: the key stays, the changed nodes ring.
+    expect(canvas).toHaveAttribute('data-layout-key', 'billing/dunning:latest');
+    expect(canvas).toHaveAttribute('data-changed', 'notify,summary');
+    // The open node is still there, so it stays open.
+    expect(inspector()).not.toBeNull();
+  });
+
+  it('closes the open node when the newer version no longer has it', async () => {
+    state.document = twoNodes;
+    const { user, rerender } = renderPage();
+    await user.click(screen.getByRole('button', { name: 'select notify' }));
+    expect(inspector()).not.toBeNull();
+
+    state.version = 4;
+    state.document = { ...twoNodes, nodes: twoNodes.nodes.slice(0, 1) };
+    rerender(page());
+
+    await waitFor(() =>
+      expect(canvasAnnouncer()).toHaveTextContent(
+        'Now showing v4. Notify is no longer in this version.',
+      ),
+    );
+    expect(inspector()).toBeNull();
+  });
+
+  it('says nothing new about the version this tab saved', async () => {
+    const { user, rerender } = renderPage();
+    await editTheNode(user);
+    await user.click(saveButton());
+    await user.click(screen.getByRole('button', { name: 'Save version' }));
+    await waitFor(() => expect(saveMutation.mutateAsync).toHaveBeenCalled());
+
+    state.version = 4;
+    rerender(page());
+    expect(canvasAnnouncer()).toHaveTextContent('');
+    expect(
+      screen.queryByRole('button', { name: /discard my draft/ }),
+    ).toBeNull();
+  });
+
+  it('leaves a draft where it is and offers the newer version', async () => {
+    const { user, rerender } = renderPage();
+    await editTheNode(user);
+
+    state.version = 4;
+    state.document = twoNodes;
+    rerender(page());
+
+    expect(screen.getByText('A newer version was saved')).toBeVisible();
+    expect(
+      screen.getByText(
+        'v4 was saved while you were editing. Your draft is based on v3.',
+      ),
+    ).toBeVisible();
+    // Nothing on the canvas moved: the draft is still what it shows.
+    expect(screen.queryByRole('button', { name: 'select notify' })).toBeNull();
+    expect(screen.getByTestId('canvas')).not.toHaveAttribute('data-changed');
+    expect(whenField()).toHaveValue('x');
+
+    await user.click(
+      screen.getByRole('button', { name: 'Show v4 and discard my draft' }),
+    );
+    expect(
+      await screen.findByRole('button', { name: 'select notify' }),
+    ).toBeInTheDocument();
+    expect(screen.queryByText('A newer version was saved')).toBeNull();
+    expect(saveButton()).toBeDisabled();
+  });
+
+  it('opens the node a link names, and keeps the open node in the link', async () => {
+    const onSearchChange = vi.fn();
+    const { user } = renderPage({ node: 'summary', onSearchChange });
+    expect(inspector()).not.toBeNull();
+    expect(onSearchChange).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('button', { name: 'deselect' }));
+    expect(onSearchChange).toHaveBeenLastCalledWith({ node: null });
+    await user.click(screen.getByRole('button', { name: 'select summary' }));
+    expect(onSearchChange).toHaveBeenLastCalledWith({ node: 'summary' });
+  });
+
+  it('opens a node at its condition when the condition is picked', async () => {
+    state.document = twoNodes;
+    const { user } = renderPage();
+    await user.click(
+      screen.getByRole('button', { name: 'select the condition of notify' }),
+    );
+    expect(inspector()).not.toBeNull();
+    await waitFor(() => expect(whenField()).toHaveFocus());
+  });
+
+  it('switches between the chart and the List view and keeps it in the link', async () => {
+    const onSearchChange = vi.fn();
+    const { user } = renderPage({ view: 'list', onSearchChange });
+    const canvas = screen.getByTestId('canvas');
+    expect(canvas).toHaveAttribute('data-view', 'list');
+
+    const views = within(screen.getByTestId('canvas-top-start')).getByRole(
+      'radiogroup',
+      { name: 'View' },
+    );
+    await user.click(within(views).getByRole('radio', { name: 'Canvas' }));
+    expect(canvas).toHaveAttribute('data-view', 'chart');
+    expect(onSearchChange).toHaveBeenLastCalledWith({ view: 'canvas' });
+  });
+
+  it('puts the coding-agent entry among the canvas verbs for an author', () => {
+    renderPage();
+    expect(
+      within(screen.getByTestId('canvas-top-end')).getByRole('button', {
+        name: 'Edit with your coding agent',
+      }),
+    ).toBeInTheDocument();
+  });
+
+  it('offers no coding-agent entry to a member', () => {
+    validationMock.canAuthor = false;
+    renderPage();
+    expect(
+      screen.queryByRole('button', { name: 'Edit with your coding agent' }),
+    ).toBeNull();
+  });
+});
diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 2b5ef18000..31209d7bef 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -32,8 +32,10 @@ import {
   ResponsiveDialogDescription,
   ResponsiveDialogTitle,
 } from '@tale/ui/responsive-dialog';
+import { SegmentedControl } from '@tale/ui/segmented-control';
 import { Select } from '@tale/ui/select';
 import { Text } from '@tale/ui/text';
+import { useFormatDate } from '@tale/ui/use-format-date';
 import { useIsMobile } from '@tale/ui/use-is-mobile';
 import { useMediaQuery } from '@tale/ui/use-media-query';
 import { useToast } from '@tale/ui/use-toast';
@@ -55,7 +57,10 @@ import {
   useState,
 } from 'react';
 
-import { useProjects } from '@/app/features/projects/hooks/queries';
+import {
+  useProjectHarnesses,
+  useProjects,
+} from '@/app/features/projects/hooks/queries';
 import { useAbility } from '@/app/hooks/use-ability';
 import { failureDetail } from '@/app/lib/backend/adapters';
 import { readStateOf } from '@/app/lib/backend/read-state';
@@ -63,6 +68,7 @@ import { ptr } from '@/lib/engine/core/syntax/pointer';
 import type { NodeDef, Automation } from '@/lib/engine/core/types';
 import { useT } from '@/lib/i18n/client';
 import { savedWarningsSchema } from '@/lib/shared/schemas/automation-issues';
+import { stableStringify } from '@/lib/shared/utils/stable-stringify';
 
 import { mergeNodeTypes } from '../hooks/backend';
 import {
@@ -74,16 +80,19 @@ import {
   useAutomation,
   useAutomationProjects,
   useAutomationRuns,
+  useAutomationTriggers,
   useNodeTypeCatalog,
 } from '../hooks/queries';
 import {
   useAutomationValidation,
   useInvalidateAutomationValidation,
+  VALIDATION_DEBOUNCE_MS,
 } from '../hooks/use-automation-validation';
 import { focusAutomationNode } from '../hooks/use-deselect-on-escape';
 import { automationDetailPathname } from '../lib/detail-paths';
 import { DOCUMENT_DIRTY_KEY } from '../lib/dirty-keys';
-import { readDocument, readPositions } from '../lib/document';
+import { readDocument } from '../lib/document';
+import type { AutomationEditorView } from '../lib/editor-search';
 import {
   automationErrorCode,
   automationErrorIssues,
@@ -92,7 +101,7 @@ import {
   isMissingAutomationRead,
   type AutomationErrorIssues,
 } from '../lib/errors';
-import { buildGraph } from '../lib/graph';
+import { flowGraphTarget } from '../lib/flow-ids';
 import { fieldsWithIssueControl } from '../lib/inspector-fields';
 import {
   issueCountsByNode,
@@ -101,19 +110,22 @@ import {
   withIssueIds,
   type AutomationIssue,
 } from '../lib/issues';
+import { nodeCatalogView, nodeTitle } from '../lib/node-face';
 import {
   cursorNodeStatus,
   nodeStatusMap,
   projectRun,
   readRunCursorNode,
+  readRunStatus,
 } from '../lib/run-view';
+import { triggerLines, triggerRows } from '../lib/trigger-summary';
 import {
   AUTOMATION_EDITOR_WORKBENCH_GRID,
   AUTOMATION_WORKBENCH_CANVAS_SLOT,
   AUTOMATION_WORKBENCH_COMPACT_QUERY,
   AUTOMATION_WORKBENCH_INSPECTOR_COLUMNS,
 } from '../lib/workbench';
-import { AutomationCanvas } from './automation-canvas';
+import { AutomationCanvas, type CanvasRun } from './automation-canvas';
 import { AutomationEditorActions } from './automation-editor-actions';
 import {
   AutomationProblemsDock,
@@ -125,6 +137,7 @@ import {
   type AutomationRunRequest,
 } from './automation-run-dialog';
 import { AutomationVersionPicker } from './automation-version-picker';
+import { CodingAgentButton } from './coding-agent-entry';
 import { NodeFields, NodeInspector } from './node-inspector';
 
 /**
@@ -200,6 +213,34 @@ interface AutomationEditorProps {
   /** The author picked a version to look at — `undefined` asks for the latest
    * again (after a save appends one). */
   onSelectVersion: (version: number | undefined) => void;
+  /** The route's `?view=`: the chart or the List view. */
+  view?: AutomationEditorView;
+  /** The route's `?node=`: the node (or Start, or End) to open on load. */
+  node?: string;
+  /** The reader switched the view or opened a node (`null`: closed it); the
+   * route keeps it in the URL without a history entry. */
+  onSearchChange?: (change: {
+    view?: AutomationEditorView;
+    node?: string | null;
+  }) => void;
+}
+
+/**
+ * A draft as the canvas draws it: at a pause in the edits (the pause the
+ * draft check waits for too), and gone at once when the draft goes, so a
+ * discarded draft never comes back for a moment under the next one.
+ */
+function usePausedDraft(draft: Automation | null): Automation | null {
+  const [paused, setPaused] = useState<Automation | null>(null);
+  useEffect(() => {
+    if (draft === null) {
+      setPaused(null);
+      return undefined;
+    }
+    const handle = setTimeout(() => setPaused(draft), VALIDATION_DEBOUNCE_MS);
+    return () => clearTimeout(handle);
+  }, [draft]);
+  return draft === null ? null : paused;
 }
 
 /** Route parameters can change without unmounting the page. Keep the draft
@@ -265,6 +306,9 @@ function AutomationEditorScope({
   version,
   showVersionHistory,
   onSelectVersion,
+  view: viewParam,
+  node: nodeParam,
+  onSearchChange,
 }: AutomationEditorProps) {
   const { t } = useT('automations');
   const isMobile = useIsMobile();
@@ -280,7 +324,20 @@ function AutomationEditorScope({
   // saving, deploying, triggering, and LIVE runs demand the
   // `developerSettings` ability — hiding what would only fail server-side.
   const canAuthor = ability.can('read', 'developerSettings');
-  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  // A `?node=` link opens its node on load. Start and End have no inspector
+  // of their own yet, so a link to them opens nothing.
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(() =>
+    nodeParam === undefined || flowGraphTarget(nodeParam).kind !== 'node'
+      ? null
+      : nodeParam,
+  );
+  // The open node follows into the URL (`?node=`), replacing the entry.
+  const writtenNodeRef = useRef<string | null>(selectedNodeId);
+  useEffect(() => {
+    if (writtenNodeRef.current === selectedNodeId) return;
+    writtenNodeRef.current = selectedNodeId;
+    onSearchChange?.({ node: selectedNodeId });
+  }, [selectedNodeId, onSearchChange]);
   const deselectNode = useCallback(() => {
     const id = selectedNodeId;
     setSelectedNodeId(null);
@@ -294,6 +351,15 @@ function AutomationEditorScope({
   /** The version the draft was built on — pinned on its first edit, sent
    * with the save so the store can refuse a draft another tab overtook. */
   const draftBaseRef = useRef<number | undefined>(undefined);
+  /** The same base, for the notice that a newer version landed under the
+   * draft. */
+  const [draftBase, setDraftBase] = useState<number | undefined>(undefined);
+  /** The document the draft started from: the canvas keeps drawing it until
+   * the first pause in the edits. */
+  const [draftOrigin, setDraftOrigin] = useState<Automation | null>(null);
+  /** The version this tab saved last: following it to the latest is no
+   * news to its author. */
+  const savedHereRef = useRef<number | undefined>(undefined);
   const draftEpochRef = useRef(0);
   /** A save the store refused because a version landed after the draft
    * started: the author decides — drop the draft and reload, or save on
@@ -401,8 +467,14 @@ function AutomationEditorScope({
     [deployedQuery.data?.document],
   );
   const automation = draft ?? stored;
-  const graph = useMemo(() => buildGraph(automation), [automation]);
-  const positions = useMemo(() => readPositions(automation), [automation]);
+  // The canvas redraws a draft at a pause in the edits — the pause the
+  // check waits for too — so typing a reference never relays it out per
+  // keystroke; until the first pause it keeps the document the draft started
+  // from, whatever version lands meanwhile. A stored version (opened, saved,
+  // switched to) shows at once.
+  const pausedDraft = usePausedDraft(draft);
+  const canvasDocument =
+    draft === null ? stored : (pausedDraft ?? draftOrigin ?? stored);
 
   const runs = runsQuery.data ?? [];
   const lastRun = runs[0];
@@ -415,12 +487,12 @@ function AutomationEditorScope({
       showLastRun && lastRun
         ? nodeStatusMap(
             lastRunProjection,
-            graph.nodes.map((node) => node.id),
+            (automation?.nodes ?? []).map((node) => node.id),
             readRunCursorNode(lastRun),
             cursorNodeStatus(lastRun),
           )
         : undefined,
-    [showLastRun, lastRun, lastRunProjection, graph.nodes],
+    [showLastRun, lastRun, lastRunProjection, automation?.nodes],
   );
 
   const nodeTypes = useMemo(
@@ -489,6 +561,182 @@ function AutomationEditorScope({
         : issueCountsByNode([...shownErrors, ...shownWarnings], automation),
     [automation, shownErrors, shownWarnings],
   );
+
+  // ── The canvas ────────────────────────────────────────────────────────
+  // What the canvas draws besides the document: the catalog's words and
+  // icons, the served models' names, what starts a run, what the check
+  // worked out, and the last run.
+  const triggersQuery = useAutomationTriggers(organizationId, automationSlug);
+  const harnesses = useProjectHarnesses(organizationId);
+  const { formatDate } = useFormatDate();
+  const catalog = useMemo(
+    () => nodeCatalogView(nodeTypes, catalogQuery.data?.connectors ?? []),
+    [nodeTypes, catalogQuery.data?.connectors],
+  );
+  const modelNames = useMemo(
+    () =>
+      new Map(
+        (harnesses.data?.models ?? []).map((model) => [model.id, model.label]),
+      ),
+    [harnesses.data?.models],
+  );
+  const modelLabel = useCallback(
+    (id: string) => modelNames.get(id),
+    [modelNames],
+  );
+  const deployedVersionNow = automationQuery.data?.deployedVersion;
+  const triggerRowsShown = useMemo(
+    () =>
+      triggerRows(
+        triggerLines(triggersQuery.data ?? [], {
+          deployed: deployedVersionNow !== undefined,
+          t,
+        }),
+        { t, formatDate: (at) => formatDate(at, 'long') },
+      ),
+    [triggersQuery.data, deployedVersionNow, t, formatDate],
+  );
+  const validationTypes = validation.types ?? null;
+  const validationAnalysis = validation.analysis ?? null;
+  const canvasCheck = useMemo(
+    () => ({
+      status: !canAuthor
+        ? ('off' as const)
+        : validation.status === 'idle' || validation.status === 'checking'
+          ? ('pending' as const)
+          : validation.status,
+      analysis: validationAnalysis,
+      types: validationTypes,
+    }),
+    [canAuthor, validation.status, validationAnalysis, validationTypes],
+  );
+  const startNotice = useMemo(() => {
+    const cause = issueViews.find(
+      (view) => view.issue.code === 'TRIGGER_INPUT_MISMATCH',
+    )?.item.cause;
+    return typeof cause === 'string' ? cause : null;
+  }, [issueViews]);
+  const canvasRun = useMemo<CanvasRun | undefined>(
+    () =>
+      showLastRun && lastRun && runStatusByNode !== undefined
+        ? {
+            statusByNode: runStatusByNode,
+            projection: lastRunProjection,
+            status: readRunStatus(lastRun.status),
+          }
+        : undefined,
+    [showLastRun, lastRun, runStatusByNode, lastRunProjection],
+  );
+  const layoutKey = `${automationSlug}:${version ?? 'latest'}`;
+
+  /** A box picked on the canvas: a node opens its inspector, a condition
+   * opens its node at the condition's field. Start and End have no
+   * inspector of their own yet. */
+  const selectOnCanvas = useCallback(
+    (id: string | null) => {
+      if (id === null) {
+        setSelectedNodeId(null);
+        return;
+      }
+      const target = flowGraphTarget(id);
+      if (target.kind === 'node') {
+        setSelectedNodeId(target.nodeId);
+        return;
+      }
+      if (target.kind !== 'gate') return;
+      setSelectedNodeId(target.nodeId);
+      const index =
+        automation?.nodes.findIndex((node) => node.id === target.nodeId) ?? -1;
+      if (index >= 0) requestIssueFocus(ptr('nodes', index, 'when'));
+    },
+    [automation, requestIssueFocus],
+  );
+
+  const [viewChoice, setViewChoice] = useState<
+    AutomationEditorView | undefined
+  >(viewParam);
+  // Below 24rem the chart is too narrow to read; the List view says the same.
+  const narrowCanvas = useMediaQuery('(width < 24rem)');
+  const canvasView =
+    viewChoice === 'list' || (viewChoice === undefined && narrowCanvas)
+      ? ('list' as const)
+      : ('chart' as const);
+  const changeView = useCallback(
+    (next: AutomationEditorView) => {
+      setViewChoice(next);
+      onSearchChange?.({ view: next });
+    },
+    [onSearchChange],
+  );
+
+  // ── A newer version saved elsewhere ─────────────────────────────────
+  // Following the latest (no `?version=`), a version another window or a
+  // coding agent saves replaces the one on screen: with no draft the
+  // canvas glides to it, rings what changed and says so; under a draft
+  // nothing moves, and a notice offers to show it.
+  const shownVersion = automationQuery.data?.version;
+  const [canvasChange, setCanvasChange] = useState<
+    { ids: ReadonlySet<string>; key: number } | undefined
+  >(undefined);
+  const [canvasNews, setCanvasNews] = useState({ text: '', key: 0 });
+  const seenRef = useRef<{
+    version: number | undefined;
+    asked: number | undefined;
+    doc: Automation | null;
+  }>({ version: shownVersion, asked: version, doc: stored });
+  useEffect(() => {
+    const seen = seenRef.current;
+    seenRef.current = { version: shownVersion, asked: version, doc: stored };
+    if (
+      seen.version === undefined ||
+      shownVersion === undefined ||
+      seen.version === shownVersion ||
+      seen.asked !== version ||
+      version !== undefined ||
+      shownVersion < seen.version ||
+      savedHereRef.current === shownVersion ||
+      draft !== null ||
+      stored === null ||
+      seen.doc === null
+    ) {
+      return;
+    }
+    const before = new Map(
+      seen.doc.nodes.map((node) => [node.id, stableStringify(node)]),
+    );
+    setCanvasChange({
+      ids: new Set(
+        stored.nodes
+          .filter((node) => before.get(node.id) !== stableStringify(node))
+          .map((node) => node.id),
+      ),
+      key: shownVersion,
+    });
+    const said = [t('canvas.updated', { version: shownVersion })];
+    if (
+      selectedNodeId !== null &&
+      !stored.nodes.some((node) => node.id === selectedNodeId)
+    ) {
+      said.push(
+        t('canvas.selectionRemoved', { node: nodeTitle(selectedNodeId) }),
+      );
+      setSelectedNodeId(null);
+    }
+    setCanvasNews((previous) => ({
+      text: said.join(' '),
+      key: previous.key + 1,
+    }));
+  }, [shownVersion, version, stored, draft, selectedNodeId, t]);
+  const newerVersion =
+    draft !== null &&
+    version === undefined &&
+    draftBase !== undefined &&
+    shownVersion !== undefined &&
+    shownVersion > draftBase &&
+    savedHereRef.current !== shownVersion
+      ? shownVersion
+      : null;
+
   const selectedNodeIssues = useMemo(
     () =>
       issueViews.filter(
@@ -651,6 +899,8 @@ function AutomationEditorScope({
       // overtook the draft, not the one it was built on.
       if (draft === null) {
         draftBaseRef.current = automationQuery.data?.version;
+        setDraftBase(automationQuery.data?.version);
+        setDraftOrigin(automation);
         draftEpochRef.current += 1;
       }
       setDraft(patchNode(automation, selectedNodeId, patch));
@@ -705,6 +955,8 @@ function AutomationEditorScope({
   const discardDraft = useCallback(() => {
     draftEpochRef.current += 1;
     setDraft(null);
+    setDraftBase(undefined);
+    setDraftOrigin(null);
   }, []);
 
   // Save waits while the check stands on errors — the draft's own, or,
@@ -849,7 +1101,7 @@ function AutomationEditorScope({
   const lookingIsLive =
     lookingVersion !== undefined && lookingVersion === meta?.deployedVersion;
   const selectedNode =
-    graph.nodes.find((node) => node.id === selectedNodeId) ?? null;
+    automation.nodes.find((node) => node.id === selectedNodeId) ?? null;
   const selectedNodeIndex = automation.nodes.findIndex(
     (node) => node.id === selectedNodeId,
   );
@@ -899,6 +1151,8 @@ function AutomationEditorScope({
       });
     }
     draftBaseRef.current = saved.version;
+    setDraftBase(saved.version);
+    savedHereRef.current = saved.version;
     setDraft((current) => (current === automation ? null : current));
     setSaveMessage('');
     // The save appended a version; show it, whichever one was on screen.
@@ -1148,6 +1402,18 @@ function AutomationEditorScope({
       {canAuthor && <AutomationEditorActions />}
     </div>
   );
+  const viewSwitch = (
+    <SegmentedControl
+      aria-label={t('canvas.view.label')}
+      value={canvasView === 'list' ? 'list' : 'canvas'}
+      onValueChange={(next) => changeView(next === 'list' ? 'list' : 'canvas')}
+      options={[
+        { value: 'canvas', label: t('canvas.view.canvas') },
+        { value: 'list', label: t('canvas.view.list') },
+      ]}
+      className="bg-background shadow-sm"
+    />
+  );
   const canvasToolbarActions = (
     <div className="flex flex-wrap items-center justify-center gap-2 md:justify-end">
       {automationActions}
@@ -1206,8 +1472,31 @@ function AutomationEditorScope({
             nothing started, which the author has to read next to the automation
             it concerns. Save feedback goes through the editor cluster instead.
             The alerts keep the page inset, in a band above the workbench. */}
-        {(refusal !== null || deployRefusal !== null || deployedReadError) && (
+        {(refusal !== null ||
+          deployRefusal !== null ||
+          deployedReadError ||
+          newerVersion !== null) && (
           <div className="border-border flex flex-col gap-3 border-b p-4">
+            {newerVersion !== null && draftBase !== undefined && (
+              <Alert
+                variant="info"
+                title={t('canvas.newerVersion.title')}
+                description={t('canvas.newerVersion.body', {
+                  version: newerVersion,
+                  base: draftBase,
+                })}
+              >
+                <Button
+                  type="button"
+                  variant="secondary"
+                  size="sm"
+                  className="mt-2"
+                  onClick={discardDraft}
+                >
+                  {t('canvas.newerVersion.show', { version: newerVersion })}
+                </Button>
+              </Alert>
+            )}
             {deployedReadError && (
               <CatalogLoadError
                 message={
@@ -1240,42 +1529,72 @@ function AutomationEditorScope({
           )}
         >
           <div className={AUTOMATION_WORKBENCH_CANVAS_SLOT}>
-            {lastRun ? (
-              <div className="pointer-events-none absolute inset-x-0 top-0 z-10 flex justify-end p-2">
-                <Button
-                  variant="secondary"
-                  size="icon"
-                  className="pointer-events-auto"
-                  aria-pressed={showLastRun}
-                  title={
-                    showLastRun
-                      ? t('detail.hideLastRun')
-                      : t('detail.showLastRun')
-                  }
-                  tooltipSide="left"
-                  onClick={() => {
-                    setShowLastRun((shown) => !shown);
-                  }}
-                >
-                  {showLastRun ? (
-                    <EyeOff className="size-4" aria-hidden="true" />
-                  ) : (
-                    <Eye className="size-4" aria-hidden="true" />
-                  )}
-                </Button>
-              </div>
-            ) : null}
-            <AutomationCanvas
-              graph={graph}
-              positions={positions}
-              selectedNodeId={selectedNodeId}
-              onSelectNode={setSelectedNodeId}
-              inspectorId={inspectorId}
-              framed={false}
-              centerActions={isMobile ? canvasToolbarActions : undefined}
-              {...(runStatusByNode !== undefined && { runStatusByNode })}
-              issueCountsByNode={countsByNode}
-            />
+            {canvasDocument !== null && (
+              <AutomationCanvas
+                automation={canvasDocument}
+                layoutKey={layoutKey}
+                catalog={catalog}
+                modelLabel={modelLabel}
+                triggers={triggerRowsShown}
+                check={canvasCheck}
+                startNotice={startNotice}
+                issueCounts={countsByNode}
+                selectedId={selectedNodeId}
+                onSelect={selectOnCanvas}
+                revealId={selectedNodeId}
+                inspectorId={inspectorId}
+                {...(canvasRun !== undefined && { run: canvasRun })}
+                {...(canvasChange !== undefined && { changed: canvasChange })}
+                framed={false}
+                view={canvasView}
+                onViewChange={(next) =>
+                  changeView(next === 'list' ? 'list' : 'canvas')
+                }
+                topStart={viewSwitch}
+                topEnd={
+                  <>
+                    {lastRun ? (
+                      <Button
+                        variant="secondary"
+                        size="icon-sm"
+                        aria-pressed={showLastRun}
+                        title={
+                          showLastRun
+                            ? t('detail.hideLastRun')
+                            : t('detail.showLastRun')
+                        }
+                        tooltipSide="bottom"
+                        onClick={() => {
+                          setShowLastRun((shown) => !shown);
+                        }}
+                      >
+                        {showLastRun ? (
+                          <EyeOff className="size-4" aria-hidden="true" />
+                        ) : (
+                          <Eye className="size-4" aria-hidden="true" />
+                        )}
+                      </Button>
+                    ) : null}
+                    {canAuthor && (
+                      <CodingAgentButton
+                        organizationId={organizationId}
+                        automationSlug={automationSlug}
+                      />
+                    )}
+                  </>
+                }
+                {...(isMobile && { toolbar: canvasToolbarActions })}
+                {...(canAuthor && {
+                  emptyAction: (
+                    <CodingAgentButton
+                      organizationId={organizationId}
+                      automationSlug={automationSlug}
+                      variant="primary"
+                    />
+                  ),
+                })}
+              />
+            )}
             {/* Under the canvas, spanning its column only, so the inspector
                 beside it keeps its full height. Below `lg` the list opens
                 in a sheet instead (further down). */}
@@ -1340,6 +1659,19 @@ function AutomationEditorScope({
           handingOn={handingOn}
         />
       )}
+      {/* What changed on the canvas while the reader looked: a version
+          saved elsewhere, a node it no longer has. */}
+      <div
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        className="sr-only"
+        data-slot="canvas-announcer"
+      >
+        {canvasNews.text === '' ? null : (
+          <span key={canvasNews.key}>{canvasNews.text}</span>
+        )}
+      </div>
       {canAuthor && (
         <IssueAnnouncer
           counts={issueCounts}
diff --git a/services/platform/app/features/automations/components/automation-node.test.tsx b/services/platform/app/features/automations/components/automation-node.test.tsx
deleted file mode 100644
index 297ce152d9..0000000000
--- a/services/platform/app/features/automations/components/automation-node.test.tsx
+++ /dev/null
@@ -1,289 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { checkAccessibility } from '@/tests/utils/a11y';
-import { render, screen } from '@/tests/utils/render';
-
-import { AutomationNodeBox } from './automation-node';
-
-/**
- * The node box is the canvas's whole keyboard story: it is a real button, so
- * Tab reaches it, Enter and Space activate it, and it announces that it expands
- * the inspector. If any of that regresses the canvas becomes pointer-only,
- * which is a defect rather than a rough edge.
- */
-
-const node = {
-  id: 'send_digest',
-  type: 'slack.post_message',
-  when: '{{ nodes.calc.output.count > 0 }}',
-  input: { text: '{{ nodes.calc.output.summary }}' },
-};
-
-/** jsdom approximates `:focus-visible` with event bookkeeping that leaks
- * across the tests sharing one document, so its verdict is order-dependent.
- * Pin the verdict to test each branch of the box's focus guard; the heuristic
- * itself is the browser's contract, not ours. */
-function stubFocusVisible(element: Element, verdict: boolean) {
-  const realMatches = element.matches.bind(element);
-  vi.spyOn(element, 'matches').mockImplementation((selector: string) =>
-    selector === ':focus-visible' ? verdict : realMatches(selector),
-  );
-}
-
-describe('AutomationNodeBox', () => {
-  it('is a button that names the node and its type', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={['calc']}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).toHaveAccessibleName(/send digest/i);
-    expect(button).toHaveAccessibleName(/slack\.post_message/i);
-  });
-
-  it('activates with the keyboard, not just a pointer', async () => {
-    const onSelect = vi.fn();
-    const { user } = render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={onSelect}
-      />,
-    );
-    await user.tab();
-    expect(screen.getByRole('button')).toHaveFocus();
-    await user.keyboard('{Enter}');
-    await user.keyboard(' ');
-    expect(onSelect).toHaveBeenCalledTimes(2);
-  });
-
-  it('announces whether the inspector is open for this node', () => {
-    const { rerender } = render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={vi.fn()}
-      />,
-    );
-    expect(screen.getByRole('button')).toHaveAttribute(
-      'aria-expanded',
-      'false',
-    );
-    rerender(
-      <AutomationNodeBox
-        node={node}
-        selected
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={vi.fn()}
-      />,
-    );
-    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'true');
-    expect(screen.getByRole('button')).toHaveAttribute(
-      'aria-controls',
-      'inspector',
-    );
-  });
-
-  it('spells out the nodes it reads, so the edges are readable without seeing them', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={['calc', 'fetch_orders']}
-        onSelect={vi.fn()}
-      />,
-    );
-    expect(screen.getByRole('button')).toHaveAccessibleName(
-      /calc, fetch orders/i,
-    );
-  });
-
-  it('shows the control flow and the run status as words, not only colour', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        runStatus="error"
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).toHaveAccessibleName(/failed/i);
-    expect(button).toHaveAccessibleName(/when/i);
-  });
-
-  it('marks an agent whose model has no pinned provider', () => {
-    render(
-      <AutomationNodeBox
-        node={{ id: 'agent', type: 'agent', model: 'claude-sonnet-4' }}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).toHaveAccessibleName(/no pinned provider/i);
-    expect(button.querySelector('svg')).not.toBeNull();
-  });
-
-  it('stays quiet when the agent model is pinned', () => {
-    render(
-      <AutomationNodeBox
-        node={{
-          id: 'agent',
-          type: 'agent',
-          model: 'claude-sonnet-4',
-          modelProvider: 'anthropic',
-        }}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={vi.fn()}
-      />,
-    );
-    expect(screen.getByRole('button')).not.toHaveAccessibleName(
-      /no pinned provider/i,
-    );
-  });
-
-  it('calls back on focus so the viewport can follow a keyboard user', async () => {
-    const onFocus = vi.fn();
-    const { user } = render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={vi.fn()}
-        onFocus={onFocus}
-      />,
-    );
-    stubFocusVisible(screen.getByRole('button'), true);
-    await user.tab();
-    expect(onFocus).toHaveBeenCalledTimes(1);
-  });
-
-  it('ignores pointer focus, which would pan the box out from under the click', async () => {
-    const onFocus = vi.fn();
-    const onSelect = vi.fn();
-    const { user } = render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        onSelect={onSelect}
-        onFocus={onFocus}
-      />,
-    );
-    const button = screen.getByRole('button');
-    stubFocusVisible(button, false);
-    await user.click(button);
-    expect(onSelect).toHaveBeenCalledTimes(1);
-    expect(onFocus).not.toHaveBeenCalled();
-  });
-
-  it('counts its problems on its face and says them in its name', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        issueCounts={{ errors: 2, warnings: 1 }}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).toHaveAccessibleName(/\(2 errors and 1 warning\)$/);
-    // The chips are decoration: the name already says it in words.
-    const marker = button.querySelector('[data-slot="flow-node-issue-marker"]');
-    expect(marker).toHaveAttribute('aria-hidden', 'true');
-    expect(marker?.querySelector('[data-severity="error"]')).toHaveTextContent(
-      '2',
-    );
-    expect(button).toHaveClass('border-destructive');
-  });
-
-  it('frames a node with warnings only in amber, and keeps the selection ring', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected
-        inspectorId="inspector"
-        sources={[]}
-        issueCounts={{ errors: 0, warnings: 1 }}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).toHaveClass('border-amber-600', 'ring-2');
-    expect(button).toHaveAccessibleName(/\(1 warning\)$/);
-  });
-
-  it('marks an unpinned model with a muted note, never a second warning', () => {
-    render(
-      <AutomationNodeBox
-        node={{ id: 'research', type: 'agent', model: 'openai/gpt-4o' }}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        issueCounts={{ errors: 0, warnings: 1 }}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    const note = button.querySelector('[data-slot="unpinned-model"]');
-    expect(note).toHaveClass('lucide-pin-off', 'text-muted-foreground');
-    expect(note?.getAttribute('class')).not.toMatch(/amber|destructive/);
-    // The one triangle on the node is the counted warning's.
-    expect(button.querySelectorAll('.lucide-triangle-alert')).toHaveLength(1);
-  });
-
-  it('says nothing more without problems', () => {
-    render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={[]}
-        issueCounts={{ errors: 0, warnings: 0 }}
-        onSelect={vi.fn()}
-      />,
-    );
-    const button = screen.getByRole('button');
-    expect(button).not.toHaveAccessibleName(/problem|error|warning/i);
-    expect(
-      button.querySelector('[data-slot="flow-node-issue-marker"]'),
-    ).toBeNull();
-  });
-
-  it('passes an axe audit', async () => {
-    const { container } = render(
-      <AutomationNodeBox
-        node={node}
-        selected={false}
-        inspectorId="inspector"
-        sources={['calc']}
-        runStatus="ok"
-        issueCounts={{ errors: 1, warnings: 1 }}
-        onSelect={vi.fn()}
-      />,
-    );
-    await checkAccessibility(container);
-  });
-});
diff --git a/services/platform/app/features/automations/components/automation-node.tsx b/services/platform/app/features/automations/components/automation-node.tsx
deleted file mode 100644
index 57dd97aeaa..0000000000
--- a/services/platform/app/features/automations/components/automation-node.tsx
+++ /dev/null
@@ -1,256 +0,0 @@
-'use client';
-
-import { Badge } from '@tale/ui/badge';
-import { cn } from '@tale/ui/cn';
-import {
-  FlowNodeIssueMarker,
-  flowNodeIssueFrameClass,
-  flowNodeIssueText,
-} from '@tale/ui/flow/node-issue-marker';
-import type { IssueCounts } from '@tale/ui/issue-summary';
-import { Handle, Position, type NodeProps } from '@xyflow/react';
-import { PinOff } from 'lucide-react';
-import { createContext, useContext, useMemo } from 'react';
-
-import type { NodeDef } from '@/lib/engine/core/types';
-import { useT } from '@/lib/i18n/client';
-
-import {
-  controlFlowBadges,
-  humanizeNodeId,
-  type DerivedEdge,
-} from '../lib/graph';
-import type { NodeRunStatus } from '../lib/run-view';
-import { RunStatusBadge } from './run-status-badge';
-
-/**
- * What the canvas hands every node box. Kept in context rather than in React
- * Flow's `data` so that selecting a node, or a run's overlay ticking forward,
- * does not rewrite the node array and re-run the layout.
- */
-export interface CanvasNodeContextValue {
-  selectedNodeId: string | null;
-  /** Id of the region the node's button expands — the inspector. */
-  inspectorId: string;
-  onSelect: (nodeId: string | null) => void;
-  /** Called when a node box takes focus, so the viewport can bring it into
-   * view for a keyboard user who cannot pan with a pointer. */
-  onFocusNode: (nodeId: string) => void;
-  /** Overlay status per node, when a run is shown on the canvas. */
-  runStatusByNode: ReadonlyMap<string, NodeRunStatus>;
-  /** The derived incoming edges, by target node. */
-  incomingByNode: ReadonlyMap<string, DerivedEdge[]>;
-  /** What the editor's check found on each node, when it checks one. */
-  issueCountsByNode: ReadonlyMap<string, IssueCounts>;
-}
-
-const CanvasNodeContext = createContext<CanvasNodeContextValue | null>(null);
-
-export const CanvasNodeProvider = CanvasNodeContext.Provider;
-
-function useCanvasNode(): CanvasNodeContextValue {
-  const value = useContext(CanvasNodeContext);
-  if (!value) {
-    throw new Error('A canvas node must render inside <CanvasNodeProvider>.');
-  }
-  return value;
-}
-
-const NO_ISSUES: IssueCounts = { errors: 0, warnings: 0 };
-
-/** The node payload React Flow carries for one document node. */
-export interface AutomationNodeData extends Record<string, unknown> {
-  node: NodeDef;
-}
-
-/**
- * An agent that names a model but not a provider — the same predicate the
- * store uses for `deployedUnpinnedAgentNodes`. The run walks connectors at
- * kick time; the editor's preselect can look pinned.
- */
-function agentHasUnpinnedModel(node: NodeDef): boolean {
-  if (node.type !== 'agent') return false;
-  if (typeof node.model !== 'string' || node.model === '') return false;
-  return typeof node.modelProvider !== 'string' || node.modelProvider === '';
-}
-
-export interface AutomationNodeBoxProps {
-  node: NodeDef;
-  selected: boolean;
-  /** Id of the region this box expands — the inspector. */
-  inspectorId: string;
-  /** Node ids this node reads from, derived from its references. */
-  sources: readonly string[];
-  runStatus?: NodeRunStatus | undefined;
-  /** The problems the editor's check found on this node. */
-  issueCounts?: IssueCounts | undefined;
-  onSelect: () => void;
-  onFocus?: () => void;
-}
-
-/**
- * One node box on the canvas.
- *
- * The box IS a button: React Flow's own focus handling is switched off on this
- * canvas, so every node is reachable with Tab in the order the document
- * executes, activates with Enter or Space, and toggles the inspector — a canvas
- * that needs a pointer is not usable at all for a keyboard user.
- *
- * What the box shows is what the engine will do: the node's id and type, its
- * declarative control flow as badges, the nodes it reads from (spelled out in
- * words, so the graph is readable without seeing the lines at all), its
- * status under the run being overlaid, and the problems the editor's check
- * found on it — counted on its face, coloured into its frame, and said in
- * words at the end of its name.
- */
-export function AutomationNodeBox({
-  node,
-  selected,
-  inspectorId,
-  sources,
-  runStatus,
-  issueCounts,
-  onSelect,
-  onFocus,
-}: AutomationNodeBoxProps) {
-  const { t } = useT('automations');
-  const counts = issueCounts ?? NO_ISSUES;
-  const issueText = flowNodeIssueText(t, counts);
-  const badges = useMemo(() => controlFlowBadges(node), [node]);
-
-  const badgeLabel = (kind: string, value: string, maxRepeats?: number) =>
-    maxRepeats === undefined
-      ? t(`canvas.controlFlow.${kind}`, { value })
-      : t('canvas.controlFlow.repeatUntilCapped', { value, maxRepeats });
-
-  return (
-    <button
-      type="button"
-      aria-expanded={selected}
-      // The inspector exists only for the picked node, so only its button
-      // names it; a collapsed disclosure points at nothing.
-      aria-controls={selected ? inspectorId : undefined}
-      // Must match AUTOMATION_NODE_ATTR — Close/Escape restore focus here.
-      data-automation-node={node.id}
-      onClick={onSelect}
-      onFocus={(event) => {
-        // A mouse press focuses the button too, and panning then would drag
-        // the box out from under the pointer mid-click — follow keyboard
-        // focus only.
-        if (event.currentTarget.matches(':focus-visible')) onFocus?.();
-      }}
-      className={cn(
-        'bg-card text-card-foreground border-border w-[18.75rem] rounded-lg border p-3 text-left shadow-sm transition-shadow',
-        'focus-visible:ring-ring cursor-pointer hover:shadow-md focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none',
-        // A skipped node stays on the path the run drew — a condition turned
-        // here — but it is not part of what happened, so it steps back.
-        runStatus === 'skipped' && 'opacity-60',
-        // The frame takes the worst problem's colour; the selection ring
-        // stays its own, so a picked node with a problem shows both.
-        flowNodeIssueFrameClass(counts),
-        selected && 'ring-ring ring-2',
-      )}
-    >
-      <span className="flex items-start justify-between gap-2">
-        <span className="min-w-0 flex-1 truncate text-sm font-medium">
-          {humanizeNodeId(node.id)}
-        </span>
-        <span className="flex shrink-0 items-center gap-1">
-          <FlowNodeIssueMarker
-            errors={counts.errors}
-            warnings={counts.warnings}
-          />
-          {agentHasUnpinnedModel(node) && (
-            // A note, not a problem: a muted glyph of its own, so it never
-            // reads as a warning the count beside it leaves out.
-            <>
-              <PinOff
-                data-slot="unpinned-model"
-                className="text-muted-foreground size-3.5"
-                aria-hidden="true"
-              />
-              <span className="sr-only">{t('canvas.unpinnedModel')}</span>
-            </>
-          )}
-          <Badge variant="slate">{node.type}</Badge>
-        </span>
-      </span>
-
-      {sources.length > 0 && (
-        <span className="text-muted-foreground mt-1 block truncate text-xs">
-          {t('canvas.readsFrom', {
-            nodes: sources.map(humanizeNodeId).join(', '),
-            count: sources.length,
-          })}
-        </span>
-      )}
-
-      {(badges.length > 0 || runStatus !== undefined) && (
-        <span className="mt-2 flex flex-wrap items-center gap-1">
-          {runStatus !== undefined && <RunStatusBadge status={runStatus} />}
-          {badges.map((badge) => (
-            <Badge key={badge.kind} variant="blue">
-              {badgeLabel(badge.kind, badge.value, badge.maxRepeats)}
-            </Badge>
-          ))}
-        </span>
-      )}
-      {issueText !== '' && <span className="sr-only"> {issueText}</span>}
-    </button>
-  );
-}
-
-/**
- * The React Flow adapter: it supplies the handles the derived edges attach to
- * and nothing else. The handles are never interactive — an edge exists because
- * one node references another, not because someone dragged a wire.
- */
-export function AutomationNode({ data }: NodeProps) {
-  const {
-    selectedNodeId,
-    inspectorId,
-    onSelect,
-    onFocusNode,
-    runStatusByNode,
-    incomingByNode,
-    issueCountsByNode,
-  } = useCanvasNode();
-  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the canvas builds every node's data itself
-  const { node } = data as AutomationNodeData;
-  const sources = (incomingByNode.get(node.id) ?? []).map(
-    (edge) => edge.source,
-  );
-
-  return (
-    <div className="relative">
-      <Handle
-        type="target"
-        position={Position.Top}
-        isConnectable={false}
-        className="!size-1 !border-0 !bg-transparent"
-        aria-hidden
-      />
-      <AutomationNodeBox
-        node={node}
-        selected={selectedNodeId === node.id}
-        inspectorId={inspectorId}
-        sources={sources}
-        runStatus={runStatusByNode.get(node.id)}
-        issueCounts={issueCountsByNode.get(node.id)}
-        onSelect={() => {
-          onSelect(selectedNodeId === node.id ? null : node.id);
-        }}
-        onFocus={() => {
-          onFocusNode(node.id);
-        }}
-      />
-      <Handle
-        type="source"
-        position={Position.Bottom}
-        isConnectable={false}
-        className="!size-1 !border-0 !bg-transparent"
-        aria-hidden
-      />
-    </div>
-  );
-}
diff --git a/services/platform/app/features/automations/components/automation-paths.tsx b/services/platform/app/features/automations/components/automation-paths.tsx
new file mode 100644
index 0000000000..849dfa40fe
--- /dev/null
+++ b/services/platform/app/features/automations/components/automation-paths.tsx
@@ -0,0 +1,207 @@
+'use client';
+
+import { Button } from '@tale/ui/button';
+import { Card } from '@tale/ui/card';
+import { cn } from '@tale/ui/cn';
+import { FlowPathList } from '@tale/ui/flow/flow-path-list';
+import { IconButton } from '@tale/ui/icon-button';
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogDescription,
+  ResponsiveDialogTitle,
+} from '@tale/ui/responsive-dialog';
+import { Route, X } from 'lucide-react';
+import { useId } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+import type { AutomationPaths, PathRowInfo } from '../lib/paths';
+
+/**
+ * The possible paths, beside the chart they light up.
+ *
+ * A Paths button among the canvas's verbs opens the list: on a wide screen
+ * as a panel under the view switch, which stays open while the reader
+ * clicks nodes (a popover would close exactly when exploring needs it), on
+ * a narrow one as a sheet. Pointing at or focusing a path previews it,
+ * Enter or a click pins it; in the sheet a pin closes the sheet and leaves
+ * a pill on the canvas that says which path is shown, with Show all.
+ */
+
+interface PathListProps {
+  paths: AutomationPaths;
+  previewId: string | null;
+  pinnedId: string | null;
+  onPreview: (id: string | null) => void;
+  onPin: (id: string | null) => void;
+  /** A halting node was chosen: select it. */
+  onActivate: (nodeId: string) => void;
+}
+
+function PathList({
+  paths,
+  previewId,
+  pinnedId,
+  onPreview,
+  onPin,
+  onActivate,
+}: PathListProps) {
+  const { t } = useT('automations');
+  return (
+    <FlowPathList
+      aria-label={t('paths.title')}
+      sections={paths.sections}
+      previewId={previewId}
+      pinnedId={pinnedId}
+      onPreview={onPreview}
+      onPin={onPin}
+      onActivate={(rowId) => {
+        const nodeId = paths.haltNode(rowId);
+        if (nodeId !== null) onActivate(nodeId);
+      }}
+    />
+  );
+}
+
+/** The canvas's Paths verb: how many ways a run can go. */
+export function AutomationPathsButton({
+  count,
+  open,
+  controls,
+  onToggle,
+}: {
+  count: number;
+  open: boolean;
+  /** The panel's id while it is open. */
+  controls: string | undefined;
+  onToggle: () => void;
+}) {
+  const { t } = useT('automations');
+  return (
+    <Button
+      type="button"
+      variant="secondary"
+      size="sm"
+      icon={Route}
+      collapseLabel
+      aria-expanded={open}
+      aria-controls={controls}
+      onClick={onToggle}
+    >
+      {t('paths.button', { count })}
+    </Button>
+  );
+}
+
+/** The list as a panel inside the canvas, for a wide screen. */
+export function AutomationPathsPanel({
+  id,
+  onClose,
+  ...list
+}: PathListProps & { id: string; onClose: () => void }) {
+  const { t } = useT('automations');
+  const { t: tCommon } = useT('common');
+  const titleId = useId();
+  return (
+    <Card
+      asChild
+      padding="none"
+      // `nowheel`/`nopan`: scrolling the list never zooms or moves the
+      // chart behind it.
+      className={cn(
+        'nowheel nopan flex max-h-[45vh] w-80 max-w-[calc(100vw-2rem)] flex-col overflow-hidden shadow-md',
+        'animate-in fade-in slide-in-from-top-1 duration-[var(--duration-standard)] ease-[var(--ease-out-quint)] motion-reduce:animate-none',
+      )}
+    >
+      <section id={id} aria-labelledby={titleId}>
+        <header className="flex items-start gap-2 px-3 pt-3 pb-2">
+          <div className="flex min-w-0 flex-1 flex-col gap-1">
+            <h2 id={titleId} className="text-sm font-medium">
+              {t('paths.title')}
+            </h2>
+            <p className="text-muted-foreground text-xs">
+              {t('paths.description')}
+            </p>
+          </div>
+          <IconButton
+            icon={X}
+            size="sm"
+            aria-label={tCommon('actions.close')}
+            onClick={onClose}
+          />
+        </header>
+        <div className="overflow-y-auto pb-2">
+          <PathList {...list} />
+        </div>
+      </section>
+    </Card>
+  );
+}
+
+/** The list in a sheet, for a narrow screen: a pin closes it. */
+export function AutomationPathsSheet({
+  open,
+  onOpenChange,
+  onPin,
+  onActivate,
+  ...list
+}: PathListProps & {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const { t } = useT('automations');
+  return (
+    <ResponsiveDialog open={open} onOpenChange={onOpenChange}>
+      <ResponsiveDialogContent className="flex flex-col gap-3">
+        <ResponsiveDialogTitle>{t('paths.title')}</ResponsiveDialogTitle>
+        <ResponsiveDialogDescription>
+          {t('paths.description')}
+        </ResponsiveDialogDescription>
+        <PathList
+          {...list}
+          onPin={(id) => {
+            onPin(id);
+            if (id !== null) onOpenChange(false);
+          }}
+          onActivate={(nodeId) => {
+            onOpenChange(false);
+            onActivate(nodeId);
+          }}
+        />
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  );
+}
+
+/** Which path the chart shows, once the sheet has closed on it. */
+export function AutomationPathsPill({
+  info,
+  onShowAll,
+}: {
+  info: PathRowInfo;
+  onShowAll: () => void;
+}) {
+  const { t } = useT('automations');
+  const { t: tFlow } = useT('flow');
+  return (
+    <div className="bg-background border-border animate-in fade-in flex h-8 items-center gap-2 rounded-full border pr-1 pl-3 text-xs shadow-sm duration-[var(--duration-short)] motion-reduce:animate-none">
+      <span className="truncate">
+        {t('paths.pill', {
+          index: info.index,
+          ran: info.ran,
+          total: info.total,
+        })}
+      </span>
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        className="h-6 rounded-full px-2"
+        onClick={onShowAll}
+      >
+        {tFlow('paths.showAll')}
+      </Button>
+    </div>
+  );
+}
diff --git a/services/platform/app/features/automations/components/coding-agent-entry.test.tsx b/services/platform/app/features/automations/components/coding-agent-entry.test.tsx
new file mode 100644
index 0000000000..84e854211f
--- /dev/null
+++ b/services/platform/app/features/automations/components/coding-agent-entry.test.tsx
@@ -0,0 +1,93 @@
+import type { AnchorHTMLAttributes } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen, within } from '@/tests/utils/render';
+
+interface MockLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  to?: string;
+  params?: Record<string, string>;
+}
+
+vi.mock('@tanstack/react-router', async () => {
+  const { forwardRef } = await import('react');
+  return {
+    Link: forwardRef<HTMLAnchorElement, MockLinkProps>(function Link(
+      { to, params, children, ...rest },
+      ref,
+    ) {
+      const href = Object.entries(params ?? {}).reduce(
+        (path, [key, value]) => path.replace(`$${key}`, value),
+        to ?? '#',
+      );
+      return (
+        <a ref={ref} href={href} {...rest}>
+          {children}
+        </a>
+      );
+    }),
+  };
+});
+
+import { CodingAgentButton } from './coding-agent-entry';
+
+/**
+ * An automation changes through a coding agent connected to Tale's MCP
+ * server; the canvas only takes small field edits. The entry says so and
+ * hands the reader what an agent needs: the automation's name, the way to
+ * set up MCP and the guide.
+ */
+describe('CodingAgentButton', () => {
+  it('opens the way to edit with a coding agent', async () => {
+    const { user } = render(
+      <CodingAgentButton
+        organizationId="org-1"
+        automationSlug="support/triage-inbox"
+      />,
+    );
+    const button = screen.getByRole('button', {
+      name: 'Edit with your coding agent',
+    });
+    expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+    await user.click(button);
+
+    const dialog = await screen.findByRole('dialog', {
+      name: 'Edit with your coding agent',
+    });
+    expect(dialog).toHaveAccessibleDescription(
+      /^Coding agents such as Claude Code, Codex and Cursor change automations through Tale's MCP server\./,
+    );
+    // The name to hand the agent, copied with one press.
+    expect(
+      within(dialog).getByRole('button', {
+        name: 'Name of this automation support/triage-inbox',
+      }),
+    ).toBeVisible();
+    expect(
+      within(dialog).getByRole('link', { name: 'Set up MCP' }),
+    ).toHaveAttribute('href', '/dashboard/org-1/settings/api/mcp');
+    const guide = within(dialog).getByRole('link', {
+      name: 'How to connect a coding agent',
+    });
+    expect(guide.getAttribute('href')).toMatch(/\/develop\/mcp-endpoint$/);
+    expect(guide).toHaveAttribute('target', '_blank');
+    await checkAccessibility(dialog);
+  });
+
+  it('is the main action of an empty automation', () => {
+    render(
+      <CodingAgentButton
+        organizationId="org-1"
+        automationSlug="support/triage-inbox"
+        variant="primary"
+      />,
+    );
+    const button = screen.getByRole('button', {
+      name: 'Edit with your coding agent',
+    });
+    // The label stays visible: on an empty canvas it is the one action.
+    expect(
+      within(button).getByText('Edit with your coding agent'),
+    ).not.toHaveClass('sr-only');
+  });
+});
diff --git a/services/platform/app/features/automations/components/coding-agent-entry.tsx b/services/platform/app/features/automations/components/coding-agent-entry.tsx
new file mode 100644
index 0000000000..66a23b6d77
--- /dev/null
+++ b/services/platform/app/features/automations/components/coding-agent-entry.tsx
@@ -0,0 +1,111 @@
+'use client';
+
+import { Button, buttonVariants } from '@tale/ui/button';
+import { CopyableField } from '@tale/ui/copyable-field';
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogDescription,
+  ResponsiveDialogTitle,
+} from '@tale/ui/responsive-dialog';
+import { TALE_DOCS_URL } from '@tale/ui/seo/globals';
+import { Link } from '@tanstack/react-router';
+import { BookOpen, Bot, PlugZap } from 'lucide-react';
+import { useState } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+/**
+ * The way to change an automation: a coding agent (Claude Code, Codex,
+ * Cursor) connected to Tale's MCP server reads it, changes it, checks it and
+ * saves a new version, which the editor then shows. The canvas is not where
+ * an automation is built; its fields take small edits.
+ *
+ * `CodingAgentButton` opens `CodingAgentDialog`: the automation's name to
+ * hand the agent, the way to set up MCP, and the guide to connecting one.
+ * It sits last among the canvas's own verbs and is the first action of an
+ * empty automation.
+ */
+export function CodingAgentButton({
+  organizationId,
+  automationSlug,
+  variant = 'toolbar',
+}: {
+  organizationId: string;
+  automationSlug: string;
+  /** `toolbar`: a secondary button that keeps only its icon on a phone;
+   *  `primary`: the main action of an empty automation. */
+  variant?: 'toolbar' | 'primary';
+}) {
+  const { t } = useT('automations');
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button
+        type="button"
+        variant={variant === 'primary' ? 'primary' : 'secondary'}
+        size={variant === 'primary' ? 'default' : 'sm'}
+        icon={Bot}
+        collapseLabel={variant === 'toolbar'}
+        aria-haspopup="dialog"
+        onClick={() => setOpen(true)}
+      >
+        {t('codingAgent.button')}
+      </Button>
+      <CodingAgentDialog
+        open={open}
+        onOpenChange={setOpen}
+        organizationId={organizationId}
+        automationSlug={automationSlug}
+      />
+    </>
+  );
+}
+
+function CodingAgentDialog({
+  open,
+  onOpenChange,
+  organizationId,
+  automationSlug,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  organizationId: string;
+  automationSlug: string;
+}) {
+  const { t } = useT('automations');
+  return (
+    <ResponsiveDialog open={open} onOpenChange={onOpenChange}>
+      <ResponsiveDialogContent className="flex flex-col gap-4">
+        <ResponsiveDialogTitle>{t('codingAgent.button')}</ResponsiveDialogTitle>
+        <ResponsiveDialogDescription>
+          {t('codingAgent.body')}
+        </ResponsiveDialogDescription>
+        <CopyableField
+          label={t('codingAgent.nameLabel')}
+          value={automationSlug}
+          mono
+        />
+        <div className="flex flex-wrap gap-2">
+          <Link
+            to="/dashboard/$id/settings/api/mcp"
+            params={{ id: organizationId }}
+            className={buttonVariants({ variant: 'secondary', size: 'sm' })}
+          >
+            <PlugZap className="mr-2 size-4" aria-hidden="true" />
+            {t('codingAgent.setUp')}
+          </Link>
+          <a
+            href={`${TALE_DOCS_URL}/develop/mcp-endpoint`}
+            target="_blank"
+            rel="noopener noreferrer"
+            className={buttonVariants({ variant: 'secondary', size: 'sm' })}
+          >
+            <BookOpen className="mr-2 size-4" aria-hidden="true" />
+            {t('codingAgent.learnMore')}
+          </a>
+        </div>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  );
+}
diff --git a/services/platform/app/features/automations/components/run-detail.test.tsx b/services/platform/app/features/automations/components/run-detail.test.tsx
index effa589d56..3ae301887e 100644
--- a/services/platform/app/features/automations/components/run-detail.test.tsx
+++ b/services/platform/app/features/automations/components/run-detail.test.tsx
@@ -143,16 +143,30 @@ vi.mock('@/app/hooks/use-current-member-context', () => ({
 }));
 vi.mock('./automation-canvas', () => ({
   AutomationCanvas: ({
-    graph,
-    runStatusByNode,
+    automation,
+    layoutKey,
+    revealId,
+    run,
   }: {
-    graph: { nodes: Array<{ id: string; type: string }> };
-    runStatusByNode: ReadonlyMap<string, string>;
+    automation: { nodes: Array<{ id: string; type: string }> };
+    layoutKey: string;
+    revealId?: string | null;
+    run?: {
+      statusByNode: ReadonlyMap<string, string>;
+      status: string;
+      startedBy?: string;
+    };
   }) => (
-    <ul data-testid="canvas">
-      {graph.nodes.map((node) => (
+    <ul
+      data-testid="canvas"
+      data-layout-key={layoutKey}
+      data-reveal-id={revealId ?? undefined}
+      data-run-status={run?.status}
+      data-started-by={run?.startedBy}
+    >
+      {automation.nodes.map((node) => (
         <li key={node.id}>
-          {node.id} ({node.type}): {runStatusByNode.get(node.id)}
+          {node.id} ({node.type}): {run?.statusByNode.get(node.id)}
         </li>
       ))}
     </ul>
@@ -963,7 +977,10 @@ describe('RunDetail without a version document', () => {
     state.trace = [{ node: 'draft', type: 'llm', status: 'ok' }];
     state.versionError = new Error('network down');
     renderRun();
-    expect(screen.getByTestId('canvas')).not.toHaveTextContent('draft');
+    expect(screen.queryByTestId('canvas')).toBeNull();
+    // The failure says itself where the chart would be.
+    expect(screen.getByText("Couldn't load the automation")).toBeVisible();
+    expect(screen.getByText('network down')).toBeVisible();
   });
 
   it('prefers the version document when it exists', () => {
@@ -1001,3 +1018,66 @@ it('renders a quarantine without acting on a retained approval or pretending to
   expect(screen.queryByText('Interrupted — resuming')).toBeNull();
   expect(readApproval).not.toHaveBeenCalled();
 });
+
+describe('RunDetail canvas', () => {
+  it('opens a failed run on its failure', () => {
+    state.status = 'failed';
+    state.finishedAt = 1789363170729;
+    state.detail = null;
+    state.waitingFor = undefined;
+    state.trace = [
+      { node: 'draft', type: 'llm', status: 'ok' },
+      {
+        node: 'send',
+        type: 'imap-smtp.send',
+        status: 'error',
+        error: 'SMTP refused',
+      },
+    ];
+    state.versionDocument = {
+      name: 'docs-approval-proof',
+      nodes: [
+        { id: 'draft', type: 'llm' },
+        {
+          id: 'send',
+          type: 'imap-smtp.send',
+          input: { body: '{{ nodes.draft.output }}' },
+        },
+        {
+          id: 'archive',
+          type: 'transform',
+          input: { sent: '{{ nodes.send.output }}' },
+          code: 'return input.sent;',
+        },
+      ],
+    };
+    renderRun();
+    const canvas = screen.getByTestId('canvas');
+    // The node that failed comes into view, with the run laid over it.
+    expect(canvas).toHaveAttribute('data-reveal-id', 'send');
+    expect(canvas).toHaveAttribute('data-run-status', 'failed');
+    expect(canvas).toHaveTextContent('send (imap-smtp.send): error');
+    expect(canvas).toHaveAttribute(
+      'data-layout-key',
+      expect.stringContaining(':run:'),
+    );
+  });
+
+  it('says on Start who started the run', () => {
+    state.status = 'success';
+    state.finishedAt = 1789363170729;
+    state.detail = null;
+    state.waitingFor = undefined;
+    state.startedBy = 'user:user-dana';
+    state.trace = [{ node: 'draft', type: 'llm', status: 'ok' }];
+    state.versionDocument = {
+      name: 'docs-approval-proof',
+      nodes: [{ id: 'draft', type: 'llm' }],
+    };
+    renderRun();
+    expect(screen.getByTestId('canvas')).toHaveAttribute(
+      'data-started-by',
+      expect.stringContaining('Dana K.'),
+    );
+  });
+});
diff --git a/services/platform/app/features/automations/components/run-detail.tsx b/services/platform/app/features/automations/components/run-detail.tsx
index becda333bf..22b1ff2651 100644
--- a/services/platform/app/features/automations/components/run-detail.tsx
+++ b/services/platform/app/features/automations/components/run-detail.tsx
@@ -31,10 +31,11 @@ import {
 } from '../hooks/queries';
 import { focusAutomationNode } from '../hooks/use-deselect-on-escape';
 import { useRunStarterLabel } from '../hooks/use-run-starter-label';
-import { readDocument, readPositions } from '../lib/document';
+import { readDocument } from '../lib/document';
 import { automationErrorMessage, isMissingAutomationRead } from '../lib/errors';
-import { buildGraph } from '../lib/graph';
+import { flowGraphTarget } from '../lib/flow-ids';
 import { issueImportResultSchema, issueSource } from '../lib/issue-import';
+import { nodeCatalogView } from '../lib/node-face';
 import {
   cursorNodeStatus,
   isRunFinished,
@@ -52,7 +53,7 @@ import {
   AUTOMATION_WORKBENCH_INSPECTOR_COLUMNS,
 } from '../lib/workbench';
 import { AgentExecutionLog } from './agent-execution-log';
-import { AutomationCanvas } from './automation-canvas';
+import { AutomationCanvas, type CanvasRun } from './automation-canvas';
 import { EffectList } from './effect-list';
 import { IssueImportContinuation } from './issue-import-continuation';
 import { IssueImportResult } from './issue-import-result';
@@ -182,22 +183,56 @@ function RunDetailBody({
     automationSlug,
     locale,
   );
-  const graph = useMemo(() => buildGraph(automation), [automation]);
-  const positions = useMemo(() => readPositions(automation), [automation]);
   const runStatusByNode = useMemo(
     () =>
       nodeStatusMap(
         projection,
-        graph.nodes.map((node) => node.id),
+        (automation?.nodes ?? []).map((node) => node.id),
         readRunCursorNode(run),
         cursorNodeStatus(run),
       ),
-    [graph.nodes, projection, run],
+    [automation?.nodes, projection, run],
   );
   const nodeTypes = useMemo(
     () => mergeNodeTypes(catalogQuery.data?.nodeTypes),
     [catalogQuery.data?.nodeTypes],
   );
+  const catalog = useMemo(
+    () => nodeCatalogView(nodeTypes, catalogQuery.data?.connectors ?? []),
+    [nodeTypes, catalogQuery.data?.connectors],
+  );
+  const canvasRun = useMemo<CanvasRun | null>(
+    () =>
+      run === null
+        ? null
+        : {
+            statusByNode: runStatusByNode,
+            projection,
+            status: readRunStatus(run.status),
+            startedBy: starterLabel(run),
+          },
+    [run, runStatusByNode, projection, starterLabel],
+  );
+  // A failed run opens on its failure: the node that failed comes into
+  // view, and the way the run took to it stands out.
+  const failedNode = useMemo(
+    () =>
+      [...runStatusByNode].find(([, status]) => status === 'error')?.[0] ??
+      null,
+    [runStatusByNode],
+  );
+  /** A condition opens its node; Start and End have no inspector of their
+   * own yet. */
+  const selectOnCanvas = useCallback((id: string | null) => {
+    if (id === null) {
+      setSelectedNodeId(null);
+      return;
+    }
+    const target = flowGraphTarget(id);
+    if (target.kind === 'node' || target.kind === 'gate') {
+      setSelectedNodeId(target.nodeId);
+    }
+  }, []);
 
   const runMissing = isMissingAutomationRead({
     data: runQuery.data,
@@ -244,7 +279,7 @@ function RunDetailBody({
 
   const status = readRunStatus(run.status);
   const selectedNode =
-    graph.nodes.find((node) => node.id === selectedNodeId) ?? null;
+    automation?.nodes.find((node) => node.id === selectedNodeId) ?? null;
   const issueImport =
     issueSource(automationSlug) === null
       ? null
@@ -453,14 +488,28 @@ function RunDetailBody({
         )}
       >
         <div className={AUTOMATION_WORKBENCH_CANVAS_SLOT}>
-          <AutomationCanvas
-            graph={graph}
-            positions={positions}
-            selectedNodeId={selectedNodeId}
-            onSelectNode={setSelectedNodeId}
-            inspectorId={inspectorId}
-            runStatusByNode={runStatusByNode}
-          />
+          {automation !== null ? (
+            <AutomationCanvas
+              automation={automation}
+              layoutKey={`${automationSlug}:run:${runId}`}
+              catalog={catalog}
+              selectedId={selectedNodeId}
+              onSelect={selectOnCanvas}
+              revealId={selectedNodeId ?? failedNode}
+              inspectorId={inspectorId}
+              {...(canvasRun !== null && { run: canvasRun })}
+            />
+          ) : (
+            versionQuery.isError && (
+              // The version read failed for now (not a deleted automation,
+              // which draws the trace): say so where the chart would be.
+              <Alert
+                variant="destructive"
+                title={t('detail.loadFailed.title')}
+                description={automationErrorMessage(versionQuery.error)}
+              />
+            )
+          )}
         </div>
         {selectedNode !== null && (
           <NodeInspector
diff --git a/services/platform/app/features/automations/hooks/use-canvas-flow.ts b/services/platform/app/features/automations/hooks/use-canvas-flow.ts
new file mode 100644
index 0000000000..baac6ea874
--- /dev/null
+++ b/services/platform/app/features/automations/hooks/use-canvas-flow.ts
@@ -0,0 +1,131 @@
+'use client';
+
+import type { FlowRow } from '@tale/ui/flow/types';
+import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { useMemo } from 'react';
+
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
+import type { Automation } from '@/lib/engine/core/types';
+import { useT } from '@/lib/i18n/client';
+import type {
+  AnalysisView,
+  TypesView,
+} from '@/lib/shared/schemas/automation-issues';
+
+import { toFlowGraph, type AutomationFlowGraph } from '../lib/flow-graph';
+import type { NodeCatalogView, ReturnsSource } from '../lib/node-face';
+import { automationPaths, type AutomationPaths } from '../lib/paths';
+
+export interface CanvasFlowInput {
+  automation: Automation;
+  catalog: NodeCatalogView;
+  modelLabel?: (id: string) => string | undefined;
+  /** Start's trigger rows. */
+  triggers: readonly FlowRow[];
+  /** What the draft check answered, for the reader who may have one. */
+  check: {
+    status: ReturnsSource['status'];
+    analysis: AnalysisView | null;
+    types: TypesView | null;
+  };
+  startNotice?: string | null;
+  /** The pinned path's row: End then says what it leaves empty. */
+  pinnedPath?: string | null;
+}
+
+export interface CanvasFlow extends AutomationFlowGraph {
+  /** The Paths list and highlights; null on a reference cycle. */
+  paths: AutomationPaths | null;
+}
+
+/**
+ * The canvas's picture of one document: the graph it draws, the flow
+ * analysis behind its conditions and paths, and the Paths list — each
+ * worked out once per document and language, in the browser, so every
+ * viewer of every version has them at once. The draft check's answer only
+ * adds what it alone knows: the shapes each node returns and why a node
+ * can fail.
+ */
+export function useCanvasFlow({
+  automation,
+  catalog,
+  modelLabel,
+  triggers,
+  check,
+  startNotice,
+  pinnedPath,
+}: CanvasFlowInput): CanvasFlow {
+  const { t } = useT('automations');
+  const { t: tSchema } = useT('schemaTree');
+  const { locale } = useLocale();
+  const { nodes } = automation;
+  const flow = useMemo(() => analyzeFlow(nodes), [nodes]);
+  const outputs = useMemo(
+    () =>
+      check.types === null
+        ? null
+        : Object.fromEntries(
+            Object.entries(check.types.nodes).map(([id, info]) => [
+              id,
+              info.output,
+            ]),
+          ),
+    [check.types],
+  );
+  const context = useMemo(
+    () => ({
+      t,
+      tSchema,
+      locale,
+      catalog,
+      ...(modelLabel !== undefined && { modelLabel }),
+      returns: { status: check.status, outputs },
+      triggers,
+      flow,
+      outputShape: check.types?.output ?? null,
+      startNotice: startNotice ?? null,
+    }),
+    [
+      t,
+      tSchema,
+      locale,
+      catalog,
+      modelLabel,
+      check.status,
+      outputs,
+      triggers,
+      flow,
+      check.types,
+      startNotice,
+    ],
+  );
+  const base = useMemo(
+    () => toFlowGraph(automation, context),
+    [automation, context],
+  );
+  const paths = useMemo(() => {
+    if (flow === null || base.hasCycle) return null;
+    const byId = new Map(automation.nodes.map((node) => [node.id, node]));
+    return automationPaths(flow, base.graph, {
+      t,
+      locale,
+      elseOf: (id) => byId.get(id)?.elseOf,
+      ...(check.analysis !== null && { halts: check.analysis.paths.halts }),
+    });
+  }, [flow, base, automation.nodes, t, locale, check.analysis]);
+  const ranOnPath = useMemo(
+    () =>
+      pinnedPath === undefined || pinnedPath === null
+        ? null
+        : (paths?.ranOn(pinnedPath) ?? null),
+    [paths, pinnedPath],
+  );
+  const shown = useMemo(
+    () =>
+      ranOnPath === null
+        ? base
+        : toFlowGraph(automation, { ...context, ranOnPath }),
+    [ranOnPath, base, automation, context],
+  );
+  return { ...shown, paths };
+}
diff --git a/services/platform/app/features/automations/hooks/use-deselect-on-escape.ts b/services/platform/app/features/automations/hooks/use-deselect-on-escape.ts
index 75fef904b3..45ef98cdcb 100644
--- a/services/platform/app/features/automations/hooks/use-deselect-on-escape.ts
+++ b/services/platform/app/features/automations/hooks/use-deselect-on-escape.ts
@@ -2,8 +2,10 @@
 
 import { useEffect } from 'react';
 
-/** Marks a canvas node button so focus can return there after the inspector closes. */
-const AUTOMATION_NODE_ATTR = 'data-automation-node';
+/** Marks a canvas node button (the flow canvas's own attribute: a node's,
+ * a condition's, Start's or End's id) so focus can return there after the
+ * inspector closes. */
+const AUTOMATION_NODE_ATTR = 'data-flow-node';
 
 export function isTypingTarget(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) return false;
@@ -13,18 +15,13 @@ export function isTypingTarget(target: EventTarget | null): boolean {
   return target.closest('[contenteditable="true"]') !== null;
 }
 
-/** The canvas button of one node, looked up inside `root`. */
-export function automationNodeElement(
-  nodeId: string,
-  root: ParentNode = document,
-): HTMLElement | null {
-  return root.querySelector<HTMLElement>(
-    `[${AUTOMATION_NODE_ATTR}="${CSS.escape(nodeId)}"]`,
-  );
-}
-
+/** Moves focus to the canvas button of one node. */
 export function focusAutomationNode(nodeId: string): void {
-  automationNodeElement(nodeId)?.focus();
+  document
+    .querySelector<HTMLElement>(
+      `[${AUTOMATION_NODE_ATTR}="${CSS.escape(nodeId)}"]`,
+    )
+    ?.focus();
 }
 
 /**
diff --git a/services/platform/app/features/automations/lib/condition-text.test.ts b/services/platform/app/features/automations/lib/condition-text.test.ts
new file mode 100644
index 0000000000..9ecaeb6272
--- /dev/null
+++ b/services/platform/app/features/automations/lib/condition-text.test.ts
@@ -0,0 +1,177 @@
+import { loadLocale } from '@tale/ui/i18n/load-locale';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import {
+  conditionText,
+  describeCondition,
+  describeList,
+  type ConditionTextContext,
+} from './condition-text';
+import { nodeTitle } from './node-face';
+
+/**
+ * Conditions in words, in every language the app ships, with the real
+ * catalogs: each recognised shape, the ones that stay code, and the German
+ * word order — every German phrase completes "wenn …", so its verb comes
+ * last.
+ */
+
+beforeAll(async () => {
+  await loadLocale(i18n, 'de-CH');
+});
+
+function ctx(locale: string): ConditionTextContext {
+  return {
+    t: i18n.getFixedT(locale, 'automations'),
+    locale,
+    nodeLabel: nodeTitle,
+  };
+}
+
+const say = (text: string, locale = 'en') => conditionText(text, ctx(locale));
+
+describe('conditionText', () => {
+  it.each([
+    [
+      '{{ nodes.score.output.total > 1000 }}',
+      'total of Score is greater than 1,000',
+    ],
+    ['{{ nodes.score.output.total >= 3 }}', 'total of Score is at least 3'],
+    [
+      '{{ nodes.score.output.total < input.limit }}',
+      'total of Score is less than limit of the run input',
+    ],
+    ['{{ nodes.score.output.total <= 0 }}', 'total of Score is at most 0'],
+    [
+      '{{ nodes.classify.output.status === "done" }}',
+      'status of Classify is "done"',
+    ],
+    ['{{ item.state != "open" }}', 'state of the item is not "open"'],
+    [
+      '{{ nodes.inbox.output.items.length > 0 }}',
+      'items of Inbox is not empty',
+    ],
+    ['{{ nodes.inbox.output.items.length === 0 }}', 'items of Inbox is empty'],
+    ['{{ !nodes.inbox.output.items?.length }}', 'items of Inbox is empty'],
+    ['{{ nodes.inbox.output.items.length }}', 'items of Inbox is not empty'],
+    [
+      '{{ nodes.inbox.output.items.length > 3 }}',
+      'the number of items of Inbox is greater than 3',
+    ],
+    ['{{ input.notify }}', 'notify of the run input is set'],
+    ['{{ !!input.notify }}', 'notify of the run input is set'],
+    ['{{ Boolean(input.notify) }}', 'notify of the run input is set'],
+    ['{{ !input.notify }}', 'notify of the run input is not set'],
+    [
+      '{{ nodes.issue.output.labels.includes("bug") }}',
+      'labels of Issue contains "bug"',
+    ],
+    [
+      '{{ !nodes.issue.output.labels.includes("bug") }}',
+      'labels of Issue doesn\'t contain "bug"',
+    ],
+    [
+      '{{ item.title.startsWith("RFC") }}',
+      'title of the item starts with "RFC"',
+    ],
+    ['{{ item.title.endsWith("?") }}', 'title of the item ends with "?"'],
+    ['{{ output.done === true }}', "done of this pass's result is true"],
+    ['{{ index > 2 }}', "the item's position is greater than 2"],
+    ['{{ nodes.check.output === null }}', 'the output of Check is empty'],
+    ['{{ nodes.check.output?.ok ?? false }}', 'ok of Check is set'],
+    [
+      '{{ (input.a > 1) && input.b }}',
+      'a of the run input is greater than 1 and b of the run input is set',
+    ],
+    [
+      '{{ input.a || input.b || input.c }}',
+      'a of the run input is set, b of the run input is set, or c of the run input is set',
+    ],
+    ['nodes.check.output.ok', 'ok of Check is set'],
+  ])('says %s', (text, words) => {
+    expect(say(text)).toBe(words);
+  });
+
+  it.each([
+    ['{{ input.a && input.b && input.c && input.d }}'],
+    ['{{ input.a && (input.b || (input.c && input.d)) }}'],
+    ['{{ nodes.a.output.n * 2 > 3 }}'],
+    ['{{ input.list.some((x) => x.ok) }}'],
+    ['Ready: {{ input.ok }}'],
+    ['{{ true }}'],
+    ['{{ nodes[input.name].output }}'],
+    ['{{ input.a > }}'],
+  ])('keeps %s as code', (text) => {
+    expect(say(text)).toBeNull();
+  });
+
+  it('says German verb last, after "wenn"', () => {
+    expect(say('{{ nodes.score.output.total > 1000 }}', 'de')).toBe(
+      'total von Score größer als 1.000 ist',
+    );
+    expect(say('{{ nodes.issue.output.labels.includes("bug") }}', 'de')).toBe(
+      'labels von Issue „bug“ enthält',
+    );
+    expect(say('{{ input.a > 1 && input.b }}', 'de')).toBe(
+      'a der Laufeingabe größer als 1 ist und b der Laufeingabe gesetzt ist',
+    );
+  });
+
+  it('says French with its own spacing and quotes', () => {
+    expect(say('{{ nodes.classify.output.status === "done" }}', 'fr')).toBe(
+      'status de Classify vaut «\u00a0done\u00a0»',
+    );
+    expect(say('{{ nodes.inbox.output.items.length === 0 }}', 'fr')).toBe(
+      'items de Inbox est vide',
+    );
+  });
+
+  it('writes Swiss German without ß and with its own quotes', () => {
+    expect(say('{{ nodes.score.output.total > 1000 }}', 'de-CH')).toBe(
+      'total von Score grösser als 1’000 ist',
+    );
+    expect(say('{{ item.state === "open" }}', 'de-CH')).toBe(
+      'state des Elements gleich «open» ist',
+    );
+  });
+});
+
+describe('describeCondition', () => {
+  it('keeps where each operand sits in the field', () => {
+    const text = '{{ nodes.score.output.total > 1000 }}';
+    const phrase = describeCondition(text);
+    expect(phrase.kind).toBe('compare');
+    if (phrase.kind !== 'compare') return;
+    expect(text.slice(...phrase.a.range)).toBe('nodes.score.output.total');
+    expect(text.slice(...phrase.b.range)).toBe('1000');
+  });
+
+  it('looks through ?? and parentheses', () => {
+    expect(
+      describeCondition('{{ (nodes.a.output.n ?? 0) > 1 }}'),
+    ).toMatchObject({
+      kind: 'compare',
+      op: 'gt',
+      a: { root: 'node', nodeId: 'a', path: ['n'] },
+    });
+  });
+});
+
+describe('describeList', () => {
+  it('reads a forEach that walks one list', () => {
+    expect(describeList('{{ nodes.open_issues.output.issues }}')).toMatchObject(
+      { kind: 'ref', root: 'node', nodeId: 'open_issues', path: ['issues'] },
+    );
+    expect(describeList('{{ input.items }}')).toMatchObject({
+      root: 'input',
+      path: ['items'],
+    });
+  });
+
+  it('gives up on anything else', () => {
+    expect(describeList('{{ input.items.filter((x) => x) }}')).toBeNull();
+    expect(describeList('items: {{ input.items }}')).toBeNull();
+  });
+});
diff --git a/services/platform/app/features/automations/lib/condition-text.ts b/services/platform/app/features/automations/lib/condition-text.ts
new file mode 100644
index 0000000000..72533fc204
--- /dev/null
+++ b/services/platform/app/features/automations/lib/condition-text.ts
@@ -0,0 +1,557 @@
+/**
+ * Conditions in words.
+ *
+ * A node's `when` and `repeatUntil` are JavaScript: `{{
+ * nodes.inbox.output.conversations.length > 0 }}`. The canvas says them the
+ * way a person would — "the number of conversations of Inbox is greater
+ * than 0" — so a reader can follow a chart without reading code. Only the
+ * shapes a condition is usually written in are described: comparisons,
+ * emptiness, truthiness, `includes`/`startsWith`/`endsWith`, and up to three
+ * of them joined with `&&` or `||`. Anything else stays code, and the canvas
+ * shows the expression itself.
+ *
+ * `describeCondition` parses once, with the engine's own parser, into a
+ * `Phrase` that keeps every operand's range in the field string — so a run
+ * view can later put the value each operand read beside its words.
+ * `renderCondition` turns a phrase into a sentence fragment in the
+ * session's language: every German template is written verb-last, because
+ * every use sits after "wenn" or "bis".
+ */
+
+import type { Node } from 'estree';
+
+import { parseExpressionIn } from '@/lib/engine/core/syntax/parse';
+import {
+  conditionKind,
+  exprSegments,
+  isSingleTemplate,
+  tokenizeTemplate,
+} from '@/lib/engine/core/syntax/tokens';
+import { renderPath } from '@/lib/engine/core/syntax/walk';
+
+/** What an operand reads: a node's output, the run input, the item a
+ *  forEach node is on, its position, or the result of a repeat's pass. */
+export type OperandRoot = 'node' | 'input' | 'item' | 'index' | 'output';
+
+export interface RefOperand {
+  kind: 'ref';
+  root: OperandRoot;
+  /** `root: 'node'`: the node read. */
+  nodeId?: string;
+  /** Keys after the root (after `.output` for a node). */
+  path: ReadonlyArray<string | number>;
+  /** Reads `.length` at the end: "the number of …". */
+  length?: true;
+  /** [start, end) in the field string. */
+  range: readonly [number, number];
+}
+
+export interface LiteralOperand {
+  kind: 'literal';
+  value: string | number | boolean | null;
+  range: readonly [number, number];
+}
+
+export type Operand = RefOperand | LiteralOperand;
+
+export type CompareOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq';
+
+export type Phrase =
+  | { kind: 'compare'; op: CompareOp; a: Operand; b: Operand }
+  | { kind: 'empty' | 'notEmpty' | 'set' | 'notSet'; a: Operand }
+  | {
+      kind: 'contains' | 'notContains' | 'startsWith' | 'endsWith';
+      a: Operand;
+      b: Operand;
+    }
+  | { kind: 'and' | 'or'; parts: readonly Phrase[] }
+  | { kind: 'raw' };
+
+const RAW: Phrase = { kind: 'raw' };
+
+/** At most this many conditions joined by one `&&` or `||`. */
+const MAX_PARTS = 3;
+/** `a && (b || c)` reads; one more level of grouping does not. */
+const MAX_GROUP_DEPTH = 2;
+
+const COMPARE_OPS: Readonly<Record<string, CompareOp>> = {
+  '>': 'gt',
+  '>=': 'gte',
+  '<': 'lt',
+  '<=': 'lte',
+  '===': 'eq',
+  '==': 'eq',
+  '!==': 'neq',
+  '!=': 'neq',
+};
+
+function rangeOf(node: Node): readonly [number, number] {
+  return node.range ?? [0, 0];
+}
+
+/** The expression inside the wrappers that do not change what a
+ *  condition means: an optional chain, `x ?? false|0|null`. */
+function unwrap(node: Node): Node {
+  let current = node;
+  for (;;) {
+    if (current.type === 'ChainExpression') {
+      current = current.expression;
+      continue;
+    }
+    if (
+      current.type === 'LogicalExpression' &&
+      current.operator === '??' &&
+      current.right.type === 'Literal' &&
+      (current.right.value === false ||
+        current.right.value === 0 ||
+        current.right.value === null)
+    ) {
+      current = current.left;
+      continue;
+    }
+    return current;
+  }
+}
+
+/** The keys of a member chain from its root identifier, or null when a
+ *  step is computed from something other than a literal. */
+function memberChain(
+  node: Node,
+): { root: string; keys: Array<string | number> } | null {
+  const keys: Array<string | number> = [];
+  let current: Node = unwrap(node);
+  while (current.type === 'MemberExpression') {
+    const { property } = current;
+    if (!current.computed && property.type === 'Identifier') {
+      keys.unshift(property.name);
+    } else if (
+      current.computed &&
+      property.type === 'Literal' &&
+      (typeof property.value === 'string' || typeof property.value === 'number')
+    ) {
+      keys.unshift(property.value);
+    } else {
+      return null;
+    }
+    if (current.object.type === 'Super') return null;
+    current =
+      current.object.type === 'ChainExpression'
+        ? current.object.expression
+        : current.object;
+  }
+  return current.type === 'Identifier' ? { root: current.name, keys } : null;
+}
+
+/** One operand: a literal, or a read of the automation's scope. */
+function operandOf(node: Node): Operand | null {
+  const inner = unwrap(node);
+  const range = rangeOf(node);
+  if (inner.type === 'Literal') {
+    const { value } = inner;
+    if (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      value === null
+    ) {
+      return { kind: 'literal', value, range };
+    }
+    return null;
+  }
+  if (inner.type === 'TemplateLiteral' && inner.expressions.length === 0) {
+    const text = inner.quasis[0]?.value.cooked;
+    return typeof text === 'string'
+      ? { kind: 'literal', value: text, range }
+      : null;
+  }
+  if (
+    inner.type === 'UnaryExpression' &&
+    inner.operator === '-' &&
+    inner.argument.type === 'Literal' &&
+    typeof inner.argument.value === 'number'
+  ) {
+    return { kind: 'literal', value: -inner.argument.value, range };
+  }
+  if (inner.type === 'Identifier' && inner.name === 'undefined') {
+    return { kind: 'literal', value: null, range };
+  }
+  const chain = memberChain(inner);
+  if (chain === null) return null;
+  let keys = chain.keys;
+  const length = keys.at(-1) === 'length';
+  if (length) keys = keys.slice(0, -1);
+  const withLength = length ? { length: true as const } : {};
+  switch (chain.root) {
+    case 'nodes': {
+      const [nodeId, output, ...path] = keys;
+      if (typeof nodeId !== 'string' || output !== 'output') return null;
+      return { kind: 'ref', root: 'node', nodeId, path, range, ...withLength };
+    }
+    case 'input':
+    case 'item':
+    case 'output':
+      return {
+        kind: 'ref',
+        root: chain.root,
+        path: keys,
+        range,
+        ...withLength,
+      };
+    case 'index':
+      return keys.length === 0 && !length
+        ? { kind: 'ref', root: 'index', path: [], range }
+        : null;
+    default:
+      return null;
+  }
+}
+
+/** `x.length` alone: the list or text whose length is read. */
+function lengthOf(node: Node): Operand | null {
+  const operand = operandOf(node);
+  if (operand?.kind !== 'ref' || operand.length !== true) return null;
+  const { length: _length, ...rest } = operand;
+  return rest;
+}
+
+/** Whether a `.length` compared with `literal` by `op` says "not empty"
+ *  (`true`), "empty" (`false`), or neither. */
+function emptiness(op: string, literal: Node): boolean | undefined {
+  if (literal.type !== 'Literal' || typeof literal.value !== 'number') {
+    return undefined;
+  }
+  const n = literal.value;
+  if ((op === '>' && n === 0) || (op === '>=' && n === 1)) return true;
+  if ((op === '!==' || op === '!=') && n === 0) return true;
+  if ((op === '===' || op === '==') && n === 0) return false;
+  if ((op === '<' && n === 1) || (op === '<=' && n === 0)) return false;
+  return undefined;
+}
+
+/** A value read for its truth: set, or (negated) not set. */
+function truth(node: Node, negated: boolean): Phrase {
+  const inner = unwrap(node);
+  const length = lengthOf(inner);
+  if (length !== null) {
+    return { kind: negated ? 'empty' : 'notEmpty', a: length };
+  }
+  if (inner.type === 'UnaryExpression' && inner.operator === '!') {
+    return truth(inner.argument, !negated);
+  }
+  const operand = operandOf(inner);
+  if (operand === null || operand.kind === 'literal') return RAW;
+  return { kind: negated ? 'notSet' : 'set', a: operand };
+}
+
+function phraseOf(node: Node, depth: number): Phrase {
+  const inner = unwrap(node);
+  switch (inner.type) {
+    case 'LogicalExpression': {
+      if (inner.operator === '??') return RAW;
+      if (depth >= MAX_GROUP_DEPTH) return RAW;
+      const operator = inner.operator;
+      const parts: Node[] = [];
+      const collect = (part: Node): void => {
+        const unwrapped = unwrap(part);
+        if (
+          unwrapped.type === 'LogicalExpression' &&
+          unwrapped.operator === operator
+        ) {
+          collect(unwrapped.left);
+          collect(unwrapped.right);
+        } else {
+          parts.push(part);
+        }
+      };
+      collect(inner);
+      if (parts.length > MAX_PARTS) return RAW;
+      const phrases = parts.map((part) => phraseOf(part, depth + 1));
+      if (phrases.some((phrase) => phrase.kind === 'raw')) return RAW;
+      return { kind: operator === '&&' ? 'and' : 'or', parts: phrases };
+    }
+    case 'UnaryExpression': {
+      if (inner.operator !== '!') return RAW;
+      const argument = unwrap(inner.argument);
+      if (argument.type === 'CallExpression') {
+        const call = callPhrase(argument);
+        return call?.kind === 'contains'
+          ? { ...call, kind: 'notContains' }
+          : RAW;
+      }
+      return truth(argument, true);
+    }
+    case 'CallExpression': {
+      if (
+        inner.callee.type === 'Identifier' &&
+        inner.callee.name === 'Boolean' &&
+        inner.arguments.length === 1 &&
+        inner.arguments[0]?.type !== 'SpreadElement'
+      ) {
+        const [argument] = inner.arguments;
+        return argument === undefined ? RAW : truth(argument, false);
+      }
+      return callPhrase(inner) ?? RAW;
+    }
+    case 'BinaryExpression': {
+      const op = COMPARE_OPS[inner.operator];
+      if (op === undefined || inner.left.type === 'PrivateIdentifier') {
+        return RAW;
+      }
+      const length = lengthOf(inner.left);
+      if (length !== null) {
+        const notEmpty = emptiness(inner.operator, inner.right);
+        if (notEmpty !== undefined) {
+          return { kind: notEmpty ? 'notEmpty' : 'empty', a: length };
+        }
+      }
+      const a = operandOf(inner.left);
+      const b = operandOf(inner.right);
+      if (a === null || b === null) return RAW;
+      return { kind: 'compare', op, a, b };
+    }
+    default:
+      return truth(inner, false);
+  }
+}
+
+/** `x.includes(v)`, `x.startsWith(v)`, `x.endsWith(v)`. */
+function callPhrase(node: Node): Phrase | null {
+  if (node.type !== 'CallExpression') return null;
+  const callee = unwrap(node.callee);
+  if (
+    callee.type !== 'MemberExpression' ||
+    callee.computed ||
+    callee.property.type !== 'Identifier' ||
+    callee.object.type === 'Super' ||
+    node.arguments.length !== 1
+  ) {
+    return null;
+  }
+  const [argument] = node.arguments;
+  if (argument === undefined || argument.type === 'SpreadElement') return null;
+  const kind =
+    callee.property.name === 'includes'
+      ? 'contains'
+      : callee.property.name === 'startsWith'
+        ? 'startsWith'
+        : callee.property.name === 'endsWith'
+          ? 'endsWith'
+          : null;
+  if (kind === null) return null;
+  const a = operandOf(callee.object);
+  const b = operandOf(argument);
+  if (a === null || b === null || a.kind !== 'ref') return null;
+  return { kind, a, b };
+}
+
+/** The one expression a field holds — bare, or one whole template — and
+ *  its range; null for text around templates. */
+function soleExpression(text: string): { start: number; end: number } | null {
+  const kind = conditionKind(text);
+  if (kind === 'mixed') return null;
+  if (kind === 'bare') {
+    const start = text.length - text.trimStart().length;
+    const end = text.trimEnd().length;
+    return end > start ? { start, end } : null;
+  }
+  const [segment] = exprSegments(tokenizeTemplate(text));
+  if (segment === undefined) return null;
+  const start = segment.exprStart ?? segment.start;
+  const end = segment.exprEnd ?? segment.end;
+  return end > start ? { start, end } : null;
+}
+
+/**
+ * The phrase a condition field says, or `raw` when it is not one of the
+ * shapes that read as words (or does not parse).
+ */
+export function describeCondition(text: string): Phrase {
+  const sole = soleExpression(text);
+  if (sole === null) return RAW;
+  const parsed = parseExpressionIn(text, sole.start, sole.end);
+  return parsed.ok ? phraseOf(parsed.ast, 0) : RAW;
+}
+
+/**
+ * What a `forEach` template walks, when it is one read of the scope
+ * (`{{ nodes.open_issues.output.issues }}`); null otherwise.
+ */
+export function describeList(text: string): Operand | null {
+  const tokens = tokenizeTemplate(text);
+  if (!isSingleTemplate(text, tokens)) return null;
+  const [segment] = exprSegments(tokens);
+  if (segment === undefined) return null;
+  const start = segment.exprStart ?? segment.start;
+  const end = segment.exprEnd ?? segment.end;
+  if (end <= start) return null;
+  const parsed = parseExpressionIn(text, start, end);
+  if (!parsed.ok) return null;
+  const operand = operandOf(parsed.ast);
+  return operand?.kind === 'ref' ? operand : null;
+}
+
+/** The translate function of the session's language, bound to the
+ *  `automations` namespace. */
+export type ConditionTranslate = (
+  key: string,
+  options?: Record<string, unknown>,
+) => string;
+
+export interface ConditionTextContext {
+  t: ConditionTranslate;
+  locale: string;
+  /** A node's name as the canvas shows it on its box. */
+  nodeLabel: (id: string) => string;
+}
+
+/** Keys as an author writes them, without a leading dot: `status.code`,
+ *  `items[0]`, `["odd key"]`. */
+function pathText(path: ReadonlyArray<string | number>): string {
+  const text = renderPath(path.map((key) => ({ key })));
+  return text.startsWith('.') ? text.slice(1) : text;
+}
+
+/** One operand in words: "issues of Open issues", "“done”", "250". */
+export function renderOperand(
+  operand: Operand,
+  ctx: ConditionTextContext,
+): string {
+  const { t } = ctx;
+  if (operand.kind === 'literal') {
+    const { value } = operand;
+    if (value === null) return t('condition.literal.valueNull');
+    if (typeof value === 'boolean') {
+      return value
+        ? t('condition.literal.valueTrue')
+        : t('condition.literal.valueFalse');
+    }
+    if (typeof value === 'number') {
+      return new Intl.NumberFormat(ctx.locale).format(value);
+    }
+    return t('condition.quote', { text: value });
+  }
+  const path = pathText(operand.path);
+  const whole = operand.path.length === 0;
+  let base: string;
+  switch (operand.root) {
+    case 'node': {
+      const node = ctx.nodeLabel(operand.nodeId ?? '');
+      base = whole
+        ? t('condition.ref.nodeOutput', { node })
+        : t('condition.ref.node', { path, node });
+      break;
+    }
+    case 'input':
+      base = whole
+        ? t('condition.ref.inputWhole')
+        : t('condition.ref.input', { path });
+      break;
+    case 'item':
+      base = whole
+        ? t('condition.ref.itemWhole')
+        : t('condition.ref.item', { path });
+      break;
+    case 'output':
+      base = whole
+        ? t('condition.ref.outputWhole')
+        : t('condition.ref.output', { path });
+      break;
+    case 'index':
+      base = t('condition.ref.index');
+      break;
+  }
+  return operand.length === true
+    ? t('condition.ref.length', { inner: base })
+    : base;
+}
+
+/** Two operands in words, as one condition fragment. */
+type PairWords = (
+  t: ConditionTranslate,
+  operands: { a: string; b: string },
+) => string;
+
+/** "{a} is greater than {b}", one key per operator. */
+const COMPARE_WORDS: Readonly<Record<CompareOp, PairWords>> = {
+  gt: (t, operands) => t('condition.gt', operands),
+  gte: (t, operands) => t('condition.gte', operands),
+  lt: (t, operands) => t('condition.lt', operands),
+  lte: (t, operands) => t('condition.lte', operands),
+  eq: (t, operands) => t('condition.eq', operands),
+  neq: (t, operands) => t('condition.neq', operands),
+};
+
+/** "{a} contains {b}" and the other text tests. */
+const TEXT_WORDS: Readonly<
+  Record<'contains' | 'notContains' | 'startsWith' | 'endsWith', PairWords>
+> = {
+  contains: (t, operands) => t('condition.contains', operands),
+  notContains: (t, operands) => t('condition.notContains', operands),
+  startsWith: (t, operands) => t('condition.startsWith', operands),
+  endsWith: (t, operands) => t('condition.endsWith', operands),
+};
+
+/** "{a} is empty", "{a} is set" and their opposites. */
+const STATE_WORDS: Readonly<
+  Record<
+    'empty' | 'notEmpty' | 'set' | 'notSet',
+    (t: ConditionTranslate, a: string) => string
+  >
+> = {
+  empty: (t, a) => t('condition.empty', { a }),
+  notEmpty: (t, a) => t('condition.notEmpty', { a }),
+  set: (t, a) => t('condition.set', { a }),
+  notSet: (t, a) => t('condition.notSet', { a }),
+};
+
+/**
+ * A phrase as a sentence fragment that completes "Runs only if …" ("…
+ * nur, wenn …", "… seulement si …"); null for a raw condition, which the
+ * canvas shows as code.
+ */
+export function renderCondition(
+  phrase: Phrase,
+  ctx: ConditionTextContext,
+): string | null {
+  const { t } = ctx;
+  switch (phrase.kind) {
+    case 'raw':
+      return null;
+    case 'and':
+    case 'or': {
+      const parts: string[] = [];
+      for (const part of phrase.parts) {
+        const text = renderCondition(part, ctx);
+        if (text === null) return null;
+        parts.push(text);
+      }
+      return new Intl.ListFormat(ctx.locale, {
+        type: phrase.kind === 'and' ? 'conjunction' : 'disjunction',
+      }).format(parts);
+    }
+    case 'compare':
+      return COMPARE_WORDS[phrase.op](t, {
+        a: renderOperand(phrase.a, ctx),
+        b: renderOperand(phrase.b, ctx),
+      });
+    case 'contains':
+    case 'notContains':
+    case 'startsWith':
+    case 'endsWith':
+      return TEXT_WORDS[phrase.kind](t, {
+        a: renderOperand(phrase.a, ctx),
+        b: renderOperand(phrase.b, ctx),
+      });
+    default:
+      // `empty`, `notEmpty`, `set`, `notSet`: one operand.
+      return STATE_WORDS[phrase.kind](t, renderOperand(phrase.a, ctx));
+  }
+}
+
+/** A condition field in words, or null when it reads only as code. */
+export function conditionText(
+  text: string,
+  ctx: ConditionTextContext,
+): string | null {
+  return renderCondition(describeCondition(text), ctx);
+}
diff --git a/services/platform/app/features/automations/lib/document.test.ts b/services/platform/app/features/automations/lib/document.test.ts
index 5c3083384e..2ba55b24c8 100644
--- a/services/platform/app/features/automations/lib/document.test.ts
+++ b/services/platform/app/features/automations/lib/document.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import { DOC_EXAMPLE } from '@/lib/engine/api/docs';
 
-import { readDocument, readPositions } from './document';
+import { readDocument } from './document';
 
 /**
  * A stored document arrives as `v.any()`. These tests pin the narrowing to the
@@ -100,18 +100,3 @@ describe('readDocument', () => {
     });
   });
 });
-
-describe('readPositions', () => {
-  it('reads hand-placed positions from the canvas metadata', () => {
-    const automation = readDocument({
-      name: 'a',
-      nodes: [{ id: 'n', type: 'transform', code: 'return 1;' }],
-      ui: { positions: { n: { x: 10, y: 20 }, bad: { x: 'left' } } },
-    });
-    expect(readPositions(automation)).toEqual({ n: { x: 10, y: 20 } });
-  });
-
-  it('reads no positions from a document that placed none', () => {
-    expect(readPositions(readDocument(DOC_EXAMPLE.automation))).toEqual({});
-  });
-});
diff --git a/services/platform/app/features/automations/lib/document.ts b/services/platform/app/features/automations/lib/document.ts
index 70e9bd97be..4945357c98 100644
--- a/services/platform/app/features/automations/lib/document.ts
+++ b/services/platform/app/features/automations/lib/document.ts
@@ -9,19 +9,13 @@
  * useless exactly when it is needed most. What cannot be understood is
  * dropped, never guessed.
  *
- * `ui` is the engine's declared canvas metadata — "ignored by the engine" — and
- * is where this feature keeps what the canvas needs and the executor must not
- * see: hand-placed node positions.
+ * `ui` is the engine's declared free metadata. The canvas lays every
+ * automation out from its references and never reads it; it is carried
+ * through a save as it was.
  */
 
 import type { NodeDef, Automation } from '@/lib/engine/core/types';
 
-/** Where a node sits on the canvas when an author placed it by hand. */
-export interface NodePosition {
-  x: number;
-  y: number;
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -115,19 +109,3 @@ export function readDocument(value: unknown): Automation | null {
   }
   return automation;
 }
-
-/** Hand-placed node positions, from `ui.positions`. Nodes without an entry are
- * laid out automatically. */
-export function readPositions(
-  automation: Automation | null,
-): Record<string, NodePosition> {
-  const raw = automation?.ui?.positions;
-  if (!isRecord(raw)) return {};
-  const out: Record<string, NodePosition> = {};
-  for (const [id, value] of Object.entries(raw)) {
-    if (!isRecord(value)) continue;
-    const { x, y } = value;
-    if (typeof x === 'number' && typeof y === 'number') out[id] = { x, y };
-  }
-  return out;
-}
diff --git a/services/platform/app/features/automations/lib/editor-search.test.ts b/services/platform/app/features/automations/lib/editor-search.test.ts
new file mode 100644
index 0000000000..577b8392e0
--- /dev/null
+++ b/services/platform/app/features/automations/lib/editor-search.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { automationEditorSearchSchema } from './editor-search';
+
+/**
+ * The Editor tab's link: the version on screen, the view, the open node.
+ * A bad value reads as absent, so a mangled link still opens the
+ * automation.
+ */
+describe('automationEditorSearchSchema', () => {
+  it('reads the version, the view and the open node', () => {
+    expect(
+      automationEditorSearchSchema.parse({
+        version: 4,
+        view: 'list',
+        node: 'open_issues',
+      }),
+    ).toEqual({ version: 4, view: 'list', node: 'open_issues' });
+  });
+
+  it('opens Start and End by their own names', () => {
+    expect(automationEditorSearchSchema.parse({ node: '__start' })).toEqual({
+      node: '__start',
+    });
+    expect(automationEditorSearchSchema.parse({ node: '__end' })).toEqual({
+      node: '__end',
+    });
+  });
+
+  it('reads a malformed value as absent', () => {
+    expect(
+      automationEditorSearchSchema.parse({
+        version: 0,
+        view: 'source',
+        node: 'Not a node id',
+      }),
+    ).toEqual({});
+    expect(automationEditorSearchSchema.parse({ node: '__gate:x' })).toEqual(
+      {},
+    );
+  });
+});
diff --git a/services/platform/app/features/automations/lib/editor-search.ts b/services/platform/app/features/automations/lib/editor-search.ts
index eecca20515..ebf678fc53 100644
--- a/services/platform/app/features/automations/lib/editor-search.ts
+++ b/services/platform/app/features/automations/lib/editor-search.ts
@@ -2,10 +2,22 @@ import { z } from 'zod';
 
 /**
  * The Editor tab's search params: `?version=<n>` shows that stored version on
- * the canvas, absent means the latest. A malformed value reads as absent
- * rather than failing the route — a bad link should still open the automation.
+ * the canvas, absent means the latest; `?view=` picks the chart or the List
+ * view; `?node=<id>` opens a node (or `__start`, `__end`) on load, so a link
+ * lands on it. A malformed value reads as absent rather than failing the
+ * route — a bad link should still open the automation.
  */
 export const automationEditorSearchSchema = z.object({
   history: z.boolean().optional().catch(undefined),
   version: z.number().int().positive().optional().catch(undefined),
+  view: z.enum(['canvas', 'list']).optional().catch(undefined),
+  node: z
+    .string()
+    .regex(/^(?:__start|__end|[a-z][a-z0-9_]{0,49})$/)
+    .optional()
+    .catch(undefined),
 });
+
+export type AutomationEditorView = NonNullable<
+  z.infer<typeof automationEditorSearchSchema>['view']
+>;
diff --git a/services/platform/app/features/automations/lib/flow-graph.test.ts b/services/platform/app/features/automations/lib/flow-graph.test.ts
new file mode 100644
index 0000000000..7d5968b4bf
--- /dev/null
+++ b/services/platform/app/features/automations/lib/flow-graph.test.ts
@@ -0,0 +1,475 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { validateFlowGraph } from '@tale/ui/flow/types';
+import type { FlowGraph, FlowStepNode } from '@tale/ui/flow/types';
+import {
+  reviewPullRequestsFlowGraph,
+  triageFlowGraph,
+  triageInboxFlowGraph,
+} from '@tale/ui/testing/flow';
+import { describe, expect, it } from 'vitest';
+import { parse } from 'yaml';
+
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { mergeNodeTypes } from '../hooks/backend';
+import { toFlowGraph, type FlowGraphContext } from './flow-graph';
+import { END_ID, START_ID, flowGraphTarget, gateIdOf } from './flow-ids';
+import { nodeCatalogView } from './node-face';
+
+/**
+ * The canvas draws what the engine runs, so the graph is held to the
+ * shipped automations themselves: the same structure the `@tale/ui` flow
+ * fixtures were drawn from (the layout tests prove those never route a
+ * line through a box), conditions above their nodes with Yes and No, a
+ * frame per iterating node, and nothing read from the document's `ui`.
+ */
+
+const REPO = path.resolve(import.meta.dirname, '../../../../../..');
+
+function shipped(pack: string): Automation {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a shipped v1 pack; the engine's corpus test validates it
+  return parse(
+    readFileSync(
+      path.join(
+        REPO,
+        'configs/platform/custom/automations',
+        pack,
+        'workflow.yml',
+      ),
+      'utf8',
+    ),
+  ) as Automation;
+}
+
+const CATALOG = nodeCatalogView(
+  mergeNodeTypes([
+    {
+      type: 'github.list_issues',
+      kind: 'connector',
+      description: 'List issues',
+      allowedFields: ['input'],
+      requiredFields: [],
+      outputKind: 'structured',
+      connector: 'github',
+      title: 'List issues',
+      i18n: { de: { title: 'Issues auflisten' } },
+    },
+  ]),
+  [{ name: 'github', displayName: 'GitHub' }],
+);
+
+function build(
+  doc: Automation,
+  extra: Partial<FlowGraphContext> = {},
+  locale = 'en',
+) {
+  const result = toFlowGraph(doc, {
+    t: i18n.getFixedT(locale, 'automations'),
+    tSchema: i18n.getFixedT(locale, 'schemaTree'),
+    locale,
+    catalog: CATALOG,
+    returns: { status: 'off', outputs: null },
+    triggers: [{ id: 'trigger:manual', label: 'By hand, the API or MCP' }],
+    flow: analyzeFlow(doc.nodes),
+    ...extra,
+  });
+  validateFlowGraph(result.graph);
+  return result;
+}
+
+/** What the layout reads of a graph: ids, kinds, lines, frames. */
+function structure(graph: FlowGraph) {
+  return {
+    nodes: graph.nodes.map((node) => `${node.kind}:${node.id}`),
+    edges: graph.edges.map(
+      (edge) =>
+        `${edge.source}>${edge.target}:${edge.kind}${edge.layoutOnly ? ':layout' : ''}`,
+    ),
+    groups: (graph.groups ?? []).map(
+      (group) => `${group.kind}:${group.id}:${group.members.join(',')}`,
+    ),
+  };
+}
+
+const step = (graph: FlowGraph, id: string): FlowStepNode => {
+  const node = graph.nodes.find((candidate) => candidate.id === id);
+  if (node?.kind !== 'step') throw new Error(`no step ${id}`);
+  return node;
+};
+
+const doc = (...nodes: NodeDef[]): Automation => ({ name: 'test', nodes });
+
+describe('toFlowGraph on the shipped automations', () => {
+  it('draws Triage GitHub issues as the flow fixture the layout is proven on', () => {
+    const { graph } = build(shipped('github/triage-issues'));
+    expect(structure(graph)).toEqual(structure(triageFlowGraph()));
+    expect(graph.groups?.[0]?.label).toBe(
+      'For each item of issues of Open issues',
+    );
+    expect(step(graph, 'issues')).toMatchObject({
+      label: 'Issues',
+      typeLabel: 'GitHub · List issues',
+      reads: [{ id: 'input', label: 'run input (owner, repo, limit)' }],
+    });
+    expect(step(graph, 'open_issues').reads?.map((row) => row.label)).toEqual([
+      'Issues',
+      'run input (limit)',
+    ]);
+    expect(step(graph, 'score')).toMatchObject({
+      typeLabel: 'Language model · anthropic/claude-haiku-4-5',
+      reads: [
+        { id: 'open_issues', label: 'Open issues' },
+        { id: 'item', label: 'each item' },
+      ],
+    });
+    expect(
+      graph.edges.find((edge) => edge.id === 'issues>open_issues')?.detail,
+    ).toBe('Carries .issues');
+  });
+
+  it('frames each of the three nodes that walk the pull requests', () => {
+    const { graph } = build(shipped('github/review-pull-requests'));
+    expect(structure(graph)).toEqual(structure(reviewPullRequestsFlowGraph()));
+  });
+
+  it('puts an only-if condition above Triage and a chip on Propose', () => {
+    const { graph } = build(shipped('gmail/triage-inbox'));
+    expect(structure(graph)).toEqual(structure(triageInboxFlowGraph()));
+    const gate = graph.nodes.find((node) => node.id === gateIdOf('triage'));
+    expect(gate).toMatchObject({
+      kind: 'gate',
+      mode: 'only-if',
+      condition: 'conversations of Inbox is not empty',
+      decisionKey: 'when:triage',
+    });
+    expect(step(graph, 'propose').chips).toEqual([
+      { id: 'onError', label: 'Continues on error', tone: 'error' },
+    ]);
+    // Every node below the condition may be skipped with it.
+    for (const id of ['triage', 'record', 'due', 'draft', 'propose']) {
+      expect(step(graph, id).conditional).toBe(true);
+    }
+    expect(step(graph, 'inbox').conditional).toBeUndefined();
+  });
+
+  it('reads the same in German, verb last', () => {
+    const { graph } = build(shipped('gmail/triage-inbox'), {}, 'de');
+    const gate = graph.nodes.find((node) => node.id === gateIdOf('triage'));
+    expect(gate).toMatchObject({
+      condition: 'conversations von Inbox nicht leer ist',
+    });
+    expect(step(graph, 'propose').chips?.[0]?.label).toBe(
+      'Läuft bei Fehler weiter',
+    );
+  });
+});
+
+describe('toFlowGraph rules', () => {
+  const pair = doc(
+    { id: 'fetch', type: 'transform', code: 'return { urgent: true };' },
+    {
+      id: 'urgent',
+      type: 'transform',
+      when: '{{ nodes.fetch.output.urgent }}',
+      code: 'return 1;',
+    },
+    { id: 'normal', type: 'transform', elseOf: 'urgent', code: 'return 2;' },
+  );
+
+  it('hangs an elseOf partner from the same condition as its No', () => {
+    const { graph } = build(pair);
+    const gate = graph.nodes.find((node) => node.id === gateIdOf('urgent'));
+    expect(gate).toMatchObject({ mode: 'if-else' });
+    expect(structure(graph).edges).toEqual([
+      '__start>fetch:entry',
+      'fetch>__gate:urgent:order',
+      '__gate:urgent>urgent:branch-yes',
+      '__gate:urgent>normal:branch-no',
+      'urgent>__end:completion',
+      'normal>__end:completion',
+    ]);
+  });
+
+  it('reads an else-if chain left to right, one condition after the other', () => {
+    const { graph } = build(
+      doc(
+        { id: 'fetch', type: 'transform', code: 'return {};' },
+        {
+          id: 'a',
+          type: 'transform',
+          when: '{{ nodes.fetch.output.a }}',
+          code: 'return 1;',
+        },
+        {
+          id: 'b',
+          type: 'transform',
+          elseOf: 'a',
+          when: '{{ nodes.fetch.output.b }}',
+          code: 'return 2;',
+        },
+        { id: 'c', type: 'transform', elseOf: 'b', code: 'return 3;' },
+      ),
+    );
+    expect(structure(graph).edges).toEqual(
+      expect.arrayContaining([
+        '__gate:a>a:branch-yes',
+        '__gate:a>__gate:b:branch-no',
+        '__gate:b>b:branch-yes',
+        '__gate:b>c:branch-no',
+      ]),
+    );
+    expect(structure(graph).edges).not.toContain('a>b:order');
+    expect(structure(graph).edges).not.toContain('b>c:order');
+  });
+
+  it('does not pair a partner that reads its node, and says nothing twice', () => {
+    const { graph } = build(
+      doc(
+        {
+          id: 'a',
+          type: 'transform',
+          when: '{{ input.go }}',
+          code: 'return 1;',
+        },
+        {
+          id: 'b',
+          type: 'transform',
+          elseOf: 'a',
+          input: { x: '{{ nodes.a.output }}' },
+          code: 'return input.x;',
+        },
+      ),
+    );
+    const edges = structure(graph).edges;
+    expect(edges).toContain('a>b:data');
+    expect(edges.filter((edge) => edge.startsWith('a>b'))).toHaveLength(1);
+    expect(graph.nodes.find((node) => node.id === gateIdOf('a'))).toMatchObject(
+      { mode: 'only-if', condition: 'go of the run input is set' },
+    );
+  });
+
+  it('hangs a condition that reads only the run input right above its node', () => {
+    const { graph } = build(
+      doc(
+        { id: 'load', type: 'transform', code: 'return {};' },
+        {
+          id: 'notify',
+          type: 'transform',
+          when: '{{ input.notify }}',
+          input: { data: '{{ nodes.load.output }}' },
+          code: 'return 1;',
+        },
+      ),
+    );
+    expect(structure(graph).edges).toEqual([
+      '__start>load:entry',
+      'load>__gate:notify:order:layout',
+      'load>notify:data',
+      '__gate:notify>notify:gate',
+      'notify>__end:completion',
+    ]);
+  });
+
+  it('starts a condition with nothing above it from Start', () => {
+    const { graph } = build(
+      doc({
+        id: 'only',
+        type: 'transform',
+        when: '{{ input.go === true }}',
+        code: 'return 1;',
+      }),
+    );
+    expect(structure(graph).edges).toEqual([
+      '__start>__gate:only:entry',
+      '__gate:only>only:gate',
+      'only>__end:completion',
+    ]);
+  });
+
+  it('draws a cycle in document order, from Start to End, with no pairing', () => {
+    const result = build(
+      doc(
+        {
+          id: 'a',
+          type: 'transform',
+          input: { x: '{{ nodes.b.output }}' },
+          code: 'return 1;',
+        },
+        {
+          id: 'b',
+          type: 'transform',
+          input: { x: '{{ nodes.a.output }}' },
+          code: 'return 2;',
+        },
+      ),
+      { flow: null },
+    );
+    expect(result.hasCycle).toBe(true);
+    expect(result.order).toEqual(['a', 'b']);
+    expect(structure(result.graph).edges).toEqual([
+      '__start>a:entry',
+      'b>a:data',
+      'a>b:data',
+      'b>__end:completion',
+    ]);
+  });
+
+  it('never reads the document’s positions', () => {
+    const triage = shipped('github/triage-issues');
+    const stacked: Automation = {
+      ...triage,
+      ui: {
+        positions: Object.fromEntries(
+          triage.nodes.map((node) => [node.id, { x: 0, y: 0 }]),
+        ),
+      },
+    };
+    expect(build(stacked).graph).toEqual(build(triage).graph);
+  });
+
+  it('keeps the first of two nodes with one id, and draws no node without a type', () => {
+    const { graph, nodeIndex } = build(
+      doc(
+        { id: 'a', type: 'transform', code: 'return 1;' },
+        { id: 'a', type: 'llm', prompt: 'x' },
+        { id: 'b', type: '' },
+      ),
+    );
+    expect(graph.nodes.map((node) => node.id)).toEqual([START_ID, 'a', END_ID]);
+    expect(nodeIndex.get('a')).toBe(0);
+  });
+
+  it('frames a repeat with its condition and cap', () => {
+    const { graph } = build(
+      doc({
+        id: 'poll',
+        type: 'transform',
+        repeatUntil: '{{ output.done }}',
+        maxRepeats: 3,
+        code: 'return { done: true };',
+      }),
+    );
+    expect(graph.groups).toEqual([
+      {
+        id: 'repeat:poll',
+        kind: 'repeat',
+        label: "Repeats until done of this pass's result is set, at most 3×",
+        members: ['poll'],
+      },
+    ]);
+  });
+
+  it('marks a node no run reaches', () => {
+    const { graph } = build(
+      doc({
+        id: 'never',
+        type: 'transform',
+        when: '{{ false }}',
+        code: 'return 1;',
+      }),
+    );
+    expect(step(graph, 'never')).toMatchObject({
+      conditional: true,
+      unreachable: true,
+    });
+    // A condition of literals only is code, not words.
+    expect(
+      graph.nodes.find((node) => node.id === gateIdOf('never')),
+    ).toMatchObject({ condition: 'false', conditionIsCode: true });
+  });
+});
+
+describe('Start and End', () => {
+  it('lists the inputs with their kinds, and tags the trigger wrapper', () => {
+    const { graph } = build(shipped('github/triage-issues'));
+    const start = graph.nodes[0];
+    expect(start?.kind).toBe('entry');
+    if (start?.kind !== 'entry') return;
+    expect(start.inputs.map((row) => `${row.label}: ${row.detail}`)).toEqual([
+      'owner: text · required',
+      'repo: text · required',
+      'limit: a number',
+      'trigger: text · from the trigger',
+      'firedAt: a number · from the trigger',
+    ]);
+    expect(start.description).toBe(
+      'By hand, the API or MCP. Input: owner, repo, limit, trigger, and firedAt.',
+    );
+  });
+
+  it('says what a run receives without an inputs schema', () => {
+    const { graph } = build(doc({ id: 'a', type: 'transform', code: '' }));
+    expect(graph.nodes[0]).toMatchObject({ inputsEmpty: 'Any JSON input' });
+  });
+
+  it('names the node the output is, and counts what stops a run', () => {
+    const { graph } = build(shipped('github/triage-issues'));
+    const end = graph.nodes.at(-1);
+    expect(end).toMatchObject({
+      kind: 'exit',
+      outputs: [{ id: 'output', label: 'The output of Report' }],
+    });
+    if (end?.kind !== 'exit') return;
+    expect(end.outcomes?.map((row) => `${row.label} ${row.detail}`)).toEqual([
+      'Succeeded returns the output',
+      'Failed when one of 4 nodes fails',
+      'Stopped when someone stops it',
+    ]);
+  });
+
+  it('lists output fields with where they come from and what may be empty', () => {
+    const { graph } = build(shipped('gmail/triage-inbox'));
+    const end = graph.nodes.at(-1);
+    if (end?.kind !== 'exit') throw new Error('no End');
+    expect(end.outputs.map((row) => `${row.label}: ${row.detail}`)).toEqual([
+      'read: from Inbox',
+      'summary: from Triage · may be empty',
+      'recorded: from Record · may be empty',
+      'needsReply: from Due · may be empty',
+      'drafted: from Propose · may be empty',
+    ]);
+    expect(end.notice).toEqual({
+      tone: 'info',
+      text: 'Some runs return empty values',
+    });
+  });
+
+  it('marks the outputs a pinned path leaves empty', () => {
+    const { graph } = build(shipped('gmail/triage-inbox'), {
+      ranOnPath: new Set(['inbox']),
+    });
+    const end = graph.nodes.at(-1);
+    if (end?.kind !== 'exit') throw new Error('no End');
+    expect(end.outputs[0]?.detail).toBe('from Inbox');
+    expect(end.outputs[1]?.detail).toBe(
+      'from Triage · may be empty · empty on this path',
+    );
+  });
+
+  it('says when an automation returns nothing', () => {
+    const { graph } = build(doc({ id: 'a', type: 'transform', code: '' }));
+    expect(graph.nodes.at(-1)).toMatchObject({
+      outputs: [],
+      outputsEmpty: 'Nothing — this automation has no output',
+    });
+  });
+});
+
+describe('flowGraphTarget', () => {
+  it('tells Start, End, a condition and a node apart', () => {
+    expect(flowGraphTarget(START_ID)).toEqual({ kind: 'start' });
+    expect(flowGraphTarget(END_ID)).toEqual({ kind: 'end' });
+    expect(flowGraphTarget(gateIdOf('triage'))).toEqual({
+      kind: 'gate',
+      nodeId: 'triage',
+    });
+    expect(flowGraphTarget('triage')).toEqual({
+      kind: 'node',
+      nodeId: 'triage',
+    });
+  });
+});
diff --git a/services/platform/app/features/automations/lib/flow-graph.ts b/services/platform/app/features/automations/lib/flow-graph.ts
new file mode 100644
index 0000000000..6dd52d96c6
--- /dev/null
+++ b/services/platform/app/features/automations/lib/flow-graph.ts
@@ -0,0 +1,672 @@
+/**
+ * An automation document as the graph the canvas draws (`@tale/ui/flow`).
+ *
+ * A v1 document has no edge list: a node names the nodes it needs by
+ * writing `{{ nodes.<id>.output }}` in its own fields, and the engine orders
+ * the run from exactly those references (`refsOf`, `topoSort`). The graph is
+ * built the same way, so what the canvas draws is what the engine runs:
+ *
+ *  - **Start** says what starts a run and what it receives; **End** what a
+ *    successful run returns and how a run can end;
+ *  - a node's `when` is a **condition** of its own, drawn just above the
+ *    node, in words when it reads as words; an `elseOf` partner hangs from
+ *    the same condition as its **No** (else-if chains read left to right);
+ *  - a line is **data** when the node reads the other's output (a skip
+ *    travels along it), **order** when only a condition or a repeat
+ *    mentions it;
+ *  - a node that iterates (`forEach`, `repeatUntil`) sits in a **frame**;
+ *  - nodes nothing reads end the run (a dotted line to End), nodes the
+ *    output reads lead to End.
+ *
+ * Positions are never read: the canvas lays itself out from this graph, so
+ * a document's `ui` metadata changes nothing here.
+ */
+
+import type {
+  FlowEdge,
+  FlowEdgeKind,
+  FlowEntryNode,
+  FlowExitNode,
+  FlowGateNode,
+  FlowGraph,
+  FlowGroup,
+  FlowNode,
+  FlowNotice,
+  FlowRow,
+  FlowStepNode,
+} from '@tale/ui/flow/types';
+import { schemaKindLabel, type SchemaTreeSchema } from '@tale/ui/schema-tree';
+import type { TFunction } from 'i18next';
+import { Ban, CircleCheck, CircleX } from 'lucide-react';
+
+import type { FlowFacts } from '@/lib/engine/core/analysis/flow';
+import { maxRepeatsOf } from '@/lib/engine/core/execute/controlflow';
+import {
+  outputSources,
+  refSitesOf,
+  type ExprSource,
+} from '@/lib/engine/core/syntax/sources';
+import {
+  exprSegments,
+  tokenizeTemplate,
+} from '@/lib/engine/core/syntax/tokens';
+import { renderPath } from '@/lib/engine/core/syntax/walk';
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import { isUnknown, toTs, type Shape } from '@/lib/engine/core/typing/shape';
+
+import {
+  describeCondition,
+  describeList,
+  renderCondition,
+  renderOperand,
+  type ConditionTextContext,
+} from './condition-text';
+import { END_ID, START_ID, decisionKeyOf, gateIdOf } from './flow-ids';
+import { orderedNodes } from './graph';
+import { nodeFace, nodeTitle, type NodeFaceContext } from './node-face';
+import { TRIGGER_WRAPPER_KEYS } from './trigger-summary';
+
+/** At most this many names in a "Carries …" or "run input (…)" list. */
+const LIST_LIMIT = 3;
+
+export interface FlowGraphContext extends NodeFaceContext {
+  /** The `schemaTree` namespace, for the kind of each input field. */
+  tSchema: TFunction;
+  /** Start's trigger rows (`triggerRows`). */
+  triggers: readonly FlowRow[];
+  /** The local flow analysis; null on a reference cycle. */
+  flow: FlowFacts | null;
+  /** The shape of the run's result, when the check worked it out. */
+  outputShape?: Shape | null;
+  /** The cause of a trigger whose input the schema refuses, shown on
+   *  Start. */
+  startNotice?: string | null;
+  /** The nodes that run on a pinned path: End says which outputs come
+   *  back empty on it. */
+  ranOnPath?: ReadonlySet<string> | null;
+}
+
+export interface AutomationFlowGraph {
+  graph: FlowGraph;
+  /** The references form a cycle: the order is the document's, and no
+   *  path can be listed. */
+  hasCycle: boolean;
+  /** Each node's position in `doc.nodes` (first occurrence of an id). */
+  nodeIndex: ReadonlyMap<string, number>;
+  /** Node ids in execution order. */
+  order: readonly string[];
+}
+
+/** `a, b, c, +2`: names are data, so no locale list words. */
+function shortList(items: readonly string[]): string {
+  const shown = items.slice(0, LIST_LIMIT);
+  const rest = items.length - shown.length;
+  return rest > 0 ? `${shown.join(', ')}, +${rest}` : shown.join(', ');
+}
+
+/** What a node reads, by the field it reads it in. */
+interface NodeReads {
+  /** Data reads of other nodes, with the member paths read. */
+  data: Map<string, Set<string>>;
+  /** Nodes its `when` reads. */
+  when: Set<string>;
+  /** Nodes its `repeatUntil` reads. */
+  repeat: Set<string>;
+  /** Top-level keys of the run input it reads (`null`: the whole of it). */
+  inputKeys: Set<string> | null;
+  readsInput: boolean;
+  readsItem: boolean;
+}
+
+function readsOf(
+  node: NodeDef,
+  index: number,
+  known: ReadonlySet<string>,
+): NodeReads {
+  const reads: NodeReads = {
+    data: new Map(),
+    when: new Set(),
+    repeat: new Set(),
+    inputKeys: new Set(),
+    readsInput: false,
+    readsItem: false,
+  };
+  for (const { source, site } of refSitesOf(node, index)) {
+    if (site.root === 'nodes') {
+      const id = site.nodeId;
+      if (id === undefined || id === node.id || !known.has(id)) continue;
+      if (source.field === 'when') reads.when.add(id);
+      else if (source.field === 'repeatUntil') reads.repeat.add(id);
+      else if (source.data) {
+        const paths = reads.data.get(id) ?? new Set<string>();
+        if (site.member === 'output' && site.path.length > 0) {
+          paths.add(renderPath(site.path));
+        }
+        reads.data.set(id, paths);
+      }
+      continue;
+    }
+    if (!source.data) continue;
+    // A transform's code reads its own input mapping as `input`, not the
+    // run input.
+    if (site.root === 'input' && source.field !== 'code') {
+      reads.readsInput = true;
+      const key = site.path[0]?.key;
+      if (typeof key === 'string') reads.inputKeys?.add(key);
+      else reads.inputKeys = null;
+    } else if (site.root === 'item') {
+      reads.readsItem = true;
+    }
+  }
+  return reads;
+}
+
+/** The node ids an `output` template reads, in reading order, by the
+ *  top-level output field they sit in (`''` for a whole-value output). */
+function outputReadsOf(
+  output: unknown,
+  known: ReadonlySet<string>,
+): { all: string[]; byField: Map<string, string[]> } {
+  const all: string[] = [];
+  const byField = new Map<string, string[]>();
+  for (const source of outputSources(output)) {
+    const field = fieldOf(source);
+    for (const unit of source.units) {
+      for (const site of unit.refs) {
+        const id = site.nodeId;
+        if (site.root !== 'nodes' || id === undefined || !known.has(id)) {
+          continue;
+        }
+        if (!all.includes(id)) all.push(id);
+        const list = byField.get(field) ?? [];
+        if (!list.includes(id)) list.push(id);
+        byField.set(field, list);
+      }
+    }
+  }
+  return { all, byField };
+}
+
+/** The top-level output field a source sits in: `/output/summary/…` →
+ *  `summary`; the whole output → `''`. */
+function fieldOf(source: ExprSource): string {
+  const [, , field] = source.pointer.split('/');
+  return field === undefined
+    ? ''
+    : field.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+/** The expression a code condition shows: the one inside its braces, or
+ *  the field as written. */
+function conditionCode(text: string): string {
+  const segments = exprSegments(tokenizeTemplate(text));
+  const [only] = segments;
+  if (segments.length === 1 && only?.source !== undefined) {
+    if (text.trim() === text.slice(only.start, only.end).trim()) {
+      return only.source;
+    }
+  }
+  return text.trim();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A JSON Schema as the schema tree reads it; anything else reads as
+ *  "anything". */
+function asSchema(value: unknown): SchemaTreeSchema {
+  // An author's JSON Schema: the kind words read only the fields they know
+  // and ignore the rest.
+  return isRecord(value) ? value : {};
+}
+
+/** Start: the triggers, then what every run receives. */
+function startNode(doc: Automation, ctx: FlowGraphContext): FlowEntryNode {
+  const { t } = ctx;
+  const inputs: FlowRow[] = [];
+  let inputsEmpty: string | undefined;
+  const schema = doc.inputs;
+  if (!isRecord(schema)) {
+    inputsEmpty = t('canvas.start.anyInput');
+  } else {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(
+      Array.isArray(schema.required)
+        ? schema.required.filter((key) => typeof key === 'string')
+        : [],
+    );
+    for (const [name, field] of Object.entries(properties)) {
+      const words = [schemaKindLabel(ctx.tSchema, asSchema(field), ctx.locale)];
+      if (required.has(name)) words.push(ctx.tSchema('required'));
+      if (TRIGGER_WRAPPER_KEYS.has(name)) {
+        words.push(t('canvas.start.fromTrigger'));
+      }
+      inputs.push({
+        id: `input:${name}`,
+        label: name,
+        detail: words.join(' · '),
+        code: true,
+      });
+    }
+    if (inputs.length === 0) inputsEmpty = t('canvas.start.noFields');
+  }
+  const list = (items: string[]) =>
+    new Intl.ListFormat(ctx.locale, { type: 'conjunction' }).format(items);
+  const notice: FlowNotice | undefined =
+    ctx.startNotice === undefined ||
+    ctx.startNotice === null ||
+    ctx.startNotice === ''
+      ? undefined
+      : { tone: 'warning', text: ctx.startNotice };
+  return {
+    id: START_ID,
+    kind: 'entry',
+    triggers: ctx.triggers,
+    inputs,
+    ...(inputsEmpty !== undefined && { inputsEmpty }),
+    ...(notice !== undefined && { notice }),
+    description: t('canvas.start.description', {
+      triggers: list(ctx.triggers.map((row) => row.label)),
+      fields:
+        inputs.length > 0
+          ? list(inputs.map((row) => row.label))
+          : (inputsEmpty ?? ''),
+    }),
+  };
+}
+
+/** End: what a successful run returns, and the three ways a run ends. */
+function endNode(
+  doc: Automation,
+  ctx: FlowGraphContext,
+  outputReads: { all: string[]; byField: Map<string, string[]> },
+  words: ConditionTextContext,
+): FlowExitNode {
+  const { t, flow } = ctx;
+  const mayBeSkipped = (id: string) => flow !== null && !flow.reach(id).always;
+  const emptyOnPath = (sources: readonly string[]) =>
+    ctx.ranOnPath !== undefined &&
+    ctx.ranOnPath !== null &&
+    sources.some((id) => !ctx.ranOnPath?.has(id));
+  const outputs: FlowRow[] = [];
+  let someEmpty = false;
+  const output = doc.output;
+  if (typeof output === 'string') {
+    const sources = outputReads.byField.get('') ?? [];
+    const operand = describeList(output);
+    const label =
+      operand?.kind === 'ref' &&
+      operand.root === 'node' &&
+      operand.path.length === 0 &&
+      operand.length !== true
+        ? t('canvas.end.returnsNode', {
+            node: nodeTitle(operand.nodeId ?? ''),
+          })
+        : operand !== null
+          ? renderOperand(operand, words)
+          : null;
+    someEmpty = sources.some(mayBeSkipped);
+    outputs.push({
+      id: 'output',
+      label: label ?? output,
+      ...(label === null && { code: true }),
+      ...(emptyOnPath(sources) && { detail: t('canvas.end.emptyOnPath') }),
+    });
+  } else if (isRecord(output)) {
+    const properties = isRecord(ctx.outputShape?.properties)
+      ? ctx.outputShape.properties
+      : undefined;
+    for (const key of Object.keys(output)) {
+      const sources = outputReads.byField.get(key) ?? [];
+      const detail: string[] = [];
+      const shape = properties?.[key];
+      if (shape !== undefined && !isUnknown(shape)) {
+        detail.push(schemaKindLabel(ctx.tSchema, asSchema(shape), ctx.locale));
+      }
+      if (sources.length > 0) {
+        detail.push(
+          t('canvas.end.fieldFrom', {
+            nodes: new Intl.ListFormat(ctx.locale, {
+              type: 'conjunction',
+            }).format(sources.map(nodeTitle)),
+          }),
+        );
+      }
+      if (sources.some(mayBeSkipped)) {
+        someEmpty = true;
+        detail.push(t('canvas.end.maybeEmpty'));
+      }
+      if (emptyOnPath(sources)) detail.push(t('canvas.end.emptyOnPath'));
+      outputs.push({
+        id: `output:${key}`,
+        label: key,
+        code: true,
+        ...(detail.length > 0 && { detail: detail.join(' · ') }),
+      });
+    }
+  } else if (output !== undefined) {
+    outputs.push({ id: 'output', label: JSON.stringify(output), code: true });
+  }
+  const shape =
+    ctx.outputShape !== undefined &&
+    ctx.outputShape !== null &&
+    !isUnknown(ctx.outputShape)
+      ? toTs(ctx.outputShape, 2)
+      : undefined;
+  return {
+    id: END_ID,
+    kind: 'exit',
+    outputs,
+    ...(outputs.length === 0 && {
+      outputsEmpty: t('canvas.end.returnsNothing'),
+    }),
+    ...(shape !== undefined && { shape }),
+    outcomes: [
+      {
+        id: 'succeeded',
+        icon: CircleCheck,
+        label: t('runs.status.success'),
+        detail: t('canvas.end.succeeded'),
+      },
+      {
+        id: 'failed',
+        icon: CircleX,
+        label: t('runs.status.failed'),
+        detail: t('canvas.end.failed', { count: flow?.halts.length ?? 0 }),
+      },
+      {
+        id: 'stopped',
+        icon: Ban,
+        label: t('runs.status.cancelled'),
+        detail: t('canvas.end.stopped'),
+      },
+    ],
+    ...(someEmpty && {
+      notice: { tone: 'info', text: t('canvas.end.someEmpty') },
+    }),
+  };
+}
+
+/** The words of a node's frame: what it iterates, or until when. */
+function frameLabel(node: NodeDef, words: ConditionTextContext): string | null {
+  const { t } = words;
+  const parts: string[] = [];
+  if (typeof node.forEach === 'string') {
+    const list = describeList(node.forEach);
+    parts.push(
+      list === null
+        ? t('canvas.controlFlow.forEachRaw')
+        : t('canvas.controlFlow.forEach', {
+            list: renderOperand(list, words),
+          }),
+    );
+  }
+  if (typeof node.repeatUntil === 'string') {
+    const condition = renderCondition(
+      describeCondition(node.repeatUntil),
+      words,
+    );
+    const maxRepeats = maxRepeatsOf(node);
+    parts.push(
+      condition === null
+        ? t('canvas.controlFlow.repeatRaw', { maxRepeats })
+        : t('canvas.controlFlow.repeatUntilCapped', { condition, maxRepeats }),
+    );
+  }
+  return parts.length === 0 ? null : parts.join(' · ');
+}
+
+/**
+ * The graph of one document. Pure: the same document and context always
+ * give the same graph, edge for edge, in the same order.
+ */
+export function toFlowGraph(
+  doc: Automation,
+  ctx: FlowGraphContext,
+): AutomationFlowGraph {
+  const { t, flow } = ctx;
+  const words: ConditionTextContext = {
+    t,
+    locale: ctx.locale,
+    nodeLabel: nodeTitle,
+  };
+
+  // Every node once (a repeated id keeps its first occurrence, as both
+  // executors do), in execution order — document order on a cycle.
+  const nodeIndex = new Map<string, number>();
+  const unique: NodeDef[] = [];
+  doc.nodes.forEach((node, index) => {
+    if (typeof node.id !== 'string' || nodeIndex.has(node.id)) return;
+    if (typeof node.type !== 'string' || node.type === '') return;
+    nodeIndex.set(node.id, index);
+    unique.push(node);
+  });
+  const { nodes: ordered, hasCycle } = orderedNodes(unique);
+  const known: ReadonlySet<string> = new Set(nodeIndex.keys());
+  const byId = new Map(ordered.map((node) => [node.id, node]));
+  const reads = new Map(
+    ordered.map((node) => [
+      node.id,
+      readsOf(node, nodeIndex.get(node.id) ?? 0, known),
+    ]),
+  );
+
+  // An elseOf partner hangs from its node's condition as the No — unless
+  // the pairing cannot hold: a cycle, a node without a condition, or a
+  // partner that reads the node's own output (the analysis explains why
+  // that partner never runs).
+  const partners = new Map<string, string[]>();
+  const paired = new Set<string>();
+  for (const node of ordered) {
+    const target = node.elseOf;
+    if (typeof target !== 'string' || target === node.id) continue;
+    const of = byId.get(target);
+    if (of === undefined || hasCycle || typeof of.when !== 'string') continue;
+    if (reads.get(node.id)?.data.has(target)) continue;
+    paired.add(node.id);
+    partners.set(target, [...(partners.get(target) ?? []), node.id]);
+  }
+
+  // ── Nodes, in model order: Start, each condition right before its node,
+  // End. ─────────────────────────────────────────────────────────────────
+  const graphNodes: FlowNode[] = [startNode(doc, ctx)];
+  const groups: FlowGroup[] = [];
+  for (const node of ordered) {
+    const own = reads.get(node.id);
+    if (typeof node.when === 'string') {
+      const condition = renderCondition(describeCondition(node.when), words);
+      const gate: FlowGateNode = {
+        id: gateIdOf(node.id),
+        kind: 'gate',
+        label: nodeTitle(node.id),
+        mode: partners.has(node.id) ? 'if-else' : 'only-if',
+        condition: condition ?? conditionCode(node.when),
+        ...(condition === null && {
+          conditionIsCode: true,
+          description: t('canvas.gate.asCode'),
+        }),
+        decisionKey: decisionKeyOf(node.id),
+      };
+      graphNodes.push(gate);
+    }
+    const face = nodeFace(node, ctx);
+    const rows: FlowRow[] = [];
+    if (own !== undefined) {
+      for (const id of ordered.map((candidate) => candidate.id)) {
+        if (own.data.has(id)) rows.push({ id, label: nodeTitle(id) });
+      }
+      if (own.readsInput) {
+        const keys = own.inputKeys === null ? [] : [...own.inputKeys];
+        rows.push({
+          id: 'input',
+          label:
+            keys.length > 0
+              ? t('canvas.node.source.input', { keys: shortList(keys) })
+              : t('canvas.node.source.inputAll'),
+        });
+      }
+      if (own.readsItem) {
+        rows.push({ id: 'item', label: t('canvas.node.source.item') });
+      }
+    }
+    const frame = frameLabel(node, words);
+    if (frame !== null) {
+      groups.push({
+        id: `${typeof node.forEach === 'string' ? 'each' : 'repeat'}:${node.id}`,
+        kind: typeof node.forEach === 'string' ? 'each' : 'repeat',
+        label: frame,
+        members: [node.id],
+      });
+    }
+    const reach = flow?.reach(node.id);
+    const sentences = [...(frame === null ? [] : [frame]), ...face.sentences];
+    const step: FlowStepNode = {
+      id: node.id,
+      kind: 'step',
+      label: face.label,
+      icon: face.icon,
+      typeLabel: face.typeLabel,
+      reads: rows,
+      readsEmpty: t('canvas.readsNothing'),
+      ...(face.returns !== undefined && { returns: face.returns }),
+      ...(face.chips.length > 0 && { chips: face.chips }),
+      ...(face.markers.length > 0 && { markers: face.markers }),
+      ...(reach !== undefined && !reach.always && { conditional: true }),
+      ...(reach !== undefined && !reach.executed && { unreachable: true }),
+      ...(sentences.length > 0 && { description: sentences.join('. ') }),
+    };
+    graphNodes.push(step);
+  }
+
+  const outputReads = outputReadsOf(doc.output, known);
+  graphNodes.push(endNode(doc, ctx, outputReads, words));
+
+  // ── Edges ──────────────────────────────────────────────────────────────
+  const edges = new Map<string, FlowEdge>();
+  const add = (
+    source: string,
+    target: string,
+    kind: FlowEdgeKind,
+    extra: Partial<FlowEdge> = {},
+  ): void => {
+    const id = `${source}>${target}`;
+    const existing = edges.get(id);
+    // One line per pair: a drawn line wins over a layout-only one, a data
+    // line over an order line.
+    if (existing !== undefined) {
+      if (existing.layoutOnly === true && extra.layoutOnly !== true) {
+        edges.set(id, { id, source, target, kind, ...extra });
+      } else if (existing.kind === 'order' && kind === 'data') {
+        edges.set(id, { id, source, target, kind, ...extra });
+      }
+      return;
+    }
+    edges.set(id, { id, source, target, kind, ...extra });
+  };
+
+  for (const node of ordered) {
+    const own = reads.get(node.id);
+    if (own === undefined) continue;
+    for (const [source, paths] of own.data) {
+      const fields = [...paths];
+      add(source, node.id, 'data', {
+        ...(fields.length > 0 && {
+          detail: t('canvas.edge.carries', { fields: shortList(fields) }),
+        }),
+      });
+    }
+    if (typeof node.when === 'string') {
+      const gate = gateIdOf(node.id);
+      for (const source of own.when) add(source, gate, 'order');
+      if (own.when.size === 0) {
+        // A condition that reads no node hangs right above its node: from
+        // what the node reads, without a line of its own.
+        for (const source of own.data.keys()) {
+          add(source, gate, 'order', { layoutOnly: true });
+        }
+      }
+      const others = partners.get(node.id);
+      add(gate, node.id, others === undefined ? 'gate' : 'branch-yes');
+      for (const partner of others ?? []) {
+        const target = byId.get(partner);
+        add(
+          gate,
+          typeof target?.when === 'string' ? gateIdOf(partner) : partner,
+          'branch-no',
+        );
+      }
+    }
+    for (const source of own.repeat) {
+      if (!own.data.has(source)) add(source, node.id, 'order');
+    }
+    const target = node.elseOf;
+    if (
+      typeof target === 'string' &&
+      target !== node.id &&
+      known.has(target) &&
+      !paired.has(node.id) &&
+      !own.data.has(target)
+    ) {
+      add(target, node.id, 'order');
+    }
+  }
+
+  // Whatever nothing leads into starts from Start; on a cycle with no
+  // such node, the first one written does.
+  const incoming = new Set([...edges.values()].map((edge) => edge.target));
+  const heads: string[] = [];
+  for (const node of ordered) {
+    const head = typeof node.when === 'string' ? gateIdOf(node.id) : node.id;
+    if (!incoming.has(head)) heads.push(head);
+    if (head !== node.id && !incoming.has(node.id)) heads.push(node.id);
+  }
+  if (heads.length === 0 && ordered.length > 0) {
+    const first = unique[0];
+    if (first !== undefined) {
+      heads.push(
+        typeof first.when === 'string' ? gateIdOf(first.id) : first.id,
+      );
+    }
+  }
+  for (const head of heads) add(START_ID, head, 'entry');
+
+  // What the output reads leads to End; every other node nothing reads
+  // ends the run there.
+  const outgoing = new Set(
+    [...edges.values()]
+      .filter((edge) => edge.layoutOnly !== true)
+      .map((edge) => edge.source),
+  );
+  for (const id of outputReads.all) add(id, END_ID, 'exit');
+  for (const node of ordered) {
+    if (!outgoing.has(node.id) && !outputReads.all.includes(node.id)) {
+      add(node.id, END_ID, 'completion');
+    }
+  }
+  if (
+    ordered.length > 0 &&
+    ![...edges.values()].some((e) => e.target === END_ID)
+  ) {
+    const last = ordered.at(-1);
+    if (last !== undefined) add(last.id, END_ID, 'completion');
+  }
+
+  const position = new Map(graphNodes.map((node, index) => [node.id, index]));
+  const sortedEdges = [...edges.values()].sort(
+    (a, b) =>
+      (position.get(a.target) ?? 0) - (position.get(b.target) ?? 0) ||
+      (position.get(a.source) ?? 0) - (position.get(b.source) ?? 0),
+  );
+
+  return {
+    graph: {
+      nodes: graphNodes,
+      edges: sortedEdges,
+      ...(groups.length > 0 && { groups }),
+    },
+    hasCycle,
+    nodeIndex,
+    order: ordered.map((node) => node.id),
+  };
+}
diff --git a/services/platform/app/features/automations/lib/flow-ids.ts b/services/platform/app/features/automations/lib/flow-ids.ts
new file mode 100644
index 0000000000..824644b9b5
--- /dev/null
+++ b/services/platform/app/features/automations/lib/flow-ids.ts
@@ -0,0 +1,35 @@
+/**
+ * The ids the canvas gives what a document does not name: Start, End and
+ * each node's condition. A document node id matches
+ * `^[a-z][a-z0-9_]{0,49}$`, so none of these can collide with one.
+ *
+ * Kept apart from `./flow-graph`, which parses the document: the Problems
+ * counts and the editor's selection only need the ids.
+ */
+
+export const START_ID = '__start';
+export const END_ID = '__end';
+const GATE_PREFIX = '__gate:';
+
+/** The condition drawn above node `nodeId`. */
+export const gateIdOf = (nodeId: string): string => `${GATE_PREFIX}${nodeId}`;
+
+/** The key a path's decision for a node's condition goes by (the flow
+ *  analysis's atom id). */
+export const decisionKeyOf = (nodeId: string): string => `when:${nodeId}`;
+
+/** What a graph id stands for in the document. */
+export type FlowGraphTarget =
+  | { kind: 'start' }
+  | { kind: 'end' }
+  | { kind: 'gate'; nodeId: string }
+  | { kind: 'node'; nodeId: string };
+
+export function flowGraphTarget(id: string): FlowGraphTarget {
+  if (id === START_ID) return { kind: 'start' };
+  if (id === END_ID) return { kind: 'end' };
+  if (id.startsWith(GATE_PREFIX)) {
+    return { kind: 'gate', nodeId: id.slice(GATE_PREFIX.length) };
+  }
+  return { kind: 'node', nodeId: id };
+}
diff --git a/services/platform/app/features/automations/lib/graph.test.ts b/services/platform/app/features/automations/lib/graph.test.ts
index 95469da5ad..fec85b1fb9 100644
--- a/services/platform/app/features/automations/lib/graph.test.ts
+++ b/services/platform/app/features/automations/lib/graph.test.ts
@@ -3,13 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { DOC_EXAMPLE } from '@/lib/engine/api/docs';
 import type { NodeDef } from '@/lib/engine/core/types';
 
-import {
-  buildGraph,
-  controlFlowBadges,
-  deriveEdges,
-  orderedNodes,
-  rankNodes,
-} from './graph';
+import { buildGraph, deriveEdges, orderedNodes } from './graph';
 
 /**
  * The canvas has no edge list of its own — it reads the same references the
@@ -186,71 +180,11 @@ describe('orderedNodes', () => {
   });
 });
 
-describe('rankNodes', () => {
-  it('places a node one level below the deepest node it reads', () => {
-    const defs = nodes(
-      { id: 'a', type: 'transform', code: 'return 1;' },
-      {
-        id: 'b',
-        type: 'transform',
-        input: { v: '{{ nodes.a.output }}' },
-        code: 'return input.v;',
-      },
-      {
-        id: 'c',
-        type: 'transform',
-        input: { v: '{{ nodes.b.output }}', w: '{{ nodes.a.output }}' },
-        code: 'return input.v;',
-      },
-    );
-    const ranks = rankNodes(defs, deriveEdges(defs));
-    expect([...ranks]).toEqual([
-      ['a', 0],
-      ['b', 1],
-      ['c', 2],
-    ]);
-  });
-});
-
-describe('controlFlowBadges', () => {
-  it('renders one badge per declared control-flow field', () => {
-    expect(
-      controlFlowBadges({
-        id: 'a',
-        type: 'transform',
-        when: '{{ x }}',
-        forEach: '{{ items }}',
-        repeatUntil: '{{ done }}',
-        maxRepeats: 3,
-        onError: 'continue',
-        code: 'return 1;',
-      }),
-    ).toEqual([
-      { kind: 'when', value: '{{ x }}' },
-      { kind: 'forEach', value: '{{ items }}' },
-      { kind: 'repeatUntil', value: '{{ done }}', maxRepeats: 3 },
-      { kind: 'onError', value: 'continue' },
-    ]);
-  });
-
-  it('says nothing about the default error policy', () => {
-    expect(
-      controlFlowBadges({
-        id: 'a',
-        type: 'transform',
-        onError: 'fail',
-        code: 'return 1;',
-      }),
-    ).toEqual([]);
-  });
-});
-
 describe('buildGraph', () => {
   it('reads an absent document as an empty graph', () => {
     expect(buildGraph(null)).toEqual({
       nodes: [],
       edges: [],
-      ranks: new Map(),
       hasCycle: false,
     });
   });
diff --git a/services/platform/app/features/automations/lib/graph.ts b/services/platform/app/features/automations/lib/graph.ts
index e686a60816..2051e21ed8 100644
--- a/services/platform/app/features/automations/lib/graph.ts
+++ b/services/platform/app/features/automations/lib/graph.ts
@@ -79,86 +79,11 @@ export function orderedNodes(nodes: readonly NodeDef[]): {
     : { nodes: sorted, hasCycle: false };
 }
 
-/** How far down the canvas a node sits: one more than the deepest node it
- * references. Computed over the ordered list, so one pass suffices. */
-export function rankNodes(
-  ordered: readonly NodeDef[],
-  edges: readonly DerivedEdge[],
-): Map<string, number> {
-  const incoming = new Map<string, string[]>();
-  for (const edge of edges) {
-    const bucket = incoming.get(edge.target);
-    if (bucket) bucket.push(edge.source);
-    else incoming.set(edge.target, [edge.source]);
-  }
-  const ranks = new Map<string, number>();
-  for (const node of ordered) {
-    const sources = incoming.get(node.id) ?? [];
-    let rank = 0;
-    for (const source of sources) {
-      const sourceRank = ranks.get(source);
-      // A source that has not been ranked yet only happens inside a cycle,
-      // where there is no honest depth to read — treat it as level 0.
-      if (sourceRank !== undefined) rank = Math.max(rank, sourceRank + 1);
-    }
-    ranks.set(node.id, rank);
-  }
-  return ranks;
-}
-
-/** The control-flow fields a node declares, as the canvas renders them: one
- * badge per field, in a fixed reading order. */
-export type ControlFlowKind =
-  | 'when'
-  | 'elseOf'
-  | 'forEach'
-  | 'repeatUntil'
-  | 'onError';
-
-export interface ControlFlowBadge {
-  kind: ControlFlowKind;
-  /** The field's own value — the condition, the iterated expression, the
-   * guarded node id, or the error policy. */
-  value: string;
-  /** `repeatUntil` only: the iteration cap the engine will apply. */
-  maxRepeats?: number;
-}
-
-/**
- * The badges for one node. `onError: 'fail'` is the engine default and says
- * nothing an author did not already assume, so only `continue` shows.
- */
-export function controlFlowBadges(node: NodeDef): ControlFlowBadge[] {
-  const badges: ControlFlowBadge[] = [];
-  if (node.when !== undefined) badges.push({ kind: 'when', value: node.when });
-  if (node.elseOf !== undefined) {
-    badges.push({ kind: 'elseOf', value: node.elseOf });
-  }
-  if (node.forEach !== undefined) {
-    badges.push({ kind: 'forEach', value: node.forEach });
-  }
-  if (node.repeatUntil !== undefined) {
-    badges.push({
-      kind: 'repeatUntil',
-      value: node.repeatUntil,
-      ...(node.maxRepeats !== undefined && { maxRepeats: node.maxRepeats }),
-    });
-  }
-  if (node.onError === 'continue') {
-    badges.push({ kind: 'onError', value: node.onError });
-  }
-  return badges;
-}
-
-/** The node label lives in `./node-label`, which loads without the parser;
- * re-exported here for the readers that already hold the graph. */
-export { humanizeNodeId } from './node-label';
-
-/** Everything the canvas needs about one document, derived in one pass. */
+/** The nodes of one document in execution order and the references between
+ * them, derived in one pass (a run's step list reads them). */
 export interface AutomationGraph {
   nodes: NodeDef[];
   edges: DerivedEdge[];
-  ranks: Map<string, number>;
   /** True when the references form a cycle: the order shown is document order,
    * not execution order. */
   hasCycle: boolean;
@@ -168,5 +93,5 @@ export function buildGraph(automation: Automation | null): AutomationGraph {
   const source = automation?.nodes ?? [];
   const { nodes, hasCycle } = orderedNodes(source);
   const edges = deriveEdges(nodes);
-  return { nodes, edges, ranks: rankNodes(nodes, edges), hasCycle };
+  return { nodes, edges, hasCycle };
 }
diff --git a/services/platform/app/features/automations/lib/issues.test.ts b/services/platform/app/features/automations/lib/issues.test.ts
index 6fdd591a46..1b459dfe5c 100644
--- a/services/platform/app/features/automations/lib/issues.test.ts
+++ b/services/platform/app/features/automations/lib/issues.test.ts
@@ -101,6 +101,47 @@ describe('issueCountsByNode', () => {
     );
     expect(counts.get('draft_reply')).toEqual({ errors: 1, warnings: 1 });
     expect(counts.get('fetch_issues')).toEqual({ errors: 0, warnings: 1 });
+    expect(counts.get('__end')).toEqual({ errors: 1, warnings: 0 });
+  });
+
+  it('marks a condition, Start and End on their own boxes', () => {
+    const doc: Automation = {
+      ...DOC,
+      nodes: [
+        ...DOC.nodes,
+        {
+          id: 'notify',
+          type: 'transform',
+          when: '{{ nodes.nope.output }}',
+          code: 'return 1;',
+        },
+      ],
+    };
+    const counts = issueCountsByNode(
+      [
+        issue({ code: 'A', at: { pointer: '/nodes/2/when', range: [3, 8] } }),
+        issue({ code: 'B', at: { pointer: '/nodes/2/code' } }),
+        issue({ code: 'C', at: { pointer: '/inputs/properties/email' } }),
+        issue({
+          code: 'TRIGGER_INPUT_MISMATCH',
+          level: 'warning',
+          at: { pointer: '/inputs' },
+        }),
+        issue({ code: 'D', at: { pointer: '/output/summary' } }),
+        // The document's name is on no box: Problems lists it.
+        issue({ code: 'E', at: { pointer: '/name' } }),
+        // A `when` that is no string draws no condition: the node has it.
+        issue({ code: 'F', at: { pointer: '/nodes/0/when' } }),
+      ],
+      doc,
+    );
+    expect(Object.fromEntries(counts)).toEqual({
+      '__gate:notify': { errors: 1, warnings: 0 },
+      notify: { errors: 1, warnings: 0 },
+      __start: { errors: 1, warnings: 1 },
+      __end: { errors: 1, warnings: 0 },
+      fetch_issues: { errors: 1, warnings: 0 },
+    });
   });
 });
 
diff --git a/services/platform/app/features/automations/lib/issues.ts b/services/platform/app/features/automations/lib/issues.ts
index 5a12163372..322dfb6be8 100644
--- a/services/platform/app/features/automations/lib/issues.ts
+++ b/services/platform/app/features/automations/lib/issues.ts
@@ -18,6 +18,7 @@ import { pointerTokens } from '@/lib/engine/core/syntax/pointer';
 import type { Automation, NodeDef } from '@/lib/engine/core/types';
 import type { WireAutomationIssue } from '@/lib/shared/schemas/automation-issues';
 
+import { END_ID, START_ID, gateIdOf } from './flow-ids';
 import {
   issueText,
   type IssueTextContext,
@@ -159,18 +160,45 @@ function nodeOf(
   return null;
 }
 
-/** Errors and warnings per node id, for the canvas markers. */
+/**
+ * The canvas box an issue is marked on: Start for the run input (and a
+ * trigger whose wrapper the input schema refuses), End for the output, a
+ * node's condition for its `when`, else the node. A place the canvas does
+ * not draw (the name, the tests) has none: Problems lists it.
+ */
+function canvasBoxOf(
+  issue: WireAutomationIssue,
+  doc: Automation,
+): string | null {
+  const tokens = pointerTokens(pointerOf(issue));
+  if (tokens[0] === 'inputs' || issue.code === 'TRIGGER_INPUT_MISMATCH') {
+    return START_ID;
+  }
+  if (tokens[0] === 'output') return END_ID;
+  const found = nodeOf(issue, doc);
+  if (found === null) return null;
+  const inWhen =
+    tokens[0] === 'nodes' &&
+    tokens[1] === String(found.index) &&
+    tokens[2] === 'when';
+  return inWhen && typeof found.node.when === 'string'
+    ? gateIdOf(found.node.id)
+    : found.node.id;
+}
+
+/** Errors and warnings per canvas box (a node, its condition, Start or
+ *  End), for the canvas markers. */
 export function issueCountsByNode(
   issues: readonly WireAutomationIssue[],
   doc: Automation,
 ): ReadonlyMap<string, IssueCounts> {
   const counts = new Map<string, IssueCounts>();
   for (const issue of issues) {
-    const found = nodeOf(issue, doc);
-    if (found === null) continue;
-    const current = counts.get(found.node.id) ?? { errors: 0, warnings: 0 };
+    const box = canvasBoxOf(issue, doc);
+    if (box === null) continue;
+    const current = counts.get(box) ?? { errors: 0, warnings: 0 };
     counts.set(
-      found.node.id,
+      box,
       issue.level === 'error'
         ? { ...current, errors: current.errors + 1 }
         : { ...current, warnings: current.warnings + 1 },
diff --git a/services/platform/app/features/automations/lib/node-face.test.ts b/services/platform/app/features/automations/lib/node-face.test.ts
new file mode 100644
index 0000000000..88881db5ae
--- /dev/null
+++ b/services/platform/app/features/automations/lib/node-face.test.ts
@@ -0,0 +1,233 @@
+import { Bot, Braces, CircleHelp, Sparkles, Workflow } from 'lucide-react';
+import { describe, expect, it } from 'vitest';
+
+import type { NodeDef } from '@/lib/engine/core/types';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { mergeNodeTypes } from '../hooks/backend';
+import {
+  catalogLabel,
+  nodeCatalogView,
+  nodeFace,
+  nodeIcon,
+  nodeTitle,
+  type NodeFaceContext,
+} from './node-face';
+
+/**
+ * What a node's box says about the node itself: its title, its kind in
+ * words (a connector's action in the reader's language), its icon, what it
+ * returns, and the marks that change how it behaves.
+ */
+
+const CATALOG = nodeCatalogView(
+  mergeNodeTypes([
+    {
+      type: 'github.list_issues',
+      kind: 'connector',
+      description: 'List issues',
+      allowedFields: ['input'],
+      requiredFields: [],
+      outputKind: 'structured',
+      connector: 'github',
+      title: 'List issues',
+      i18n: {
+        de: { title: 'Issues auflisten' },
+        fr: { title: 'Lister les tickets' },
+      },
+    },
+    {
+      type: 'tasks.update_status',
+      kind: 'connector',
+      description: 'Update status',
+      allowedFields: ['input'],
+      requiredFields: [],
+      outputKind: 'structured',
+      hasEffect: true,
+      connector: 'tasks',
+      title: 'Change task status',
+      i18n: { de: { title: 'Aufgabenstatus ändern' } },
+    },
+  ]),
+  [
+    { name: 'github', displayName: 'GitHub', iconUrl: 'data:image/svg+xml,x' },
+    {
+      name: 'tasks',
+      displayName: 'Tasks',
+      i18n: { de: { displayName: 'Aufgaben' } },
+    },
+  ],
+);
+
+function ctx(
+  locale = 'en',
+  extra: Partial<NodeFaceContext> = {},
+): NodeFaceContext {
+  return {
+    t: i18n.getFixedT(locale, 'automations'),
+    locale,
+    catalog: CATALOG,
+    returns: { status: 'off', outputs: null },
+    ...extra,
+  };
+}
+
+const node = (def: Partial<NodeDef> & { id: string; type: string }) =>
+  def as NodeDef;
+
+describe('nodeTitle', () => {
+  it('reads an id as words with a capital', () => {
+    expect(nodeTitle('open_issues')).toBe('Open issues');
+    expect(nodeTitle('a')).toBe('A');
+  });
+});
+
+describe('catalogLabel', () => {
+  it('names a connector action by its connector and title', () => {
+    const issues = node({ id: 'issues', type: 'github.list_issues' });
+    expect(catalogLabel(issues, ctx())).toBe('GitHub · List issues');
+    expect(catalogLabel(issues, ctx('de'))).toBe('GitHub · Issues auflisten');
+    expect(catalogLabel(issues, ctx('fr'))).toBe('GitHub · Lister les tickets');
+    // A regional language falls back to its base language.
+    expect(catalogLabel(issues, ctx('de-CH'))).toBe(
+      'GitHub · Issues auflisten',
+    );
+  });
+
+  it('translates a connector named with ordinary words', () => {
+    const update = node({ id: 'mark', type: 'tasks.update_status' });
+    expect(catalogLabel(update, ctx('de'))).toBe(
+      'Aufgaben · Aufgabenstatus ändern',
+    );
+  });
+
+  it('falls back to the action id in words when the catalog has no title', () => {
+    expect(
+      catalogLabel(node({ id: 'x', type: 'slack.post_message' }), ctx()),
+    ).toBe('slack · Post message');
+  });
+
+  it('names the core types, with the model a model node calls', () => {
+    expect(catalogLabel(node({ id: 'x', type: 'transform' }), ctx())).toBe(
+      'Transform',
+    );
+    expect(
+      catalogLabel(
+        node({ id: 'x', type: 'llm', model: 'anthropic/claude-haiku-4-5' }),
+        ctx('en', { modelLabel: () => 'Claude Haiku 4.5' }),
+      ),
+    ).toBe('Language model · Claude Haiku 4.5');
+    expect(
+      catalogLabel(node({ id: 'x', type: 'agent', model: 'gpt-5' }), ctx('de')),
+    ).toBe('Agent · gpt-5');
+    expect(
+      catalogLabel(
+        node({
+          id: 'x',
+          type: 'subautomation',
+          automation: 'billing/send_dunning',
+        }),
+        ctx(),
+      ),
+    ).toBe('Calls send dunning');
+    expect(catalogLabel(node({ id: 'x', type: 'subautomation' }), ctx())).toBe(
+      'Calls an automation',
+    );
+    expect(catalogLabel(node({ id: 'x', type: 'mystery' }), ctx())).toBe(
+      'Unknown type mystery',
+    );
+  });
+});
+
+describe('nodeIcon', () => {
+  it('draws core types with their own glyph and connectors with their icon', () => {
+    expect(nodeIcon(node({ id: 'x', type: 'transform' }), CATALOG)).toBe(
+      Braces,
+    );
+    expect(nodeIcon(node({ id: 'x', type: 'llm' }), CATALOG)).toBe(Sparkles);
+    expect(nodeIcon(node({ id: 'x', type: 'agent' }), CATALOG)).toBe(Bot);
+    expect(nodeIcon(node({ id: 'x', type: 'subautomation' }), CATALOG)).toBe(
+      Workflow,
+    );
+    expect(nodeIcon(node({ id: 'x', type: 'mystery' }), CATALOG)).toBe(
+      CircleHelp,
+    );
+    const github = nodeIcon(
+      node({ id: 'x', type: 'github.list_issues' }),
+      CATALOG,
+    );
+    // One component per icon, so a box keeps its loaded image.
+    expect(
+      nodeIcon(node({ id: 'y', type: 'github.list_issues' }), CATALOG),
+    ).toBe(github);
+  });
+});
+
+describe('nodeFace', () => {
+  it('reserves the returns row until the check answers, then shows the shape', () => {
+    const issues = node({ id: 'issues', type: 'github.list_issues' });
+    expect(
+      nodeFace(issues, ctx('en', { returns: { status: 'off', outputs: null } }))
+        .returns,
+    ).toBeUndefined();
+    expect(
+      nodeFace(
+        issues,
+        ctx('en', { returns: { status: 'pending', outputs: null } }),
+      ).returns,
+    ).toBeNull();
+    const ready = nodeFace(
+      issues,
+      ctx('en', {
+        returns: {
+          status: 'ready',
+          outputs: {
+            issues: {
+              type: 'object',
+              properties: {
+                issues: { type: 'array', items: { type: 'object' } },
+              },
+              required: ['issues'],
+            },
+          },
+        },
+      }),
+    );
+    expect(ready.returns).toEqual({
+      text: '{ issues: Array<object> }',
+      code: true,
+    });
+    expect(ready.sentences).toContain('Returns { issues: Array<object> }');
+    expect(
+      nodeFace(
+        issues,
+        ctx('en', { returns: { status: 'ready', outputs: { issues: {} } } }),
+      ).returns,
+    ).toEqual({ text: 'Shape known after a run', code: false });
+  });
+
+  it('marks a write, a question, an unpinned model and a tolerated failure', () => {
+    const write = nodeFace(
+      node({ id: 'mark', type: 'tasks.update_status', onError: 'continue' }),
+      ctx(),
+    );
+    expect(write.chips).toEqual([
+      { id: 'onError', label: 'Continues on error', tone: 'error' },
+    ]);
+    expect(write.markers.map((marker) => marker.label)).toEqual([
+      'Changes data in Tasks. A live run may wait for approval.',
+    ]);
+    const agent = nodeFace(
+      node({ id: 'helper', type: 'agent', model: 'gpt-5' }),
+      ctx(),
+    );
+    expect(agent.markers.map((marker) => marker.id)).toEqual([
+      'asks',
+      'unpinnedModel',
+    ]);
+    expect(agent.sentences).toEqual([
+      'May ask a question and wait for the answer.',
+      'No pinned provider — each run picks one automatically.',
+    ]);
+  });
+});
diff --git a/services/platform/app/features/automations/lib/node-face.ts b/services/platform/app/features/automations/lib/node-face.ts
new file mode 100644
index 0000000000..6cf89bb620
--- /dev/null
+++ b/services/platform/app/features/automations/lib/node-face.ts
@@ -0,0 +1,295 @@
+/**
+ * What a node's box on the canvas says: an icon, its title, what kind of
+ * node it is ("GitHub · List issues", "Language model · claude-haiku-4-5"),
+ * what it returns, and the marks that change how it behaves (it writes, it
+ * may ask, it goes on after a failure).
+ *
+ * Built from the document and the node-type catalog alone, so the box
+ * reads the same for every viewer. What it returns comes from the draft
+ * check's inferred types when the reader may have the document checked;
+ * the row is reserved until the check answers, so its arrival never moves
+ * a box.
+ */
+
+import type { FlowChip, FlowIcon, FlowMarker } from '@tale/ui/flow/types';
+import { VendorIcon } from '@tale/ui/vendor-icon';
+import {
+  Bot,
+  Braces,
+  CircleHelp,
+  MessageCircleQuestion,
+  PinOff,
+  ShieldCheck,
+  Sparkles,
+  Workflow,
+} from 'lucide-react';
+import { createElement } from 'react';
+
+import type { NodeDef } from '@/lib/engine/core/types';
+import { isUnknown, toTs, type Shape } from '@/lib/engine/core/typing/shape';
+import type { NodeTypeCatalog } from '@/lib/shared/schemas/node-type-catalog';
+
+import type { NodeTypeSummary } from '../hooks/backend';
+import type { ConditionTranslate } from './condition-text';
+import { humanizeNodeId } from './node-label';
+
+export type ConnectorDisplay = NodeTypeCatalog['connectors'][number];
+
+/** The node-type catalog, keyed for lookups. */
+export interface NodeCatalogView {
+  types: ReadonlyMap<string, NodeTypeSummary>;
+  connectors: ReadonlyMap<string, ConnectorDisplay>;
+}
+
+export function nodeCatalogView(
+  nodeTypes: readonly NodeTypeSummary[],
+  connectors: readonly ConnectorDisplay[] = [],
+): NodeCatalogView {
+  return {
+    types: new Map(nodeTypes.map((def) => [def.type, def])),
+    connectors: new Map(connectors.map((entry) => [entry.name, entry])),
+  };
+}
+
+/** What the draft check said each node returns, when the reader may have
+ *  the document checked. */
+export interface ReturnsSource {
+  /**
+   * `off`: nobody checks this document for this reader (no row at all);
+   * `pending`: no answer yet (the row is reserved);
+   * `ready`/`failed`: the last answer, or none when the check failed.
+   */
+  status: 'off' | 'pending' | 'ready' | 'failed';
+  outputs: Readonly<Record<string, Shape>> | null;
+}
+
+export interface NodeFaceContext {
+  t: ConditionTranslate;
+  locale: string;
+  catalog: NodeCatalogView;
+  /** A served model's display name; the id as written when unknown. */
+  modelLabel?: (id: string) => string | undefined;
+  returns: ReturnsSource;
+}
+
+/** A node's title on its box: its id in words, capitalised ("Open
+ *  issues"). Sentences about nodes use the same title, so a reader finds
+ *  the box a sentence names. */
+export function nodeTitle(id: string): string {
+  const words = humanizeNodeId(id);
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+const CORE_ICONS: Readonly<Record<string, FlowIcon>> = {
+  transform: Braces,
+  llm: Sparkles,
+  agent: Bot,
+  subautomation: Workflow,
+};
+
+const CORE_TYPES: ReadonlySet<string> = new Set(Object.keys(CORE_ICONS));
+
+/** A per-URL icon component: a box re-rendering with the same connector
+ *  keeps the same component, and so its loaded image. */
+const vendorIcons = new Map<string, FlowIcon>();
+
+function vendorIcon(url: string | undefined): FlowIcon {
+  const key = url ?? '';
+  let icon = vendorIcons.get(key);
+  if (icon === undefined) {
+    const Icon = ({ className }: { className?: string }) =>
+      createElement(VendorIcon, {
+        ...(url !== undefined && { iconUrl: url }),
+        ...(className !== undefined && { className }),
+      });
+    Icon.displayName = 'ConnectorIcon';
+    icon = Icon;
+    vendorIcons.set(key, icon);
+  }
+  return icon;
+}
+
+/** A per-locale override: the exact tag, then its base language, then
+ *  the English. */
+function localized<T extends string>(
+  english: string | undefined,
+  overrides: Readonly<Record<string, Partial<Record<T, string>>>> | undefined,
+  field: T,
+  locale: string,
+): string | undefined {
+  const base = locale.split('-')[0] ?? locale;
+  return overrides?.[locale]?.[field] ?? overrides?.[base]?.[field] ?? english;
+}
+
+/** The connector a `<connector>.<action>` type belongs to, and the action. */
+function connectorParts(
+  type: string,
+): { connector: string; action: string } | null {
+  const dot = type.indexOf('.');
+  if (dot <= 0 || dot === type.length - 1) return null;
+  return { connector: type.slice(0, dot), action: type.slice(dot + 1) };
+}
+
+/** A connector's name in the reader's language. */
+function connectorName(
+  slug: string,
+  catalog: NodeCatalogView,
+  locale: string,
+): string {
+  const entry = catalog.connectors.get(slug);
+  if (entry === undefined) return slug;
+  return (
+    localized(entry.displayName, entry.i18n, 'displayName', locale) ?? slug
+  );
+}
+
+/** The node's icon: the connector's own, or one per core type. */
+export function nodeIcon(node: NodeDef, catalog: NodeCatalogView): FlowIcon {
+  const core = CORE_ICONS[node.type];
+  if (core !== undefined) return core;
+  const parts = connectorParts(node.type);
+  if (parts === null) return CircleHelp;
+  return vendorIcon(catalog.connectors.get(parts.connector)?.iconUrl);
+}
+
+/** A core type's word: "Transform", "Language model", "Agent". */
+function coreTypeWord(type: string, t: ConditionTranslate): string {
+  switch (type) {
+    case 'llm':
+      return t('canvas.node.catalog.llm');
+    case 'agent':
+      return t('canvas.node.catalog.agent');
+    default:
+      return t('canvas.node.catalog.transform');
+  }
+}
+
+/** "GitHub · List issues", "Transform", "Language model · claude-haiku-4-5". */
+export function catalogLabel(node: NodeDef, ctx: NodeFaceContext): string {
+  const { t, catalog, locale } = ctx;
+  if (CORE_TYPES.has(node.type)) {
+    if (node.type === 'subautomation') {
+      return typeof node.automation === 'string' && node.automation !== ''
+        ? t('canvas.node.catalog.subautomation', {
+            automation: humanizeNodeId(
+              node.automation.split('/').at(-1) ?? node.automation,
+            ),
+          })
+        : t('canvas.node.catalog.subautomationUnset');
+    }
+    const type = coreTypeWord(node.type, t);
+    if (
+      (node.type === 'llm' || node.type === 'agent') &&
+      typeof node.model === 'string' &&
+      node.model !== ''
+    ) {
+      return t('canvas.node.catalog.withModel', {
+        type,
+        model: ctx.modelLabel?.(node.model) ?? node.model,
+      });
+    }
+    return type;
+  }
+  const parts = connectorParts(node.type);
+  if (parts === null) {
+    return t('canvas.node.catalog.unknown', { type: node.type });
+  }
+  const entry = catalog.types.get(node.type);
+  const action =
+    localized(entry?.title, entry?.i18n, 'title', locale) ??
+    nodeTitle(parts.action);
+  return t('canvas.node.catalog.connector', {
+    connector: connectorName(parts.connector, catalog, locale),
+    action,
+  });
+}
+
+/**
+ * An agent that names a model but not a provider — the same predicate the
+ * store uses for `deployedUnpinnedAgentNodes`. The run walks connectors at
+ * kick time; the editor's preselect can look pinned.
+ */
+function agentHasUnpinnedModel(node: NodeDef): boolean {
+  if (node.type !== 'agent') return false;
+  if (typeof node.model !== 'string' || node.model === '') return false;
+  return typeof node.modelProvider !== 'string' || node.modelProvider === '';
+}
+
+/** What the node returns: a shape, a sentence, a reserved row, or none. */
+function returnsOf(
+  node: NodeDef,
+  ctx: NodeFaceContext,
+): { text: string; code: boolean } | null | undefined {
+  const { status, outputs } = ctx.returns;
+  if (status === 'off') return undefined;
+  const known = CORE_TYPES.has(node.type) || connectorParts(node.type) !== null;
+  if (!known) return undefined;
+  const shape = outputs?.[node.id];
+  if (shape === undefined) {
+    return status === 'pending'
+      ? null
+      : { text: ctx.t('canvas.node.returnsUnknown'), code: false };
+  }
+  return isUnknown(shape)
+    ? { text: ctx.t('canvas.node.returnsUnknown'), code: false }
+    : { text: toTs(shape, 1), code: true };
+}
+
+export interface NodeFace {
+  label: string;
+  icon: FlowIcon;
+  typeLabel: string;
+  returns: { text: string; code: boolean } | null | undefined;
+  chips: FlowChip[];
+  markers: FlowMarker[];
+  /** The sentences the chips, markers and returns row stand for. */
+  sentences: string[];
+}
+
+/** Everything a node's box says that comes from the node itself. */
+export function nodeFace(node: NodeDef, ctx: NodeFaceContext): NodeFace {
+  const { t, catalog, locale } = ctx;
+  const chips: FlowChip[] = [];
+  const markers: FlowMarker[] = [];
+  const sentences: string[] = [];
+  const returns = returnsOf(node, ctx);
+  if (returns?.code === true) {
+    sentences.push(t('canvas.node.returns', { shape: returns.text }));
+  } else if (returns !== undefined && returns !== null) {
+    sentences.push(returns.text);
+  }
+  if (node.onError === 'continue') {
+    const label = t('canvas.controlFlow.onError');
+    chips.push({ id: 'onError', label, tone: 'error' });
+    sentences.push(label);
+  }
+  const parts = connectorParts(node.type);
+  if (parts !== null && catalog.types.get(node.type)?.hasEffect === true) {
+    const label = t('canvas.node.writes', {
+      connector: connectorName(parts.connector, catalog, locale),
+    });
+    markers.push({ id: 'writes', icon: ShieldCheck, label });
+    sentences.push(label);
+  }
+  if (node.type === 'agent') {
+    const label = t('canvas.node.asks');
+    markers.push({ id: 'asks', icon: MessageCircleQuestion, label });
+    sentences.push(label);
+  }
+  if (agentHasUnpinnedModel(node)) {
+    // A note, not a problem: a muted glyph of its own, so it never reads
+    // as a warning the issue count beside it leaves out.
+    const label = t('canvas.unpinnedModel');
+    markers.push({ id: 'unpinnedModel', icon: PinOff, label });
+    sentences.push(label);
+  }
+  return {
+    label: nodeTitle(node.id),
+    icon: nodeIcon(node, catalog),
+    typeLabel: catalogLabel(node, ctx),
+    returns,
+    chips,
+    markers,
+    sentences,
+  };
+}
diff --git a/services/platform/app/features/automations/lib/paths.test.ts b/services/platform/app/features/automations/lib/paths.test.ts
new file mode 100644
index 0000000000..704d6b90ce
--- /dev/null
+++ b/services/platform/app/features/automations/lib/paths.test.ts
@@ -0,0 +1,211 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+import { parse } from 'yaml';
+
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { mergeNodeTypes } from '../hooks/backend';
+import { toFlowGraph } from './flow-graph';
+import { gateIdOf } from './flow-ids';
+import { nodeCatalogView } from './node-face';
+import { automationPaths, type PathsContext } from './paths';
+
+/**
+ * The Paths list and its highlights, from the flow analysis the browser
+ * runs itself: a row per distinct successful path with the decisions that
+ * make it, the nodes that end a run when they fail, and what the chart
+ * brings forward for each.
+ */
+
+const REPO = path.resolve(import.meta.dirname, '../../../../../..');
+const t = i18n.getFixedT('en', 'automations');
+
+function paths(doc: Automation, extra: Partial<PathsContext> = {}) {
+  const flow = analyzeFlow(doc.nodes);
+  if (flow === null) throw new Error('cycle');
+  const { graph } = toFlowGraph(doc, {
+    t,
+    tSchema: i18n.getFixedT('en', 'schemaTree'),
+    locale: 'en',
+    catalog: nodeCatalogView(mergeNodeTypes([])),
+    returns: { status: 'off', outputs: null },
+    triggers: [],
+    flow,
+  });
+  const byId = new Map(doc.nodes.map((node) => [node.id, node]));
+  return {
+    graph,
+    paths: automationPaths(flow, graph, {
+      t,
+      locale: 'en',
+      elseOf: (id) => byId.get(id)?.elseOf,
+      ...extra,
+    }),
+  };
+}
+
+const inbox: Automation = parse(
+  readFileSync(
+    path.join(
+      REPO,
+      'configs/platform/custom/automations/gmail/triage-inbox/workflow.yml',
+    ),
+    'utf8',
+  ),
+) as Automation;
+
+const doc = (...nodes: NodeDef[]): Automation => ({ name: 'test', nodes });
+
+/** `count` independent conditions on the run input. */
+function conditions(count: number): Automation {
+  return doc(
+    ...Array.from({ length: count }, (_, i) => ({
+      id: `n${i}`,
+      type: 'transform',
+      when: `{{ input.c${i} }}`,
+      code: 'return 1;',
+    })),
+  );
+}
+
+describe('automationPaths', () => {
+  it('lists every way Triage inbox can go, with the decisions that make it', () => {
+    const { paths: result } = paths(inbox);
+    expect(result.count).toBe(3);
+    const [list, halts] = result.sections;
+    expect(
+      list?.rows.map((row) => [
+        row.title,
+        row.meta,
+        row.clauses?.map((clause) => `${clause.label} (${clause.tone})`),
+      ]),
+    ).toEqual([
+      [
+        'Path 1',
+        '6 of 6 nodes run',
+        ['Triage runs (positive)', 'Propose succeeds (neutral)'],
+      ],
+      [
+        'Path 2',
+        '5 of 6 nodes run',
+        ['Triage runs (positive)', 'Propose fails, the run goes on (error)'],
+      ],
+      ['Path 3', '1 of 6 nodes runs', ['Triage is skipped (negative)']],
+    ]);
+    expect(list?.footer).toBeUndefined();
+    expect(halts?.title).toBe('Ends the run when it fails');
+    expect(halts?.rows.map((row) => [row.title, row.pinnable])).toEqual([
+      ['Inbox', false],
+      ['Triage', false],
+      ['Record', false],
+      ['Due', false],
+      ['Draft', false],
+    ]);
+  });
+
+  it('says why a halting node fails once the server said', () => {
+    const { paths: result } = paths(inbox, {
+      halts: [{ nodeId: 'inbox', reasons: ['external', 'input-contract'] }],
+    });
+    expect(result.sections[1]?.rows[0]?.title).toBe(
+      'Inbox fails when a service it calls fails or its input is refused',
+    );
+  });
+
+  it('brings a path forward and says why each other node steps back', () => {
+    const { paths: result, graph } = paths(inbox);
+    const preview = result.highlightFor('path:3', false);
+    expect(preview?.announcement).toBeUndefined();
+    expect([...(preview?.nodes ?? [])].sort()).toEqual(
+      ['__end', '__start', gateIdOf('triage'), 'inbox'].sort(),
+    );
+    expect(preview?.reasons).toEqual({
+      triage: 'Skipped: condition false',
+      record: 'Skipped: Triage is skipped',
+      due: 'Skipped: Triage is skipped',
+      draft: 'Skipped: Due is skipped',
+      propose: 'Skipped: Draft is skipped',
+    });
+    // The condition's line into Triage is not on a path where it was false.
+    expect(preview?.edges.has(`${gateIdOf('triage')}>triage`)).toBe(false);
+    expect(preview?.edges.has('inbox>__gate:triage')).toBe(true);
+    expect(graph.edges.some((edge) => edge.id === 'inbox>__gate:triage')).toBe(
+      true,
+    );
+    expect(result.highlightFor('path:3', true)?.announcement).toBe(
+      'Showing path 3: 1 of 6 nodes runs.',
+    );
+    expect([...(result.ranOn('path:3') ?? [])]).toEqual(['inbox']);
+  });
+
+  it('rings every halting node in red when one of them is pointed at', () => {
+    const { paths: result } = paths(inbox);
+    const halts = result.highlightFor('halt:due', false);
+    expect(halts?.tone).toBe('error');
+    expect([...(halts?.nodes ?? [])].sort()).toEqual(
+      ['draft', 'due', 'inbox', 'record', 'triage'].sort(),
+    );
+    expect(result.haltNode('halt:due')).toBe('due');
+    expect(result.haltNode('path:1')).toBeNull();
+  });
+
+  it('says every run takes one path instead of listing it', () => {
+    const { paths: result } = paths(
+      doc(
+        { id: 'a', type: 'transform', code: 'return 1;' },
+        {
+          id: 'b',
+          type: 'transform',
+          input: { x: '{{ nodes.a.output }}' },
+          code: 'return 1;',
+        },
+      ),
+    );
+    expect(result.sections[0]?.rows).toEqual([]);
+    expect(result.sections[0]?.footer).toBe(
+      'Every run takes the same path: all 2 nodes run.',
+    );
+  });
+
+  it('lists 32 paths and counts the rest', () => {
+    const { paths: result } = paths(conditions(6));
+    expect(result.count).toBe(64);
+    expect(result.sections[0]?.rows).toHaveLength(32);
+    expect(result.sections[0]?.footer).toBe("32 more paths aren't listed");
+    expect(result.flowPaths).toHaveLength(64);
+  });
+
+  it('lists no path when there are too many conditions', () => {
+    const { paths: result } = paths(conditions(13));
+    expect(result.truncated).toBe(true);
+    expect(result.sections[0]?.rows).toEqual([]);
+    expect(result.sections[0]?.footer).toBe(
+      'This automation has 13 conditions, too many to list every path. Each node still says when it runs.',
+    );
+  });
+
+  it('says an else partner was skipped because its node ran', () => {
+    const { paths: result } = paths(
+      doc(
+        {
+          id: 'urgent',
+          type: 'transform',
+          when: '{{ input.urgent }}',
+          code: 'return 1;',
+        },
+        { id: 'normal', type: 'transform', elseOf: 'urgent', code: '' },
+      ),
+    );
+    const yes = result.flowPaths.find(
+      (candidate) => candidate.decisions['when:urgent'],
+    );
+    expect(yes?.nodes).toEqual(['urgent', gateIdOf('urgent')]);
+    expect(result.highlightFor(yes?.id ?? '', false)?.reasons).toEqual({
+      normal: 'Skipped: Urgent runs',
+    });
+  });
+});
diff --git a/services/platform/app/features/automations/lib/paths.ts b/services/platform/app/features/automations/lib/paths.ts
new file mode 100644
index 0000000000..deff493a38
--- /dev/null
+++ b/services/platform/app/features/automations/lib/paths.ts
@@ -0,0 +1,304 @@
+/**
+ * The possible paths of an automation, as the canvas's Paths list shows
+ * them and the chart highlights them.
+ *
+ * The flow analysis (`analyzeFlow`, the same code the server's check runs)
+ * replays a run for every way its conditions and tolerated failures can
+ * go, and keeps each distinct outcome: which nodes run, which are skipped
+ * and why. It runs in the browser on the document on screen, so every
+ * viewer sees the paths of every version at once, without asking the
+ * server. Only the reasons a node can fail come from the server's check,
+ * when it has answered.
+ *
+ * A path row says how many nodes run and the decisions that make it
+ * ("Triage runs", "Propose fails, the run goes on"); pointing at it
+ * previews it on the chart, pinning it keeps it there — the rest steps
+ * back, each skipped node saying why. A second section lists the nodes
+ * that end a run when they fail.
+ */
+
+import type {
+  FlowPathClause,
+  FlowPathListRow,
+  FlowPathListSection,
+} from '@tale/ui/flow/flow-path-list';
+import {
+  highlightForNodes,
+  highlightForPaths,
+  type FlowHighlight,
+  type FlowPath,
+} from '@tale/ui/flow/paths';
+import type { FlowGraph } from '@tale/ui/flow/types';
+
+import type { FlowFacts, PathOutcome } from '@/lib/engine/core/analysis/flow';
+import { MAX_LISTED_PATHS } from '@/lib/engine/core/analysis/summary';
+
+import type { ConditionTranslate } from './condition-text';
+import { decisionKeyOf, flowGraphTarget, gateIdOf } from './flow-ids';
+import { nodeTitle } from './node-face';
+
+/** What can make a node fail, as the server's check names it, in words;
+ *  null for a reason a newer server names and this build has no words
+ *  for. */
+function failureReasonWords(
+  reason: string,
+  t: ConditionTranslate,
+): string | null {
+  switch (reason) {
+    case 'external':
+      return t('failureReason.external');
+    case 'code':
+      return t('failureReason.code');
+    case 'expression':
+      return t('failureReason.expression');
+    case 'iteration':
+      return t('failureReason.iteration');
+    case 'input-contract':
+      return t('failureReason.inputContract');
+    case 'subautomation':
+      return t('failureReason.subautomation');
+    default:
+      return null;
+  }
+}
+
+const PATHS_SECTION = 'paths';
+const HALTS_SECTION = 'halts';
+
+const HALT_PREFIX = 'halt:';
+
+export interface PathRowInfo {
+  /** Counted from one, as the list names it. */
+  index: number;
+  ran: number;
+  total: number;
+}
+
+export interface AutomationPaths {
+  /** Every distinct successful path, for the chart's hover on a
+   *  condition or a Yes or No. */
+  flowPaths: readonly FlowPath[];
+  /** The Paths list: the paths, then the nodes that end a run when they
+   *  fail. */
+  sections: readonly FlowPathListSection[];
+  /** Distinct successful paths in total (none listed when `truncated`). */
+  count: number;
+  /** Too many conditions to list the paths. */
+  truncated: boolean;
+  /** The row of each listed path. */
+  rows: ReadonlyMap<string, PathRowInfo>;
+  /** What the chart brings forward for a row; `pinned` adds the sentence
+   *  a screen reader hears once. */
+  highlightFor(rowId: string, pinned: boolean): FlowHighlight | null;
+  /** The nodes that run on a path row, for End's "empty on this path". */
+  ranOn(rowId: string): ReadonlySet<string> | null;
+  /** The node a halting-node row stands for. */
+  haltNode(rowId: string): string | null;
+}
+
+export interface PathsContext {
+  t: ConditionTranslate;
+  locale: string;
+  /** Each node's `elseOf`, for "Skipped: Urgent runs". */
+  elseOf: (nodeId: string) => string | undefined;
+  /** What can make each halting node fail, when the server said. */
+  halts?: ReadonlyArray<{ nodeId: string; reasons: readonly string[] }>;
+}
+
+/** The nodes and conditions a path goes through, and how each condition
+ *  decided. A condition is on a path when it was evaluated there: its
+ *  node ran, failed after it, or was skipped by it. */
+function flowPathOf(
+  flow: FlowFacts,
+  path: PathOutcome,
+  id: string,
+  gated: ReadonlySet<string>,
+): FlowPath {
+  const nodes: string[] = [...path.ran];
+  const decisions: Record<string, boolean> = {};
+  for (const nodeId of flow.order) {
+    if (!gated.has(nodeId)) continue;
+    const outcome = flow.outcomeOf(path, nodeId);
+    if (outcome === 'ran' || outcome === 'when' || outcome === 'error') {
+      nodes.push(gateIdOf(nodeId));
+      decisions[decisionKeyOf(nodeId)] = outcome !== 'when';
+    }
+  }
+  return { id, nodes, decisions };
+}
+
+/** The Paths list and the highlights of one document's flow. */
+export function automationPaths(
+  flow: FlowFacts,
+  graph: FlowGraph,
+  ctx: PathsContext,
+): AutomationPaths {
+  const { t } = ctx;
+  const gated = new Set(
+    graph.nodes.flatMap((node) => {
+      const target = flowGraphTarget(node.id);
+      return target.kind === 'gate' ? [target.nodeId] : [];
+    }),
+  );
+  const total = flow.order.length;
+  const pathId = (index: number) => `path:${index + 1}`;
+  const flowPaths = flow.paths.map((path, index) =>
+    flowPathOf(flow, path, pathId(index), gated),
+  );
+  const byId = new Map(
+    flow.paths.map((path, index) => [pathId(index), { path, index }]),
+  );
+  const atomOrder = new Map(flow.atoms.map((atom, index) => [atom.id, index]));
+  const atomsById = new Map(flow.atoms.map((atom) => [atom.id, atom]));
+
+  const rows = new Map<string, PathRowInfo>();
+  const pathRows: FlowPathListRow[] = [];
+  const listed =
+    flow.paths.length > 1 ? flow.paths.slice(0, MAX_LISTED_PATHS) : [];
+  listed.forEach((path, index) => {
+    const id = pathId(index);
+    const info = { index: index + 1, ran: path.ran.length, total };
+    rows.set(id, info);
+    const clauses = Object.entries(path.assignment)
+      .sort(([a], [b]) => (atomOrder.get(a) ?? 0) - (atomOrder.get(b) ?? 0))
+      .flatMap(([atomId, value]): FlowPathClause[] => {
+        const atom = atomsById.get(atomId);
+        if (atom === undefined) return [];
+        const node = nodeTitle(atom.nodeId);
+        if (atom.kind === 'when') {
+          return [
+            {
+              id: atomId,
+              label: value
+                ? t('paths.clause.runs', { node })
+                : t('paths.clause.skipped', { node }),
+              tone: value ? 'positive' : 'negative',
+            },
+          ];
+        }
+        return [
+          {
+            id: atomId,
+            label: value
+              ? t('paths.clause.fails', { node })
+              : t('paths.clause.succeeds', { node }),
+            tone: value ? 'error' : 'neutral',
+          },
+        ];
+      });
+    pathRows.push({
+      id,
+      title: t('paths.row', { index: info.index }),
+      meta: t('paths.rowRuns', { ran: info.ran, total }),
+      ...(clauses.length > 0 && { clauses }),
+    });
+  });
+
+  const freeAtoms = flow.atoms.filter((atom) => atom.fixed !== true).length;
+  const footer = flow.truncated
+    ? t('paths.truncated', { count: freeAtoms })
+    : flow.paths.length === 1
+      ? t('paths.single', { count: flow.paths[0]?.ran.length ?? 0 })
+      : flow.paths.length > MAX_LISTED_PATHS
+        ? t('paths.more', { count: flow.paths.length - MAX_LISTED_PATHS })
+        : undefined;
+
+  const reasonsOf = new Map(
+    (ctx.halts ?? []).map((halt) => [halt.nodeId, halt.reasons]),
+  );
+  const haltIds = flow.halts.map((halt) => halt.nodeId);
+  const either = new Intl.ListFormat(ctx.locale, { type: 'disjunction' });
+  const haltRows: FlowPathListRow[] = haltIds.map((nodeId) => {
+    const words = (reasonsOf.get(nodeId) ?? []).flatMap((reason) => {
+      const text = failureReasonWords(reason, t);
+      return text === null ? [] : [text];
+    });
+    const node = nodeTitle(nodeId);
+    return {
+      id: `${HALT_PREFIX}${nodeId}`,
+      title:
+        words.length === 0
+          ? node
+          : t('paths.halts.row', { node, reasons: either.format(words) }),
+      pinnable: false,
+    };
+  });
+
+  const sections: FlowPathListSection[] = [
+    {
+      id: PATHS_SECTION,
+      rows: pathRows,
+      ...(footer !== undefined && { footer }),
+    },
+    {
+      id: HALTS_SECTION,
+      title: t('paths.halts.title'),
+      rows: haltRows,
+    },
+  ];
+
+  const skipReason = (
+    nodeId: string,
+    skip: PathOutcome['skipped'][number],
+  ): string => {
+    switch (skip.reason) {
+      case 'when':
+        return t('paths.skip.when');
+      case 'else': {
+        const partner = ctx.elseOf(nodeId);
+        return t('paths.skip.else', {
+          node: nodeTitle(partner ?? nodeId),
+        });
+      }
+      case 'upstream':
+        return t('paths.skip.upstream', {
+          node: nodeTitle(skip.via ?? nodeId),
+        });
+      default:
+        // `error`: it failed and the run went on without it.
+        return t('paths.skip.error');
+    }
+  };
+
+  return {
+    flowPaths,
+    sections,
+    count: flow.paths.length,
+    truncated: flow.truncated,
+    rows,
+    highlightFor(rowId, pinned) {
+      if (rowId.startsWith(HALT_PREFIX)) {
+        return highlightForNodes(graph, haltIds, { tone: 'error' });
+      }
+      const found = byId.get(rowId);
+      const flowPath = flowPaths[found?.index ?? -1];
+      if (found === undefined || flowPath === undefined) return null;
+      const reasons: Record<string, string> = {};
+      for (const skip of found.path.skipped) {
+        reasons[skip.nodeId] = skipReason(skip.nodeId, skip);
+      }
+      const info = rows.get(rowId);
+      return {
+        ...highlightForPaths(graph, [flowPath]),
+        reasons,
+        ...(pinned &&
+          info !== undefined && {
+            announcement: t('paths.showing', {
+              index: info.index,
+              ran: info.ran,
+              total,
+            }),
+          }),
+      };
+    },
+    ranOn(rowId) {
+      const found = byId.get(rowId);
+      return found === undefined ? null : new Set(found.path.ran);
+    },
+    haltNode(rowId) {
+      return rowId.startsWith(HALT_PREFIX)
+        ? rowId.slice(HALT_PREFIX.length)
+        : null;
+    },
+  };
+}
diff --git a/services/platform/app/features/automations/lib/run-overlay.test.ts b/services/platform/app/features/automations/lib/run-overlay.test.ts
new file mode 100644
index 0000000000..ef3fca9ec3
--- /dev/null
+++ b/services/platform/app/features/automations/lib/run-overlay.test.ts
@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest';
+
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
+import type { Automation } from '@/lib/engine/core/types';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { toFlowGraph } from './flow-graph';
+import { END_ID, START_ID, gateIdOf } from './flow-ids';
+import { nodeCatalogView } from './node-face';
+import { runOverlay } from './run-overlay';
+import type { NodeRunStatus, RunProjection, RunStatus } from './run-view';
+
+/**
+ * A run laid over the canvas: every node in the package's state words, the
+ * way each condition decided, who started the run and how it ended.
+ */
+
+const t = i18n.getFixedT('en', 'automations');
+
+const DOC: Automation = {
+  name: 'triage',
+  nodes: [
+    { id: 'inbox', type: 'transform', code: 'return [];' },
+    {
+      id: 'triage',
+      type: 'llm',
+      when: '{{ nodes.inbox.output.length > 0 }}',
+      prompt: '{{ nodes.inbox.output }}',
+    },
+    {
+      id: 'quiet',
+      type: 'transform',
+      elseOf: 'triage',
+      code: 'return null;',
+    },
+    {
+      id: 'report',
+      type: 'transform',
+      input: { triage: '{{ nodes.triage.output }}' },
+      code: 'return input;',
+    },
+  ],
+};
+
+const { graph } = toFlowGraph(DOC, {
+  t,
+  tSchema: i18n.getFixedT('en', 'schemaTree'),
+  locale: 'en',
+  catalog: nodeCatalogView([]),
+  returns: { status: 'off', outputs: null },
+  triggers: [{ id: 'trigger:manual', label: 'By hand, the API or MCP' }],
+  flow: analyzeFlow(DOC.nodes),
+});
+
+function overlay(
+  statuses: Record<string, NodeRunStatus>,
+  status: RunStatus,
+  byNode: RunProjection['byNode'] = new Map(),
+  startedBy?: string,
+) {
+  return runOverlay({
+    graph,
+    statusByNode: new Map(Object.entries(statuses)),
+    projection: { byNode, effects: [], trace: [] },
+    status,
+    t,
+    ...(startedBy !== undefined && { startedBy }),
+  });
+}
+
+describe('runOverlay', () => {
+  it('reads a run that took the No branch, with durations and who started it', () => {
+    const result = overlay(
+      { inbox: 'ok', triage: 'skipped', quiet: 'ok', report: 'skipped' },
+      'success',
+      new Map([['inbox', { status: 'ok', ms: 1200, effects: [] }]]),
+      'Started by you',
+    );
+    expect(result.finished).toBe(true);
+    expect(result.nodes.inbox).toEqual({ state: 'succeeded', detail: '2s' });
+    expect(result.nodes.triage).toEqual({ state: 'skipped' });
+    // The condition decided No: its node was skipped while what it reads ran.
+    expect(result.nodes[gateIdOf('triage')]).toEqual({
+      state: 'succeeded',
+      decision: false,
+    });
+    expect(result.nodes[START_ID]).toEqual({
+      state: 'succeeded',
+      detail: 'Started by you',
+    });
+    expect(result.nodes[END_ID]).toEqual({ state: 'succeeded' });
+  });
+
+  it('says Yes for a condition whose node ran', () => {
+    const result = overlay(
+      { inbox: 'ok', triage: 'ok', quiet: 'skipped', report: 'ok' },
+      'success',
+    );
+    expect(result.nodes[gateIdOf('triage')]).toEqual({
+      state: 'succeeded',
+      decision: true,
+    });
+  });
+
+  it('marks where a failed run stopped, its error line, and what it never reached', () => {
+    const result = overlay(
+      { inbox: 'ok', triage: 'error', quiet: 'pending', report: 'pending' },
+      'failed',
+      new Map([
+        [
+          'triage',
+          {
+            status: 'error',
+            error: 'Model refused the prompt\n  at call',
+            effects: [],
+          },
+        ],
+      ]),
+    );
+    expect(result.nodes.triage).toEqual({
+      state: 'failed',
+      reason: 'Model refused the prompt',
+    });
+    // A finished run never comes back for them: not run, not "not yet".
+    expect(result.nodes.report).toEqual({ state: 'not-run' });
+    expect(result.nodes[END_ID]).toEqual({
+      state: 'failed',
+      reason: 'Failed at Triage',
+    });
+  });
+
+  it('keeps nodes ahead of a live run pending, and End too', () => {
+    const result = overlay(
+      { inbox: 'ok', triage: 'running', quiet: 'pending', report: 'pending' },
+      'running',
+    );
+    expect(result.finished).toBe(false);
+    expect(result.nodes.triage).toEqual({ state: 'running' });
+    expect(result.nodes.report).toEqual({ state: 'pending' });
+    expect(result.nodes[gateIdOf('triage')]).toEqual({
+      state: 'succeeded',
+      decision: true,
+    });
+    expect(result.nodes[END_ID]).toEqual({ state: 'pending' });
+  });
+
+  it('says why a node whose server stopped is not being worked on', () => {
+    const result = overlay(
+      {
+        inbox: 'interrupted',
+        triage: 'pending',
+        quiet: 'pending',
+        report: 'pending',
+      },
+      'running',
+    );
+    expect(result.nodes.inbox).toEqual({
+      state: 'pending',
+      reason: 'Interrupted here',
+    });
+  });
+
+  it('reads a stopped run as stopped', () => {
+    const result = overlay(
+      { inbox: 'ok', triage: 'stopped', quiet: 'pending', report: 'pending' },
+      'cancelled',
+    );
+    expect(result.nodes.triage).toEqual({ state: 'stopped' });
+    expect(result.nodes[END_ID]).toEqual({ state: 'stopped' });
+  });
+});
diff --git a/services/platform/app/features/automations/lib/run-overlay.ts b/services/platform/app/features/automations/lib/run-overlay.ts
new file mode 100644
index 0000000000..3debeeabf4
--- /dev/null
+++ b/services/platform/app/features/automations/lib/run-overlay.ts
@@ -0,0 +1,139 @@
+/**
+ * A run laid over the canvas: where each node ended, which way each
+ * condition decided, how the run began and how it ended.
+ *
+ * The run's own record (`projectRun`, `nodeStatusMap`) says what happened
+ * to each node; the canvas's package derives the lines from it (a line is
+ * travelled when its source succeeded and its target started) and brings
+ * the way to a failure forward. A condition decided Yes when its node ran,
+ * and No when its node was skipped although everything it reads ran — the
+ * one skip a condition causes.
+ */
+
+import type { FlowNodeState } from '@tale/ui/flow/node-status';
+import type { FlowNodeRunInfo, FlowRunOverlay } from '@tale/ui/flow/playback';
+import type { FlowGraph } from '@tale/ui/flow/types';
+
+import { formatDurationSeconds } from '@/lib/utils/format/duration';
+
+import type { ConditionTranslate } from './condition-text';
+import { END_ID, START_ID, flowGraphTarget } from './flow-ids';
+import { nodeTitle } from './node-face';
+import {
+  flowNodeState,
+  isRunFinished,
+  type NodeRunStatus,
+  type RunProjection,
+  type RunStatus,
+} from './run-view';
+
+const RAN: ReadonlySet<FlowNodeState> = new Set([
+  'succeeded',
+  'failed',
+  'running',
+  'waiting',
+]);
+
+export interface RunOverlayInput {
+  graph: FlowGraph;
+  statusByNode: ReadonlyMap<string, NodeRunStatus>;
+  projection: RunProjection;
+  /** The run's own status: how End reads. */
+  status: RunStatus;
+  t: ConditionTranslate;
+  /** Start's words: who or what started the run. */
+  startedBy?: string;
+}
+
+/** The first line of an error: the strip has room for one. */
+function firstLine(text: string): string {
+  return text.split('\n', 1)[0]?.trim() ?? '';
+}
+
+/** The overlay of one run on its document's graph. */
+export function runOverlay({
+  graph,
+  statusByNode,
+  projection,
+  status,
+  t,
+  startedBy,
+}: RunOverlayInput): FlowRunOverlay {
+  const finished = isRunFinished(status);
+  const nodes: Record<string, FlowNodeRunInfo> = {};
+  for (const [id, nodeStatus] of statusByNode) {
+    const view = projection.byNode.get(id);
+    // A node a finished run never reached was not run, not "not yet".
+    const shown = flowNodeState(nodeStatus);
+    const state = finished && shown === 'pending' ? 'not-run' : shown;
+    const info: FlowNodeRunInfo = { state };
+    if (
+      view?.ms !== undefined &&
+      (state === 'succeeded' || state === 'failed')
+    ) {
+      info.detail = formatDurationSeconds(Math.ceil(view.ms / 1000));
+    }
+    if (state === 'failed' && view?.error !== undefined) {
+      const line = firstLine(view.error);
+      if (line !== '') info.reason = line;
+    }
+    if (nodeStatus === 'interrupted') {
+      info.reason = t('runs.nodeStatus.interrupted');
+    }
+    nodes[id] = info;
+  }
+
+  // A condition decided when its node was reached: Yes when the node
+  // started, No when it was skipped while everything it reads had run.
+  const dataSources = new Map<string, string[]>();
+  for (const edge of graph.edges) {
+    if (edge.kind !== 'data' || edge.layoutOnly === true) continue;
+    dataSources.set(edge.target, [
+      ...(dataSources.get(edge.target) ?? []),
+      edge.source,
+    ]);
+  }
+  for (const node of graph.nodes) {
+    const target = flowGraphTarget(node.id);
+    if (target.kind !== 'gate') continue;
+    const of = nodes[target.nodeId];
+    if (of === undefined) continue;
+    if (RAN.has(of.state)) {
+      nodes[node.id] = { state: 'succeeded', decision: true };
+    } else if (
+      of.state === 'skipped' &&
+      (dataSources.get(target.nodeId) ?? []).every(
+        (source) => nodes[source]?.state === 'succeeded',
+      )
+    ) {
+      nodes[node.id] = { state: 'succeeded', decision: false };
+    } else {
+      nodes[node.id] = {
+        state: of.state === 'pending' ? 'pending' : 'not-run',
+      };
+    }
+  }
+
+  nodes[START_ID] = {
+    state: 'succeeded',
+    ...(startedBy !== undefined && startedBy !== '' && { detail: startedBy }),
+  };
+  const failedAt = [...statusByNode].find(
+    ([, nodeStatus]) => nodeStatus === 'error',
+  )?.[0];
+  nodes[END_ID] =
+    status === 'success'
+      ? { state: 'succeeded' }
+      : status === 'failed'
+        ? {
+            state: 'failed',
+            ...(failedAt !== undefined && {
+              reason: t('canvas.end.failedAt', { node: nodeTitle(failedAt) }),
+            }),
+          }
+        : status === 'cancelled'
+          ? { state: 'stopped' }
+          : { state: 'pending' };
+
+  return { nodes, finished };
+}
diff --git a/services/platform/app/features/automations/lib/trigger-summary.test.ts b/services/platform/app/features/automations/lib/trigger-summary.test.ts
new file mode 100644
index 0000000000..0864f799b6
--- /dev/null
+++ b/services/platform/app/features/automations/lib/trigger-summary.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { triggerLines, triggerRows } from './trigger-summary';
+
+/**
+ * What starts an automation, as its Start node says it: each binding with
+ * the schedule in words (or the cron as written), whether it would fire
+ * now, and always the line for a start by hand, the API or MCP.
+ */
+
+const t = i18n.getFixedT('en', 'automations');
+const NOW = new Date('2026-10-08T05:00:00Z');
+const formatDate = (at: Date) => at.toISOString();
+
+describe('triggerLines', () => {
+  it('words a daily schedule and its next run', () => {
+    const lines = triggerLines(
+      [{ kind: 'schedule', enabled: true, cron: '0 7 * * *', timezone: 'UTC' }],
+      { deployed: true, t, now: NOW },
+    );
+    expect(lines).toEqual([
+      {
+        kind: 'schedule',
+        text: 'Every day at 07:00',
+        code: false,
+        zone: 'UTC',
+        nextAt: Date.parse('2026-10-08T07:00:00Z'),
+        state: 'on',
+      },
+      { kind: 'manual', only: false },
+    ]);
+    expect(triggerRows(lines, { t, formatDate })).toEqual([
+      expect.objectContaining({
+        label: 'Every day at 07:00 · UTC',
+        note: 'Next run 2026-10-08T07:00:00.000Z',
+      }),
+      expect.objectContaining({ label: 'By hand, the API or MCP' }),
+    ]);
+  });
+
+  it('shows a cron it has no words for as written', () => {
+    const [line] = triggerLines(
+      [{ kind: 'schedule', enabled: true, cron: '15 9 * * 1-5' }],
+      { deployed: true, t, now: NOW },
+    );
+    expect(line).toMatchObject({ text: '15 9 * * 1-5', code: true });
+    const [row] = triggerRows(line === undefined ? [] : [line], {
+      t,
+      formatDate,
+    });
+    expect(row).toMatchObject({ label: '15 9 * * 1-5 · UTC', code: true });
+  });
+
+  it('says why a binding would not start a run', () => {
+    const lines = triggerLines(
+      [
+        { kind: 'webhook', enabled: false },
+        {
+          kind: 'schedule',
+          enabled: false,
+          cron: '0 7 * * *',
+          lastSkipReason: 'paused_after_failures',
+        },
+        { kind: 'event', enabled: true, event: 'conversation.created' },
+      ],
+      { deployed: false, t, now: NOW },
+    );
+    const rows = triggerRows(lines, { t, formatDate });
+    expect(rows.map((row) => [row.label, row.badge?.label, row.note])).toEqual([
+      ['A request to its webhook URL', 'Off', undefined],
+      ['Every day at 07:00 · UTC', 'Paused — no runs start', undefined],
+      ['When conversation.created', 'Waits for a live version', undefined],
+      ['By hand, the API or MCP', undefined, undefined],
+    ]);
+    expect(rows[1]?.badge?.tone).toBe('warning');
+  });
+
+  it('says a run starts only by hand when nothing else starts it', () => {
+    const lines = triggerLines([{ kind: 'api-key', enabled: true }], {
+      deployed: true,
+      t,
+    });
+    expect(lines).toEqual([{ kind: 'manual', only: true }]);
+    expect(triggerRows(lines, { t, formatDate })[0]?.label).toBe(
+      'Only by hand, the API or MCP — no trigger',
+    );
+  });
+
+  it('speaks the reader’s language', () => {
+    const de = i18n.getFixedT('de', 'automations');
+    const rows = triggerRows(
+      triggerLines([{ kind: 'schedule', enabled: true, cron: '*/5 * * * *' }], {
+        deployed: true,
+        t: de,
+        now: NOW,
+      }),
+      { t: de, formatDate },
+    );
+    expect(rows.map((row) => row.label)).toEqual([
+      'Alle 5 Minuten · UTC',
+      'Von Hand, über die API oder MCP',
+    ]);
+  });
+});
diff --git a/services/platform/app/features/automations/lib/trigger-summary.ts b/services/platform/app/features/automations/lib/trigger-summary.ts
new file mode 100644
index 0000000000..094eddfb10
--- /dev/null
+++ b/services/platform/app/features/automations/lib/trigger-summary.ts
@@ -0,0 +1,206 @@
+/**
+ * What starts an automation, in the words its Start node shows.
+ *
+ * The automation's trigger bindings (`listTriggers`) say what can start a
+ * run: a schedule, a webhook, a platform event. Every automation can also be
+ * started by hand, through the API or MCP, so that line is always there.
+ * Each binding carries whether it would fire now: off, waiting for a live
+ * version (a trigger always runs the deployed version), or paused after
+ * repeated failures.
+ *
+ * Schedule words come from the cron preview the trigger editor shows under
+ * its Cron field ("Every day at 07:00"); a cron it has no words for is
+ * shown as written.
+ */
+
+import type { FlowRow } from '@tale/ui/flow/types';
+import { Clock, Hand, Radio, Webhook } from 'lucide-react';
+
+import {
+  cronPatternText,
+  previewCronExpression,
+  type CronTranslate,
+} from './cron-preview';
+
+/** Whether a binding would start a run now, and if not, why. */
+export type TriggerState = 'on' | 'off' | 'notLive' | 'paused';
+
+/** A trigger binding, narrowed to what its line reads. */
+export interface TriggerBinding {
+  kind: string;
+  enabled: boolean;
+  cron?: string;
+  timezone?: string;
+  event?: string;
+  lastSkipReason?: string | null;
+}
+
+export type TriggerLine =
+  | {
+      kind: 'schedule';
+      /** The schedule in words, or the cron as written (`code`). */
+      text: string;
+      code: boolean;
+      zone: string;
+      /** The next run, epoch ms, when there is one. */
+      nextAt?: number;
+      state: TriggerState;
+    }
+  | { kind: 'webhook'; state: TriggerState }
+  | { kind: 'event'; name: string; state: TriggerState }
+  | {
+      kind: 'manual';
+      /** No binding starts it: only by hand. */
+      only: boolean;
+    };
+
+/**
+ * The input wrapper every trigger-started run arrives in
+ * (`docs/en/platform/automations/triggers.md`): an `inputs` schema that
+ * declares these fields describes the wrapper, not the author's own data.
+ */
+export const TRIGGER_WRAPPER_KEYS: ReadonlySet<string> = new Set([
+  'trigger',
+  'firedAt',
+  'event',
+  'payload',
+]);
+
+function stateOf(binding: TriggerBinding, deployed: boolean): TriggerState {
+  if (!binding.enabled) {
+    return binding.lastSkipReason === 'paused_after_failures'
+      ? 'paused'
+      : 'off';
+  }
+  return deployed ? 'on' : 'notLive';
+}
+
+/**
+ * One line per binding the canvas can say, then the line every automation
+ * has: by hand, the API or MCP.
+ */
+export function triggerLines(
+  bindings: readonly TriggerBinding[],
+  ctx: {
+    /** A version is deployed: a trigger has something to run. */
+    deployed: boolean;
+    t: CronTranslate;
+    now?: Date;
+  },
+): TriggerLine[] {
+  const lines: TriggerLine[] = [];
+  for (const binding of bindings) {
+    const state = stateOf(binding, ctx.deployed);
+    switch (binding.kind) {
+      case 'schedule': {
+        const cron = binding.cron ?? '';
+        const zone = binding.timezone ?? 'UTC';
+        const preview = previewCronExpression(cron, zone, ctx.now);
+        const words =
+          preview.kind === 'ok'
+            ? cronPatternText(preview.pattern, ctx.t)
+            : undefined;
+        lines.push({
+          kind: 'schedule',
+          text: words ?? cron,
+          code: words === undefined,
+          zone,
+          ...(preview.kind === 'ok' && { nextAt: preview.nextAt.getTime() }),
+          state,
+        });
+        break;
+      }
+      case 'webhook':
+        lines.push({ kind: 'webhook', state });
+        break;
+      case 'event':
+        if (binding.event !== undefined && binding.event !== '') {
+          lines.push({ kind: 'event', name: binding.event, state });
+        }
+        break;
+      default:
+        // Another kind (an API key binding) starts runs through the API,
+        // which the line below already says.
+        break;
+    }
+  }
+  lines.push({ kind: 'manual', only: lines.length === 0 });
+  return lines;
+}
+
+function badgeOf(
+  state: TriggerState,
+  t: CronTranslate,
+): FlowRow['badge'] | undefined {
+  switch (state) {
+    case 'off':
+      return { label: t('canvas.start.off'), tone: 'neutral' };
+    case 'notLive':
+      return { label: t('canvas.start.notLive'), tone: 'neutral' };
+    case 'paused':
+      return { label: t('trigger.paused'), tone: 'warning' };
+    default:
+      // `on`: it starts runs, nothing to say beside it.
+      return undefined;
+  }
+}
+
+/** The lines as Start's rows: an icon, the words, the next run, a state. */
+export function triggerRows(
+  lines: readonly TriggerLine[],
+  ctx: { t: CronTranslate; formatDate: (at: Date) => string },
+): FlowRow[] {
+  const { t } = ctx;
+  return lines.map((line, index): FlowRow => {
+    const id = `trigger:${index}`;
+    switch (line.kind) {
+      case 'schedule': {
+        const badge = badgeOf(line.state, t);
+        const runs = line.state === 'on' || line.state === 'notLive';
+        return {
+          id,
+          icon: Clock,
+          label: t('canvas.start.scheduleZone', {
+            schedule: line.text,
+            zone: line.zone,
+          }),
+          ...(line.code && { code: true }),
+          ...(runs &&
+            line.nextAt !== undefined && {
+              note: t('trigger.cronNext', {
+                at: ctx.formatDate(new Date(line.nextAt)),
+              }),
+            }),
+          ...(badge !== undefined && { badge }),
+        };
+      }
+      case 'webhook': {
+        const badge = badgeOf(line.state, t);
+        return {
+          id,
+          icon: Webhook,
+          label: t('canvas.start.webhook'),
+          ...(badge !== undefined && { badge }),
+        };
+      }
+      case 'event': {
+        const badge = badgeOf(line.state, t);
+        return {
+          id,
+          icon: Radio,
+          label: t('canvas.start.event', { event: line.name }),
+          ...(badge !== undefined && { badge }),
+        };
+      }
+      default:
+        // `manual`: by hand, the API or MCP.
+        return {
+          id: 'trigger:manual',
+          icon: Hand,
+          label: line.only
+            ? t('canvas.start.manualOnly')
+            : t('canvas.start.manual'),
+        };
+    }
+  });
+}
diff --git a/services/platform/app/routes/dashboard/$id/automations/$automationSlug/editor.tsx b/services/platform/app/routes/dashboard/$id/automations/$automationSlug/editor.tsx
index ab85b7de37..10c1a05752 100644
--- a/services/platform/app/routes/dashboard/$id/automations/$automationSlug/editor.tsx
+++ b/services/platform/app/routes/dashboard/$id/automations/$automationSlug/editor.tsx
@@ -2,7 +2,10 @@ import { createFileRoute } from '@tanstack/react-router';
 import { useCallback } from 'react';
 
 import { AutomationEditor } from '@/app/features/automations/components/automation-editor';
-import { automationEditorSearchSchema } from '@/app/features/automations/lib/editor-search';
+import {
+  automationEditorSearchSchema,
+  type AutomationEditorView,
+} from '@/app/features/automations/lib/editor-search';
 import { paramToAutomationSlug } from '@/lib/automations/slug';
 
 export const Route = createFileRoute(
@@ -17,12 +20,17 @@ export const Route = createFileRoute(
 
 function AutomationEditorPage() {
   const { id: organizationId, automationSlug } = Route.useParams();
-  const { version, history } = Route.useSearch();
+  const { version, history, view, node } = Route.useSearch();
   const navigate = Route.useNavigate();
   const onSelectVersion = useCallback(
     (next: number | undefined) => {
       void navigate({
-        search: next === undefined ? {} : { version: next },
+        // The view and the open node stay with the reader across versions.
+        search: (previous) => ({
+          ...(previous.view !== undefined && { view: previous.view }),
+          ...(previous.node !== undefined && { node: previous.node }),
+          ...(next !== undefined && { version: next }),
+        }),
         // Returning to the latest (after a save appends one) corrects the URL
         // rather than adding a history entry; picking a version is a move.
         replace: next === undefined,
@@ -30,6 +38,22 @@ function AutomationEditorPage() {
     },
     [navigate],
   );
+  const onSearchChange = useCallback(
+    (change: { view?: AutomationEditorView; node?: string | null }) => {
+      void navigate({
+        search: (previous) => {
+          const next = { ...previous };
+          if (change.view !== undefined) next.view = change.view;
+          if (change.node === null) delete next.node;
+          else if (change.node !== undefined) next.node = change.node;
+          return next;
+        },
+        // Following the reader's view and selection is no move of its own.
+        replace: true,
+      });
+    },
+    [navigate],
+  );
   return (
     <AutomationEditor
       organizationId={organizationId}
@@ -37,6 +61,9 @@ function AutomationEditorPage() {
       {...(version !== undefined && { version })}
       showVersionHistory={history}
       onSelectVersion={onSelectVersion}
+      {...(view !== undefined && { view })}
+      {...(node !== undefined && { node })}
+      onSearchChange={onSearchChange}
     />
   );
 }
diff --git a/services/platform/app/routes/dashboard/$id/projects/$projectId/automations/$automationSlug/editor.tsx b/services/platform/app/routes/dashboard/$id/projects/$projectId/automations/$automationSlug/editor.tsx
index a894721839..58dc30c190 100644
--- a/services/platform/app/routes/dashboard/$id/projects/$projectId/automations/$automationSlug/editor.tsx
+++ b/services/platform/app/routes/dashboard/$id/projects/$projectId/automations/$automationSlug/editor.tsx
@@ -2,7 +2,10 @@ import { createFileRoute } from '@tanstack/react-router';
 import { useCallback } from 'react';
 
 import { AutomationEditor } from '@/app/features/automations/components/automation-editor';
-import { automationEditorSearchSchema } from '@/app/features/automations/lib/editor-search';
+import {
+  automationEditorSearchSchema,
+  type AutomationEditorView,
+} from '@/app/features/automations/lib/editor-search';
 import { asProjectId } from '@/app/features/projects/hooks/use-project-id-param';
 import { paramToAutomationSlug } from '@/lib/automations/slug';
 
@@ -17,17 +20,36 @@ export const Route = createFileRoute(
 
 function ProjectAutomationEditorPage() {
   const { id: organizationId, projectId, automationSlug } = Route.useParams();
-  const { version, history } = Route.useSearch();
+  const { version, history, view, node } = Route.useSearch();
   const navigate = Route.useNavigate();
   const onSelectVersion = useCallback(
     (next: number | undefined) => {
       void navigate({
-        search: next === undefined ? {} : { version: next },
+        search: (previous) => ({
+          ...(previous.view !== undefined && { view: previous.view }),
+          ...(previous.node !== undefined && { node: previous.node }),
+          ...(next !== undefined && { version: next }),
+        }),
         replace: next === undefined,
       });
     },
     [navigate],
   );
+  const onSearchChange = useCallback(
+    (change: { view?: AutomationEditorView; node?: string | null }) => {
+      void navigate({
+        search: (previous) => {
+          const next = { ...previous };
+          if (change.view !== undefined) next.view = change.view;
+          if (change.node === null) delete next.node;
+          else if (change.node !== undefined) next.node = change.node;
+          return next;
+        },
+        replace: true,
+      });
+    },
+    [navigate],
+  );
   return (
     <AutomationEditor
       organizationId={organizationId}
@@ -36,6 +58,9 @@ function ProjectAutomationEditorPage() {
       {...(version !== undefined && { version })}
       showVersionHistory={history}
       onSelectVersion={onSelectVersion}
+      {...(view !== undefined && { view })}
+      {...(node !== undefined && { node })}
+      onSearchChange={onSearchChange}
     />
   );
 }
diff --git a/services/platform/messages/de-CH/automations.yml b/services/platform/messages/de-CH/automations.yml
index 17a0c6d997..3e3d2d25c5 100644
--- a/services/platform/messages/de-CH/automations.yml
+++ b/services/platform/messages/de-CH/automations.yml
@@ -1,3 +1,6 @@
+condition:
+  gt: '{a} grösser als {b} ist'
+  quote: '«{text}»'
 runs:
   quarantine:
     changed: Die Sperre hat sich geändert. Schliesse diesen Dialog und prüfe die aktuellen Angaben, bevor du entscheidest.
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index ce76a766d1..c4c1daf35c 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -201,29 +201,87 @@ trigger:
   revokedToast: Die bisherige Webhook-URL wurde widerrufen — Absender, die sie nutzen, bekommen jetzt 404.
 canvas:
   ariaLabel: Canvas der Automatisierung
-  readsFrom: 'Liest {nodes}'
   unpinnedModel: Kein fester Anbieter — der Lauf wählt ihn automatisch.
   empty:
     title: Diese Version hat keine Nodes
-    description:
-      Ein Automatisierungsdokument besteht aus Nodes. Sobald du dem Dokument
-      eine hinzufügst, erscheint sie hier.
+    description: Eine Automatisierung erledigt ihre Arbeit in Nodes. Bitte deinen Coding-Agent, welche hinzuzufügen.
   cycle:
     title: Diese Nodes verweisen im Kreis aufeinander
     description: Gezeigt wird die Reihenfolge, in der die Nodes im Dokument
       stehen – nicht die Reihenfolge, in der sie laufen würden, denn die Engine
       kann keinen Kreis ausführen. Entferne eine der Referenzen, um ihn
       aufzubrechen.
+  view:
+    label: Ansicht
+    canvas: Canvas
+    list: Liste
+  legend:
+    data: 'Durchgezogene Linie: liest die Ausgabe der Node darüber'
+    control: 'Gestrichelte Linie: läuft danach, ohne ihre Ausgabe zu lesen'
+    gate: 'Bedingung: entscheidet, ob die Node darunter läuft'
+    yes: 'Ja: läuft, wenn die Bedingung zutrifft'
+    no: 'Nein: läuft, wenn die Bedingung nicht zutrifft'
+    completion: 'Gepunktete Linie: Der Lauf endet nach dieser Node'
+    conditional: 'Gestrichelter Rahmen: läuft vielleicht nicht oder lief nicht'
+    loop: 'Rahmen: läuft einmal pro Element oder wiederholt sich'
+  readsNothing: Liest keine andere Node
+  node:
+    returnsUnknown: Struktur nach einem Lauf bekannt
+    returns: 'Gibt {shape} zurück'
+    writes: Ändert Daten in {connector}. Ein Live-Lauf wartet unter Umständen auf eine Freigabe.
+    asks: Kann eine Frage stellen und auf die Antwort warten.
+    catalog:
+      transform: Transformation
+      llm: Sprachmodell
+      agent: Agent
+      subautomation: 'Ruft {automation} auf'
+      subautomationUnset: Ruft eine Automatisierung auf
+      connector: '{connector} · {action}'
+      withModel: '{type} · {model}'
+      unknown: 'Unbekannter Typ {type}'
+    source:
+      input: 'Laufeingabe ({keys})'
+      inputAll: Laufeingabe
+      item: jedes Element
+  gate:
+    asCode: Als Code geschrieben
   edge:
-    data: '{target} liest die Ausgabe von {source}'
-    control: '{target} läuft nach {source}'
+    carries: 'Trägt {fields}'
   controlFlow:
-    when: 'wenn {value}'
-    elseOf: 'sonst zu {value}'
-    forEach: 'für jedes {value}'
-    repeatUntil: 'wiederholen bis {value}'
-    repeatUntilCapped: 'wiederholen bis {value}, höchstens {maxRepeats}×'
-    onError: bei Fehler weiterlaufen
+    forEach: 'Für jedes Element von {list}'
+    forEachRaw: Für jedes Element ihrer Liste
+    repeatUntilCapped: 'Wiederholt sich, bis {condition}, höchstens {maxRepeats}×'
+    repeatRaw: 'Wiederholt sich, bis ihre Bedingung zutrifft, höchstens {maxRepeats}×'
+    onError: Läuft bei Fehler weiter
+  updated: 'Jetzt wird v{version} angezeigt.'
+  selectionRemoved: '{node} ist in dieser Version nicht mehr enthalten.'
+  newerVersion:
+    title: Eine neuere Version wurde gespeichert
+    body: 'v{version} wurde gespeichert, während du bearbeitet hast. Dein Entwurf basiert auf v{base}.'
+    show: 'v{version} zeigen und Entwurf verwerfen'
+  start:
+    manual: Von Hand, über die API oder MCP
+    manualOnly: Nur von Hand, über die API oder MCP – kein Trigger
+    webhook: Eine Anfrage an ihre Webhook-URL
+    event: 'Wenn {event}'
+    scheduleZone: '{schedule} · {zone}'
+    off: Aus
+    notLive: Wartet auf eine Live-Version
+    anyInput: Beliebige JSON-Eingabe
+    noFields: Keine Eingabefelder
+    fromTrigger: vom Trigger
+    description: '{triggers}. Eingabe: {fields}.'
+  end:
+    returnsNode: 'Die Ausgabe von {node}'
+    returnsNothing: Nichts – diese Automatisierung hat keine Ausgabe
+    fieldFrom: 'aus {nodes}'
+    maybeEmpty: kann leer sein
+    emptyOnPath: auf diesem Pfad leer
+    succeeded: gibt die Ausgabe zurück
+    failed: '{count, plural, =0 {keine Node stoppt den Lauf} one {wenn # Node fehlschlägt} other {wenn eine von # Nodes fehlschlägt}}'
+    stopped: wenn jemand ihn stoppt
+    someEmpty: Manche Läufe geben leere Werte zurück
+    failedAt: 'Fehlgeschlagen bei {node}'
 editor:
   unknownType: 'Unbekannter Node-Typ: {type}'
   catalogUnavailable:
@@ -236,7 +294,7 @@ editor:
     description: Diese Automatisierung hat keine Version mit dieser Nummer — der Link ist vielleicht veraltet oder die Nummer vertippt.
     openLatest: Neueste öffnen
   controlFlowTitle: Ablaufsteuerung
-  nodeSheetDescription: Bearbeite die Felder dieses Knotens, dann speichere die
+  nodeSheetDescription: Bearbeite die Felder dieser Node, dann speichere die
     Änderung oder verwirf sie.
   agent:
     equipmentLabel: Ausrüstung
@@ -547,7 +605,7 @@ problems:
   refusedDeploy: Diese Version hat Probleme, die das Live-Schalten verhindern. Du findest sie unter Probleme.
   refusedDeployDraft: Diese Version hat Probleme, die das Live-Schalten verhindern. Verwirf deinen Entwurf, um sie unter Probleme zu sehen.
   open: Probleme anzeigen
-  notEditableHere: Dieser Teil der Automatisierung lässt sich hier nicht bearbeiten. Ändere ihn über MCP, die API oder ein hochgeladenes Paket.
+  notEditableHere: Ändere das mit deinem Coding-Agent.
   nodeTitle: Probleme in dieser Node
   filter:
     label: Probleme anzeigen
@@ -556,3 +614,71 @@ problems:
     warnings: Warnungen
   emptyFiltered: '{filter, select, errors {Keine Fehler} warnings {Keine Warnungen} other {Keine Probleme}}'
   fieldPart: '{part}: {message}'
+condition:
+  gt: '{a} größer als {b} ist'
+  gte: '{a} mindestens {b} ist'
+  lt: '{a} kleiner als {b} ist'
+  lte: '{a} höchstens {b} ist'
+  eq: '{a} gleich {b} ist'
+  neq: '{a} nicht gleich {b} ist'
+  empty: '{a} leer ist'
+  notEmpty: '{a} nicht leer ist'
+  set: '{a} gesetzt ist'
+  notSet: '{a} nicht gesetzt ist'
+  contains: '{a} {b} enthält'
+  notContains: '{a} {b} nicht enthält'
+  startsWith: '{a} mit {b} beginnt'
+  endsWith: '{a} auf {b} endet'
+  ref:
+    node: '{path} von {node}'
+    nodeOutput: 'die Ausgabe von {node}'
+    input: '{path} der Laufeingabe'
+    inputWhole: die Laufeingabe
+    item: '{path} des Elements'
+    itemWhole: das Element
+    index: die Position des Elements
+    output: '{path} des Ergebnisses dieses Durchlaufs'
+    outputWhole: das Ergebnis dieses Durchlaufs
+    length: 'die Anzahl von {inner}'
+  literal:
+    valueTrue: wahr
+    valueFalse: falsch
+    valueNull: leer
+  quote: '„{text}“'
+paths:
+  button: '{count, plural, one {# Pfad} other {# Pfade}}'
+  title: Mögliche Pfade
+  description: Jeder Weg, den ein erfolgreicher Lauf nehmen kann. Zeig auf einen oder wähle ihn aus, um ihn im Canvas zu sehen.
+  single: 'Jeder Lauf nimmt denselben Pfad: {count, plural, one {die # Node läuft} other {alle # Nodes laufen}}.'
+  row: 'Pfad {index}'
+  rowRuns: '{ran, plural, one {# von {total} Nodes läuft} other {# von {total} Nodes laufen}}'
+  clause:
+    runs: '{node} läuft'
+    skipped: '{node} wird übersprungen'
+    fails: '{node} schlägt fehl, der Lauf geht weiter'
+    succeeds: '{node} gelingt'
+  more: '{count, plural, one {# weiterer Pfad ist nicht aufgeführt} other {# weitere Pfade sind nicht aufgeführt}}'
+  truncated: Diese Automatisierung hat {count} Bedingungen – zu viele, um jeden Pfad aufzuführen. Jede Node zeigt trotzdem, wann sie läuft.
+  halts:
+    title: Beendet den Lauf, wenn sie fehlschlägt
+    row: '{node} schlägt fehl, wenn {reasons}'
+  showing: 'Pfad {index} wird gezeigt: {ran, plural, one {# von {total} Nodes läuft} other {# von {total} Nodes laufen}}.'
+  pill: 'Pfad {index} · {ran, plural, one {# von {total} Nodes läuft} other {# von {total} Nodes laufen}}'
+  skip:
+    when: 'Übersprungen: Bedingung trifft nicht zu'
+    else: 'Übersprungen: {node} läuft'
+    upstream: 'Übersprungen: {node} wird übersprungen'
+    error: Schlägt fehl, der Lauf geht weiter
+failureReason:
+  external: ein aufgerufener Dienst fehlschlägt
+  code: ihr Code einen Fehler wirft
+  expression: einer ihrer Ausdrücke fehlschlägt
+  iteration: ihre Liste nicht durchlaufen werden kann
+  inputContract: ihre Eingabe abgelehnt wird
+  subautomation: die aufgerufene Automatisierung fehlschlägt
+codingAgent:
+  button: Mit deinem Coding-Agent bearbeiten
+  body: Coding-Agents wie Claude Code, Codex und Cursor ändern Automatisierungen über den MCP-Server von Tale. Sie lesen diese Automatisierung, ändern und prüfen sie und speichern eine neue Version, die dann hier erscheint.
+  nameLabel: Name dieser Automatisierung
+  setUp: MCP einrichten
+  learnMore: So verbindest du einen Coding-Agent
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index adbb525840..54cf672935 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -197,29 +197,87 @@ trigger:
   revokedToast: The previous webhook URL has been revoked — senders using it now get 404.
 canvas:
   ariaLabel: Automation canvas
-  readsFrom: 'Reads {nodes}'
   unpinnedModel: No pinned provider — each run picks one automatically.
   empty:
     title: This version has no nodes
-    description:
-      An automation document is a list of nodes. Add one to the document
-      and it appears here.
+    description: An automation does its work in nodes. Ask your coding agent to add them.
   cycle:
     title: These nodes reference each other in a circle
     description:
       The order shown is the order the nodes are written in, not the
       order they would run in — the engine cannot run a cycle. Remove one of
       the references to break it.
+  view:
+    label: View
+    canvas: Canvas
+    list: List
+  legend:
+    data: 'Solid line: reads the output of the node above'
+    control: 'Dashed line: runs after it, without reading its output'
+    gate: 'Condition: decides whether the node below runs'
+    yes: 'Yes: runs when the condition holds'
+    no: "No: runs when the condition doesn't hold"
+    completion: 'Dotted line: the run ends after this node'
+    conditional: "Dashed box: may not run, or didn't run"
+    loop: 'Frame: runs once per item, or repeats'
+  readsNothing: Reads no other node
+  node:
+    returnsUnknown: Shape known after a run
+    returns: 'Returns {shape}'
+    writes: Changes data in {connector}. A live run may wait for approval.
+    asks: May ask a question and wait for the answer.
+    catalog:
+      transform: Transform
+      llm: Language model
+      agent: Agent
+      subautomation: 'Calls {automation}'
+      subautomationUnset: Calls an automation
+      connector: '{connector} · {action}'
+      withModel: '{type} · {model}'
+      unknown: 'Unknown type {type}'
+    source:
+      input: 'run input ({keys})'
+      inputAll: run input
+      item: each item
+  gate:
+    asCode: Written as code
   edge:
-    data: '{target} reads the output of {source}'
-    control: '{target} runs after {source}'
+    carries: 'Carries {fields}'
   controlFlow:
-    when: 'when {value}'
-    elseOf: 'else of {value}'
-    forEach: 'for each {value}'
-    repeatUntil: 'repeat until {value}'
-    repeatUntilCapped: 'repeat until {value}, at most {maxRepeats}×'
-    onError: continue on error
+    forEach: 'For each item of {list}'
+    forEachRaw: For each item of its list
+    repeatUntilCapped: 'Repeats until {condition}, at most {maxRepeats}×'
+    repeatRaw: 'Repeats until its condition holds, at most {maxRepeats}×'
+    onError: Continues on error
+  updated: 'Now showing v{version}.'
+  selectionRemoved: '{node} is no longer in this version.'
+  newerVersion:
+    title: A newer version was saved
+    body: 'v{version} was saved while you were editing. Your draft is based on v{base}.'
+    show: 'Show v{version} and discard my draft'
+  start:
+    manual: By hand, the API or MCP
+    manualOnly: Only by hand, the API or MCP — no trigger
+    webhook: A request to its webhook URL
+    event: 'When {event}'
+    scheduleZone: '{schedule} · {zone}'
+    off: 'Off'
+    notLive: Waits for a live version
+    anyInput: Any JSON input
+    noFields: No input fields
+    fromTrigger: from the trigger
+    description: '{triggers}. Input: {fields}.'
+  end:
+    returnsNode: 'The output of {node}'
+    returnsNothing: Nothing — this automation has no output
+    fieldFrom: 'from {nodes}'
+    maybeEmpty: may be empty
+    emptyOnPath: empty on this path
+    succeeded: returns the output
+    failed: '{count, plural, =0 {no node stops the run} one {when # node fails} other {when one of # nodes fails}}'
+    stopped: when someone stops it
+    someEmpty: Some runs return empty values
+    failedAt: 'Failed at {node}'
 editor:
   unknownType: 'Unknown node type: {type}'
   catalogUnavailable: Couldn't load the node-type catalog — only built-in types are described. The node's fields are still shown.
@@ -537,7 +595,7 @@ problems:
   refusedDeploy: This version has problems that block deploying it. Problems lists them.
   refusedDeployDraft: This version has problems that block deploying it. Discard your draft to see them in Problems.
   open: Show problems
-  notEditableHere: This part of the automation can't be edited here. Change it through MCP, the API or an uploaded package.
+  notEditableHere: Change this with your coding agent.
   nodeTitle: Problems in this node
   filter:
     label: Show problems
@@ -546,3 +604,71 @@ problems:
     warnings: Warnings
   emptyFiltered: '{filter, select, errors {No errors} warnings {No warnings} other {No problems}}'
   fieldPart: '{part}: {message}'
+condition:
+  gt: '{a} is greater than {b}'
+  gte: '{a} is at least {b}'
+  lt: '{a} is less than {b}'
+  lte: '{a} is at most {b}'
+  eq: '{a} is {b}'
+  neq: '{a} is not {b}'
+  empty: '{a} is empty'
+  notEmpty: '{a} is not empty'
+  set: '{a} is set'
+  notSet: '{a} is not set'
+  contains: '{a} contains {b}'
+  notContains: "{a} doesn't contain {b}"
+  startsWith: '{a} starts with {b}'
+  endsWith: '{a} ends with {b}'
+  ref:
+    node: '{path} of {node}'
+    nodeOutput: 'the output of {node}'
+    input: '{path} of the run input'
+    inputWhole: the run input
+    item: '{path} of the item'
+    itemWhole: the item
+    index: "the item's position"
+    output: "{path} of this pass's result"
+    outputWhole: "this pass's result"
+    length: 'the number of {inner}'
+  literal:
+    valueTrue: 'true'
+    valueFalse: 'false'
+    valueNull: empty
+  quote: '"{text}"'
+paths:
+  button: '{count, plural, one {# path} other {# paths}}'
+  title: Possible paths
+  description: Every way a successful run can go. Point at one, or select it, to see it on the canvas.
+  single: 'Every run takes the same path: {count, plural, one {its # node runs} other {all # nodes run}}.'
+  row: 'Path {index}'
+  rowRuns: '{ran, plural, one {# of {total} nodes runs} other {# of {total} nodes run}}'
+  clause:
+    runs: '{node} runs'
+    skipped: '{node} is skipped'
+    fails: '{node} fails, the run goes on'
+    succeeds: '{node} succeeds'
+  more: "{count, plural, one {# more path isn't listed} other {# more paths aren't listed}}"
+  truncated: This automation has {count} conditions, too many to list every path. Each node still says when it runs.
+  halts:
+    title: Ends the run when it fails
+    row: '{node} fails when {reasons}'
+  showing: 'Showing path {index}: {ran, plural, one {# of {total} nodes runs} other {# of {total} nodes run}}.'
+  pill: 'Path {index} · {ran, plural, one {# of {total} nodes runs} other {# of {total} nodes run}}'
+  skip:
+    when: 'Skipped: condition false'
+    else: 'Skipped: {node} runs'
+    upstream: 'Skipped: {node} is skipped'
+    error: Fails, the run goes on
+failureReason:
+  external: a service it calls fails
+  code: its code throws an error
+  expression: one of its expressions fails
+  iteration: "its list can't be gone through"
+  inputContract: its input is refused
+  subautomation: the automation it calls fails
+codingAgent:
+  button: Edit with your coding agent
+  body: Coding agents such as Claude Code, Codex and Cursor change automations through Tale's MCP server. They read this automation, change and check it, and save a new version, which then appears here.
+  nameLabel: Name of this automation
+  setUp: Set up MCP
+  learnMore: How to connect a coding agent
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index bb80a0b446..c139f17691 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -200,30 +200,88 @@ trigger:
     body: L’URL actuelle cesse de fonctionner dès que le nouveau token est généré. Copie la nouvelle URL et mets à jour chaque système expéditeur.
   revokedToast: L’ancienne URL du webhook a été révoquée — les expéditeurs qui l’utilisent reçoivent désormais 404.
 canvas:
-  ariaLabel: Canvas de l’automatisation
-  readsFrom: 'Lit {nodes}'
+  ariaLabel: Canevas de l’automatisation
   unpinnedModel: Pas de fournisseur épinglé — chaque exécution en choisit un.
   empty:
     title: Cette version ne contient aucun nœud
-    description:
-      Un document d'automatisation est une liste de nœuds. Ajoutes-en un au
-      document et il apparaît ici.
+    description: Une automatisation travaille avec des nœuds. Demande à ton agent de code d’en ajouter.
   cycle:
     title: Ces nœuds se référencent en boucle
     description:
       L’ordre affiché est celui dans lequel les nœuds sont écrits, pas
       celui dans lequel ils s’exécuteraient, car le moteur ne peut pas
       exécuter une boucle. Retire l’une des références pour la rompre.
+  view:
+    label: Vue
+    canvas: Canevas
+    list: Liste
+  legend:
+    data: 'Trait plein : lit la sortie du nœud au-dessus'
+    control: 'Trait tireté : s’exécute après lui, sans lire sa sortie'
+    gate: 'Condition : décide si le nœud en dessous s’exécute'
+    yes: 'Oui : s’exécute quand la condition est remplie'
+    no: 'Non : s’exécute quand la condition n’est pas remplie'
+    completion: 'Trait pointillé : l’exécution se termine après ce nœud'
+    conditional: 'Cadre tireté : peut ne pas s’exécuter, ou ne s’est pas exécuté'
+    loop: 'Cadre : s’exécute une fois par élément, ou se répète'
+  readsNothing: Ne lit aucun autre nœud
+  node:
+    returnsUnknown: Structure connue après une exécution
+    returns: 'Renvoie {shape}'
+    writes: Modifie des données dans {connector}. Une exécution en service peut attendre une approbation.
+    asks: Peut poser une question et attendre la réponse.
+    catalog:
+      transform: Transformation
+      llm: Modèle de langage
+      agent: Agent
+      subautomation: 'Appelle {automation}'
+      subautomationUnset: Appelle une automatisation
+      connector: '{connector} · {action}'
+      withModel: '{type} · {model}'
+      unknown: 'Type inconnu {type}'
+    source:
+      input: 'entrée ({keys})'
+      inputAll: entrée
+      item: chaque élément
+  gate:
+    asCode: Écrite en code
   edge:
-    data: '{target} lit la sortie de {source}'
-    control: '{target} s’exécute après {source}'
+    carries: 'Transporte {fields}'
   controlFlow:
-    when: 'si {value}'
-    elseOf: 'sinon de {value}'
-    forEach: 'pour chaque {value}'
-    repeatUntil: 'répéter jusqu’à {value}'
-    repeatUntilCapped: 'répéter jusqu’à {value}, {maxRepeats}× au plus'
-    onError: continuer en cas d’erreur
+    forEach: 'Pour chaque élément de {list}'
+    forEachRaw: Pour chaque élément de sa liste
+    repeatUntilCapped: 'Se répète jusqu’à : {condition}, {maxRepeats} fois au plus'
+    repeatRaw: 'Se répète jusqu’à ce que sa condition soit remplie, {maxRepeats} fois au plus'
+    onError: Continue en cas d’erreur
+  updated: 'Affichage de la v{version}.'
+  selectionRemoved: '{node} ne fait plus partie de cette version.'
+  newerVersion:
+    title: Une version plus récente a été enregistrée
+    body: 'La v{version} a été enregistrée pendant ta modification. Ton brouillon part de la v{base}.'
+    show: 'Afficher la v{version} et abandonner mon brouillon'
+  start:
+    manual: À la main, via l’API ou MCP
+    manualOnly: Seulement à la main, via l’API ou MCP — aucun déclencheur
+    webhook: Une requête vers son URL de webhook
+    event: 'Quand {event}'
+    scheduleZone: '{schedule} · {zone}'
+    off: Désactivé
+    notLive: Attend une version en service
+    anyInput: N’importe quelle entrée JSON
+    noFields: Aucun champ d’entrée
+    fromTrigger: du déclencheur
+    description: '{triggers}. Entrée : {fields}.'
+  end:
+    returnsNode: 'La sortie de {node}'
+    returnsNothing: Rien — cette automatisation n’a pas de sortie
+    fieldFrom: 'de {nodes}'
+    maybeEmpty: peut être vide
+    emptyOnPath: vide sur ce chemin
+    succeeded: renvoie la sortie
+    failed: '{count, plural, =0 {aucun nœud n’arrête l’exécution} one {quand # nœud échoue} other {quand l’un des # nœuds échoue}}'
+    stopped: quand quelqu’un l’arrête
+    someEmpty: Certaines exécutions renvoient des valeurs vides
+    failedAt: 'Échec à {node}'
 editor:
   unknownType: 'Type de nœud inconnu : {type}'
   catalogUnavailable:
@@ -549,7 +607,7 @@ problems:
   refusedDeploy: Cette version a des problèmes qui empêchent sa mise en service. Ils sont listés dans Problèmes.
   refusedDeployDraft: Cette version a des problèmes qui empêchent sa mise en service. Abandonne ton brouillon pour les voir dans Problèmes.
   open: Afficher les problèmes
-  notEditableHere: Cette partie de l’automatisation ne se modifie pas ici. Modifie-la via MCP, l’API ou un paquet téléversé.
+  notEditableHere: Modifie-le avec ton agent de code.
   nodeTitle: Problèmes de ce nœud
   filter:
     label: Afficher les problèmes
@@ -558,3 +616,71 @@ problems:
     warnings: Avertissements
   emptyFiltered: '{filter, select, errors {Aucune erreur} warnings {Aucun avertissement} other {Aucun problème}}'
   fieldPart: '{part} : {message}'
+condition:
+  gt: '{a} est supérieur à {b}'
+  gte: '{a} vaut au moins {b}'
+  lt: '{a} est inférieur à {b}'
+  lte: '{a} vaut au plus {b}'
+  eq: '{a} vaut {b}'
+  neq: '{a} ne vaut pas {b}'
+  empty: '{a} est vide'
+  notEmpty: '{a} n’est pas vide'
+  set: '{a} est défini'
+  notSet: '{a} n’est pas défini'
+  contains: '{a} contient {b}'
+  notContains: '{a} ne contient pas {b}'
+  startsWith: '{a} commence par {b}'
+  endsWith: '{a} se termine par {b}'
+  ref:
+    node: '{path} de {node}'
+    nodeOutput: 'la sortie de {node}'
+    input: '{path} de l’entrée'
+    inputWhole: l’entrée
+    item: '{path} de l’élément'
+    itemWhole: l’élément
+    index: la position de l’élément
+    output: '{path} du résultat de ce passage'
+    outputWhole: le résultat de ce passage
+    length: 'le nombre de {inner}'
+  literal:
+    valueTrue: vrai
+    valueFalse: faux
+    valueNull: vide
+  quote: '« {text} »'
+paths:
+  button: '{count, plural, one {# chemin} other {# chemins}}'
+  title: Chemins possibles
+  description: Chaque chemin qu’une exécution réussie peut prendre. Survole-en un ou sélectionne-le pour le voir sur le canevas.
+  single: 'Chaque exécution suit le même chemin : {count, plural, one {son # nœud s’exécute} other {les # nœuds s’exécutent}}.'
+  row: 'Chemin {index}'
+  rowRuns: '{ran, plural, one {# nœud sur {total} s’exécute} other {# nœuds sur {total} s’exécutent}}'
+  clause:
+    runs: '{node} s’exécute'
+    skipped: '{node} est ignoré'
+    fails: '{node} échoue, l’exécution continue'
+    succeeds: '{node} réussit'
+  more: '{count, plural, one {# autre chemin n’est pas listé} other {# autres chemins ne sont pas listés}}'
+  truncated: Cette automatisation a {count} conditions, trop pour lister chaque chemin. Chaque nœud indique quand même quand il s’exécute.
+  halts:
+    title: Arrête l’exécution en cas d’échec
+    row: '{node} échoue si {reasons}'
+  showing: 'Chemin {index} affiché : {ran, plural, one {# nœud sur {total} s’exécute} other {# nœuds sur {total} s’exécutent}}.'
+  pill: 'Chemin {index} · {ran, plural, one {# nœud sur {total} s’exécute} other {# nœuds sur {total} s’exécutent}}'
+  skip:
+    when: 'Ignoré : condition non remplie'
+    else: 'Ignoré : {node} s’exécute'
+    upstream: 'Ignoré : {node} est ignoré'
+    error: Échoue, l’exécution continue
+failureReason:
+  external: un service appelé échoue
+  code: son code lève une erreur
+  expression: l’une de ses expressions échoue
+  iteration: sa liste ne peut pas être parcourue
+  inputContract: son entrée est refusée
+  subautomation: l’automatisation appelée échoue
+codingAgent:
+  button: Modifier avec ton agent de code
+  body: Les agents de code comme Claude Code, Codex et Cursor modifient les automatisations via le serveur MCP de Tale. Ils lisent cette automatisation, la modifient, la vérifient et enregistrent une nouvelle version, qui apparaît ensuite ici.
+  nameLabel: Nom de cette automatisation
+  setUp: Configurer MCP
+  learnMore: Connecter un agent de code
diff --git a/services/platform/package.json b/services/platform/package.json
index 3292c9d37f..69bdcd313c 100644
--- a/services/platform/package.json
+++ b/services/platform/package.json
@@ -60,7 +60,6 @@
     "@tanstack/react-router": "1.168.10",
     "@tanstack/react-table": "8.21.3",
     "@xmldom/xmldom": "0.8.15",
-    "@xyflow/react": "12.10.2",
     "acorn": "8.18.0",
     "ajv": "8.20.0",
     "aws4fetch": "^1.0.20",
diff --git a/services/platform/tests/docs-screenshots/manifest.ts b/services/platform/tests/docs-screenshots/manifest.ts
index ef45514a67..a016ebe651 100644
--- a/services/platform/tests/docs-screenshots/manifest.ts
+++ b/services/platform/tests/docs-screenshots/manifest.ts
@@ -1375,7 +1375,7 @@ export const SHOTS: readonly Shot[] = [
     route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
     // Select the LLM step so the inspector shows a node's fields instead of
     // its "select a node" hint — the frame then teaches both halves at once.
-    // A node box is a button carrying `data-automation-node=<id>` (the same
+    // A node box is a button carrying `data-flow-node=<id>` (the same
     // attribute the inspector's Close restores focus to).
     prepare: async (page) => {
       await expect(
@@ -1390,7 +1390,7 @@ export const SHOTS: readonly Shot[] = [
           exact: true,
         }),
       ).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
-      const triageStep = page.locator('[data-automation-node="triage"]');
+      const triageStep = page.locator('[data-flow-node="triage"]');
       await triageStep.waitFor({ timeout: 30_000 });
       await triageStep.click();
     },
@@ -1417,7 +1417,7 @@ export const SHOTS: readonly Shot[] = [
           exact: true,
         }),
       ).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
-      const triageStep = page.locator('[data-automation-node="triage"]');
+      const triageStep = page.locator('[data-flow-node="triage"]');
       await triageStep.waitFor({ timeout: 30_000 });
       await triageStep.click();
       const prompt = page.getByRole('textbox', {
@@ -1529,7 +1529,7 @@ export const SHOTS: readonly Shot[] = [
     },
     readyWhen: (page) =>
       page
-        .locator('[data-automation-node="report"]')
+        .locator('[data-flow-node="report"]')
         .getByText(t('automations.runs.nodeStatus.ok'), { exact: true }),
   },
   {
diff --git a/services/platform/tests/manual/suites/automations.md b/services/platform/tests/manual/suites/automations.md
index ee300a8fd2..c8d5a80bcd 100644
--- a/services/platform/tests/manual/suites/automations.md
+++ b/services/platform/tests/manual/suites/automations.md
@@ -206,9 +206,10 @@ output:
       beside or under the canvas.
 - [ ] `AUTO-F13` · **Canvas graph** — On the workbench, inspect the canvas →
       Region labelled **Automation canvas** (`automations.canvas.ariaLabel`); each
-      node is a box naming its type and inputs it reads
-      (`automations.canvas.readsFrom`); edges carry data/order semantics
-      (`automations.canvas.edge.data` / `automations.canvas.edge.control`); a
+      node is a box naming its type and the nodes it reads (`flow.list.reads`,
+      else `automations.canvas.readsNothing`); the legend says what each line
+      means (`automations.canvas.legend.data` /
+      `automations.canvas.legend.control`); a
       versionless/empty document shows `automations.canvas.empty.title`
 - [ ] `AUTO-F14` · **Node inspector** — Click a node; **Close**
       (`common.aria.close`); Escape; click the box again; click empty canvas →
diff --git a/services/platform/vitest.config.ts b/services/platform/vitest.config.ts
index e039ce30ec..e6afb7dd5d 100644
--- a/services/platform/vitest.config.ts
+++ b/services/platform/vitest.config.ts
@@ -38,6 +38,9 @@ export default defineConfig({
       '@sentry/browser',
       '@sentry/tanstackstart-react',
       'ajv',
+      // The flow canvas lays itself out with ELK behind a dynamic import.
+      'elkjs/lib/elk-api',
+      'elkjs/lib/elk.bundled.js',
       'framer-motion',
       'he',
       'qrcode.react',

From 8acbb1d7e40653462e71dfdfdde0d466c46df86a Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:39:21 +0200
Subject: [PATCH 41/78] refactor(ui): drop the old ELK layout exports

`@tale/ui/flow/elk-layout` and `@tale/ui/flow/use-elk-layout` laid out
nodes for React Flow's own edges; the platform canvas now draws through
`WorkflowCanvas` and `@tale/ui/flow/layout`, so nothing imports them.
---
 packages/ui/package.json                      |   2 -
 .../components/flow/layout/elk-layout.test.ts | 151 -----------
 .../src/components/flow/layout/elk-layout.ts  | 240 ------------------
 .../components/flow/layout/use-elk-layout.ts  |  72 ------
 4 files changed, 465 deletions(-)
 delete mode 100644 packages/ui/src/components/flow/layout/elk-layout.test.ts
 delete mode 100644 packages/ui/src/components/flow/layout/elk-layout.ts
 delete mode 100644 packages/ui/src/components/flow/layout/use-elk-layout.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 7c297c4859..3a1ca360b2 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -146,7 +146,6 @@
     "./filters/filter-panel": "./src/components/filters/filter-panel.tsx",
     "./filters/filter-section": "./src/components/filters/filter-section.tsx",
     "./flow/edge-palette": "./src/components/flow/edge-palette.ts",
-    "./flow/elk-layout": "./src/components/flow/layout/elk-layout.ts",
     "./flow/flow-canvas": "./src/components/flow/flow-canvas.tsx",
     "./flow/flow-legend": "./src/components/flow/flow-legend.tsx",
     "./flow/flow-path-list": "./src/components/flow/flow-path-list.tsx",
@@ -158,7 +157,6 @@
     "./flow/playback": "./src/components/flow/playback/index.ts",
     "./flow/playback-bar": "./src/components/flow/playback/flow-playback-bar.tsx",
     "./flow/types": "./src/components/flow/types.ts",
-    "./flow/use-elk-layout": "./src/components/flow/layout/use-elk-layout.ts",
     "./flow/workflow-canvas": "./src/components/flow/workflow-canvas.tsx",
     "./form": "./src/components/forms/form.tsx",
     "./form-section": "./src/components/forms/form-section.tsx",
diff --git a/packages/ui/src/components/flow/layout/elk-layout.test.ts b/packages/ui/src/components/flow/layout/elk-layout.test.ts
deleted file mode 100644
index f21dbd3d9c..0000000000
--- a/packages/ui/src/components/flow/layout/elk-layout.test.ts
+++ /dev/null
@@ -1,151 +0,0 @@
-import type { Edge, Node } from '@xyflow/react';
-import { describe, expect, it } from 'vitest';
-
-import { layoutWithElk } from './elk-layout';
-
-// Minimal Node factory — layoutWithElk only reads id/parentId/width/height/style.
-function node(id: string, extra: Partial<Node> = {}): Node {
-  return { id, position: { x: 0, y: 0 }, data: {}, ...extra };
-}
-
-function byId(nodes: Node[], id: string): Node {
-  const found = nodes.find((n) => n.id === id);
-  if (!found) throw new Error(`node ${id} missing from layout output`);
-  return found;
-}
-
-describe('layoutWithElk', () => {
-  it('returns the input unchanged for an empty graph', async () => {
-    const { nodes } = await layoutWithElk([], []);
-    expect(nodes).toEqual([]);
-  });
-
-  it('assigns finite positions to a simple chain', async () => {
-    const nodes = [
-      node('a', { width: 100, height: 50 }),
-      node('b', { width: 100, height: 50 }),
-    ];
-    const edges: Edge[] = [{ id: 'e', source: 'a', target: 'b' }];
-    const { nodes: out } = await layoutWithElk(nodes, edges);
-
-    for (const n of out) {
-      expect(Number.isFinite(n.position.x)).toBe(true);
-      expect(Number.isFinite(n.position.y)).toBe(true);
-    }
-    // Top-to-bottom: the target sits below the source.
-    const a = byId(out, 'a');
-    const b = byId(out, 'b');
-    expect(b.position.y).toBeGreaterThan(a.position.y);
-  });
-
-  it('returns an absolute orthogonal route for each layout edge', async () => {
-    const nodes = [
-      node('a', { width: 100, height: 50 }),
-      node('b', { width: 100, height: 50 }),
-    ];
-    const edges: Edge[] = [{ id: 'e', source: 'a', target: 'b' }];
-    const { nodes: out, edgeRoutes } = await layoutWithElk(nodes, edges);
-
-    const route = edgeRoutes.e;
-    expect(route).toBeDefined();
-    expect(route.length).toBeGreaterThanOrEqual(2);
-    for (const p of route) {
-      expect(Number.isFinite(p.x)).toBe(true);
-      expect(Number.isFinite(p.y)).toBe(true);
-    }
-    // The route's endpoints sit between the two stacked nodes (absolute coords).
-    const a = byId(out, 'a');
-    const b = byId(out, 'b');
-    const ys = route.map((p) => p.y);
-    expect(Math.min(...ys)).toBeGreaterThanOrEqual(a.position.y - 1);
-    expect(Math.max(...ys)).toBeLessThanOrEqual(b.position.y + 51);
-  });
-
-  it('offsets routes of edges inside a container to absolute coordinates', async () => {
-    // A node above the loop pushes the container's absolute Y well down, so the
-    // assertion below distinguishes an absolute route from a (wrongly) parent-
-    // relative one.
-    const nodes = [
-      node('top', { width: 100, height: 50 }),
-      node('loop'),
-      node('c1', { parentId: 'loop', width: 80, height: 40 }),
-      node('c2', { parentId: 'loop', width: 80, height: 40 }),
-    ];
-    const edges: Edge[] = [
-      { id: 'enter', source: 'top', target: 'loop' },
-      { id: 'inner', source: 'c1', target: 'c2' },
-    ];
-    const { nodes: out, edgeRoutes } = await layoutWithElk(nodes, edges, {
-      compoundPadding: { top: 80, right: 16, bottom: 24, left: 16 },
-    });
-
-    const route = edgeRoutes.inner;
-    expect(route).toBeDefined();
-    // c1/c2 positions are parent-relative; the route is absolute. Its lowest
-    // point must clear the container's absolute top + header padding — which is
-    // only true if the parent offset was added.
-    const loop = byId(out, 'loop');
-    const minY = Math.min(...route.map((p) => p.y));
-    expect(minY).toBeGreaterThan(loop.position.y + 80);
-  });
-
-  it('lays out a cyclic graph without throwing or producing NaN', async () => {
-    const nodes = [
-      node('a', { width: 100, height: 50 }),
-      node('b', { width: 100, height: 50 }),
-      node('c', { width: 100, height: 50 }),
-    ];
-    const edges: Edge[] = [
-      { id: 'e1', source: 'a', target: 'b' },
-      { id: 'e2', source: 'b', target: 'c' },
-      { id: 'e3', source: 'c', target: 'a' }, // closes the cycle
-    ];
-    const { nodes: out } = await layoutWithElk(nodes, edges, {
-      cycleBreaking: 'DEPTH_FIRST',
-    });
-
-    expect(out).toHaveLength(3);
-    for (const n of out) {
-      expect(Number.isFinite(n.position.x)).toBe(true);
-      expect(Number.isFinite(n.position.y)).toBe(true);
-    }
-  });
-
-  it('auto-sizes a compound container to fit its children plus header padding', async () => {
-    const childWidth = 80;
-    const childHeight = 40;
-    const padding = { top: 80, right: 16, bottom: 24, left: 16 };
-    const nodes = [
-      node('loop'), // compound: no fixed size
-      node('child-1', {
-        parentId: 'loop',
-        width: childWidth,
-        height: childHeight,
-      }),
-      node('child-2', {
-        parentId: 'loop',
-        width: childWidth,
-        height: childHeight,
-      }),
-    ];
-    const edges: Edge[] = [{ id: 'e', source: 'child-1', target: 'child-2' }];
-    const { nodes: out } = await layoutWithElk(nodes, edges, {
-      compoundPadding: padding,
-    });
-
-    const loop = byId(out, 'loop');
-    // Container grew beyond a single child to wrap both children + padding.
-    expect(loop.width ?? 0).toBeGreaterThan(childWidth);
-    expect(loop.height ?? 0).toBeGreaterThan(childHeight + padding.top);
-
-    // Children are positioned relative to the parent, below the header padding,
-    // and within the container bounds (React Flow's nested-node model).
-    for (const id of ['child-1', 'child-2']) {
-      const child = byId(out, id);
-      expect(child.position.y).toBeGreaterThanOrEqual(padding.top - 1);
-      expect(child.position.x + childWidth).toBeLessThanOrEqual(
-        (loop.width ?? 0) + 1,
-      );
-    }
-  });
-});
diff --git a/packages/ui/src/components/flow/layout/elk-layout.ts b/packages/ui/src/components/flow/layout/elk-layout.ts
deleted file mode 100644
index a7ce6208f3..0000000000
--- a/packages/ui/src/components/flow/layout/elk-layout.ts
+++ /dev/null
@@ -1,240 +0,0 @@
-import type { Edge, Node } from '@xyflow/react';
-import { Position } from '@xyflow/react';
-import type { ELK, ElkNode } from 'elkjs/lib/elk-api';
-
-/**
- * The ONE graph-layout engine shared by every React Flow editor in the app
- * (the automation canvas today). It wraps
- * ELK's `layered` algorithm, which — unlike Dagre — natively understands:
- *
- *  - **Compound / nested nodes**: a loop container is laid out as a sub-graph
- *    and auto-sized to fit its children plus padding. ELK reports child
- *    coordinates relative to their parent, which is exactly React Flow's model
- *    for `parentId` nodes, so they map across 1:1 with no manual centering.
- *  - **Cycles**: graphs with cycles are laid out cleanly via a cycle-breaking
- *    pass.
- *  - **Crossing minimisation**: layered sweep keeps complex branches readable.
- *
- * Callers build the React Flow node/edge model (handles, colours, parentId,
- * fixed sizes) and hand it here purely for positioning. Edges passed in
- * `layoutEdges` drive the layering only — render whatever edge set you like.
- */
-
-const DEFAULT_NODE_WIDTH = 300;
-const DEFAULT_NODE_HEIGHT = 80;
-
-export interface ElkLayoutOptions {
-  /** Primary flow direction. 'DOWN' = top-to-bottom (default). */
-  direction?: 'DOWN' | 'RIGHT';
-  /** Spacing between adjacent nodes in the same layer. */
-  nodeNodeSpacing?: number;
-  /** Spacing between consecutive layers (the "rank" gap). */
-  layerSpacing?: number;
-  /** Minimum gap kept between an edge and a node it routes past. */
-  edgeNodeSpacing?: number;
-  /** Cycle-breaking strategy for graphs that may contain cycles. */
-  cycleBreaking?: 'GREEDY' | 'DEPTH_FIRST' | 'INTERACTIVE' | 'MODEL_ORDER';
-  /** Inner padding for compound (container) nodes. `top` reserves header room. */
-  compoundPadding?: {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
-  };
-}
-
-const DEFAULTS: Required<Omit<ElkLayoutOptions, 'compoundPadding'>> & {
-  compoundPadding: NonNullable<ElkLayoutOptions['compoundPadding']>;
-} = {
-  direction: 'DOWN',
-  nodeNodeSpacing: 80,
-  layerSpacing: 70,
-  edgeNodeSpacing: 24,
-  cycleBreaking: 'DEPTH_FIRST',
-  compoundPadding: { top: 80, right: 16, bottom: 24, left: 16 },
-};
-
-// elkjs ships a ~500KB bundle; load it lazily and keep a single instance so it
-// is excluded from the initial chunk and instantiated at most once.
-let elkInstance: Promise<ELK> | null = null;
-function getElk(): Promise<ELK> {
-  if (!elkInstance) {
-    elkInstance = import('elkjs/lib/elk.bundled.js').then(
-      (mod) => new mod.default(),
-    );
-  }
-  return elkInstance;
-}
-
-function nodeDimensions(node: Node): { width: number; height: number } {
-  const styleWidth =
-    typeof node.style?.width === 'number' ? node.style.width : undefined;
-  const styleHeight =
-    typeof node.style?.height === 'number' ? node.style.height : undefined;
-  return {
-    width: node.width ?? styleWidth ?? DEFAULT_NODE_WIDTH,
-    height: node.height ?? styleHeight ?? DEFAULT_NODE_HEIGHT,
-  };
-}
-
-/**
- * Position React Flow nodes with ELK. Returns the same nodes with `position`
- * set (relative to parent for nested nodes, absolute otherwise) and, for
- * compound containers, the ELK-computed `width`/`height` written back so the
- * container renders at the size that actually fits its children.
- */
-export interface ElkPoint {
-  x: number;
-  y: number;
-}
-
-/** Absolute polyline a routed edge should follow, keyed by edge id. */
-export type EdgeRoutes = Record<string, ElkPoint[]>;
-
-export async function layoutWithElk(
-  nodes: Node[],
-  layoutEdges: Edge[],
-  options: ElkLayoutOptions = {},
-): Promise<{ nodes: Node[]; edgeRoutes: EdgeRoutes }> {
-  if (nodes.length === 0) return { nodes, edgeRoutes: {} };
-
-  const opts = { ...DEFAULTS, ...options };
-  const isHorizontal = opts.direction === 'RIGHT';
-
-  // Group nodes by their parent so we can build ELK's hierarchical tree. A node
-  // is "compound" when its id appears as some other node's parentId.
-  const childrenByParent = new Map<string | undefined, Node[]>();
-  for (const node of nodes) {
-    const key = node.parentId ?? undefined;
-    const bucket = childrenByParent.get(key);
-    if (bucket) bucket.push(node);
-    else childrenByParent.set(key, [node]);
-  }
-  const isCompound = (id: string) => childrenByParent.has(id);
-
-  const pad = opts.compoundPadding;
-  const compoundPaddingValue = `[top=${pad.top},left=${pad.left},bottom=${pad.bottom},right=${pad.right}]`;
-
-  const toElkNode = (node: Node): ElkNode => {
-    if (isCompound(node.id)) {
-      // Compound: omit width/height so ELK sizes the container to its children.
-      return {
-        id: node.id,
-        layoutOptions: { 'elk.padding': compoundPaddingValue },
-        children: (childrenByParent.get(node.id) ?? []).map(toElkNode),
-      };
-    }
-    const { width, height } = nodeDimensions(node);
-    return { id: node.id, width, height };
-  };
-
-  const nodeIds = new Set(nodes.map((n) => n.id));
-
-  const root: ElkNode = {
-    id: 'root',
-    layoutOptions: {
-      'elk.algorithm': 'layered',
-      'elk.direction': opts.direction,
-      // Lay out the full hierarchy as one graph so edges may cross container
-      // boundaries (e.g. into / out of a loop) and still route cleanly.
-      'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
-      'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
-      'elk.layered.cycleBreaking.strategy': opts.cycleBreaking,
-      // Orthogonal routing draws arrows as clean right-angles that trace each
-      // path and never cut through a box — the familiar flowchart look. The
-      // routed polyline is returned in `edgeRoutes` for the edge renderer.
-      'elk.edgeRouting': 'ORTHOGONAL',
-      'elk.layered.spacing.nodeNodeBetweenLayers': String(opts.layerSpacing),
-      'elk.layered.spacing.edgeNodeBetweenLayers': String(opts.edgeNodeSpacing),
-      'elk.layered.spacing.edgeEdgeBetweenLayers': String(opts.edgeNodeSpacing),
-      'elk.spacing.nodeNode': String(opts.nodeNodeSpacing),
-      'elk.spacing.edgeNode': String(opts.edgeNodeSpacing),
-    },
-    children: (childrenByParent.get(undefined) ?? []).map(toElkNode),
-    edges: layoutEdges
-      .filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target))
-      .map((edge) => ({
-        id: edge.id,
-        sources: [edge.source],
-        targets: [edge.target],
-      })),
-  };
-
-  const elk = await getElk();
-  const laid = await elk.layout(root);
-
-  // Walk the laid-out tree once, recording both the React-Flow position (ELK
-  // reports child coords relative to their parent — exactly RF's model) and the
-  // absolute top-left of every node (needed to place edge routes). Collect
-  // every edge object across all containers as we go.
-  const relPos = new Map<
-    string,
-    { x: number; y: number; width?: number; height?: number }
-  >();
-  const absPos = new Map<string, ElkPoint>();
-  const elkEdges: NonNullable<ElkNode['edges']> = [];
-  const walk = (elkNode: ElkNode, offsetX: number, offsetY: number) => {
-    const nx = elkNode.x ?? 0;
-    const ny = elkNode.y ?? 0;
-    if (elkNode.id !== 'root') {
-      relPos.set(elkNode.id, {
-        x: nx,
-        y: ny,
-        width: elkNode.width,
-        height: elkNode.height,
-      });
-      absPos.set(elkNode.id, { x: offsetX + nx, y: offsetY + ny });
-    }
-    if (elkNode.edges) elkEdges.push(...elkNode.edges);
-    // Children are positioned relative to this node's origin (root sits at 0,0).
-    const childOffsetX = elkNode.id === 'root' ? 0 : offsetX + nx;
-    const childOffsetY = elkNode.id === 'root' ? 0 : offsetY + ny;
-    elkNode.children?.forEach((c) => walk(c, childOffsetX, childOffsetY));
-  };
-  walk(laid, 0, 0);
-
-  // ELK edge-section coordinates are relative to the lowest common ancestor of
-  // the edge's endpoints. In these graphs an edge is always either between two
-  // top-level nodes (ancestor = root, offset 0) or between two nodes in the
-  // same loop (ancestor = that loop). So the offset is the source's parent.
-  const parentById = new Map<string, string | undefined>(
-    nodes.map((n) => [n.id, n.parentId ?? undefined]),
-  );
-  const edgeRoutes: EdgeRoutes = {};
-  for (const edge of elkEdges) {
-    const section = edge.sections?.[0];
-    if (!section || !edge.id) continue;
-    const sourceId = edge.sources?.[0];
-    const parentId = sourceId ? parentById.get(sourceId) : undefined;
-    const offset = (parentId && absPos.get(parentId)) || { x: 0, y: 0 };
-    const points = [
-      section.startPoint,
-      ...(section.bendPoints ?? []),
-      section.endPoint,
-    ].map((p) => ({ x: p.x + offset.x, y: p.y + offset.y }));
-    edgeRoutes[edge.id] = points;
-  }
-
-  const sourcePosition = isHorizontal ? Position.Right : Position.Bottom;
-  const targetPosition = isHorizontal ? Position.Left : Position.Top;
-
-  const layoutedNodes = nodes.map((node) => {
-    const pos = relPos.get(node.id);
-    if (!pos) return node;
-    const next: Node = {
-      ...node,
-      position: { x: pos.x, y: pos.y },
-      sourcePosition,
-      targetPosition,
-    };
-    // Write ELK's computed size back onto containers so they render to fit.
-    if (isCompound(node.id) && pos.width && pos.height) {
-      next.width = pos.width;
-      next.height = pos.height;
-      next.style = { ...node.style, width: pos.width, height: pos.height };
-    }
-    return next;
-  });
-
-  return { nodes: layoutedNodes, edgeRoutes };
-}
diff --git a/packages/ui/src/components/flow/layout/use-elk-layout.ts b/packages/ui/src/components/flow/layout/use-elk-layout.ts
deleted file mode 100644
index 3c023243f5..0000000000
--- a/packages/ui/src/components/flow/layout/use-elk-layout.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-'use client';
-
-import type { Edge, Node } from '@xyflow/react';
-import { useEffect, useMemo, useRef, useState } from 'react';
-
-import {
-  type EdgeRoutes,
-  type ElkLayoutOptions,
-  layoutWithElk,
-} from './elk-layout';
-
-/**
- * Runs {@link layoutWithElk} (async) and returns positioned nodes for a React
- * Flow canvas. ELK layout is asynchronous, so until the first run resolves
- * `nodes` is empty and `isLayouting` is true.
- *
- * Re-layout fires only when the graph's *structure* changes — a signature of
- * node ids/sizes/parents plus the layered-edge endpoints — so unrelated
- * re-renders (selection, hover) don't thrash the layout. Stale async results
- * are discarded via a cancellation flag.
- */
-export function useElkLayout(
-  nodes: Node[],
-  layoutEdges: Edge[],
-  options?: ElkLayoutOptions,
-): { nodes: Node[]; edgeRoutes: EdgeRoutes; isLayouting: boolean } {
-  const [layouted, setLayouted] = useState<Node[]>([]);
-  const [edgeRoutes, setEdgeRoutes] = useState<EdgeRoutes>({});
-  const [isLayouting, setIsLayouting] = useState(true);
-
-  const signature = useMemo(() => {
-    const nodeSig = nodes
-      .map((n) => {
-        const w = n.width ?? n.style?.width ?? '';
-        const h = n.height ?? n.style?.height ?? '';
-        return `${n.id}:${w}x${h}:${n.parentId ?? ''}`;
-      })
-      .join('|');
-    const edgeSig = layoutEdges.map((e) => `${e.source}>${e.target}`).join('|');
-    return `${nodeSig}#${edgeSig}#${JSON.stringify(options ?? {})}`;
-  }, [nodes, layoutEdges, options]);
-
-  // Keep the latest inputs without widening the effect's dependency list to
-  // referentially-unstable arrays.
-  const latest = useRef({ nodes, layoutEdges, options });
-  latest.current = { nodes, layoutEdges, options };
-
-  useEffect(() => {
-    let cancelled = false;
-    setIsLayouting(true);
-    const { nodes: n, layoutEdges: e, options: o } = latest.current;
-    layoutWithElk(n, e, o)
-      .then((result) => {
-        if (cancelled) return;
-        setLayouted(result.nodes);
-        setEdgeRoutes(result.edgeRoutes);
-        setIsLayouting(false);
-      })
-      .catch((error: unknown) => {
-        console.error('ELK layout failed; rendering unpositioned nodes', error);
-        if (cancelled) return;
-        setLayouted(latest.current.nodes);
-        setEdgeRoutes({});
-        setIsLayouting(false);
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [signature]);
-
-  return { nodes: layouted, edgeRoutes, isLayouting };
-}

From 15b27875ecbca76a6636a76ad8b4ff32727572a6 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:39:27 +0200
Subject: [PATCH 42/78] build(platform): keep the flow layout engine out of the
 cold load

elkjs joins the packages no preloaded chunk may carry: its worker file
and its main-thread build load with the first canvas. The dev server
pre-bundles `elkjs/lib/elk-api`, which starts the layout worker, beside
the bundled build, so its first dynamic import never re-optimizes
mid-session.
---
 services/platform/scripts/check-entry-budget.test.ts | 4 +++-
 services/platform/scripts/check-entry-budget.ts      | 5 ++++-
 services/platform/vite.config.ts                     | 5 ++++-
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/services/platform/scripts/check-entry-budget.test.ts b/services/platform/scripts/check-entry-budget.test.ts
index bb6a582e59..d1c56dd641 100644
--- a/services/platform/scripts/check-entry-budget.test.ts
+++ b/services/platform/scripts/check-entry-budget.test.ts
@@ -56,12 +56,13 @@ describe('findForbiddenPreloads', () => {
 });
 
 describe('forbiddenPackagesIn', () => {
-  it('names the charts, the flow canvas, KaTeX and the single-page libraries a chunk carries', () => {
+  it('names the charts, the flow canvas and its layout engine, KaTeX and the single-page libraries a chunk carries', () => {
     expect(
       forbiddenPackagesIn([
         '../../app/main.tsx',
         '../../../../node_modules/recharts/es6/chart/LineChart.js',
         '../../../../node_modules/@xyflow/react/dist/esm/index.js',
+        '../../../../node_modules/elkjs/lib/elk-api.js',
         '../../../../node_modules/katex/dist/katex.mjs',
         '../../../../node_modules/jszip/dist/jszip.min.js',
         '../../../../node_modules/ajv/dist/ajv.js',
@@ -75,6 +76,7 @@ describe('forbiddenPackagesIn', () => {
     ).toEqual([
       'recharts',
       '@xyflow/react',
+      'elkjs',
       'katex',
       'jszip',
       'ajv',
diff --git a/services/platform/scripts/check-entry-budget.ts b/services/platform/scripts/check-entry-budget.ts
index 99cfc09643..c47334c3b9 100644
--- a/services/platform/scripts/check-entry-budget.ts
+++ b/services/platform/scripts/check-entry-budget.ts
@@ -30,7 +30,9 @@ export const FORBIDDEN_PRELOADS = [
 /**
  * Packages no preloaded chunk may carry, whatever chunk they land in: the
  * charts (recharts has no chunk of its own; its dependencies are the
- * entry's too), the flow canvas, KaTeX, and what single pages need: zip
+ * entry's too), the flow canvas and its layout engine (elkjs: its worker
+ * file and the main-thread build load with the first canvas), KaTeX, and
+ * what single pages need: zip
  * files (skill uploads, document previews), the automation engine's schema
  * validation and YAML (the MCP settings page), its expression parser and
  * scope analysis (the automation editor and the run dialogs), cron schedules
@@ -42,6 +44,7 @@ export const FORBIDDEN_PRELOADS = [
 export const FORBIDDEN_PACKAGES = [
   'recharts',
   '@xyflow/react',
+  'elkjs',
   'katex',
   'jszip',
   'ajv',
diff --git a/services/platform/vite.config.ts b/services/platform/vite.config.ts
index cc9aca6eba..f054447f98 100644
--- a/services/platform/vite.config.ts
+++ b/services/platform/vite.config.ts
@@ -271,9 +271,12 @@ export default defineConfig({
       // discovers it mid-session and triggers a re-optimization that 504s the
       // in-flight dynamic import (an "Outdated Optimize Dep"), crashing the
       // feature into its error boundary:
-      //   - `elkjs`       -> the shared flow layout engine (lazy `elk.bundled.js`)
+      //   - `elkjs`       -> the shared flow layout engine (lazy `elk-api`,
+      //     which starts the layout worker, and `elk.bundled.js`, the
+      //     main-thread fallback)
       //   - react-json-view -> the JSON input/viewer (workflow step config panel)
       // Pre-bundling them keeps the optimizer hash stable from cold start.
+      'elkjs/lib/elk-api',
       'elkjs/lib/elk.bundled.js',
       '@microlink/react-json-view',
     ],

From a8b98fe336d257489711ff814f8b0b47e3a7ceb9 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:39:40 +0200
Subject: [PATCH 43/78] docs(platform): say the canvas lays itself out and
 ignores ui

The `ui` block no longer holds positions anyone reads: the concepts page
in English, German and French, the engine's type comment and the MCP
`get_docs` text now say Tale lays the canvas out from the references,
keeps `ui` as written and ignores it, so an agent never writes
positions.
---
 docs/de/platform/automations/concepts.md   | 2 +-
 docs/en/platform/automations/concepts.md   | 2 +-
 docs/fr/platform/automations/concepts.md   | 2 +-
 services/platform/lib/engine/api/docs.ts   | 1 +
 services/platform/lib/engine/core/types.ts | 3 ++-
 5 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/de/platform/automations/concepts.md b/docs/de/platform/automations/concepts.md
index 583cc6fa20..c959839f55 100644
--- a/docs/de/platform/automations/concepts.md
+++ b/docs/de/platform/automations/concepts.md
@@ -42,7 +42,7 @@ tests:
     input: { invoiceId: 'inv-1' }
 ```
 
-Der `ui`-Block speichert die Positionen auf dem Canvas. Verschieben ändert die Anordnung, nicht die Ausführung einer Node.
+Tale ordnet den Canvas anhand der Verweise zwischen den Nodes an, niemand platziert eine Node von Hand. Ein `ui`-Block ist freie Metadaten: Tale behält ihn unverändert und ignoriert ihn.
 
 ### Kanten entstehen, sie werden nicht deklariert
 
diff --git a/docs/en/platform/automations/concepts.md b/docs/en/platform/automations/concepts.md
index 25b24c7319..80d3562d32 100644
--- a/docs/en/platform/automations/concepts.md
+++ b/docs/en/platform/automations/concepts.md
@@ -42,7 +42,7 @@ tests:
     input: { invoiceId: 'inv-1' }
 ```
 
-The `ui` block stores canvas positions. Moving a node changes the layout, without changing its execution.
+Tale lays out the canvas from the references between nodes, so nobody places a node. A `ui` block is free metadata: Tale keeps it as written and ignores it.
 
 ### Edges are derived, not declared
 
diff --git a/docs/fr/platform/automations/concepts.md b/docs/fr/platform/automations/concepts.md
index 006756ddd5..5a1de706fb 100644
--- a/docs/fr/platform/automations/concepts.md
+++ b/docs/fr/platform/automations/concepts.md
@@ -42,7 +42,7 @@ tests:
     input: { invoiceId: 'inv-1' }
 ```
 
-Le bloc `ui` conserve la disposition du canvas. Déplacer un nœud modifie sa position, sans changer son exécution.
+Tale dispose le canevas à partir des références entre les nœuds : personne ne place un nœud à la main. Un bloc `ui` contient des métadonnées libres que Tale conserve telles quelles et ignore.
 
 ### Les liaisons se déduisent, elles ne se déclarent pas
 
diff --git a/services/platform/lib/engine/api/docs.ts b/services/platform/lib/engine/api/docs.ts
index a579bb2277..f111b14041 100644
--- a/services/platform/lib/engine/api/docs.ts
+++ b/services/platform/lib/engine/api/docs.ts
@@ -182,6 +182,7 @@ An automation is a node graph. Execution order is computed automatically from da
 - "inputs": JSON Schema describing the runtime input.
 - "output": the automation's return value (templates allowed inside).
 - "tests": [{name, input, expect: {output?, effects?: [{connector, input}]}}] — acceptance tests run by test_automation.
+- "ui": free metadata. Tale lays the canvas out from the references; never write positions — "ui" is kept but ignored.
 
 YAML gotchas (top causes of failure):
 - ALWAYS double-quote any string containing {{ }} or starting with # — unquoted they break YAML.
diff --git a/services/platform/lib/engine/core/types.ts b/services/platform/lib/engine/core/types.ts
index 5017962e38..61140b68b2 100644
--- a/services/platform/lib/engine/core/types.ts
+++ b/services/platform/lib/engine/core/types.ts
@@ -131,7 +131,8 @@ export interface Automation {
   /** The automation's return value; templates allowed anywhere inside. */
   output?: unknown;
   tests?: AutomationTest[];
-  /** Canvas metadata (e.g. `{positions}`); ignored by the engine. */
+  /** Free metadata; ignored — the canvas lays out every automation from its
+   * references. */
   ui?: Record<string, unknown>;
 }
 

From bdded78ac3d36ca69740287aa76c049048e48100 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:41:24 +0200
Subject: [PATCH 44/78] test(platform): hash the shipped automations the canvas
 suites read

The canvas's component suites lay out the automations Tale ships (Triage
GitHub issues, Gmail triage inbox): the browser suite imports their
documents and the jsdom suites read them as text. `test:ui` and
`test:browser` now hash `configs/platform/custom/automations`, so an edit
to one of those documents re-runs the suites that measure it.
---
 services/platform/turbo.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/services/platform/turbo.json b/services/platform/turbo.json
index 9ddbf0f17a..252f3dfb0f 100644
--- a/services/platform/turbo.json
+++ b/services/platform/turbo.json
@@ -115,6 +115,7 @@
         "!backend/domains/websites/**",
         "!tests/e2e/**",
         "!tests/manual/**",
+        "$TURBO_ROOT$/configs/platform/custom/automations/**",
         "$TURBO_ROOT$/packages/ui/package.json",
         "$TURBO_ROOT$/packages/ui/src/**",
         "$TURBO_ROOT$/packages/ui/tailwind-preset.ts"
@@ -182,6 +183,7 @@
         "!backend/domains/websites/**",
         "!tests/e2e/**",
         "!tests/manual/**",
+        "$TURBO_ROOT$/configs/platform/custom/automations/**",
         "$TURBO_ROOT$/packages/ui/package.json",
         "$TURBO_ROOT$/packages/ui/src/**",
         "$TURBO_ROOT$/packages/ui/tailwind-preset.ts"

From 524426ab0d0262d795c292444350333bb1bf7491 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 21:59:23 +0200
Subject: [PATCH 45/78] fix(platform): keep every key of an automation through
 an editor save

The editor's draft is now the raw stored document: an inspector edit
patches it, and the check and a save send it back. A connector's
credential, keys this build does not know, a node without a type, the
tests and ui are no longer dropped or rewritten by an unrelated edit.
The reading view keeps every key it does not narrow, and keeps an
untyped node at its index so the check's pointers still name it.
---
 .../components/automation-editor.test.tsx     |  40 +++++
 .../components/automation-editor.tsx          | 102 ++++-------
 .../hooks/use-automation-validation.test.tsx  |  11 +-
 .../hooks/use-automation-validation.ts        |   9 +-
 .../features/automations/lib/document.test.ts |  19 +-
 .../app/features/automations/lib/document.ts  | 107 +++++++----
 .../automations/lib/draft-document.test.ts    | 167 ++++++++++++++++++
 .../automations/lib/draft-document.ts         |  84 +++++++++
 8 files changed, 424 insertions(+), 115 deletions(-)
 create mode 100644 services/platform/app/features/automations/lib/draft-document.test.ts
 create mode 100644 services/platform/app/features/automations/lib/draft-document.ts

diff --git a/services/platform/app/features/automations/components/automation-editor.test.tsx b/services/platform/app/features/automations/components/automation-editor.test.tsx
index cc08f4fd4e..c242e2a3bd 100644
--- a/services/platform/app/features/automations/components/automation-editor.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.test.tsx
@@ -1393,6 +1393,46 @@ describe('AutomationEditor', () => {
     expect(toastSpy).not.toHaveBeenCalled();
   });
 
+  it('saves and checks the document as stored, with only the edit changed', async () => {
+    // What this build has no control for — a connector's credential, a key
+    // a newer engine knows, a node without a type, the tests, the canvas
+    // metadata, an unknown top-level key — travels with the edit unchanged.
+    const stored = {
+      version: 1,
+      name: 'billing/dunning',
+      nodes: [
+        { id: 'summary', type: 'llm', prompt: 'One sentence, please.' },
+        {
+          id: 'post',
+          type: 'slack.post_message',
+          credential: 'slack-ops',
+          input: { channel: '#billing' },
+          reviewNote: 'kept',
+        },
+        { id: 'draft_only', prompt: 'no type yet' },
+      ],
+      tests: [{ name: 'smoke', expect: { output: null } }],
+      ui: { positions: { summary: { x: 0, y: 0 } } },
+      owner: 'billing team',
+    };
+    state.document = stored;
+    const { user } = renderPage();
+    await editTheNode(user);
+    const checked = validationMock.calls.at(-1)?.document;
+    expect(checked).toEqual({
+      ...stored,
+      nodes: [{ ...stored.nodes[0], when: 'x' }, ...stored.nodes.slice(1)],
+    });
+    await user.click(saveButton());
+    await user.click(screen.getByRole('button', { name: 'Save version' }));
+    await waitFor(() => {
+      expect(saveMutation.mutateAsync).toHaveBeenCalledTimes(1);
+    });
+    expect(saveMutation.mutateAsync.mock.calls[0]?.[0].automation).toEqual(
+      checked,
+    );
+  });
+
   it('keeps the edited version’s package metadata when saving a node change', async () => {
     state.presentation = { name: 'Pack title' };
     state.settings = { folder: 'Setup', forms: [] };
diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 31209d7bef..17a2e290d5 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -92,6 +92,11 @@ import { focusAutomationNode } from '../hooks/use-deselect-on-escape';
 import { automationDetailPathname } from '../lib/detail-paths';
 import { DOCUMENT_DIRTY_KEY } from '../lib/dirty-keys';
 import { readDocument } from '../lib/document';
+import {
+  applyNodePatch,
+  rawDocumentOf,
+  type RawDocument,
+} from '../lib/draft-document';
 import type { AutomationEditorView } from '../lib/editor-search';
 import {
   automationErrorCode,
@@ -140,63 +145,11 @@ import { AutomationVersionPicker } from './automation-version-picker';
 import { CodingAgentButton } from './coding-agent-entry';
 import { NodeFields, NodeInspector } from './node-inspector';
 
-/**
- * Every field of a node a patch may clear. Spelling them out keeps the unset
- * path typed — `delete` needs a key the compiler knows is optional — and the
- * list is checked against `NodeDef` itself, so a field added to the document
- * grammar cannot silently become unclearable.
- */
-const CLEARABLE_NODE_FIELDS = [
-  'when',
-  'elseOf',
-  'forEach',
-  'repeatUntil',
-  'maxRepeats',
-  'onError',
-  'input',
-  'code',
-  'prompt',
-  'system',
-  'model',
-  'modelProvider',
-  'outputSchema',
-  'automation',
-  // Agent equipment — clearing a picker to empty must delete the field, not
-  // leave the previous grant behind (and `readNode` now round-trips these).
-  'harness',
-  'skills',
-  'connectors',
-  'tools',
-  'secrets',
-  'files',
-] as const satisfies readonly Exclude<keyof NodeDef, 'id' | 'type'>[];
-
 /** The run-scope Select's "organization-wide" choice. A Radix Select item
  * cannot carry an empty value, so the org-wide option needs a real sentinel
  * that maps back to an omitted `projectId`. */
 const RUN_SCOPE_ORG_WIDE = '__org_wide__';
 
-/** Apply one node patch to a document, dropping the fields the patch clears. */
-function patchNode(
-  automation: Automation,
-  nodeId: string,
-  patch: Partial<NodeDef>,
-): Automation {
-  return {
-    ...automation,
-    nodes: automation.nodes.map((node) => {
-      if (node.id !== nodeId) return node;
-      const next: NodeDef = { ...node, ...patch };
-      for (const field of CLEARABLE_NODE_FIELDS) {
-        // `undefined` in a patch means "unset": a cleared `when` must leave the
-        // document, not sit in it as an empty condition the engine would read.
-        if (field in patch && patch[field] === undefined) delete next[field];
-      }
-      return next;
-    }),
-  };
-}
-
 const NO_DIRTY_KEYS: ReadonlySet<string> = new Set();
 /** A draft diverges from the stored version as one thing — its document. */
 const DOCUMENT_DIRTY_KEYS: ReadonlySet<string> = new Set([DOCUMENT_DIRTY_KEY]);
@@ -347,7 +300,10 @@ function AutomationEditorScope({
       });
     }
   }, [selectedNodeId]);
-  const [draft, setDraft] = useState<Automation | null>(null);
+  /** The draft: the raw document with the author's edits (see
+   * `../lib/draft-document`) — what the check, a save and the Source view
+   * read. The canvas and the inspector read its narrowed view. */
+  const [draft, setDraft] = useState<RawDocument | null>(null);
   /** The version the draft was built on — pinned on its first edit, sent
    * with the save so the store can refuse a draft another tab overtook. */
   const draftBaseRef = useRef<number | undefined>(undefined);
@@ -458,23 +414,30 @@ function AutomationEditorScope({
         ? t('detail.runScope.confirmProject', { project: runProjectName })
         : t('detail.runScope.confirmOrgWide');
 
-  const stored = useMemo(
-    () => readDocument(automationQuery.data?.document),
+  const storedRaw = useMemo(
+    () => rawDocumentOf(automationQuery.data?.document),
     [automationQuery.data?.document],
   );
+  const stored = useMemo(() => readDocument(storedRaw), [storedRaw]);
   const deployed = useMemo(
     () => readDocument(deployedQuery.data?.document),
     [deployedQuery.data?.document],
   );
-  const automation = draft ?? stored;
+  const draftView = useMemo(
+    () => (draft === null ? null : readDocument(draft)),
+    [draft],
+  );
+  const automation = draftView ?? stored;
+  /** The document on screen as stored or edited, every key kept. */
+  const rawDocument = draft ?? storedRaw;
   // The canvas redraws a draft at a pause in the edits — the pause the
   // check waits for too — so typing a reference never relays it out per
   // keystroke; until the first pause it keeps the document the draft started
   // from, whatever version lands meanwhile. A stored version (opened, saved,
   // switched to) shows at once.
-  const pausedDraft = usePausedDraft(draft);
+  const pausedDraft = usePausedDraft(draftView);
   const canvasDocument =
-    draft === null ? stored : (pausedDraft ?? draftOrigin ?? stored);
+    draftView === null ? stored : (pausedDraft ?? draftOrigin ?? stored);
 
   const runs = runsQuery.data ?? [];
   const lastRun = runs[0];
@@ -512,7 +475,7 @@ function AutomationEditorScope({
   const validation = useAutomationValidation({
     organizationId,
     automationSlug,
-    document: automation,
+    document: rawDocument,
     isDraft: draft !== null,
     enabled: canAuthor,
   });
@@ -892,7 +855,9 @@ function AutomationEditorScope({
 
   const onChangeNode = useCallback(
     (patch: Partial<NodeDef>) => {
-      if (!automation || selectedNodeId === null) return;
+      if (!automation || rawDocument === null || selectedNodeId === null) {
+        return;
+      }
       // The base is pinned on the draft's FIRST edit: the detail query
       // follows every version another tab saves (its hint invalidates the
       // read), so reading the version at save time would name the one that
@@ -903,9 +868,15 @@ function AutomationEditorScope({
         setDraftOrigin(automation);
         draftEpochRef.current += 1;
       }
-      setDraft(patchNode(automation, selectedNodeId, patch));
+      setDraft(applyNodePatch(rawDocument, selectedNodeId, patch));
     },
-    [automation, selectedNodeId, draft, automationQuery.data?.version],
+    [
+      automation,
+      rawDocument,
+      selectedNodeId,
+      draft,
+      automationQuery.data?.version,
+    ],
   );
 
   const isDirty = draft !== null;
@@ -1110,11 +1081,12 @@ function AutomationEditorScope({
   const submitSave = async (baseVersion: number | undefined): Promise<void> => {
     const submittedEpoch = draftEpochRef.current;
     const submittedHash = validation.currentHash;
+    const submitted = rawDocument;
     const saved = await save.mutateAsync({
       organizationId,
-      automation,
+      automation: submitted,
       // Package metadata belongs to the version being edited, even when
-      // the author only changes a node or its canvas position.
+      // the author only changes a node.
       ...(automationQuery.data?.presentation !== undefined && {
         presentation: automationQuery.data.presentation,
       }),
@@ -1153,7 +1125,7 @@ function AutomationEditorScope({
     draftBaseRef.current = saved.version;
     setDraftBase(saved.version);
     savedHereRef.current = saved.version;
-    setDraft((current) => (current === automation ? null : current));
+    setDraft((current) => (current === submitted ? null : current));
     setSaveMessage('');
     // The save appended a version; show it, whichever one was on screen.
     onSelectVersion(undefined);
diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
index 7a7a22c1ec..81872077a9 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
@@ -3,8 +3,6 @@ import { act, renderHook, waitFor } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { Automation } from '@/lib/engine/core/types';
-
 const { validate } = vi.hoisted(() => ({ validate: vi.fn() }));
 vi.mock('@/app/lib/backend/automation-validation', async (importOriginal) => ({
   ...(await importOriginal<
@@ -13,6 +11,7 @@ vi.mock('@/app/lib/backend/automation-validation', async (importOriginal) => ({
   validateAutomationDraft: validate,
 }));
 
+import type { RawDocument } from '../lib/draft-document';
 import {
   documentHash,
   useAutomationValidation,
@@ -27,7 +26,7 @@ import {
  * is on its way, and a failure that says so without a toast.
  */
 
-function doc(prompt: string): Automation {
+function doc(prompt: string): RawDocument {
   return {
     version: 1,
     name: 'support/triage',
@@ -52,7 +51,7 @@ function wrapper({ children }: { children: ReactNode }) {
 }
 
 interface Props {
-  document: Automation | null;
+  document: RawDocument | null;
   isDraft: boolean;
   enabled: boolean;
 }
@@ -285,8 +284,8 @@ describe('useAutomationValidation', () => {
 
 describe('documentHash', () => {
   it('names a document by its content, whatever order its keys are in', () => {
-    const a = { name: 'x', version: 1, nodes: [] } as unknown as Automation;
-    const b = { nodes: [], version: 1, name: 'x' } as unknown as Automation;
+    const a = { name: 'x', version: 1, nodes: [] } satisfies RawDocument;
+    const b = { nodes: [], version: 1, name: 'x' } satisfies RawDocument;
     expect(documentHash(a)).toBe(documentHash(b));
     expect(documentHash(a)).not.toBe(documentHash(doc('A')));
   });
diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.ts b/services/platform/app/features/automations/hooks/use-automation-validation.ts
index ca8938ac6a..4d680225a3 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.ts
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.ts
@@ -15,13 +15,13 @@ import {
   type ValidationDetail,
 } from '@/app/lib/backend/automation-validation';
 import { backendKey } from '@/app/lib/backend/query-keys';
-import type { Automation } from '@/lib/engine/core/types';
 import type {
   AnalysisView,
   TypesView,
 } from '@/lib/shared/schemas/automation-issues';
 import { stableStringify } from '@/lib/shared/utils/stable-stringify';
 
+import type { RawDocument } from '../lib/draft-document';
 import { withIssueIds, type AutomationIssue } from '../lib/issues';
 
 /** How long the editor waits after the last edit before it checks a draft. */
@@ -116,7 +116,7 @@ function cyrb53(text: string): string {
 }
 
 /** The same document hashes the same, whatever order its keys were written in. */
-export function documentHash(document: Automation): string {
+export function documentHash(document: RawDocument): string {
   return cyrb53(stableStringify(document));
 }
 
@@ -184,8 +184,9 @@ export function useAutomationValidation({
 }: {
   organizationId: string;
   automationSlug: string;
-  /** The draft, or the stored version on screen. */
-  document: Automation | null;
+  /** The draft, or the stored version on screen — raw, every key kept, as
+   * a save would send it. */
+  document: RawDocument | null;
   /** A draft waits for a pause in the edits; a stored version does not. */
   isDraft: boolean;
   /** Only authors may have a document checked (the route is author-gated). */
diff --git a/services/platform/app/features/automations/lib/document.test.ts b/services/platform/app/features/automations/lib/document.test.ts
index 2ba55b24c8..60cd01d852 100644
--- a/services/platform/app/features/automations/lib/document.test.ts
+++ b/services/platform/app/features/automations/lib/document.test.ts
@@ -29,7 +29,7 @@ describe('readDocument', () => {
     expect(readDocument({})).toEqual({ name: '', nodes: [] });
   });
 
-  it('drops a node that cannot be drawn instead of rendering a blank box', () => {
+  it('keeps a node without a type at its index, and drops one without an id', () => {
     const automation = readDocument({
       name: 'partial',
       nodes: [
@@ -39,7 +39,22 @@ describe('readDocument', () => {
         'nonsense',
       ],
     });
-    expect(automation?.nodes.map((node) => node.id)).toEqual(['ok']);
+    expect(automation?.nodes).toEqual([
+      { id: 'ok', type: 'transform', code: 'return 1;' },
+      { id: 'no_type', type: '' },
+    ]);
+  });
+
+  it('keeps every key it does not narrow, as written', () => {
+    const node = {
+      id: 'post',
+      type: 'slack.post_message',
+      credential: 'slack-ops',
+      input: { channel: '#ops' },
+      futureKey: { nested: [1, 2] },
+    };
+    const automation = readDocument({ name: 'a', nodes: [node] });
+    expect(automation?.nodes[0]).toEqual(node);
   });
 
   it('keeps only the control-flow values the engine would accept', () => {
diff --git a/services/platform/app/features/automations/lib/document.ts b/services/platform/app/features/automations/lib/document.ts
index 4945357c98..e845467a6d 100644
--- a/services/platform/app/features/automations/lib/document.ts
+++ b/services/platform/app/features/automations/lib/document.ts
@@ -3,11 +3,16 @@
  *
  * The store keeps a version's document as `v.any()` — the engine owns the v1
  * grammar and Convex would have to mirror the whole node grammar to type it —
- * so every surface that renders one starts by narrowing the raw value here.
- * The narrowing is deliberately forgiving: a document authored by an agent may
+ * so every surface that renders one reads it through this narrowed view. The
+ * narrowing is deliberately forgiving: a document authored by an agent may
  * be incomplete, and a canvas that refuses to draw an imperfect document is
- * useless exactly when it is needed most. What cannot be understood is
- * dropped, never guessed.
+ * useless exactly when it is needed most. A known field whose value has the
+ * wrong kind is left out of the view, never guessed; every other key stays
+ * on it as written.
+ *
+ * This is a reading view only. The editor's draft is the raw document
+ * (`./draft-document`): an edit patches the raw object, and a save sends it,
+ * so nothing this view leaves out is lost.
  *
  * `ui` is the engine's declared free metadata. The canvas lays every
  * automation out from its references and never reads it; it is carried
@@ -32,50 +37,76 @@ function readStringArray(value: unknown): string[] | undefined {
   return value.filter((item): item is string => typeof item === 'string');
 }
 
-/** Narrow one raw node. A node without a usable `id` and `type` cannot be
- * drawn or referenced, so it is dropped rather than rendered as a blank box. */
+/** The node fields that hold a string. */
+const STRING_FIELDS = [
+  'when',
+  'elseOf',
+  'forEach',
+  'repeatUntil',
+  'code',
+  'prompt',
+  'system',
+  'model',
+  // The provider pin saved with the model pick. Dropping it made every
+  // stored pick render as unpinned — the editor showed whatever provider the
+  // serving walk would choose.
+  'modelProvider',
+  'automation',
+  // Agent equipment: the harness that runs the turn.
+  'harness',
+] as const;
+
+/** The node fields that hold a JSON object. */
+const OBJECT_FIELDS = ['input', 'outputSchema', 'files'] as const;
+
+/** An agent node's string-list equipment. */
+const LIST_FIELDS = ['skills', 'connectors', 'tools', 'secrets'] as const;
+
+/** The keys the view narrows to their kinds; a value of the wrong kind is
+ *  left out. */
+const NARROWED_FIELDS: ReadonlySet<string> = new Set([
+  'id',
+  'type',
+  ...STRING_FIELDS,
+  ...OBJECT_FIELDS,
+  ...LIST_FIELDS,
+  'maxRepeats',
+  'onError',
+]);
+
+/**
+ * Narrow one raw node. A node without a usable `id` cannot be referenced,
+ * selected or pointed at, so it is left out of the view (the check reports
+ * it). A node without a `type` stays, with an empty type: it is not drawn,
+ * but its place in the list keeps every later node at the index the check's
+ * pointers name.
+ */
 function readNode(value: unknown): NodeDef | undefined {
   if (!isRecord(value)) return undefined;
   const id = readString(value.id);
-  const type = readString(value.type);
-  if (!id || !type) return undefined;
-  const node: NodeDef = { id, type };
-  for (const field of [
-    'when',
-    'elseOf',
-    'forEach',
-    'repeatUntil',
-    'code',
-    'prompt',
-    'system',
-    'model',
-    // The provider pin saved with the model pick. Dropping it here made every
-    // stored pick render as unpinned — the editor showed whatever provider the
-    // serving walk would choose — and the next save persisted that loss.
-    'modelProvider',
-    'automation',
-    // Agent equipment: the harness that runs the turn. Dropping it here would
-    // make the canvas read an agent node as unequipped and a later save would
-    // persist that loss.
-    'harness',
-  ] as const) {
+  if (!id) return undefined;
+  const node: NodeDef = { id, type: readString(value.type) ?? '' };
+  // Every key this view does not narrow stays as written — a connector's
+  // `credential`, a key a newer engine knows.
+  for (const [key, raw] of Object.entries(value)) {
+    if (!NARROWED_FIELDS.has(key)) Object.assign(node, { [key]: raw });
+  }
+  for (const field of STRING_FIELDS) {
     const raw = value[field];
     if (typeof raw === 'string') node[field] = raw;
   }
-  if (typeof value.maxRepeats === 'number') node.maxRepeats = value.maxRepeats;
-  if (value.onError === 'fail' || value.onError === 'continue') {
-    node.onError = value.onError;
+  for (const field of OBJECT_FIELDS) {
+    const raw = value[field];
+    if (isRecord(raw)) node[field] = raw;
   }
-  if (isRecord(value.input)) node.input = value.input;
-  if (isRecord(value.outputSchema)) node.outputSchema = value.outputSchema;
-  // The rest of an agent node's equipment — the skills, connectors, platform
-  // tools and secrets the wizard binds, and staged files. Same reason as
-  // `harness`: read them through so a prompt edit + save preserves them.
-  for (const field of ['skills', 'connectors', 'tools', 'secrets'] as const) {
+  for (const field of LIST_FIELDS) {
     const list = readStringArray(value[field]);
     if (list !== undefined) node[field] = list;
   }
-  if (isRecord(value.files)) node.files = value.files;
+  if (typeof value.maxRepeats === 'number') node.maxRepeats = value.maxRepeats;
+  if (value.onError === 'fail' || value.onError === 'continue') {
+    node.onError = value.onError;
+  }
   return node;
 }
 
diff --git a/services/platform/app/features/automations/lib/draft-document.test.ts b/services/platform/app/features/automations/lib/draft-document.test.ts
new file mode 100644
index 0000000000..9e5afb46d2
--- /dev/null
+++ b/services/platform/app/features/automations/lib/draft-document.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest';
+
+import { readDocument } from './document';
+import {
+  applyDocumentPatch,
+  applyNodePatch,
+  rawDocumentOf,
+  type RawDocument,
+} from './draft-document';
+
+/**
+ * The draft is the stored document, raw. These tests pin what an inspector
+ * edit must never do to the parts of a document it does not touch: drop a
+ * key this build has no control for, a node it cannot draw, the tests or
+ * the canvas metadata.
+ */
+
+const stored: RawDocument = {
+  version: 1,
+  name: 'ops/post-summary',
+  description: 'Posts the day in one line.',
+  inputs: {
+    type: 'object',
+    properties: { day: { type: 'string' } },
+    required: ['day'],
+  },
+  nodes: [
+    {
+      id: 'summary',
+      type: 'llm',
+      model: 'anthropic/claude-haiku-4-5',
+      prompt: 'Summarize {{ input.day }}',
+    },
+    {
+      id: 'post',
+      type: 'slack.post_message',
+      credential: 'slack-ops',
+      input: { channel: '#ops', text: '{{ nodes.summary.output.text }}' },
+      reviewNote: 'kept by a newer engine',
+    },
+    { id: 'draft_only', prompt: 'no type yet' },
+  ],
+  output: { posted: '{{ nodes.post.output.ok }}' },
+  tests: [{ name: 'smoke', expect: { output: { posted: true } } }],
+  ui: { positions: { summary: { x: 0, y: 0 }, post: { x: 0, y: 0 } } },
+  owner: 'a top-level key the validator reports',
+};
+
+describe('applyNodePatch', () => {
+  const edited = applyNodePatch(stored, 'summary', { prompt: 'Shorter.' });
+
+  it('patches the node it names and nothing else', () => {
+    expect(edited.nodes).toEqual([
+      {
+        id: 'summary',
+        type: 'llm',
+        model: 'anthropic/claude-haiku-4-5',
+        prompt: 'Shorter.',
+      },
+      (stored.nodes as unknown[])[1],
+      (stored.nodes as unknown[])[2],
+    ]);
+  });
+
+  it("keeps a connector's credential and a key this build does not know", () => {
+    const patched = applyNodePatch(stored, 'post', {
+      input: { channel: '#ops-daily', text: 'hi' },
+    });
+    expect((patched.nodes as unknown[])[1]).toEqual({
+      id: 'post',
+      type: 'slack.post_message',
+      credential: 'slack-ops',
+      input: { channel: '#ops-daily', text: 'hi' },
+      reviewNote: 'kept by a newer engine',
+    });
+  });
+
+  it('keeps a node without a type, the tests, ui and unknown top-level keys byte for byte', () => {
+    const { nodes: _nodes, ...rest } = edited;
+    const { nodes: _storedNodes, ...storedRest } = stored;
+    expect(JSON.stringify(rest)).toBe(JSON.stringify(storedRest));
+    expect((edited.nodes as unknown[])[2]).toBe((stored.nodes as unknown[])[2]);
+    expect(edited.tests).toBe(stored.tests);
+    expect(edited.ui).toBe(stored.ui);
+  });
+
+  it('removes a key patched to undefined, whatever the key', () => {
+    const cleared = applyNodePatch(stored, 'post', {
+      credential: undefined,
+      reviewNote: undefined,
+    });
+    expect((cleared.nodes as unknown[])[1]).toEqual({
+      id: 'post',
+      type: 'slack.post_message',
+      input: { channel: '#ops', text: '{{ nodes.summary.output.text }}' },
+    });
+  });
+
+  it('patches the first node of a repeated id, as both executors run it', () => {
+    const doubled: RawDocument = {
+      name: 'a',
+      nodes: [
+        { id: 'x', type: 'transform', code: 'return 1;' },
+        { id: 'x', type: 'transform', code: 'return 2;' },
+      ],
+    };
+    expect(applyNodePatch(doubled, 'x', { code: 'return 3;' }).nodes).toEqual([
+      { id: 'x', type: 'transform', code: 'return 3;' },
+      { id: 'x', type: 'transform', code: 'return 2;' },
+    ]);
+  });
+
+  it('answers the same document for an id it does not have', () => {
+    expect(applyNodePatch(stored, 'missing', { prompt: 'x' })).toBe(stored);
+    expect(applyNodePatch({ name: 'a' }, 'x', { prompt: 'x' })).toEqual({
+      name: 'a',
+    });
+  });
+
+  it('never changes the document it was given', () => {
+    const before = JSON.stringify(stored);
+    applyNodePatch(stored, 'summary', { prompt: 'changed', model: undefined });
+    expect(JSON.stringify(stored)).toBe(before);
+  });
+});
+
+describe('applyDocumentPatch', () => {
+  it('sets the run input schema and the output', () => {
+    const patched = applyDocumentPatch(stored, {
+      inputs: { type: 'object' },
+      output: '{{ nodes.post.output }}',
+    });
+    expect(patched.inputs).toEqual({ type: 'object' });
+    expect(patched.output).toBe('{{ nodes.post.output }}');
+    expect(patched.nodes).toBe(stored.nodes);
+    expect(patched.owner).toBe(stored.owner);
+  });
+
+  it('removes a field patched to undefined and leaves one it does not name', () => {
+    const patched = applyDocumentPatch(stored, { output: undefined });
+    expect('output' in patched).toBe(false);
+    expect(patched.inputs).toBe(stored.inputs);
+  });
+});
+
+describe('the reading view of a raw draft', () => {
+  it('reads the patched draft with every key the view does not narrow', () => {
+    const view = readDocument(
+      applyNodePatch(stored, 'summary', { prompt: 'Shorter.' }),
+    );
+    expect(view?.nodes.map((node) => [node.id, node.type])).toEqual([
+      ['summary', 'llm'],
+      ['post', 'slack.post_message'],
+      ['draft_only', ''],
+    ]);
+    expect(view?.nodes[1]).toMatchObject({ credential: 'slack-ops' });
+  });
+});
+
+describe('rawDocumentOf', () => {
+  it('is the stored object itself, or null when it is not one', () => {
+    expect(rawDocumentOf(stored)).toBe(stored);
+    expect(rawDocumentOf(null)).toBeNull();
+    expect(rawDocumentOf([])).toBeNull();
+    expect(rawDocumentOf('yaml')).toBeNull();
+  });
+});
diff --git a/services/platform/app/features/automations/lib/draft-document.ts b/services/platform/app/features/automations/lib/draft-document.ts
new file mode 100644
index 0000000000..e71da7d215
--- /dev/null
+++ b/services/platform/app/features/automations/lib/draft-document.ts
@@ -0,0 +1,84 @@
+/**
+ * The editor's draft is the stored document itself, raw: every key an
+ * author, an agent or an older build wrote stays in it, whether or not this
+ * build has a control for it. The canvas and the inspector read a narrowed
+ * view of it (`readDocument` in `./document`); an edit patches the raw
+ * object, and the check, a save and a deploy send the raw object back.
+ *
+ * Narrowing the draft itself once dropped a connector node's `credential`,
+ * any key the reading view did not know and every node it could not draw,
+ * and gave each test an `input: null` it never had — all of it persisted by
+ * the next save of an unrelated prompt edit.
+ */
+
+/** A document as stored: a JSON object, nothing about it assumed. */
+export type RawDocument = Readonly<Record<string, unknown>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The stored value as a raw document; `null` when it is not an object. */
+export function rawDocumentOf(value: unknown): RawDocument | null {
+  return isRecord(value) ? value : null;
+}
+
+/**
+ * Set every key of `patch` on `target`; a key patched to `undefined` is
+ * removed, so a cleared field leaves the document instead of sitting in it
+ * as an empty value the engine would read.
+ */
+function applyPatch(
+  target: Readonly<Record<string, unknown>>,
+  patch: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...target };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
+
+/**
+ * Patch the node with `nodeId` — its first occurrence, the one both
+ * executors run — and leave every other node, and every other key of this
+ * one, exactly as it was. Answers the same document when no node has the id.
+ */
+export function applyNodePatch(
+  raw: RawDocument,
+  nodeId: string,
+  patch: Readonly<Record<string, unknown>>,
+): RawDocument {
+  const nodes = raw.nodes;
+  if (!Array.isArray(nodes)) return raw;
+  const index = nodes.findIndex(
+    (node: unknown) => isRecord(node) && node.id === nodeId,
+  );
+  const node: unknown = nodes[index];
+  if (index === -1 || !isRecord(node)) return raw;
+  const nextNodes = [...nodes];
+  nextNodes[index] = applyPatch(node, patch);
+  return { ...raw, nodes: nextNodes };
+}
+
+/** The document's own fields Start and End edit: the run input's schema and
+ *  what a successful run returns. */
+export interface DocumentPatch {
+  inputs?: unknown;
+  output?: unknown;
+}
+
+/**
+ * Patch the document's `inputs` or `output`. A field patched to `undefined`
+ * is removed; a field the patch does not name is left alone.
+ */
+export function applyDocumentPatch(
+  raw: RawDocument,
+  patch: DocumentPatch,
+): RawDocument {
+  const named: Record<string, unknown> = {};
+  if ('inputs' in patch) named.inputs = patch.inputs;
+  if ('output' in patch) named.output = patch.output;
+  return applyPatch(raw, named);
+}

From dc0293e6d27eb75f561dbd6fad3f3cd2b70b15d4 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 22:26:40 +0200
Subject: [PATCH 46/78] feat(platform): complete, explain and mark automation
 fields in code

An automation field's code editor gets what it needs from the draft
check: the names the field can read, the nodes that run before it, the
fields of each value with their kinds, and the problems of the field at
the characters they are about, with a one-click fix where the engine
suggested a name. The editor's templates are split by the engine's own
tokenizer, and a parity test holds it to the package's rule on every
shipped template and 10 000 generated ones. The check keeps the
document it answered for, so a range is read in the text it indexes.
---
 .../hooks/use-automation-validation.test.tsx  |   2 +
 .../hooks/use-automation-validation.ts        |  12 +-
 .../automations/lib/code-diagnostics.test.ts  | 185 +++++++++
 .../automations/lib/code-diagnostics.ts       | 184 +++++++++
 .../automations/lib/code-providers.test.ts    | 352 +++++++++++++++++
 .../automations/lib/code-providers.ts         | 362 ++++++++++++++++++
 .../lib/template-scan.parity.test.ts          | 186 +++++++++
 .../automations/lib/template-scanner.ts       |  31 ++
 services/platform/messages/de/automations.yml |   1 +
 services/platform/messages/en/automations.yml |   1 +
 services/platform/messages/fr/automations.yml |   1 +
 11 files changed, 1316 insertions(+), 1 deletion(-)
 create mode 100644 services/platform/app/features/automations/lib/code-diagnostics.test.ts
 create mode 100644 services/platform/app/features/automations/lib/code-diagnostics.ts
 create mode 100644 services/platform/app/features/automations/lib/code-providers.test.ts
 create mode 100644 services/platform/app/features/automations/lib/code-providers.ts
 create mode 100644 services/platform/app/features/automations/lib/template-scan.parity.test.ts
 create mode 100644 services/platform/app/features/automations/lib/template-scanner.ts

diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
index 81872077a9..f52dbf4804 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.test.tsx
@@ -102,6 +102,8 @@ describe('useAutomationValidation', () => {
       expect.objectContaining({ code: 'REF_UNKNOWN_NODE' }),
     ]);
     expect(result.current.settledFor).toBe(documentHash(stored));
+    // The text the issues' ranges index into, kept beside the result.
+    expect(result.current.settledDocument).toBe(stored);
     expect(validate).toHaveBeenCalledWith(
       'org-1',
       'support/triage',
diff --git a/services/platform/app/features/automations/hooks/use-automation-validation.ts b/services/platform/app/features/automations/hooks/use-automation-validation.ts
index 4d680225a3..6c4e2c5207 100644
--- a/services/platform/app/features/automations/hooks/use-automation-validation.ts
+++ b/services/platform/app/features/automations/hooks/use-automation-validation.ts
@@ -140,6 +140,9 @@ export interface AutomationValidation {
   warnings: AutomationIssue[];
   /** Hash of the document the shown result belongs to. */
   settledFor: string | null;
+  /** The document the shown result belongs to: the text an issue's range
+   * indexes into, while the one on screen may have moved on. */
+  settledDocument: RawDocument | null;
   /** Hash of the document on screen. */
   currentHash: string | null;
   /** Why the last check failed, when it did. */
@@ -155,6 +158,7 @@ export interface AutomationValidation {
 interface Settled {
   hash: string;
   answer: DraftCheck;
+  document: RawDocument;
 }
 
 /** What every check asks for beside the issues: the canvas words why a
@@ -231,11 +235,16 @@ export function useAutomationValidation({
   if (
     query.data !== undefined &&
     !query.isPlaceholderData &&
+    target !== null &&
     targetHash !== null &&
     (settledRef.current?.hash !== targetHash ||
       settledRef.current.answer !== query.data)
   ) {
-    settledRef.current = { hash: targetHash, answer: query.data };
+    settledRef.current = {
+      hash: targetHash,
+      answer: query.data,
+      document: target,
+    };
   }
   const settled = enabled ? settledRef.current : null;
 
@@ -261,6 +270,7 @@ export function useAutomationValidation({
     errors,
     warnings,
     settledFor: settled?.hash ?? null,
+    settledDocument: settled?.document ?? null,
     currentHash,
     ...(status === 'failed' && { failure: query.error }),
     analysis: settled?.answer.analysis ?? null,
diff --git a/services/platform/app/features/automations/lib/code-diagnostics.test.ts b/services/platform/app/features/automations/lib/code-diagnostics.test.ts
new file mode 100644
index 0000000000..5f3a5a3607
--- /dev/null
+++ b/services/platform/app/features/automations/lib/code-diagnostics.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import type { WireAutomationIssue } from '@/lib/shared/schemas/automation-issues';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+
+import { fieldDiagnostics } from './code-diagnostics';
+import { toIssueView, withIssueIds, type AutomationIssueView } from './issues';
+
+/**
+ * A field's problems on the characters they are about: the engine's range
+ * inside a string as is, a pointer deeper inside a JSON value found in the
+ * text the reader edits (escapes included), and the engine's did-you-mean
+ * as a fix that rewrites exactly the misspelled name.
+ */
+
+const prompt =
+  'Summarize {{ nodes.fetch_isues.output.items }} for {{ input.emial }}';
+const input = {
+  to: '{{ input.email }}',
+  note: 'say "hi"\n{{ nodes.fetch.output.ttle }}',
+};
+
+const DOC: Automation = {
+  name: 'support/triage',
+  nodes: [
+    { id: 'fetch', type: 'transform', code: 'return { title: 1 };' },
+    { id: 'reply', type: 'llm', prompt, input },
+  ],
+};
+
+const controlsOf = (_node: NodeDef): ReadonlySet<string> =>
+  new Set(['prompt', 'input', 'code']);
+
+const t = i18n.getFixedT('en', 'automations');
+
+function views(issues: WireAutomationIssue[]): AutomationIssueView[] {
+  return withIssueIds(issues).map((issue) =>
+    toIssueView(issue, DOC, { locale: 'en', t, controlsOf }),
+  );
+}
+
+describe('a string field', () => {
+  const [unknownNode, unknownKey, whole] = views([
+    {
+      level: 'error',
+      code: 'REF_UNKNOWN_NODE',
+      message: 'node "reply" references nodes.fetch_isues …',
+      at: { pointer: '/nodes/1/prompt', range: [13, 43] },
+      params: {
+        node: 'reply',
+        field: 'prompt',
+        ref: 'fetch_isues',
+        suggestion: 'fetch',
+        known: ['fetch', 'reply'],
+      },
+    },
+    {
+      level: 'warning',
+      code: 'INPUT_KEY_UNKNOWN',
+      message: 'node "reply" uses input.emial …',
+      at: { pointer: '/nodes/1/prompt', range: [54, 65] },
+      params: {
+        node: 'reply',
+        field: 'prompt',
+        key: 'emial',
+        suggestion: 'email',
+        declared: ['email'],
+      },
+    },
+    {
+      level: 'warning',
+      code: 'TEMPLATE_UNTERMINATED',
+      message: 'whole field',
+      at: { pointer: '/nodes/1/prompt' },
+      params: { node: 'reply', field: 'prompt' },
+    },
+  ]);
+
+  const marks = fieldDiagnostics({
+    views: [unknownNode, unknownKey, whole].flatMap((view) =>
+      view === undefined ? [] : [view],
+    ),
+    fieldPointer: '/nodes/1/prompt',
+    text: prompt,
+    kind: 'string',
+    t,
+  });
+
+  it("marks the engine's range as is, with the field's words and code", () => {
+    expect(marks[0]).toMatchObject({
+      id: unknownNode?.issue.id,
+      severity: 'error',
+      range: [13, 43],
+      code: 'REF_UNKNOWN_NODE',
+      message: unknownNode === undefined ? '' : unknownNode.item.cause,
+    });
+    expect(prompt.slice(13, 43)).toBe('nodes.fetch_isues.output.items');
+  });
+
+  it('rewrites exactly the misspelled name to the one the engine suggests', () => {
+    expect(marks[0]?.fixes).toEqual([
+      {
+        label: 'Replace with fetch',
+        changes: [{ range: [19, 30], insert: 'fetch' }],
+      },
+    ]);
+    expect(marks[1]?.fixes?.[0]?.changes).toEqual([
+      { range: [60, 65], insert: 'email' },
+    ]);
+    expect(prompt.slice(60, 65)).toBe('emial');
+  });
+
+  it('marks a problem with the field as a whole without a range', () => {
+    expect(marks[2]).toMatchObject({ severity: 'warning' });
+    expect(marks[2]?.range).toBeUndefined();
+    expect(marks[2]?.fixes).toBeUndefined();
+  });
+
+  it('marks the whole field when the range no longer fits its text', () => {
+    const [late] = fieldDiagnostics({
+      views: unknownNode === undefined ? [] : [unknownNode],
+      fieldPointer: '/nodes/1/prompt',
+      text: 'short',
+      kind: 'string',
+      t,
+    });
+    expect(late?.range).toBeUndefined();
+    expect(late?.fixes).toBeUndefined();
+  });
+});
+
+describe('a JSON field', () => {
+  const text = JSON.stringify(input, null, 2);
+  const [deep] = views([
+    {
+      level: 'warning',
+      code: 'REF_UNKNOWN_FIELD',
+      message: 'nodes.fetch.output.ttle …',
+      at: { pointer: '/nodes/1/input/note', range: [12, 35] },
+      params: {
+        node: 'reply',
+        field: 'input',
+        ref: 'nodes.fetch.output.ttle',
+        root: 'nodes',
+        source: 'fetch',
+        key: 'ttle',
+        suggestion: 'title',
+        known: ['title'],
+        closed: true,
+        listWrapped: false,
+      },
+    },
+  ]);
+
+  it('finds a pointer inside the value in the text, past escapes', () => {
+    expect(input.note.slice(12, 35)).toBe('nodes.fetch.output.ttle');
+    const [mark] = fieldDiagnostics({
+      views: deep === undefined ? [] : [deep],
+      fieldPointer: '/nodes/1/input',
+      text,
+      kind: 'json',
+      t,
+    });
+    const range = mark?.range;
+    expect(range).toBeDefined();
+    if (range === undefined) return;
+    expect(text.slice(range[0], range[1])).toBe('nodes.fetch.output.ttle');
+    const change = mark?.fixes?.[0]?.changes[0];
+    expect(change?.insert).toBe('title');
+    if (change === undefined) return;
+    expect(text.slice(change.range[0], change.range[1])).toBe('ttle');
+  });
+
+  it('marks the whole field when the pointer names nothing in the text', () => {
+    const [mark] = fieldDiagnostics({
+      views: deep === undefined ? [] : [deep],
+      fieldPointer: '/nodes/1/input',
+      text: '{ "to": 1 }',
+      kind: 'json',
+      t,
+    });
+    expect(mark?.range).toBeUndefined();
+  });
+});
diff --git a/services/platform/app/features/automations/lib/code-diagnostics.ts b/services/platform/app/features/automations/lib/code-diagnostics.ts
new file mode 100644
index 0000000000..2a529af62f
--- /dev/null
+++ b/services/platform/app/features/automations/lib/code-diagnostics.ts
@@ -0,0 +1,184 @@
+/**
+ * A field's problems as the code editor marks them: the check's issues for
+ * one field, each at the characters it is about — the exact range the
+ * engine reported inside a string, or, for a problem deeper inside a JSON
+ * value (`/nodes/2/input/to`), the place that pointer names in the text the
+ * reader edits — with the words the Problems list uses and, where the
+ * engine suggested the name the author probably meant, a one-click fix.
+ *
+ * The ranges index into the text the check saw (`diagnosticsFor`); the
+ * editor maps them through every edit made since.
+ */
+
+import type { CodeEditorDiagnostic } from '@tale/ui/code-editor';
+import {
+  locateJsonPointer,
+  locateYamlPointer,
+  type LocatedRange,
+} from '@tale/ui/code-editor/locate';
+import { IssueDetail } from '@tale/ui/issue-list';
+import { createElement } from 'react';
+
+import type { IssueTranslate } from './issue-text';
+import { fieldIssueMessage, type AutomationIssueView } from './issues';
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** How a pointer below the field is found in its text. */
+export type FieldTextKind = 'string' | 'json' | 'yaml';
+
+export interface FieldDiagnosticsOptions {
+  /** This field's problems. */
+  views: readonly AutomationIssueView[];
+  /** The field's own pointer (`/nodes/2/input`, `/output`). */
+  fieldPointer: string;
+  /** The field's text as the check saw it. */
+  text: string;
+  kind: FieldTextKind;
+  t: IssueTranslate;
+}
+
+/** The did-you-mean of an issue, when the engine made one and it can be
+ *  written where the misspelled name stands. */
+interface Suggestion {
+  /** The name as written, to find inside the issue's span. */
+  wrong: string;
+  /** The name to write instead. */
+  right: string;
+  /** Where in the span the name sits: after a scope name, or at its end. */
+  after?: string;
+  last: boolean;
+}
+
+function suggestionOf(view: AutomationIssueView): Suggestion | null {
+  const params = view.issue.params ?? {};
+  const right = params.suggestion;
+  if (typeof right !== 'string' || right === '') return null;
+  switch (view.issue.code) {
+    case 'REF_UNKNOWN_NODE':
+      return typeof params.ref === 'string'
+        ? { wrong: params.ref, right, after: 'nodes', last: false }
+        : null;
+    case 'INPUT_KEY_UNKNOWN':
+      return typeof params.key === 'string'
+        ? { wrong: params.key, right, after: 'input', last: false }
+        : null;
+    case 'REF_UNKNOWN_FIELD':
+      return typeof params.key === 'string'
+        ? { wrong: params.key, right, last: true }
+        : null;
+    default:
+      return null;
+  }
+}
+
+/** The fix that writes the suggested name over the wrong one, inside the
+ *  marked span; none when the name cannot be found there or written as is. */
+function fixFor(
+  view: AutomationIssueView,
+  text: string,
+  span: readonly [number, number],
+  t: IssueTranslate,
+): CodeEditorDiagnostic['fixes'] {
+  const suggestion = suggestionOf(view);
+  if (suggestion === null) return undefined;
+  const slice = text.slice(span[0], span[1]);
+  let at: number;
+  if (suggestion.last) {
+    at = slice.lastIndexOf(suggestion.wrong);
+  } else {
+    const scope =
+      suggestion.after === undefined ? -1 : slice.indexOf(suggestion.after);
+    at =
+      scope === -1
+        ? -1
+        : slice.indexOf(
+            suggestion.wrong,
+            scope + (suggestion.after?.length ?? 0),
+          );
+  }
+  if (at === -1) return undefined;
+  // A name that is not an identifier needs brackets in a dotted path; one
+  // already in quotes can take any name.
+  const quoted = /["']/.test(slice[at - 1] ?? '');
+  if (!quoted && !IDENTIFIER.test(suggestion.right)) return undefined;
+  const from = span[0] + at;
+  return [
+    {
+      label: t('editor.fixSuggestion', {
+        ns: 'automations',
+        name: suggestion.right,
+      }),
+      changes: [
+        {
+          range: [from, from + suggestion.wrong.length],
+          insert: suggestion.right,
+        },
+      ],
+    },
+  ];
+}
+
+function locate(
+  kind: FieldTextKind,
+  text: string,
+  pointer: string,
+  options: Parameters<typeof locateJsonPointer>[2],
+): LocatedRange | null {
+  if (kind === 'json') return locateJsonPointer(text, pointer, options);
+  if (kind === 'yaml') return locateYamlPointer(text, pointer, options);
+  return null;
+}
+
+/** Where in the field's text one issue is; undefined for the whole field. */
+function rangeOf(
+  view: AutomationIssueView,
+  options: FieldDiagnosticsOptions,
+): readonly [number, number] | undefined {
+  const at = view.issue.at;
+  const pointer = at?.pointer ?? '';
+  const { fieldPointer, text, kind } = options;
+  if (pointer === fieldPointer) {
+    // A JSON or YAML value as a whole is marked as the whole field.
+    const range = at?.range;
+    if (kind !== 'string' || range === undefined || at?.subject === 'key') {
+      return undefined;
+    }
+    // A range past the text (it changed since) marks the whole field.
+    return range[1] <= text.length ? range : undefined;
+  }
+  if (!pointer.startsWith(`${fieldPointer}/`) || kind === 'string') {
+    return undefined;
+  }
+  const located = locate(kind, text, pointer.slice(fieldPointer.length), {
+    ...(at?.range !== undefined && { range: at.range }),
+    ...(at?.subject !== undefined && { subject: at.subject }),
+  });
+  return located === null ? undefined : [located.from, located.to];
+}
+
+/** One field's problems as editor marks. */
+export function fieldDiagnostics(
+  options: FieldDiagnosticsOptions,
+): CodeEditorDiagnostic[] {
+  return options.views.map((view) => {
+    const range = rangeOf(view, options);
+    const fixes =
+      range === undefined
+        ? undefined
+        : fixFor(view, options.text, range, options.t);
+    return {
+      id: view.issue.id,
+      severity: view.issue.level,
+      message: fieldIssueMessage(view, options.t),
+      code: view.issue.code,
+      detail: createElement(IssueDetail, {
+        issue: view.item,
+        density: 'compact',
+        className: 'pl-0',
+      }),
+      ...(range !== undefined && { range }),
+      ...(fixes !== undefined && { fixes }),
+    };
+  });
+}
diff --git a/services/platform/app/features/automations/lib/code-providers.test.ts b/services/platform/app/features/automations/lib/code-providers.test.ts
new file mode 100644
index 0000000000..8c9ac5b106
--- /dev/null
+++ b/services/platform/app/features/automations/lib/code-providers.test.ts
@@ -0,0 +1,352 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import type { TypesView } from '@/lib/shared/schemas/automation-issues';
+
+import {
+  automationCompletion,
+  automationHover,
+  referableNodes,
+  type CodeAssistScope,
+} from './code-providers';
+
+/**
+ * Completion and hover read the document and the check's shapes the way
+ * the engine scopes a field: these tests pin which names each field sees,
+ * which nodes it may reference, and the members and kinds it offers.
+ */
+
+const fetch: NodeDef = {
+  id: 'fetch',
+  type: 'github.list_issues',
+  input: { repo: '{{ input.repo }}' },
+};
+const score: NodeDef = {
+  id: 'score',
+  type: 'llm',
+  forEach: '{{ nodes.fetch.output.issues }}',
+  prompt: 'Score {{ item.title }}',
+};
+const report: NodeDef = {
+  id: 'report',
+  type: 'transform',
+  input: { scores: '{{ nodes.score.output }}' },
+  code: 'return { count: input.scores.length };',
+};
+const unrelated: NodeDef = {
+  id: 'audit',
+  type: 'transform',
+  code: 'return 1;',
+};
+const poll: NodeDef = {
+  id: 'poll',
+  type: 'transform',
+  code: 'return { done: true };',
+  repeatUntil: '{{ output.done }}',
+};
+
+const doc: Automation = {
+  name: 'github/triage',
+  nodes: [report, score, fetch, unrelated, poll],
+};
+
+const issue = {
+  type: 'object' as const,
+  properties: {
+    title: { type: 'string' as const, description: 'The issue title.' },
+    labels: { type: 'array' as const, items: { type: 'string' as const } },
+    assignee: { type: 'string' as const },
+  },
+  required: ['title', 'labels'],
+};
+
+const types: TypesView = {
+  inputs: {
+    type: 'object',
+    properties: { repo: { type: 'string' }, limit: { type: 'number' } },
+    required: ['repo'],
+  },
+  nodes: {
+    fetch: {
+      output: {
+        type: 'object',
+        properties: { issues: { type: 'array', items: issue } },
+        required: ['issues'],
+      },
+    },
+    score: {
+      output: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { text: { type: 'string' } },
+          required: ['text'],
+        },
+      },
+      item: issue,
+    },
+    report: {
+      output: {
+        type: 'object',
+        properties: { count: { type: 'number' } },
+        required: ['count'],
+      },
+      input: {
+        type: 'object',
+        properties: { scores: { type: 'array', items: {} } },
+        required: ['scores'],
+      },
+    },
+    poll: {
+      output: {
+        type: 'object',
+        properties: { done: { type: 'boolean' } },
+        required: ['done'],
+      },
+    },
+  },
+  output: {},
+};
+
+function scope(
+  node: NodeDef | undefined,
+  field: CodeAssistScope['field'],
+  extra: Partial<CodeAssistScope> = {},
+): CodeAssistScope {
+  return { doc, ...(node !== undefined && { node }), field, types, ...extra };
+}
+
+function labels(
+  s: CodeAssistScope,
+  path: readonly (string | number)[] | null,
+  region: 'code' | 'template' | 'string' | 'key' = 'template',
+): string[] | null {
+  const result = automationCompletion(s, { region, path });
+  return result === null ? null : result.items.map((item) => item.label);
+}
+
+describe('the names a field sees', () => {
+  it('offers input and nodes in a template, and item and index under forEach', () => {
+    expect(labels(scope(fetch, 'input'), [])).toEqual(['input', 'nodes']);
+    expect(labels(scope(score, 'prompt'), [])).toEqual([
+      'input',
+      'nodes',
+      'item',
+      'index',
+    ]);
+  });
+
+  it('never offers item in a condition or in forEach itself', () => {
+    const conditional = { ...score, when: '{{ true }}' };
+    expect(labels(scope(conditional, 'when'), [])).toEqual(['input', 'nodes']);
+    expect(labels(scope(score, 'forEach'), [])).toEqual(['input', 'nodes']);
+  });
+
+  it('offers the pass result in repeatUntil', () => {
+    expect(labels(scope(poll, 'repeatUntil'), [])).toContain('output');
+    expect(labels(scope(poll, 'repeatUntil'), ['output'])).toEqual(['done']);
+  });
+
+  it('declares input, nodes, item and index in transform code, as the runtime does', () => {
+    expect(labels(scope(report, 'code'), [], 'code')).toEqual([
+      'input',
+      'nodes',
+      'item',
+      'index',
+    ]);
+  });
+
+  it('offers nothing outside an expression', () => {
+    expect(labels(scope(fetch, 'input'), [], 'string')).toBeNull();
+    expect(labels(scope(fetch, 'input'), [], 'key')).toBeNull();
+    expect(labels(scope(fetch, 'input'), null)).toBeNull();
+    expect(labels(scope(fetch, 'input'), ['window'])).toBeNull();
+  });
+});
+
+describe('the nodes a field may reference', () => {
+  it('offers only the nodes that run before it, in run order', () => {
+    expect(labels(scope(report, 'code'), ['nodes'], 'code')).toEqual([
+      'fetch',
+      'score',
+    ]);
+    expect(labels(scope(score, 'prompt'), ['nodes'])).toEqual(['fetch']);
+    expect(labels(scope(fetch, 'input'), ['nodes'])).toEqual([]);
+  });
+
+  it('never offers the node itself or a node that reads it', () => {
+    const offered = labels(scope(score, 'prompt'), ['nodes']) ?? [];
+    expect(offered).not.toContain('score');
+    expect(offered).not.toContain('report');
+  });
+
+  it('lets the document output read every node', () => {
+    expect(referableNodes(doc, undefined).map((node) => node.id)).toEqual(
+      expect.arrayContaining(['fetch', 'score', 'report', 'audit', 'poll']),
+    );
+  });
+
+  it('names each node by its title and its output type', () => {
+    const result = automationCompletion(scope(report, 'code'), {
+      region: 'code',
+      path: ['nodes'],
+    });
+    expect(result?.items[0]).toMatchObject({
+      label: 'fetch',
+      kind: 'node',
+      detail: 'Fetch',
+      info: { type: expect.stringContaining('issues') },
+    });
+  });
+
+  it('reads a node through its output and nothing else', () => {
+    expect(labels(scope(report, 'code'), ['nodes', 'fetch'], 'code')).toEqual([
+      'output',
+    ]);
+    expect(
+      labels(scope(report, 'code'), ['nodes', 'fetch', 'input'], 'code'),
+    ).toBeNull();
+    expect(
+      labels(scope(fetch, 'input'), ['nodes', 'report', 'output']),
+    ).toBeNull();
+  });
+});
+
+describe('members', () => {
+  it('lists the fields of a value with their kinds and whether they may be missing', () => {
+    const result = automationCompletion(scope(score, 'prompt'), {
+      region: 'template',
+      path: ['item'],
+    });
+    expect(result?.items).toEqual([
+      expect.objectContaining({
+        label: 'title',
+        valueType: 'string',
+        optional: false,
+        detail: 'string',
+        info: expect.objectContaining({ description: 'The issue title.' }),
+      }),
+      expect.objectContaining({
+        label: 'labels',
+        valueType: 'array',
+        optional: false,
+        detail: 'Array<string>',
+      }),
+      expect.objectContaining({
+        label: 'assignee',
+        valueType: 'string',
+        optional: true,
+      }),
+    ]);
+  });
+
+  it('walks a node output path, through a list', () => {
+    expect(
+      labels(scope(report, 'code'), ['nodes', 'fetch', 'output'], 'code'),
+    ).toEqual(['issues']);
+    expect(
+      labels(
+        scope(report, 'code'),
+        ['nodes', 'fetch', 'output', 'issues'],
+        'code',
+      ),
+    ).toEqual(['length']);
+    expect(
+      labels(
+        scope(report, 'code'),
+        ['nodes', 'fetch', 'output', 'issues', 0],
+        'code',
+      ),
+    ).toEqual(['title', 'labels', 'assignee']);
+  });
+
+  it("reads transform code's input as its own input mapping", () => {
+    expect(labels(scope(report, 'code'), ['input'], 'code')).toEqual([
+      'scores',
+    ]);
+    expect(labels(scope(fetch, 'input'), ['input'])).toEqual(['repo', 'limit']);
+  });
+
+  it('adds what the last run recorded, shortened', () => {
+    const result = automationCompletion(
+      scope(report, 'code', {
+        sampleOf: (id) =>
+          id === 'fetch'
+            ? { issues: [{ title: 'x'.repeat(200), labels: [] }] }
+            : undefined,
+      }),
+      { region: 'code', path: ['nodes', 'fetch', 'output', 'issues', 0] },
+    );
+    const sample = result?.items[0]?.info?.sample ?? '';
+    expect(sample.startsWith('"xxx')).toBe(true);
+    expect(sample.length).toBe(80);
+    expect(sample.endsWith('…')).toBe(true);
+  });
+
+  it('offers nothing until the check worked out the shapes', () => {
+    expect(
+      labels(
+        scope(report, 'code', { types: null }),
+        ['nodes', 'fetch', 'output'],
+        'code',
+      ),
+    ).toEqual([]);
+    expect(
+      labels(scope(score, 'prompt', { types: null }), ['item']),
+    ).toBeNull();
+  });
+});
+
+describe('hover', () => {
+  it('says what a path holds, as a type, with its description', () => {
+    expect(
+      automationHover(scope(score, 'prompt'), {
+        region: 'template',
+        path: ['item', 'title'],
+      }),
+    ).toEqual({
+      title: 'item.title',
+      type: 'string',
+      description: 'The issue title.',
+    });
+    expect(
+      automationHover(scope(report, 'code'), {
+        region: 'code',
+        path: ['nodes', 'fetch', 'output', 'issues'],
+      }),
+    ).toMatchObject({
+      title: 'nodes.fetch.output.issues',
+      type: expect.stringMatching(/^Array<\{ title: string/),
+    });
+  });
+
+  it('names a node by its title', () => {
+    expect(
+      automationHover(scope(report, 'code'), {
+        region: 'code',
+        path: ['nodes', 'fetch'],
+      }),
+    ).toMatchObject({
+      title: 'Fetch',
+      type: expect.stringContaining('output'),
+    });
+  });
+
+  it('says nothing about a name the field cannot read or a missing member', () => {
+    expect(
+      automationHover(scope(score, 'forEach'), {
+        region: 'template',
+        path: ['item'],
+      }),
+    ).toBeNull();
+    expect(
+      automationHover(scope(score, 'prompt'), {
+        region: 'template',
+        path: ['item', 'nope'],
+      }),
+    ).toBeNull();
+    expect(
+      automationHover(scope(score, 'prompt'), { region: 'text', path: null }),
+    ).toBeNull();
+  });
+});
diff --git a/services/platform/app/features/automations/lib/code-providers.ts b/services/platform/app/features/automations/lib/code-providers.ts
new file mode 100644
index 0000000000..3431b63859
--- /dev/null
+++ b/services/platform/app/features/automations/lib/code-providers.ts
@@ -0,0 +1,362 @@
+/**
+ * What the code editor offers inside an automation's fields: the names a
+ * field can read (`input`, `nodes`, `item`, …), the nodes it may reference,
+ * and the fields of each value as the draft check worked them out, with
+ * their kinds — while typing (completion) and on hover.
+ *
+ * Pure over the document, the check's inferred shapes and the engine's own
+ * scope rules (`scopeNamesFor`), so it answers the same in a test as in the
+ * editor, and a field never offers a name its runtime would not have.
+ *
+ * `nodes.` offers only the nodes that run before this one: a reference to
+ * itself or to a node that reads it would close a circle the engine refuses.
+ */
+
+import type {
+  CodeCompletionContext,
+  CodeCompletionItem,
+  CodeCompletionKind,
+  CodeCompletionResult,
+  CodeEditorProviders,
+  CodeHoverContext,
+  CodeHoverInfo,
+  CodePathSegment,
+  CodeValueType,
+} from '@tale/ui/code-editor/providers';
+
+import {
+  scopeNamesFor,
+  type SourceField,
+} from '@/lib/engine/core/syntax/globals';
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
+import {
+  elementOf,
+  isUnknown,
+  kindsOf,
+  lookup,
+  NUMBER_SHAPE,
+  toTs,
+  UNKNOWN,
+  type Shape,
+} from '@/lib/engine/core/typing/shape';
+import type { TypesView } from '@/lib/shared/schemas/automation-issues';
+
+import { orderedNodes } from './graph';
+import { nodeTitle } from './node-face';
+
+/** Where the editor is: one field of one node, or the document's output. */
+export interface CodeAssistScope {
+  /** The document on screen (its reading view). */
+  doc: Automation;
+  /** The node whose field this is; absent for the document's `output`. */
+  node?: NodeDef;
+  field: SourceField;
+  /** The draft check's inferred shapes; null until it answered. */
+  types: TypesView | null;
+  /** What a node returned in the run laid over the canvas. */
+  sampleOf?: (nodeId: string) => unknown;
+}
+
+/** The longest sample a tooltip shows. */
+const SAMPLE_LENGTH = 80;
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** The kind a value of this shape has, for the icon beside its name. */
+function valueTypeOf(shape: Shape): CodeValueType {
+  if (shape.type === 'integer') return 'integer';
+  const kinds = kindsOf(shape);
+  if (kinds === null || kinds.size !== 1) return 'unknown';
+  const [kind] = kinds;
+  return kind ?? 'unknown';
+}
+
+/**
+ * The nodes a field of `node` may reference: those that run before it, in
+ * the order they run (document order when the references form a circle).
+ * The document's output may read every node.
+ */
+export function referableNodes(
+  doc: Automation,
+  node: NodeDef | undefined,
+): NodeDef[] {
+  const drawn = doc.nodes.filter((candidate) => candidate.type !== '');
+  const { nodes: order } = orderedNodes(drawn);
+  if (node === undefined) return order;
+  const at = order.findIndex((candidate) => candidate.id === node.id);
+  return at === -1 ? [] : order.slice(0, at);
+}
+
+function nodeOutput(scope: CodeAssistScope, id: string): Shape | undefined {
+  const types = scope.types;
+  if (types === null || !Object.hasOwn(types.nodes, id)) return undefined;
+  return types.nodes[id]?.output;
+}
+
+/** The names this field can read, in the engine's own words. */
+function rootsOf(scope: CodeAssistScope): ReadonlySet<string> {
+  return scopeNamesFor(scope.field, scope.node);
+}
+
+/** The shape of a scope name other than `nodes`; undefined when unknown. */
+function rootShape(scope: CodeAssistScope, root: string): Shape | undefined {
+  const { types, node, field } = scope;
+  if (root === 'index') return NUMBER_SHAPE;
+  if (types === null) return undefined;
+  const info =
+    node !== undefined && Object.hasOwn(types.nodes, node.id)
+      ? types.nodes[node.id]
+      : undefined;
+  switch (root) {
+    case 'input':
+      // Transform code reads its own input mapping as `input`.
+      return field === 'code' ? (info?.input ?? UNKNOWN) : types.inputs;
+    case 'item':
+      return info?.item ?? UNKNOWN;
+    case 'output': {
+      const out = info?.output ?? UNKNOWN;
+      return typeof node?.forEach === 'string' ? elementOf(out) : out;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Follow member steps from `shape`; undefined where a step is unknown. */
+function walk(
+  shape: Shape,
+  steps: readonly CodePathSegment[],
+): { shape: Shape; optional: boolean } | undefined {
+  let current = shape;
+  let optional = false;
+  for (const step of steps) {
+    const found = lookup(current, step);
+    if (found.kind !== 'found') return undefined;
+    current = found.shape;
+    optional ||= found.optional;
+  }
+  return { shape: current, optional };
+}
+
+/** The value a path names in a node's recorded output, shortened. */
+function sampleAt(
+  scope: CodeAssistScope,
+  nodeId: string,
+  steps: readonly CodePathSegment[],
+): string | undefined {
+  if (scope.sampleOf === undefined) return undefined;
+  let value: unknown = scope.sampleOf(nodeId);
+  for (const step of steps) {
+    if (value === null || typeof value !== 'object') return undefined;
+    value = Reflect.get(value, step);
+  }
+  if (value === undefined) return undefined;
+  let text: string;
+  try {
+    text = JSON.stringify(value);
+  } catch (error) {
+    console.warn('[automations] a recorded value is not serialisable', error);
+    return undefined;
+  }
+  return text.length <= SAMPLE_LENGTH
+    ? text
+    : `${text.slice(0, SAMPLE_LENGTH - 1)}…`;
+}
+
+/** The members a value of this shape has, each with its kind. */
+function membersOf(
+  shape: Shape,
+  sample?: (key: string) => string | undefined,
+): CodeCompletionItem[] {
+  if (isUnknown(shape)) return [];
+  const keys = new Set<string>();
+  for (const member of shape.anyOf ?? [shape]) {
+    for (const key of Object.keys(member.properties ?? {})) keys.add(key);
+  }
+  const kinds = kindsOf(shape);
+  if (
+    kinds !== null &&
+    (kinds.has('array') || kinds.has('string')) &&
+    !kinds.has('object')
+  ) {
+    keys.add('length');
+  }
+  const items: CodeCompletionItem[] = [];
+  for (const key of keys) {
+    const found = lookup(shape, key);
+    if (found.kind !== 'found') continue;
+    const example = sample?.(key);
+    items.push({
+      label: key,
+      kind: 'property',
+      valueType: valueTypeOf(found.shape),
+      detail: toTs(found.shape, 1),
+      optional: found.optional,
+      info: {
+        type: toTs(found.shape),
+        ...(found.shape.description !== undefined && {
+          description: found.shape.description,
+        }),
+        ...(example !== undefined && { sample: example }),
+      },
+    });
+  }
+  return items;
+}
+
+const ROOT_KIND: Readonly<Record<string, CodeCompletionKind>> = {
+  input: 'input',
+  nodes: 'variable',
+  item: 'variable',
+  index: 'variable',
+  output: 'variable',
+};
+
+function rootItems(scope: CodeAssistScope): CodeCompletionItem[] {
+  return [...rootsOf(scope)].map((root) => {
+    const shape = rootShape(scope, root);
+    const item: CodeCompletionItem = {
+      label: root,
+      kind: ROOT_KIND[root] ?? 'variable',
+    };
+    if (shape !== undefined) {
+      item.valueType = valueTypeOf(shape);
+      item.detail = toTs(shape, 1);
+      item.info = { type: toTs(shape) };
+    }
+    return item;
+  });
+}
+
+function nodeItems(scope: CodeAssistScope): CodeCompletionItem[] {
+  return referableNodes(scope.doc, scope.node).map((candidate) => {
+    const output = nodeOutput(scope, candidate.id);
+    const item: CodeCompletionItem = {
+      label: candidate.id,
+      kind: 'node',
+      detail: nodeTitle(candidate.id),
+    };
+    if (output !== undefined) item.info = { type: toTs(output) };
+    return item;
+  });
+}
+
+function referable(scope: CodeAssistScope, id: string): boolean {
+  return referableNodes(scope.doc, scope.node).some(
+    (candidate) => candidate.id === id,
+  );
+}
+
+/** What can come next at the cursor in one field. */
+export function automationCompletion(
+  scope: CodeAssistScope,
+  context: Pick<CodeCompletionContext, 'region' | 'path'>,
+): CodeCompletionResult {
+  if (context.region !== 'code' && context.region !== 'template') return null;
+  const path = context.path;
+  if (path === null) return null;
+  if (path.length === 0) return { items: rootItems(scope) };
+  const [root, ...rest] = path;
+  if (typeof root !== 'string' || !rootsOf(scope).has(root)) return null;
+  if (root === 'nodes') {
+    if (rest.length === 0) return { items: nodeItems(scope) };
+    const [id, member, ...steps] = rest;
+    if (typeof id !== 'string' || !referable(scope, id)) return null;
+    const output = nodeOutput(scope, id) ?? UNKNOWN;
+    // A node is read through its `output` and nothing else.
+    if (member === undefined) {
+      return {
+        items: [
+          {
+            label: 'output',
+            kind: 'property',
+            valueType: valueTypeOf(output),
+            detail: toTs(output, 1),
+            info: { type: toTs(output) },
+          },
+        ],
+      };
+    }
+    if (member !== 'output') return null;
+    const walked = walk(output, steps);
+    if (walked === undefined) return null;
+    return {
+      items: membersOf(walked.shape, (key) =>
+        sampleAt(scope, id, [...steps, key]),
+      ),
+    };
+  }
+  const base = rootShape(scope, root);
+  if (base === undefined) return null;
+  const walked = walk(base, rest);
+  if (walked === undefined) return null;
+  return { items: membersOf(walked.shape) };
+}
+
+/** `nodes.score.output.items[0]["a b"]` */
+function pathText(path: readonly CodePathSegment[]): string {
+  return path
+    .map((segment, index) => {
+      if (typeof segment === 'number') return `[${segment}]`;
+      if (IDENTIFIER.test(segment)) {
+        return index === 0 ? segment : `.${segment}`;
+      }
+      return `[${JSON.stringify(segment)}]`;
+    })
+    .join('');
+}
+
+/** What the name under the pointer holds, as a type. */
+export function automationHover(
+  scope: CodeAssistScope,
+  context: Pick<CodeHoverContext, 'region' | 'path'>,
+): CodeHoverInfo | null {
+  if (context.region !== 'code' && context.region !== 'template') return null;
+  const path = context.path;
+  if (path === null || path.length === 0) return null;
+  const [root, ...rest] = path;
+  if (typeof root !== 'string' || !rootsOf(scope).has(root)) return null;
+  const title = pathText(path);
+  if (root === 'nodes') {
+    const [id, member, ...steps] = rest;
+    if (typeof id !== 'string') return null;
+    const output = nodeOutput(scope, id);
+    if (output === undefined) return null;
+    if (member === undefined) {
+      return { title: nodeTitle(id), type: `{ output: ${toTs(output, 2)} }` };
+    }
+    if (member !== 'output') return null;
+    const walked = walk(output, steps);
+    if (walked === undefined) return null;
+    const sample = sampleAt(scope, id, steps);
+    return {
+      title,
+      type: toTs(walked.shape),
+      ...(walked.shape.description !== undefined && {
+        description: walked.shape.description,
+      }),
+      ...(sample !== undefined && { sample }),
+    };
+  }
+  const base = rootShape(scope, root);
+  if (base === undefined) return null;
+  const walked = walk(base, rest);
+  if (walked === undefined) return null;
+  return {
+    title,
+    type: toTs(walked.shape),
+    ...(walked.shape.description !== undefined && {
+      description: walked.shape.description,
+    }),
+  };
+}
+
+/** The completion and hover providers for one field. */
+export function automationProviders(
+  scope: CodeAssistScope,
+): CodeEditorProviders {
+  return {
+    completion: (context) => automationCompletion(scope, context),
+    hover: (context) => automationHover(scope, context),
+  };
+}
diff --git a/services/platform/app/features/automations/lib/template-scan.parity.test.ts b/services/platform/app/features/automations/lib/template-scan.parity.test.ts
new file mode 100644
index 0000000000..5aa8d1ea23
--- /dev/null
+++ b/services/platform/app/features/automations/lib/template-scan.parity.test.ts
@@ -0,0 +1,186 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { scanTemplates } from '@tale/ui/code-editor/template-scan';
+import { describe, expect, it } from 'vitest';
+import { parse } from 'yaml';
+
+import { engineTemplateScan } from './template-scanner';
+
+/**
+ * `@tale/ui`'s template scanner decides where a `{{ … }}` ends without a
+ * JavaScript parser ("balanced" for "parses"); the engine's tokenizer, which
+ * the run evaluates with, uses one. The editor hands the engine's rule to
+ * the code editor, and every other host of the editor relies on the
+ * package's. These tests hold the two to the same spans on every template
+ * the shipped automations hold and on 10 000 generated texts of valid
+ * expressions — strings holding `}}`, object literals, arrow bodies,
+ * template literals — so the package's rule cannot drift from the
+ * runtime's for anything an author writes.
+ *
+ * They differ on purpose only where "balanced" and "parses" part ways: a
+ * comment or a regular expression holding `}}`, and a span that is
+ * balanced but not an expression. The generator writes neither.
+ */
+
+/** The spans as both scanners must agree on them. */
+function shape(scan: ReturnType<typeof scanTemplates>) {
+  return {
+    spans: scan.spans.map((span) => [span.open, span.end]),
+    unterminated: scan.unterminated,
+  };
+}
+
+function expectSame(text: string): void {
+  expect(shape(scanTemplates(text)), JSON.stringify(text)).toEqual(
+    shape(engineTemplateScan(text)),
+  );
+}
+
+const REPO = path.resolve(import.meta.dirname, '../../../../../..');
+const SHIPPED = path.join(REPO, 'configs/platform/custom/automations');
+
+function documentFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const full = path.join(dir, name);
+    if (statSync(full).isDirectory()) return documentFiles(full);
+    return name === 'workflow.yml' ? [full] : [];
+  });
+}
+
+function templatedStrings(value: unknown): string[] {
+  if (typeof value === 'string') return value.includes('{{') ? [value] : [];
+  if (Array.isArray(value)) return value.flatMap(templatedStrings);
+  if (value !== null && typeof value === 'object') {
+    return Object.values(value).flatMap(templatedStrings);
+  }
+  return [];
+}
+
+describe('the package scanner and the engine tokenizer', () => {
+  it('agree on every template the shipped automations hold', () => {
+    const files = documentFiles(SHIPPED);
+    expect(files.length).toBeGreaterThan(0);
+    const strings = files.flatMap((file) =>
+      templatedStrings(parse(readFileSync(file, 'utf8'))),
+    );
+    expect(strings.length).toBeGreaterThan(50);
+    for (const text of strings) expectSame(text);
+  });
+
+  it.each([
+    'plain text',
+    '{{ input.name }}',
+    'Hi {{ input.name }}, {{ nodes.score.output.total > 3 ? "high" : "low" }}.',
+    '{{ xs.map(x => ({ y: x })) }}',
+    '{{ "a }} b" }} tail',
+    "{{ '{{ not a template }}' }}",
+    '{{ `a ${nodes.a.output.x} }} b` }}',
+    '{{ ({ a: { b: 1 } }) }}',
+    '{{ [1, [2, [3]]].flat(2) }}',
+    '{{ a }}}',
+    '{{}} stays text',
+    '{{ unterminated',
+    'before {{ a }} {{ b',
+    '{{ a }}{{ b }}',
+    '{{ nodes.list.output.filter((i) => { return i.ok; }).length }}',
+  ])('agree on %j', (text) => {
+    expectSame(text);
+  });
+});
+
+/** A small seeded generator, so a failure names a reproducible text. */
+function generator(seed: number) {
+  let state = seed >>> 0;
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const pick = <T>(items: readonly T[]): T => {
+    const item = items[Math.floor(next() * items.length)];
+    if (item === undefined) throw new Error('empty choice');
+    return item;
+  };
+  const space = () => pick(['', ' ', '  ', '\n']);
+
+  const expr = (depth: number): string => {
+    if (depth <= 0) {
+      return pick([
+        'input.name',
+        'nodes.a.output.total',
+        'item',
+        'index',
+        '42',
+        '"}}"',
+        "'{{ x }}'",
+        '"a"',
+        'true',
+        'null',
+      ]);
+    }
+    const inner = () => expr(depth - 1);
+    switch (Math.floor(next() * 11)) {
+      case 0:
+        return `{${space()}k:${space()}${inner()}${space()}}`;
+      case 1:
+        return `[${inner()},${space()}${inner()}]`;
+      case 2:
+        return `f(${inner()})`;
+      case 3:
+        return `xs.map((x) => ({ y: ${inner()} }))`;
+      case 4:
+        return `xs.map((x) => { return ${inner()}; })`;
+      case 5:
+        return `\`t\${${inner()}}}\``;
+      case 6:
+        return `${inner()} ? ${inner()} : ${inner()}`;
+      case 7:
+        return `${inner()} + ${inner()}`;
+      case 8:
+        return `(${inner()})`;
+      case 9:
+        return `(${inner()}).length`;
+      default:
+        return `{${space()}${pick(['a', '"b c"'])}:${space()}{ d: ${inner()} }${space()}}`;
+    }
+  };
+
+  const text = (): string => {
+    const parts: string[] = [];
+    const count = 1 + Math.floor(next() * 3);
+    for (let i = 0; i < count; i++) {
+      parts.push(pick(['', 'Hello ', 'a } b ', 'x: ', '\n', '} ', ' { ', ' ']));
+      parts.push(`{{${space()}${expr(Math.floor(next() * 4))}${space()}}}`);
+    }
+    parts.push(pick(['', '.', ' }', ' {{ open', ' tail']));
+    return parts.join('');
+  };
+  return { text };
+}
+
+describe('engineTemplateScan', () => {
+  it('marks a span the engine could not read as an expression, as the run reports it', () => {
+    expect(engineTemplateScan('{{ a b }} and {{ c }}').spans).toEqual([
+      { open: 0, bodyFrom: 2, bodyTo: 7, end: 9, balanced: false },
+      { open: 14, bodyFrom: 16, bodyTo: 19, end: 21, balanced: true },
+    ]);
+  });
+
+  it('follows the run where the package rule cannot: a comment holding the closer', () => {
+    const text = '{{ a /* }} */ }}';
+    expect(engineTemplateScan(text).spans.map((span) => span.end)).toEqual([
+      10,
+    ]);
+    expect(scanTemplates(text).spans.map((span) => span.end)).toEqual([16]);
+  });
+});
+
+describe('generated texts', () => {
+  it('agree on 10 000 texts of valid expressions', () => {
+    const { text } = generator(20261008);
+    for (let i = 0; i < 10_000; i++) expectSame(text());
+  });
+});
diff --git a/services/platform/app/features/automations/lib/template-scanner.ts b/services/platform/app/features/automations/lib/template-scanner.ts
new file mode 100644
index 0000000000..2de9512c5b
--- /dev/null
+++ b/services/platform/app/features/automations/lib/template-scanner.ts
@@ -0,0 +1,31 @@
+/**
+ * The engine's template rule, as the code editor reads it: where each
+ * `{{ <expression> }}` of a field begins and ends, decided by the same
+ * tokenizer the runtime evaluates with (`tokenizeTemplate`), so the editor
+ * colours exactly the span a run evaluates — exotic input included, such
+ * as a regular expression or a comment holding `}}`.
+ */
+
+import type { TemplateScan } from '@tale/ui/code-editor/template-scan';
+
+import { tokenizeTemplate } from '@/lib/engine/core/syntax/tokens';
+
+export function engineTemplateScan(text: string): TemplateScan {
+  const tokens = tokenizeTemplate(text);
+  return {
+    spans: tokens.segments.flatMap((segment) =>
+      segment.kind === 'expr'
+        ? [
+            {
+              open: segment.start,
+              bodyFrom: segment.start + 2,
+              bodyTo: segment.end - 2,
+              end: segment.end,
+              balanced: segment.parsed !== false,
+            },
+          ]
+        : [],
+    ),
+    unterminated: tokens.unterminated,
+  };
+}
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index c4c1daf35c..a3b5b3f9c6 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -289,6 +289,7 @@ editor:
     sind nur die eingebauten Typen beschrieben. Die Felder dieser Node siehst
     du trotzdem.
   invalidJson: Das ist noch kein gültiges JSON, deshalb wurde die Node nicht geändert.
+  fixSuggestion: 'Durch {name} ersetzen'
   versionNotFound:
     title: 'Version {version} gibt es nicht'
     description: Diese Automatisierung hat keine Version mit dieser Nummer — der Link ist vielleicht veraltet oder die Nummer vertippt.
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index 54cf672935..d08b5f8d30 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -282,6 +282,7 @@ editor:
   unknownType: 'Unknown node type: {type}'
   catalogUnavailable: Couldn't load the node-type catalog — only built-in types are described. The node's fields are still shown.
   invalidJson: This is not valid JSON yet, so the node was not changed.
+  fixSuggestion: 'Replace with {name}'
   versionNotFound:
     title: "Version {version} doesn't exist"
     description: This automation has no version with that number — the link may be stale, or the number mistyped.
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index c139f17691..52541e9fc3 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -288,6 +288,7 @@ editor:
     Le catalogue des types de nœuds n’a pas pu être chargé, donc seuls
     les types intégrés sont décrits. Les champs de ce nœud restent affichés.
   invalidJson: Ce n’est pas encore du JSON valide, le nœud n’a donc pas été modifié.
+  fixSuggestion: 'Remplacer par {name}'
   versionNotFound:
     title: 'La version {version} n’existe pas'
     description: Cette automatisation n’a aucune version portant ce numéro — le lien est peut-être périmé, ou le numéro mal saisi.

From f18e5b89039ac6480b1ad2c2f7ab4053d346e175 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:05:44 +0200
Subject: [PATCH 47/78] feat(platform): edit every node field in the code
 editor

The node inspector names the node by its title, says what kind it is
and gives its id to copy. Under it, When it runs says how often the
node runs, each way it can be skipped and what a failure does, worked
out in the browser from the conditions. Three tabs follow.

Fields edits code, prompts, conditions and JSON in the code editor,
in the language the engine reads each one, with completion, types on
hover and the check's problems at their characters. A JSON field
commits only a value of its kind and never rewrites the author's text
with its own echo, so the caret stays put. On error, Maximum repeats
and Else of get controls that offer exactly their values.

Shape shows what the node receives and returns, where that shape
comes from and which nodes read it. Last run shows what the run on
the canvas did here. The jsdom suites edit code fields through a text
box with the editor's contract.
---
 .../automation-editor.browser.test.tsx        |   39 +-
 .../components/automation-editor.test.tsx     |    6 +
 .../components/automation-editor.tsx          |  125 +-
 .../components/json-code-field.test.tsx       |  123 ++
 .../components/json-code-field.tsx            |  171 +++
 .../components/node-flow-summary.tsx          |  115 ++
 .../components/node-inspector.test.tsx        |  373 ++++-
 .../automations/components/node-inspector.tsx | 1305 ++++++++++++-----
 .../components/node-shape-panel.test.tsx      |  155 ++
 .../components/node-shape-panel.tsx           |  209 +++
 .../automations/components/run-detail.tsx     |   28 +-
 .../components/run-step-detail.tsx            |    9 +-
 .../features/automations/lib/flow-graph.ts    |    7 +
 .../automations/lib/inspector-fields.ts       |  152 +-
 .../app/features/automations/lib/node-face.ts |    4 +-
 .../app/features/automations/lib/paths.ts     |    2 +-
 services/platform/messages/de/automations.yml |   51 +-
 services/platform/messages/en/automations.yml |   51 +-
 services/platform/messages/fr/automations.yml |   51 +-
 services/platform/tests/setup-ui.ts           |    5 +
 .../tests/utils/code-editor-stand-in.tsx      |  173 +++
 services/platform/vitest.config.ts            |   15 +
 22 files changed, 2777 insertions(+), 392 deletions(-)
 create mode 100644 services/platform/app/features/automations/components/json-code-field.test.tsx
 create mode 100644 services/platform/app/features/automations/components/json-code-field.tsx
 create mode 100644 services/platform/app/features/automations/components/node-flow-summary.tsx
 create mode 100644 services/platform/app/features/automations/components/node-shape-panel.test.tsx
 create mode 100644 services/platform/app/features/automations/components/node-shape-panel.tsx
 create mode 100644 services/platform/tests/utils/code-editor-stand-in.tsx

diff --git a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
index 64bec4401b..01feab58ed 100644
--- a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
@@ -116,7 +116,10 @@ vi.mock('../hooks/use-automation-validation', async (importOriginal) => ({
       errors: check.errors,
       warnings: check.warnings,
       settledFor: hash,
+      settledDocument: document,
       currentHash: hash,
+      analysis: null,
+      types: null,
     };
   },
   useInvalidateAutomationValidation: () => () => undefined,
@@ -398,9 +401,14 @@ describe('automation editor workbench in Chromium', () => {
       try {
         renderEditorTab();
         await userEvent.click(
-          await screen.findByRole('button', { name: /^pulls/i }),
+          // The first chart of the file waits for the layout worker.
+          await screen.findByRole(
+            'button',
+            { name: /^pulls/i },
+            { timeout: 15_000 },
+          ),
         );
-        const sheet = await screen.findByRole('dialog', { name: 'pulls' });
+        const sheet = await screen.findByRole('dialog', { name: 'Pulls' });
         const closeActions = within(sheet).getAllByRole('button', {
           name: /^(Close|Schließen|Fermer)$/,
         });
@@ -599,7 +607,7 @@ describe('automation editor workbench in Chromium', () => {
     expect(canvasBox.width).toBeCloseTo(canvasBoxBefore.width, 0);
     expect(canvasBox.height).toBeCloseTo(canvasBoxBefore.height, 0);
     expect(pageScroll.scrollHeight).toBe(pageScroll.clientHeight);
-    expect(screen.queryByRole('region', { name: 'pulls' })).toBeNull();
+    expect(screen.queryByRole('region', { name: 'Pulls' })).toBeNull();
 
     // The fields — and the document's Save/Discard — live in a sheet over
     // the canvas instead, not the side panel and not the canvas's own
@@ -653,12 +661,12 @@ describe('automation editor workbench in Chromium', () => {
     expect(canvasBox.left).toBeCloseTo(frame.left, 0);
     expect(canvasBox.top).toBeCloseTo(strip.getBoundingClientRect().bottom, 0);
     expect(canvasBox.right).toBeCloseTo(frame.left + pageScroll.clientWidth, 0);
-    expect(screen.queryByRole('region', { name: 'pulls' })).toBeNull();
+    expect(screen.queryByRole('region', { name: 'Pulls' })).toBeNull();
 
     // A picked node opens the inspector: it ends at the page's right and
     // bottom edges, and meets the canvas at its border with no gutter.
     await selectNode('pulls');
-    const inspector = screen.getByRole('region', { name: 'pulls' });
+    const inspector = screen.getByRole('region', { name: 'Pulls' });
     canvasBox = canvas.getBoundingClientRect();
     const inspectorBox = inspector.getBoundingClientRect();
     expect(inspectorBox.right).toBeCloseTo(
@@ -765,11 +773,12 @@ describe('automation editor workbench in Chromium', () => {
     await vi.waitFor(() => expect(row).toHaveFocus());
     await userEvent.keyboard('{Enter}');
 
-    const code = await screen.findByRole<HTMLTextAreaElement>('textbox', {
-      name: 'Code',
-    });
+    const code = await screen.findByRole('textbox', { name: 'Code' });
+    // The code editor selects exactly the offending characters.
     await vi.waitFor(() => expect(code).toHaveFocus());
-    expect([code.selectionStart, code.selectionEnd]).toEqual([0, 6]);
+    await vi.waitFor(() =>
+      expect(document.getSelection()?.toString()).toBe('return'),
+    );
     // The inspector opened beside the canvas, and the dock stays open.
     expect(screen.getByRole('region', { name: 'Problems' })).toBeVisible();
     const box = screen.getByRole('button', { name: /^diff/i });
@@ -788,12 +797,14 @@ describe('automation editor workbench in Chromium', () => {
     await vi.waitFor(() => expect(row).toHaveFocus());
     await userEvent.keyboard('{Enter}');
 
-    const nodeSheet = await screen.findByRole('dialog', { name: 'diff' });
-    const code = within(nodeSheet).getByRole<HTMLTextAreaElement>('textbox', {
+    const nodeSheet = await screen.findByRole('dialog', { name: 'Diff' });
+    const code = await within(nodeSheet).findByRole('textbox', {
       name: 'Code',
     });
     await vi.waitFor(() => expect(code).toHaveFocus());
-    expect([code.selectionStart, code.selectionEnd]).toEqual([0, 6]);
+    await vi.waitFor(() =>
+      expect(document.getSelection()?.toString()).toBe('return'),
+    );
     expect(screen.queryByRole('dialog', { name: 'Problems' })).toBeNull();
   });
 
@@ -826,7 +837,7 @@ describe('automation editor workbench in Chromium', () => {
       ).toHaveAccessibleName(/\(1 warning\)$/);
       // Let the dock finish fading in: axe reads colours at rest.
       await new Promise((resolve) => setTimeout(resolve, 400));
-      const inspector = screen.getByRole('region', { name: 'summary' });
+      const inspector = screen.getByRole('region', { name: 'Summary' });
       for (const region of [dock, inspector]) {
         const result = await axe.run(region, {
           runOnly: [
@@ -894,7 +905,7 @@ describe('automation editor workbench in Chromium', () => {
     const sheet = await screen.findByRole('dialog', { name: 'Problems' });
     const row = within(sheet).getByRole('button', { name: /Error:/ });
     await vi.waitFor(() => expect(row).toHaveFocus());
-    expect(screen.queryByRole('dialog', { name: 'summary' })).toBeNull();
+    expect(screen.queryByRole('dialog', { name: 'Summary' })).toBeNull();
   });
 
   it('says why Save waits in a visible line on a phone', async () => {
diff --git a/services/platform/app/features/automations/components/automation-editor.test.tsx b/services/platform/app/features/automations/components/automation-editor.test.tsx
index c242e2a3bd..5b4391a354 100644
--- a/services/platform/app/features/automations/components/automation-editor.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.test.tsx
@@ -111,7 +111,10 @@ vi.mock('../hooks/use-automation-validation', () => ({
         errors: [],
         warnings: [],
         settledFor: null,
+        settledDocument: null,
         currentHash,
+        analysis: null,
+        types: null,
       };
     }
     return {
@@ -120,7 +123,10 @@ vi.mock('../hooks/use-automation-validation', () => ({
       warnings: validationMock.warnings,
       settledFor:
         validationMock.status === 'ready' ? currentHash : 'an older draft',
+      settledDocument: validationMock.status === 'ready' ? document : null,
       currentHash,
+      analysis: null,
+      types: null,
     };
   },
   useInvalidateAutomationValidation: () => invalidateValidation,
diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 17a2e290d5..66db90184c 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -5,6 +5,7 @@ import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
 import { CatalogLoadError } from '@tale/ui/catalog/catalog-view';
 import { cn } from '@tale/ui/cn';
+import type { CodeEditorDiagnosticsStatus } from '@tale/ui/code-editor';
 import { ContentArea } from '@tale/ui/content-area';
 import { ConfirmDialog } from '@tale/ui/dialog/confirm-dialog';
 import { Dialog } from '@tale/ui/dialog/dialog';
@@ -64,6 +65,7 @@ import {
 import { useAbility } from '@/app/hooks/use-ability';
 import { failureDetail } from '@/app/lib/backend/adapters';
 import { readStateOf } from '@/app/lib/backend/read-state';
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
 import { ptr } from '@/lib/engine/core/syntax/pointer';
 import type { NodeDef, Automation } from '@/lib/engine/core/types';
 import { useT } from '@/lib/i18n/client';
@@ -143,7 +145,12 @@ import {
 } from './automation-run-dialog';
 import { AutomationVersionPicker } from './automation-version-picker';
 import { CodingAgentButton } from './coding-agent-entry';
-import { NodeFields, NodeInspector } from './node-inspector';
+import {
+  NodeFields,
+  NodeInspector,
+  type InspectorContext,
+} from './node-inspector';
+import type { ShapeStatus } from './node-shape-panel';
 
 /** The run-scope Select's "organization-wide" choice. A Radix Select item
  * cannot carry an empty value, so the org-wide option needs a real sentinel
@@ -615,6 +622,70 @@ function AutomationEditorScope({
     [automation, requestIssueFocus],
   );
 
+  // ── The inspector ────────────────────────────────────────────────────
+  // What a node's inspector reads besides the node: when it runs (the flow
+  // facts of the document the canvas draws, so typing never re-works them
+  // per keystroke), the check's shapes and failure reasons, and where the
+  // check stands for the marks in its code fields.
+  const canvasNodes = canvasDocument?.nodes;
+  const flowFacts = useMemo(
+    () => (canvasNodes === undefined ? null : analyzeFlow(canvasNodes)),
+    [canvasNodes],
+  );
+  const diagnosticsStatus: CodeEditorDiagnosticsStatus =
+    validation.status === 'failed'
+      ? 'failed'
+      : validation.status === 'ready' &&
+          validation.settledFor === validation.currentHash
+        ? 'ready'
+        : 'checking';
+  const shapeStatus: ShapeStatus | 'off' = !canAuthor
+    ? 'off'
+    : validation.status === 'failed'
+      ? 'failed'
+      : validationTypes === null
+        ? 'pending'
+        : diagnosticsStatus === 'ready'
+          ? 'ready'
+          : 'checking';
+  const settledDocument = validation.settledDocument;
+  const sampleOf = useCallback(
+    (nodeId: string) =>
+      showLastRun ? lastRunProjection.byNode.get(nodeId)?.output : undefined,
+    [showLastRun, lastRunProjection],
+  );
+  const inspectorContext = useMemo<InspectorContext | null>(
+    () =>
+      automation === null
+        ? null
+        : {
+            doc: automation,
+            flow: flowFacts,
+            analysis: validationAnalysis,
+            types: validationTypes,
+            shapeStatus,
+            diagnosticsStatus,
+            settled: settledDocument,
+            catalog,
+            modelLabel,
+            onSelect: (id) => selectOnCanvas(id),
+            sampleOf,
+          },
+    [
+      automation,
+      flowFacts,
+      validationAnalysis,
+      validationTypes,
+      shapeStatus,
+      diagnosticsStatus,
+      settledDocument,
+      catalog,
+      modelLabel,
+      selectOnCanvas,
+      sampleOf,
+    ],
+  );
+
   const [viewChoice, setViewChoice] = useState<
     AutomationEditorView | undefined
   >(viewParam);
@@ -1590,27 +1661,32 @@ function AutomationEditorScope({
               (`lg` up) it opens there; below that there is no panel to
               stack against, so it opens in the sheet below instead — never
               both, `isWorkbenchCompact` picks exactly one. */}
-          {selectedNode !== null && !isWorkbenchCompact && (
-            <NodeInspector
-              id={inspectorId}
-              variant="panel"
-              node={selectedNode}
-              nodeType={nodeTypes.find((def) => def.type === selectedNode.type)}
-              catalogUnavailable={catalogQuery.isError}
-              runView={
-                showLastRun
-                  ? lastRunProjection.byNode.get(selectedNode.id)
-                  : undefined
-              }
-              readOnly={!canAuthor}
-              onChange={onChangeNode}
-              organizationId={organizationId}
-              {...(projectId !== undefined && { projectId })}
-              onDeselect={deselectNode}
-              issues={selectedNodeIssues}
-              nodeIndex={selectedNodeIndex}
-            />
-          )}
+          {selectedNode !== null &&
+            inspectorContext !== null &&
+            !isWorkbenchCompact && (
+              <NodeInspector
+                id={inspectorId}
+                variant="panel"
+                node={selectedNode}
+                nodeType={nodeTypes.find(
+                  (def) => def.type === selectedNode.type,
+                )}
+                catalogUnavailable={catalogQuery.isError}
+                runView={
+                  showLastRun
+                    ? lastRunProjection.byNode.get(selectedNode.id)
+                    : undefined
+                }
+                readOnly={!canAuthor}
+                onChange={onChangeNode}
+                organizationId={organizationId}
+                {...(projectId !== undefined && { projectId })}
+                onDeselect={deselectNode}
+                issues={selectedNodeIssues}
+                nodeIndex={selectedNodeIndex}
+                context={inspectorContext}
+              />
+            )}
         </div>
       </div>
 
@@ -1676,10 +1752,10 @@ function AutomationEditorScope({
             // Closing onto the Problems sheet: its list takes focus.
             preventCloseAutoFocus={nodeSheetHandsOn}
           >
-            {selectedNode !== null && (
+            {selectedNode !== null && inspectorContext !== null && (
               <>
                 <ResponsiveDialogTitle className="sr-only">
-                  {selectedNode.id}
+                  {nodeTitle(selectedNode.id)}
                 </ResponsiveDialogTitle>
                 <ResponsiveDialogDescription className="sr-only">
                   {t('editor.nodeSheetDescription')}
@@ -1703,6 +1779,7 @@ function AutomationEditorScope({
                   onDeselect={deselectNode}
                   issues={selectedNodeIssues}
                   nodeIndex={selectedNodeIndex}
+                  context={inspectorContext}
                 />
                 {canAuthor && (
                   <div className="bg-background border-border sticky bottom-0 z-10 -mb-6 flex flex-wrap items-center justify-end gap-2 border-t pt-3 pb-6">
diff --git a/services/platform/app/features/automations/components/json-code-field.test.tsx b/services/platform/app/features/automations/components/json-code-field.test.tsx
new file mode 100644
index 0000000000..9169015f0c
--- /dev/null
+++ b/services/platform/app/features/automations/components/json-code-field.test.tsx
@@ -0,0 +1,123 @@
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { render, screen } from '@/tests/utils/render';
+
+import { JsonCodeField, jsonFieldText } from './json-code-field';
+
+/**
+ * A JSON field commits only a value that parses and has the field's kind,
+ * and never rewrites the author's text with the value its own commit
+ * echoes back — the caret jump and the cleared field of the old box.
+ */
+function Owner({
+  initial,
+  expect: kind = 'object',
+  onValue,
+}: {
+  initial: unknown;
+  expect?: 'object' | 'array' | 'any';
+  onValue?: (value: unknown) => void;
+}) {
+  const [value, setValue] = useState<unknown>(initial);
+  return (
+    <>
+      <JsonCodeField
+        label="Input"
+        value={value}
+        expect={kind}
+        anchor={null}
+        readOnly={false}
+        onCommit={(next) => {
+          setValue(next);
+          onValue?.(next);
+        }}
+      />
+      <button type="button" onClick={() => setValue({ replaced: true })}>
+        replace
+      </button>
+    </>
+  );
+}
+
+describe('jsonFieldText', () => {
+  it('shows a value as two-space JSON and an absent one as nothing', () => {
+    expect(jsonFieldText({ a: [1] })).toBe('{\n  "a": [\n    1\n  ]\n}');
+    expect(jsonFieldText(undefined)).toBe('');
+  });
+});
+
+describe('JsonCodeField', () => {
+  it('keeps the text as typed when its own value comes back', async () => {
+    const onValue = vi.fn();
+    const { user } = render(<Owner initial={undefined} onValue={onValue} />);
+    const box = screen.getByRole('textbox', { name: 'Input' });
+    await user.type(box, '{{"a": 1}');
+    // One line, as typed — not re-serialised over two.
+    expect(box).toHaveValue('{"a": 1}');
+    expect(onValue).toHaveBeenLastCalledWith({ a: 1 });
+  });
+
+  it('takes a value that changed for another reason', async () => {
+    const { user } = render(<Owner initial={{ a: 1 }} />);
+    await user.click(screen.getByRole('button', { name: 'replace' }));
+    expect(screen.getByRole('textbox', { name: 'Input' })).toHaveValue(
+      '{\n  "replaced": true\n}',
+    );
+  });
+
+  it('clears the field when the text is blank', async () => {
+    const onValue = vi.fn();
+    const { user } = render(<Owner initial={{ a: 1 }} onValue={onValue} />);
+    await user.clear(screen.getByRole('textbox', { name: 'Input' }));
+    expect(onValue).toHaveBeenLastCalledWith(undefined);
+  });
+
+  it('says why text that is not JSON yet changes nothing', async () => {
+    const onValue = vi.fn();
+    const { user } = render(<Owner initial={undefined} onValue={onValue} />);
+    await user.type(screen.getByRole('textbox', { name: 'Input' }), '{{"a":');
+    expect(onValue).not.toHaveBeenCalled();
+    expect(
+      screen.getByText(
+        'This is not valid JSON yet, so the node was not changed.',
+      ),
+    ).toBeVisible();
+  });
+
+  it('refuses a value of the wrong kind', async () => {
+    const onValue = vi.fn();
+    const { user } = render(<Owner initial={{ a: 1 }} onValue={onValue} />);
+    const box = screen.getByRole('textbox', { name: 'Input' });
+    await user.clear(box);
+    onValue.mockClear();
+    // `[[` types one bracket.
+    await user.type(box, '[[1]');
+    expect(onValue).not.toHaveBeenCalled();
+    expect(
+      screen.getByText('This must be a JSON object, in curly braces.'),
+    ).toBeVisible();
+    expect(box).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('asks for a list where a list is due', async () => {
+    const onValue = vi.fn();
+    const { user } = render(
+      <Owner initial={undefined} expect="array" onValue={onValue} />,
+    );
+    await user.type(screen.getByRole('textbox', { name: 'Input' }), '{{}');
+    expect(
+      screen.getByText('This must be a JSON list, in square brackets.'),
+    ).toBeVisible();
+    expect(onValue).not.toHaveBeenCalled();
+  });
+
+  it('takes any JSON value where any is due', async () => {
+    const onValue = vi.fn();
+    const { user } = render(
+      <Owner initial={undefined} expect="any" onValue={onValue} />,
+    );
+    await user.type(screen.getByRole('textbox', { name: 'Input' }), '"hi"');
+    expect(onValue).toHaveBeenLastCalledWith('hi');
+  });
+});
diff --git a/services/platform/app/features/automations/components/json-code-field.tsx b/services/platform/app/features/automations/components/json-code-field.tsx
new file mode 100644
index 0000000000..2726f5f8ae
--- /dev/null
+++ b/services/platform/app/features/automations/components/json-code-field.tsx
@@ -0,0 +1,171 @@
+'use client';
+
+import {
+  CodeEditor,
+  type CodeEditorDiagnostic,
+  type CodeEditorDiagnosticsStatus,
+} from '@tale/ui/code-editor';
+import type { CodeEditorProviders } from '@tale/ui/code-editor/providers';
+import type { TemplateScan } from '@tale/ui/code-editor/template-scan';
+import { Field } from '@tale/ui/field';
+import type { FieldIssue } from '@tale/ui/field-issue-messages';
+import { useEffect, useId, useRef, useState } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+import { stableStringify } from '@/lib/shared/utils/stable-stringify';
+
+/** The text a JSON field shows for a value: two-space JSON, nothing for
+ *  an absent one. The check's ranges index into the same text. */
+export function jsonFieldText(value: unknown): string {
+  if (value === undefined) return '';
+  try {
+    return JSON.stringify(value, null, 2) ?? '';
+  } catch (error) {
+    console.warn('[automations] a field value is not serialisable', error);
+    return '';
+  }
+}
+
+/** What a JSON field accepts: an object, a list, or any JSON value. */
+export type JsonExpect = 'object' | 'array' | 'any';
+
+function kindMatches(value: unknown, expect: JsonExpect): boolean {
+  if (expect === 'any') return true;
+  if (expect === 'array') return Array.isArray(value);
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export interface JsonCodeFieldProps {
+  label: string;
+  description?: string;
+  /** The value as the document holds it. */
+  value: unknown;
+  expect: JsonExpect;
+  /** `{{ js }}` inside the JSON's strings. */
+  templates?: boolean;
+  templateScanner?: (text: string) => TemplateScan;
+  /** A value that parses and has the expected kind; `undefined` for a
+   *  cleared field. */
+  onCommit: (next: unknown) => void;
+  /** Where "go to" a problem in this field (or inside it) lands. */
+  anchor: string | null;
+  /** Opens what hides the field (its tab, its disclosure) before a "go to". */
+  issueReveal?: () => void;
+  /** The problems the check found here, one line each under the editor. */
+  issues?: readonly FieldIssue[];
+  diagnostics?: readonly CodeEditorDiagnostic[];
+  diagnosticsFor?: string;
+  diagnosticsStatus?: CodeEditorDiagnosticsStatus;
+  providers?: CodeEditorProviders;
+  readOnly: boolean;
+  required?: boolean;
+  minRows?: number;
+  maxRows?: number;
+  expandable?: boolean;
+}
+
+/**
+ * A JSON value edited as text in the code editor: the node changes only
+ * when the text parses to a value of the kind the field takes, and the text
+ * is the author's own — the node's value coming back from an edit never
+ * rewrites it, so the caret stays where it was. A value that changes for
+ * another reason (another node, a reloaded version, a new version an agent
+ * saved) replaces the text.
+ */
+export function JsonCodeField({
+  label,
+  description,
+  value,
+  expect,
+  templates = false,
+  templateScanner,
+  onCommit,
+  anchor,
+  issueReveal,
+  issues,
+  diagnostics,
+  diagnosticsFor,
+  diagnosticsStatus,
+  providers,
+  readOnly,
+  required,
+  minRows = 3,
+  maxRows = 14,
+  expandable = true,
+}: JsonCodeFieldProps) {
+  const { t } = useT('automations');
+  const id = useId();
+  const [text, setText] = useState(() => jsonFieldText(value));
+  const [error, setError] = useState<string | null>(null);
+  /** The value this field last committed or showed, by content. */
+  const committed = useRef(stableStringify(value));
+
+  useEffect(() => {
+    const next = stableStringify(value);
+    if (next === committed.current) return;
+    committed.current = next;
+    setText(jsonFieldText(value));
+    setError(null);
+  }, [value]);
+
+  const change = (next: string): void => {
+    setText(next);
+    if (next.trim() === '') {
+      setError(null);
+      committed.current = stableStringify(undefined);
+      onCommit(undefined);
+      return;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(next);
+    } catch {
+      // The editor marks where the text stops being JSON; the line under
+      // it says the node was not changed.
+      setError(t('editor.invalidJson'));
+      return;
+    }
+    if (!kindMatches(parsed, expect)) {
+      setError(
+        expect === 'array'
+          ? t('editor.jsonMustBeList')
+          : t('editor.jsonMustBeObject'),
+      );
+      return;
+    }
+    setError(null);
+    committed.current = stableStringify(parsed);
+    onCommit(parsed);
+  };
+
+  return (
+    <Field
+      label={label}
+      htmlFor={id}
+      {...(description !== undefined && { description })}
+      {...(error !== null && { error })}
+      {...(issues !== undefined && issues.length > 0 && { issues })}
+      {...(required !== undefined && { required })}
+    >
+      <CodeEditor
+        id={id}
+        value={text}
+        onChange={change}
+        language="json"
+        templates={templates}
+        {...(templateScanner !== undefined && { templateScanner })}
+        readOnly={readOnly}
+        minRows={minRows}
+        maxRows={maxRows}
+        expandable={expandable && !readOnly ? { title: label } : false}
+        issueAnchor={anchor}
+        {...(issueReveal !== undefined && { issueReveal })}
+        {...(diagnostics !== undefined && { diagnostics })}
+        {...(diagnosticsFor !== undefined && { diagnosticsFor })}
+        {...(diagnosticsStatus !== undefined && { diagnosticsStatus })}
+        {...(providers !== undefined && { providers })}
+        describeDiagnostics={false}
+      />
+    </Field>
+  );
+}
diff --git a/services/platform/app/features/automations/components/node-flow-summary.tsx b/services/platform/app/features/automations/components/node-flow-summary.tsx
new file mode 100644
index 0000000000..0783b079f8
--- /dev/null
+++ b/services/platform/app/features/automations/components/node-flow-summary.tsx
@@ -0,0 +1,115 @@
+'use client';
+
+import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { useId } from 'react';
+
+import type { FlowFacts, PathSkip } from '@/lib/engine/core/analysis/flow';
+import type { NodeDef } from '@/lib/engine/core/types';
+import { useT } from '@/lib/i18n/client';
+
+import { nodeTitle } from '../lib/node-face';
+import { failureReasonWords } from '../lib/paths';
+
+export interface NodeFlowSummaryProps {
+  node: NodeDef;
+  /** The document's flow facts; null on a reference cycle. */
+  flow: FlowFacts | null;
+  /** Why the node can fail, as the draft check named it. */
+  failureReasons?: readonly string[];
+  /** How many nodes read this node's output. */
+  readerCount: number;
+  /** The sentences of the marks on the node's box: it writes, it may ask. */
+  marks?: readonly string[];
+}
+
+type Translate = ReturnType<typeof useT>['t'];
+
+function skipSentence(skip: PathSkip, node: NodeDef, t: Translate): string {
+  if (skip.reason === 'when') return t('editor.flow.skipWhen');
+  if (skip.reason === 'else') {
+    return t('editor.flow.skipElse', { node: nodeTitle(node.elseOf ?? '') });
+  }
+  if (skip.reason === 'upstream') {
+    return t('editor.flow.skipUpstream', { node: nodeTitle(skip.via ?? '') });
+  }
+  return t('editor.flow.skipError');
+}
+
+/** How often the node runs: always, on some paths, or never. */
+function reachSentence(
+  flow: FlowFacts,
+  id: string,
+  t: Translate,
+): string | null {
+  const reach = flow.reach(id);
+  if (!reach.ran) return t('editor.flow.never');
+  if (reach.always) return t('editor.flow.always');
+  // Too many conditions to list the paths: no count to give.
+  if (flow.truncated || flow.paths.length === 0) return null;
+  return t('editor.flow.some', {
+    count: flow.pathsWhere((path) => path.ran.includes(id)).length,
+    total: flow.paths.length,
+  });
+}
+
+/**
+ * "When it runs": how often the node runs, each way it can be skipped,
+ * what happens when it fails and why it can — worked out in the browser
+ * from the document's conditions, with the draft check's failure reasons
+ * once it answered.
+ */
+export function NodeFlowSummary({
+  node,
+  flow,
+  failureReasons,
+  readerCount,
+  marks = [],
+}: NodeFlowSummaryProps) {
+  const { t } = useT('automations');
+  const { locale } = useLocale();
+  const titleId = useId();
+  const lines: string[] = [];
+  if (flow !== null) {
+    const reach = reachSentence(flow, node.id, t);
+    if (reach !== null) lines.push(reach);
+    if (flow.reach(node.id).ran) {
+      for (const skip of flow.maySkip(node.id)) {
+        lines.push(skipSentence(skip, node, t));
+      }
+    }
+  }
+  lines.push(
+    node.onError === 'continue'
+      ? t('editor.flow.failContinues', { count: readerCount })
+      : t('editor.flow.failHalts'),
+  );
+  const reasons = (failureReasons ?? []).flatMap((reason) => {
+    const words = failureReasonWords(reason, t);
+    return words === null ? [] : [words];
+  });
+  if (reasons.length > 0) {
+    lines.push(
+      t('editor.flow.failsWhen', {
+        reasons: new Intl.ListFormat(locale, { type: 'disjunction' }).format(
+          reasons,
+        ),
+      }),
+    );
+  }
+  lines.push(...marks);
+  return (
+    <section aria-labelledby={titleId} className="flex flex-col gap-1">
+      <h4 id={titleId} className="text-foreground text-sm font-medium">
+        {t('editor.flow.title')}
+      </h4>
+      <ul className="text-muted-foreground flex flex-col gap-0.5 text-xs">
+        {lines.map((line, index) => (
+          // A sentence can repeat (two upstream skips through one node are
+          // one line each); the position keeps the keys apart.
+          // oxlint-disable-next-line react/no-array-index-key -- the lines are static per render
+          <li key={`${index}:${line}`}>{line}</li>
+        ))}
+      </ul>
+    </section>
+  );
+}
diff --git a/services/platform/app/features/automations/components/node-inspector.test.tsx b/services/platform/app/features/automations/components/node-inspector.test.tsx
index f19f245dbe..041dda2ef4 100644
--- a/services/platform/app/features/automations/components/node-inspector.test.tsx
+++ b/services/platform/app/features/automations/components/node-inspector.test.tsx
@@ -1,12 +1,13 @@
 import { IssueFocusProvider, useRequestIssueFocus } from '@tale/ui/issue-focus';
-import type { ReactNode } from 'react';
+import { useState, type ReactNode } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
 import type { NodeDef } from '@/lib/engine/core/types';
 import type { WireAutomationIssue } from '@/lib/shared/schemas/automation-issues';
 import { checkAccessibility } from '@/tests/utils/a11y';
 import { i18n } from '@/tests/utils/i18n-all-languages';
-import { render, screen, within } from '@/tests/utils/render';
+import { render, screen, waitFor, within } from '@/tests/utils/render';
 
 import { coreNodeTypes } from '../hooks/backend';
 import { fieldsWithIssueControl } from '../lib/inspector-fields';
@@ -15,7 +16,8 @@ import {
   withIssueIds,
   type AutomationIssueView,
 } from '../lib/issues';
-import { NodeInspector } from './node-inspector';
+import { nodeCatalogView } from '../lib/node-face';
+import { NodeInspector, type InspectorContext } from './node-inspector';
 
 /**
  * The inspector shows the fields the ENGINE REGISTRY declares for a node type —
@@ -66,6 +68,18 @@ vi.mock('@/app/features/projects/hooks/queries', () => ({
 }));
 
 const llmType = coreNodeTypes().find((def) => def.type === 'llm');
+
+/** A document around the node under test, with no check behind it. */
+const baseContext: InspectorContext = {
+  doc: { version: 1, name: 'support/reply', nodes: [] },
+  flow: null,
+  analysis: null,
+  types: null,
+  shapeStatus: 'off',
+  diagnosticsStatus: 'ready',
+  settled: null,
+  catalog: nodeCatalogView(coreNodeTypes()),
+};
 const transformType = coreNodeTypes().find((def) => def.type === 'transform');
 
 const llmNode = {
@@ -85,6 +99,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -99,6 +114,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -116,6 +132,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -148,6 +165,7 @@ describe('NodeInspector', () => {
           nodeType={llmType}
           readOnly={false}
           organizationId="org_test"
+          context={baseContext}
           onChange={onChange}
         />,
       );
@@ -174,6 +192,7 @@ describe('NodeInspector', () => {
           nodeType={llmType}
           readOnly={false}
           organizationId="org_test"
+          context={baseContext}
           onChange={vi.fn()}
         />,
       );
@@ -196,6 +215,7 @@ describe('NodeInspector', () => {
           nodeType={llmType}
           readOnly={false}
           organizationId="org_test"
+          context={baseContext}
           onChange={onChange}
         />,
       );
@@ -219,6 +239,7 @@ describe('NodeInspector', () => {
         nodeType={transformType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -236,6 +257,7 @@ describe('NodeInspector', () => {
         nodeType={transformType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={onChange}
       />,
     );
@@ -252,6 +274,7 @@ describe('NodeInspector', () => {
         nodeType={transformType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={onChange}
       />,
     );
@@ -268,6 +291,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -286,6 +310,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -302,6 +327,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -319,6 +345,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -338,6 +365,7 @@ describe('NodeInspector', () => {
         nodeType={transformType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -359,6 +387,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -378,6 +407,7 @@ describe('NodeInspector', () => {
         catalogUnavailable
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -388,8 +418,8 @@ describe('NodeInspector', () => {
     ).toBeVisible();
   });
 
-  it('shows what the overlaid run did to this node, effects included', () => {
-    render(
+  it('shows what the overlaid run did to this node, effects included', async () => {
+    const { user } = render(
       <NodeInspector
         id="inspector"
         node={llmNode}
@@ -409,13 +439,15 @@ describe('NodeInspector', () => {
         readOnly
         onChange={vi.fn()}
         organizationId="org_test"
+        context={baseContext}
       />,
     );
-    expect(screen.getByText('In this run')).toBeVisible();
-    expect(screen.getByText('slack.post_message')).toBeVisible();
     expect(screen.getByRole('textbox', { name: 'Prompt' })).toHaveAttribute(
       'readonly',
     );
+    // What the run did is its own tab, there only while a run is shown.
+    await user.click(screen.getByRole('tab', { name: 'Last run' }));
+    expect(screen.getByText('slack.post_message')).toBeVisible();
   });
 
   it('closes from the header control', async () => {
@@ -427,6 +459,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
         onDeselect={onDeselect}
       />,
@@ -444,6 +477,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
         onDeselect={onDeselect}
       />,
@@ -461,6 +495,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
         onDeselect={onDeselect}
       />,
@@ -478,6 +513,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
         onDeselect={vi.fn()}
       />,
@@ -493,6 +529,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -507,6 +544,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
       />,
     );
@@ -521,6 +559,7 @@ describe('NodeInspector', () => {
         nodeType={llmType}
         readOnly={false}
         organizationId="org_test"
+        context={baseContext}
         onChange={vi.fn()}
         onDeselect={vi.fn()}
       />,
@@ -584,6 +623,7 @@ describe('NodeInspector problems', () => {
           nodeType={llmType}
           readOnly={false}
           organizationId="org_test"
+          context={baseContext}
           onChange={vi.fn()}
           issues={issues}
           nodeIndex={0}
@@ -663,14 +703,15 @@ describe('NodeInspector problems', () => {
     const prompt = screen.getByRole<HTMLTextAreaElement>('textbox', {
       name: 'Prompt',
     });
-    expect(prompt).toHaveFocus();
+    // The field first makes sure its tab is the one shown.
+    await waitFor(() => expect(prompt).toHaveFocus());
     expect([prompt.selectionStart, prompt.selectionEnd]).toEqual([4, 12]);
   });
 
   it('takes the reader to the node for a problem with the node as a whole', async () => {
     const { user } = inspector([], <GoTo anchor="/nodes/0" />);
     await user.click(screen.getByRole('button', { name: 'go to' }));
-    expect(screen.getByText('summary', { selector: 'span' })).toHaveFocus();
+    expect(screen.getByText('Summary', { selector: 'span' })).toHaveFocus();
   });
 
   it('passes an axe audit with problems shown', async () => {
@@ -689,3 +730,317 @@ describe('NodeInspector problems', () => {
     await checkAccessibility(container);
   });
 });
+
+describe('NodeInspector header, When it runs and tabs', () => {
+  const calc = { id: 'calc', type: 'transform', code: 'return { count: 1 };' };
+  const doc = { version: 1, name: 'support/reply', nodes: [calc, llmNode] };
+  const context: InspectorContext = {
+    ...baseContext,
+    doc,
+    flow: analyzeFlow(doc.nodes),
+    shapeStatus: 'ready',
+  };
+
+  function inspect(
+    node: NodeDef,
+    overrides: Partial<InspectorContext> = {},
+    onChange = vi.fn(),
+  ) {
+    return render(
+      <NodeInspector
+        id="inspector"
+        node={node}
+        nodeType={coreNodeTypes().find((def) => def.type === node.type)}
+        readOnly={false}
+        organizationId="org_test"
+        context={{ ...context, ...overrides }}
+        onChange={onChange}
+      />,
+    );
+  }
+
+  it('names the node by its title, says what kind it is and copies its id', () => {
+    inspect(llmNode);
+    expect(
+      screen.getByRole('heading', { level: 3, name: 'Summary' }),
+    ).toBeVisible();
+    expect(
+      screen.getByText('Language model · anthropic/claude-haiku-4-5'),
+    ).toBeVisible();
+    expect(screen.getByText('summary', { selector: 'code' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Copy node ID' })).toBeVisible();
+  });
+
+  it('says how often the node runs, how it is skipped and what a failure does', () => {
+    inspect(llmNode, {
+      analysis: {
+        nodes: { summary: { failureReasons: ['external'] } },
+        paths: { count: 2, truncated: false, halts: [] },
+        output: { reads: [], maybeEmpty: false },
+      },
+    });
+    const section = screen.getByRole('region', { name: 'When it runs' });
+    expect(within(section).getByText('On 1 of 2 paths')).toBeVisible();
+    expect(
+      within(section).getByText('Skipped when its condition is false'),
+    ).toBeVisible();
+    expect(
+      within(section).getByText('If it fails, the run stops with its error.'),
+    ).toBeVisible();
+    expect(
+      within(section).getByText('Fails when a service it calls fails.'),
+    ).toBeVisible();
+  });
+
+  it('counts the readers a failure that goes on skips', () => {
+    const report = {
+      id: 'report',
+      type: 'transform',
+      code: 'return 1;',
+      input: { text: '{{ nodes.calc.output.count }}' },
+    };
+    const goesOn = { ...calc, onError: 'continue' as const };
+    const nodes = [goesOn, report];
+    inspect(goesOn, {
+      doc: { ...doc, nodes },
+      flow: analyzeFlow(nodes),
+    });
+    expect(
+      screen.getByText(
+        'If it fails, the run goes on without it and skips 1 node that reads it.',
+      ),
+    ).toBeVisible();
+    // Going on after a failure is a way of producing nothing.
+    expect(screen.getByText('Skipped when it fails')).toBeVisible();
+  });
+
+  it('shows Fields and Shape, and Last run only while a run is shown', async () => {
+    const { user } = inspect(llmNode);
+    expect(screen.getByRole('tab', { name: 'Fields' })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(screen.queryByRole('tab', { name: 'Last run' })).toBeNull();
+    await user.click(screen.getByRole('tab', { name: 'Shape' }));
+    expect(screen.getByRole('heading', { name: 'Read by' })).toBeVisible();
+  });
+
+  it('has no Shape tab where nothing checks the document', () => {
+    inspect(llmNode, { shapeStatus: 'off' });
+    expect(screen.queryByRole('tab', { name: 'Shape' })).toBeNull();
+  });
+
+  it('keeps a half-typed field across a look at the shapes', async () => {
+    const { user } = inspect({ ...calc, input: { a: 1 } });
+    const input = screen.getByRole('textbox', { name: 'Input' });
+    await user.clear(input);
+    await user.type(input, '[[');
+    await user.click(screen.getByRole('tab', { name: 'Shape' }));
+    await user.click(screen.getByRole('tab', { name: 'Fields' }));
+    expect(screen.getByRole('textbox', { name: 'Input' })).toHaveValue('[');
+  });
+});
+
+describe('NodeInspector fields', () => {
+  const doc = {
+    version: 1,
+    name: 'support/reply',
+    nodes: [
+      { id: 'calc', type: 'transform', code: 'return 1;' },
+      { id: 'triage', type: 'llm', prompt: 'Hi', when: 'input.urgent' },
+      { id: 'fallback', type: 'llm', prompt: 'Hi', elseOf: 'triage' },
+      llmNode,
+    ],
+  };
+  const context: InspectorContext = { ...baseContext, doc };
+  const typeOf = (node: NodeDef) =>
+    coreNodeTypes().find((def) => def.type === node.type);
+
+  function inspect(node: NodeDef, onChange = vi.fn()) {
+    return render(
+      <NodeInspector
+        id="inspector"
+        node={node}
+        nodeType={typeOf(node)}
+        readOnly={false}
+        organizationId="org_test"
+        context={context}
+        onChange={onChange}
+      />,
+    );
+  }
+
+  const languageOf = (name: string) =>
+    screen.getByRole('textbox', { name }).getAttribute('data-language');
+
+  it('edits every code field in the code editor, in its language', () => {
+    inspect({
+      ...llmNode,
+      system: 'Be brief.',
+      forEach: '{{ nodes.calc.output }}',
+      repeatUntil: 'output.done',
+    });
+    expect(languageOf('Prompt')).toBe('markdown');
+    expect(screen.getByRole('textbox', { name: 'Prompt' })).toHaveAttribute(
+      'data-templates',
+    );
+    expect(languageOf('System prompt')).toBe('markdown');
+    expect(languageOf('Input')).toBe('json');
+    // A condition is one expression until it holds a template.
+    expect(languageOf('When')).toBe('template');
+    expect(languageOf('Repeat until')).toBe('expression');
+    expect(languageOf('For each')).toBe('template');
+  });
+
+  it('edits transform code as JavaScript', () => {
+    inspect({ id: 'calc', type: 'transform', code: 'return 1;' });
+    expect(languageOf('Code')).toBe('javascript');
+  });
+
+  it('says a condition in words under it', () => {
+    inspect({ ...llmNode, when: 'input.urgent' });
+    expect(
+      screen.getByText(
+        /^Runs only if .+\. Otherwise it's skipped, and so is every node that reads its output\.$/,
+      ),
+    ).toBeVisible();
+  });
+
+  it('sets On error to go on without the node, and back', async () => {
+    const onChange = vi.fn();
+    const { user } = inspect(llmNode, onChange);
+    await user.click(
+      screen.getByRole('radio', { name: 'Continue without it' }),
+    );
+    expect(onChange).toHaveBeenLastCalledWith({ onError: 'continue' });
+    expect(
+      screen.getByText(/^What happens when this node fails\./),
+    ).toBeVisible();
+  });
+
+  it('removes On error when the run should stop', async () => {
+    const onChange = vi.fn();
+    const { user } = inspect({ ...llmNode, onError: 'continue' }, onChange);
+    await user.click(screen.getByRole('radio', { name: 'Stop the run' }));
+    expect(onChange).toHaveBeenLastCalledWith({ onError: undefined });
+  });
+
+  it('offers Maximum repeats only beside Repeat until, and refuses 25', async () => {
+    const onChange = vi.fn();
+    const { user, unmount } = inspect(llmNode, onChange);
+    expect(
+      screen.queryByRole('spinbutton', { name: 'Maximum repeats' }),
+    ).toBeNull();
+    unmount();
+    const second = inspect(
+      { ...llmNode, repeatUntil: 'output.done' },
+      onChange,
+    );
+    const box = screen.getByRole('spinbutton', { name: 'Maximum repeats' });
+    await second.user.type(box, '25');
+    expect(
+      screen.getByText('Enter a whole number from 1 to 20.'),
+    ).toBeVisible();
+    expect(onChange).not.toHaveBeenCalledWith({ maxRepeats: 25 });
+    await second.user.clear(box);
+    await second.user.type(box, '3');
+    expect(onChange).toHaveBeenLastCalledWith({ maxRepeats: 3 });
+    void user;
+  });
+
+  it('offers only nodes with a condition as Else of, never itself or its own partner', () => {
+    const triage = { id: 'triage', type: 'llm', prompt: 'Hi', when: 'input.a' };
+    const fallback = {
+      id: 'fallback',
+      type: 'llm',
+      prompt: 'Hi',
+      when: 'input.b',
+      elseOf: 'triage',
+    };
+    render(
+      <NodeInspector
+        id="inspector"
+        node={triage}
+        nodeType={llmType}
+        readOnly={false}
+        organizationId="org_test"
+        context={{
+          ...baseContext,
+          doc: {
+            ...doc,
+            nodes: [{ id: 'calc', type: 'transform' }, triage, fallback],
+          },
+        }}
+        onChange={vi.fn()}
+      />,
+    );
+    // Fallback has a condition, but it is already Triage's otherwise:
+    // pairing the two both ways would make each wait on the other.
+    expect(screen.getByText('No other node has a condition.')).toBeVisible();
+  });
+
+  it('pairs a node with a condition as its otherwise', async () => {
+    const onChange = vi.fn();
+    const { user } = inspect(llmNode, onChange);
+    await user.click(screen.getByRole('button', { name: /^Else of/ }));
+    await user.click(await screen.findByRole('option', { name: /Triage/ }));
+    expect(onChange).toHaveBeenLastCalledWith({ elseOf: 'triage' });
+  });
+});
+
+describe('NodeInspector JSON fields', () => {
+  /** The inspector over a node it really edits: each patch lands on the
+   *  node and comes back, as the editor's draft does it. */
+  function Harness({ onNode }: { onNode: (node: NodeDef) => void }) {
+    const [node, setNode] = useState<NodeDef>({
+      id: 'calc',
+      type: 'transform',
+      code: 'return input;',
+    });
+    return (
+      <NodeInspector
+        id="inspector"
+        node={node}
+        nodeType={transformType}
+        readOnly={false}
+        organizationId="org_test"
+        context={baseContext}
+        onChange={(patch) => {
+          setNode((current) => {
+            const updated: NodeDef = { ...current, ...patch };
+            for (const [key, value] of Object.entries(patch)) {
+              if (value === undefined) Reflect.deleteProperty(updated, key);
+            }
+            onNode(updated);
+            return updated;
+          });
+        }}
+      />
+    );
+  }
+
+  it('never moves the caret while typing, and keeps the node on a scalar', async () => {
+    const seen: NodeDef[] = [];
+    const { user } = render(<Harness onNode={(node) => seen.push(node)} />);
+    const input = screen.getByRole<HTMLTextAreaElement>('textbox', {
+      name: 'Input',
+    });
+    const typed = '{"a":1}';
+    for (let i = 0; i < typed.length; i++) {
+      const key = typed[i] === '{' ? '{{' : (typed[i] ?? '');
+      await user.type(input, key);
+      // The text is the author's own: a value parsed from it never comes
+      // back reformatted, so the caret stays at the end of what was typed.
+      expect(input).toHaveValue(typed.slice(0, i + 1));
+      expect(input.selectionStart).toBe(i + 1);
+    }
+    expect(seen.at(-1)?.input).toEqual({ a: 1 });
+
+    await user.clear(input);
+    await user.type(input, '1');
+    expect(
+      screen.getByText('This must be a JSON object, in curly braces.'),
+    ).toBeVisible();
+    expect(seen.at(-1)?.input).toBeUndefined();
+  });
+});
diff --git a/services/platform/app/features/automations/components/node-inspector.tsx b/services/platform/app/features/automations/components/node-inspector.tsx
index 4264e23730..086dadc609 100644
--- a/services/platform/app/features/automations/components/node-inspector.tsx
+++ b/services/platform/app/features/automations/components/node-inspector.tsx
@@ -1,60 +1,105 @@
 'use client';
 
 import { Alert } from '@tale/ui/alert';
-import { Badge } from '@tale/ui/badge';
 import { Card } from '@tale/ui/card';
 import { cn } from '@tale/ui/cn';
+import {
+  CodeEditor,
+  type CodeEditorDiagnostic,
+  type CodeEditorDiagnosticsStatus,
+} from '@tale/ui/code-editor';
+import type { CodeEditorProviders } from '@tale/ui/code-editor/providers';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
 import { Field } from '@tale/ui/field';
-import type { FieldIssue } from '@tale/ui/field-issue-messages';
+import {
+  FieldIssueMessages,
+  fieldIssuesHaveError,
+  type FieldIssue,
+} from '@tale/ui/field-issue-messages';
+import { useLocale } from '@tale/ui/i18n/locale-provider';
 import { IconButton } from '@tale/ui/icon-button';
 import { Input } from '@tale/ui/input';
 import { useIssueFocusTarget } from '@tale/ui/issue-focus';
 import { IssueList } from '@tale/ui/issue-list';
+import { SearchableSelect } from '@tale/ui/searchable-select';
 import { SectionHeader } from '@tale/ui/section-header';
-import { Textarea } from '@tale/ui/textarea';
-import { AlertTriangle, X } from 'lucide-react';
+import { SegmentedControl } from '@tale/ui/segmented-control';
+import { Tabs } from '@tale/ui/tabs';
+import { useCopyButton } from '@tale/ui/use-copy';
+import { AlertTriangle, Check, Copy, X } from 'lucide-react';
 import { useEffect, useId, useMemo, useRef, useState } from 'react';
 
+import type { FlowFacts } from '@/lib/engine/core/analysis/flow';
 import { ptr } from '@/lib/engine/core/syntax/pointer';
-import type { NodeDef } from '@/lib/engine/core/types';
+import type { Automation, NodeDef } from '@/lib/engine/core/types';
 import { useT } from '@/lib/i18n/client';
+import type {
+  AnalysisView,
+  TypesView,
+} from '@/lib/shared/schemas/automation-issues';
 
 import type { NodeTypeSummary } from '../hooks/backend';
 import { useDeselectOnEscape } from '../hooks/use-deselect-on-escape';
+import { fieldDiagnostics, type FieldTextKind } from '../lib/code-diagnostics';
+import { automationProviders } from '../lib/code-providers';
+import {
+  conditionText,
+  describeList,
+  renderOperand,
+} from '../lib/condition-text';
+import type { RawDocument } from '../lib/draft-document';
+import { outputReaders } from '../lib/flow-graph';
+import { END_ID } from '../lib/flow-ids';
+import { deriveEdges } from '../lib/graph';
 import {
-  CONTROL_FLOW_FIELDS,
   declaredInspectorFields,
+  fieldEditor,
+  shownControlFlowFields,
+  type FieldEditor,
 } from '../lib/inspector-fields';
 import { fieldIssueMessage, type AutomationIssueView } from '../lib/issues';
+import {
+  catalogLabel,
+  connectorName,
+  coreTypeWord,
+  nodeFace,
+  nodeTitle,
+  type NodeCatalogView,
+} from '../lib/node-face';
 import type { NodeRunView } from '../lib/run-view';
+import { engineTemplateScan } from '../lib/template-scanner';
 import { AgentNodeFields } from './agent-node-fields';
+import { JsonCodeField, jsonFieldText } from './json-code-field';
 import { LlmModelField } from './llm-model-field';
+import { NodeFlowSummary } from './node-flow-summary';
+import { NodeShapePanel, type ShapeStatus } from './node-shape-panel';
 import { RunStepDetail } from './run-step-detail';
 
 /**
- * How one declared field is edited. The SET of fields comes from the engine
- * registry — `allowedFields` on the node type — so a connector that ships a new
- * action needs no change here; only the control a known field name deserves is
- * decided locally, and an unrecognised field falls back to a single-line box
- * rather than being hidden.
+ * What the inspector reads besides the node: the document it is in, the
+ * flow facts and the draft check's answer, the catalog's words, and a way
+ * to pick another box on the canvas.
  */
-const FIELD_CONTROL: Record<string, 'text' | 'multiline' | 'json'> = {
-  input: 'json',
-  outputSchema: 'json',
-  code: 'multiline',
-  prompt: 'multiline',
-  system: 'multiline',
-  model: 'text',
-  harness: 'text',
-  skills: 'json',
-  connectors: 'json',
-  tools: 'json',
-  secrets: 'json',
-  files: 'json',
-  automation: 'text',
-  credential: 'text',
-};
+export interface InspectorContext {
+  /** The document on screen, as the inspector reads it. */
+  doc: Automation;
+  /** The document's flow facts; null on a reference cycle. */
+  flow: FlowFacts | null;
+  analysis: AnalysisView | null;
+  types: TypesView | null;
+  /** Where the draft check stands, for the Shape tab; `off` hides it. */
+  shapeStatus: ShapeStatus | 'off';
+  /** Where the draft check stands, for the marks in the code fields. */
+  diagnosticsStatus: CodeEditorDiagnosticsStatus;
+  /** The document the check answered for: its ranges index into it. */
+  settled: RawDocument | null;
+  catalog: NodeCatalogView;
+  modelLabel?: (id: string) => string | undefined;
+  /** Picks a box on the canvas: a node, Start or End. */
+  onSelect?: (id: string) => void;
+  /** What a node returned in the run laid over the canvas. */
+  sampleOf?: (nodeId: string) => unknown;
+}
 
 /**
  * Read one declared field off a node by name. `NodeDef` carries no index
@@ -67,14 +112,27 @@ function readNodeField(node: NodeDef, field: string): unknown {
   return record[field];
 }
 
-function stringify(value: unknown): string {
-  if (value === undefined) return '';
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch (error) {
-    console.warn('Node field is not serialisable as JSON', error);
-    return '';
+/** The field's value in the document the check answered for, when that
+ *  document still has this node at this place. */
+function settledField(
+  settled: RawDocument | null,
+  nodeIndex: number | undefined,
+  node: NodeDef,
+  field: string,
+): unknown {
+  if (settled === null || nodeIndex === undefined) {
+    return readNodeField(node, field);
   }
+  const nodes = settled.nodes;
+  const raw: unknown = Array.isArray(nodes) ? nodes[nodeIndex] : undefined;
+  if (
+    typeof raw !== 'object' ||
+    raw === null ||
+    Reflect.get(raw, 'id') !== node.id
+  ) {
+    return readNodeField(node, field);
+  }
+  return Reflect.get(raw, field);
 }
 
 /** Where a field's problems are, and what they say under its control. */
@@ -83,6 +141,8 @@ interface FieldIssueProps {
    * problem there, or inside it, lands on this control. */
   anchor?: string | null;
   issues?: readonly FieldIssue[];
+  /** Opens what hides the control before "go to" focuses it. */
+  reveal?: () => void;
 }
 
 /** A text field, with its label really tied to its control. */
@@ -90,30 +150,29 @@ function TextField({
   label,
   description,
   required,
-  multiline,
-  monospace,
-  rows,
   value,
   readOnly,
   onChange,
   anchor = null,
   issues,
+  reveal,
 }: {
   label: string;
   description?: string;
   required?: boolean;
-  multiline?: boolean;
-  monospace?: boolean;
-  rows?: number;
   value: string;
   readOnly: boolean;
   onChange: (next: string) => void;
 } & FieldIssueProps) {
   const id = useId();
-  const controlRef = useRef<HTMLInputElement & HTMLTextAreaElement>(null);
+  const controlRef = useRef<HTMLInputElement>(null);
   // The box shows the field's string as it is stored, so a problem's range
   // inside it selects exactly the offending text.
-  useIssueFocusTarget(anchor, controlRef);
+  useIssueFocusTarget(
+    anchor,
+    controlRef,
+    reveal === undefined ? undefined : { reveal },
+  );
   return (
     <Field
       label={label}
@@ -122,120 +181,324 @@ function TextField({
       {...(required !== undefined && { required })}
       {...(issues !== undefined && issues.length > 0 && { issues })}
     >
-      {multiline === true ? (
-        <Textarea
-          ref={controlRef}
-          id={id}
-          rows={rows ?? 3}
-          readOnly={readOnly}
-          className={monospace === true ? 'font-mono text-xs' : undefined}
-          value={value}
-          onChange={(event) => {
-            onChange(event.target.value);
-          }}
-        />
-      ) : (
-        <Input
-          ref={controlRef}
-          id={id}
-          readOnly={readOnly}
-          value={value}
-          onChange={(event) => {
-            onChange(event.target.value);
-          }}
-        />
-      )}
+      <Input
+        ref={controlRef}
+        id={id}
+        readOnly={readOnly}
+        value={value}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
+      />
     </Field>
   );
 }
 
-/** A JSON-valued field: parsed on every keystroke so the error appears where
- * it was made, and the node is only patched once the text parses. */
-function JsonField({
+/** A field written in code, a template or a prompt. */
+function CodeField({
   label,
   description,
-  title,
-  rows = 3,
+  required,
+  editor,
   value,
   readOnly,
-  onCommit,
+  onChange,
   anchor = null,
   issues,
+  reveal,
+  diagnostics,
+  diagnosticsFor,
+  diagnosticsStatus,
+  providers,
 }: {
   label: string;
   description?: string;
-  /** Hover hint — used when the help would otherwise eat a paragraph of height. */
-  title?: string;
-  rows?: number;
-  value: unknown;
+  required?: boolean;
+  editor: Extract<FieldEditor, { kind: 'code' }>;
+  value: string;
+  readOnly: boolean;
+  onChange: (next: string) => void;
+  diagnostics?: readonly CodeEditorDiagnostic[];
+  diagnosticsFor?: string;
+  diagnosticsStatus?: CodeEditorDiagnosticsStatus;
+  providers?: CodeEditorProviders;
+} & FieldIssueProps) {
+  const id = useId();
+  return (
+    <Field
+      label={label}
+      htmlFor={id}
+      {...(description !== undefined && { description })}
+      {...(required !== undefined && { required })}
+      {...(issues !== undefined && issues.length > 0 && { issues })}
+    >
+      <CodeEditor
+        id={id}
+        value={value}
+        onChange={onChange}
+        language={editor.language}
+        templates={editor.templates}
+        {...(editor.templates && { templateScanner: engineTemplateScan })}
+        font={editor.font}
+        singleLine={editor.singleLine}
+        minRows={editor.minRows}
+        maxRows={editor.maxRows}
+        lineNumbers={editor.lineNumbers}
+        expandable={editor.expandable && !readOnly ? { title: label } : false}
+        readOnly={readOnly}
+        {...(required === true && { required })}
+        issueAnchor={anchor}
+        {...(reveal !== undefined && { issueReveal: reveal })}
+        {...(diagnostics !== undefined && { diagnostics })}
+        {...(diagnosticsFor !== undefined && { diagnosticsFor })}
+        {...(diagnosticsStatus !== undefined && { diagnosticsStatus })}
+        {...(providers !== undefined && { providers })}
+        describeDiagnostics={false}
+      />
+    </Field>
+  );
+}
+
+/** Maximum repeats: a whole number from 1 to 20, or empty for the
+ *  engine's default. A value out of range is refused with the reason and
+ *  never reaches the node. */
+function MaxRepeatsField({
+  value,
+  readOnly,
+  onChange,
+  anchor = null,
+  issues,
+  reveal,
+}: {
+  value: number | undefined;
   readOnly: boolean;
-  onCommit: (parsed: unknown) => void;
+  onChange: (next: number | undefined) => void;
 } & FieldIssueProps) {
   const { t } = useT('automations');
   const id = useId();
-  const controlRef = useRef<HTMLTextAreaElement>(null);
-  // The box shows the value re-serialised as JSON, so offsets into a string
-  // inside it do not apply: a problem there focuses the box as a whole.
-  const focusTarget = useMemo(
-    () => ({
-      focus: () => {
-        const box = controlRef.current;
-        if (box === null) return;
-        box.closest('details')?.setAttribute('open', '');
-        box.focus({ preventScroll: true });
-        box.scrollIntoView({ block: 'nearest' });
-      },
-    }),
-    [],
+  const controlRef = useRef<HTMLInputElement>(null);
+  useIssueFocusTarget(
+    anchor,
+    controlRef,
+    reveal === undefined ? undefined : { reveal },
   );
-  useIssueFocusTarget(anchor, focusTarget);
-  const [text, setText] = useState(() => stringify(value));
+  const [text, setText] = useState(value === undefined ? '' : String(value));
   const [error, setError] = useState<string | null>(null);
-
-  // A different node (or a reloaded document) replaces the text outright — an
-  // edit in progress belongs to the node it was typed into.
   useEffect(() => {
-    setText(stringify(value));
-    setError(null);
+    setText((current) => {
+      const shown = current.trim() === '' ? undefined : Number(current);
+      return shown === value
+        ? current
+        : value === undefined
+          ? ''
+          : String(value);
+    });
   }, [value]);
-
   return (
     <Field
-      label={label}
+      label={t('editor.fields.maxRepeats')}
       htmlFor={id}
-      {...(description !== undefined && { description })}
+      description={t('editor.fields.maxRepeatsDescription')}
       {...(error !== null && { error })}
       {...(issues !== undefined && issues.length > 0 && { issues })}
     >
-      <Textarea
+      <Input
         ref={controlRef}
         id={id}
-        rows={rows}
+        type="number"
+        inputMode="numeric"
+        min={1}
+        max={20}
+        step={1}
+        placeholder="5"
         readOnly={readOnly}
-        className="font-mono text-xs"
         value={text}
-        {...(title !== undefined && { title })}
         onChange={(event) => {
           const next = event.target.value;
           setText(next);
           if (next.trim() === '') {
             setError(null);
-            onCommit(undefined);
+            onChange(undefined);
             return;
           }
-          try {
-            const parsed: unknown = JSON.parse(next);
-            setError(null);
-            onCommit(parsed);
-          } catch {
-            setError(t('editor.invalidJson'));
+          const parsed = Number(next);
+          if (!Number.isInteger(parsed) || parsed < 1 || parsed > 20) {
+            setError(t('editor.fields.maxRepeatsRange'));
+            return;
           }
+          setError(null);
+          onChange(parsed);
         }}
       />
     </Field>
   );
 }
 
+/** What a condition field is for, under it while it is empty. */
+const CONDITION_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  when: 'editor.fields.whenDescription',
+  forEach: 'editor.fields.forEachDescription',
+  repeatUntil: 'editor.fields.repeatUntilDescription',
+};
+
+/** The `__none__` choice of Else of: the node has no partner. */
+const ELSE_OF_NONE = '__none__';
+
+/** Else of: the node with a condition this one is the otherwise of. */
+function ElseOfField({
+  node,
+  doc,
+  readOnly,
+  onChange,
+  anchor = null,
+  issues,
+  reveal,
+}: {
+  node: NodeDef;
+  doc: Automation;
+  readOnly: boolean;
+  onChange: (next: string | undefined) => void;
+} & FieldIssueProps) {
+  const { t } = useT('automations');
+  const id = useId();
+  useIssueFocusTarget(
+    anchor,
+    {
+      focus: () => document.getElementById(id)?.focus(),
+      ...(reveal !== undefined && { reveal }),
+    },
+    reveal === undefined ? undefined : { reveal },
+  );
+  // Nodes with a condition — not this node, and not one that is already
+  // the otherwise of this one, which would make the two wait on each other.
+  const candidates = doc.nodes.filter(
+    (other) =>
+      other.id !== node.id &&
+      typeof other.when === 'string' &&
+      other.when !== '' &&
+      other.elseOf !== node.id,
+  );
+  const current = node.elseOf;
+  const options = [
+    { value: ELSE_OF_NONE, label: t('editor.fields.elseOfNone') },
+    ...candidates.map((other) => ({
+      value: other.id,
+      label: nodeTitle(other.id),
+      description: other.id,
+    })),
+    // A stored partner the list would not offer stays shown; the check
+    // says what is wrong with it.
+    ...(current !== undefined &&
+    current !== '' &&
+    !candidates.some((other) => other.id === current)
+      ? [{ value: current, label: current }]
+      : []),
+  ];
+  const explain =
+    current !== undefined && current !== ''
+      ? t('editor.explain.elseOf', { node: nodeTitle(current) })
+      : candidates.length === 0
+        ? t('editor.fields.elseOfEmpty')
+        : t('editor.fields.elseOfDescription');
+  return (
+    <div className="flex flex-col gap-1.5">
+      <SearchableSelect
+        id={id}
+        label={t('editor.fields.elseOf')}
+        description={explain}
+        error={fieldIssuesHaveError(issues)}
+        value={current === undefined || current === '' ? ELSE_OF_NONE : current}
+        options={options}
+        disabled={readOnly}
+        onValueChange={(next) => {
+          onChange(next === ELSE_OF_NONE ? undefined : next);
+        }}
+      />
+      <FieldIssueMessages issues={issues} idPrefix={`${id}-issue`} />
+    </div>
+  );
+}
+
+/** On error: stop the run, or go on without this node. */
+function OnErrorField({
+  value,
+  readOnly,
+  onChange,
+  anchor = null,
+  issues,
+  reveal,
+}: {
+  value: NodeDef['onError'];
+  readOnly: boolean;
+  onChange: (next: 'continue' | undefined) => void;
+} & FieldIssueProps) {
+  const { t } = useT('automations');
+  const id = useId();
+  const descriptionId = useId();
+  const groupRef = useRef<HTMLDivElement>(null);
+  useIssueFocusTarget(
+    anchor,
+    {
+      focus: () =>
+        groupRef.current
+          ?.querySelector<HTMLElement>('[data-state="on"], button')
+          ?.focus(),
+    },
+    reveal === undefined ? undefined : { reveal },
+  );
+  return (
+    <div ref={groupRef} className="flex flex-col gap-1.5">
+      <SegmentedControl
+        id={id}
+        label={t('editor.fields.onError')}
+        value={value === 'continue' ? 'continue' : 'fail'}
+        disabled={readOnly}
+        options={[
+          { value: 'fail', label: t('editor.fields.onErrorStop') },
+          { value: 'continue', label: t('editor.fields.onErrorContinue') },
+        ]}
+        onValueChange={(next) => {
+          onChange(next === 'continue' ? 'continue' : undefined);
+        }}
+      />
+      <p
+        id={descriptionId}
+        className="text-xs text-[color:var(--color-fg-muted)]"
+      >
+        {t('editor.fields.onErrorDescription')}
+      </p>
+      <FieldIssueMessages issues={issues} idPrefix={`${id}-issue`} />
+    </div>
+  );
+}
+
+/** The node's id, monospaced, with a button that copies it: authors and
+ *  agents reference a node by its id. */
+function NodeIdRow({ nodeId }: { nodeId: string }) {
+  const { t } = useT('automations');
+  const { t: tCommon } = useT('common');
+  const { copied, onClick } = useCopyButton(nodeId);
+  return (
+    <div className="flex min-w-0 items-center gap-1">
+      <code className="text-muted-foreground truncate font-mono text-xs">
+        {nodeId}
+      </code>
+      <IconButton
+        icon={copied ? Check : Copy}
+        size="sm"
+        iconSize={3}
+        className="size-6 shrink-0"
+        aria-label={t('editor.inspector.copyId')}
+        title={t('editor.inspector.copyId')}
+        onClick={onClick}
+      />
+      <span className="sr-only" role="status" aria-live="polite">
+        {copied ? tCommon('actions.copied') : ''}
+      </span>
+    </div>
+  );
+}
+
 export interface NodeInspectorProps {
   /** The region id the canvas's selected node button points at. */
   id: string;
@@ -266,56 +529,43 @@ export interface NodeInspectorProps {
   issues?: readonly AutomationIssueView[];
   /** The node's position in the document — its problems' pointers name it. */
   nodeIndex?: number;
+  context: InspectorContext;
+  /** The tab it opens on; a run's page opens on what the run did. */
+  defaultTab?: InspectorTab;
 }
 
-/**
- * The inspector beside the canvas, for the node picked on it.
- *
- * Clicking a box opens this panel with that node's fields; clicking the same
- * box again, Close, Escape (when not typing), or the empty canvas closes it
- * and hands the width back to the canvas — the automation's own settings
- * (trigger, projects) are its General tab. Focus moves into this panel on
- * select so Tab reaches the fields next.
- *
- * It edits the document, not a model of it: the id and type identify the node,
- * the control-flow fields are the engine's own declarative branching and
- * iteration, and the remaining fields are exactly the ones the node type
- * declares. When a run is overlaid the same panel shows what that run did here.
- */
-export function NodeInspector({
+/** The inspector's frame: a card in a page inset, or a panel flush
+ *  against the canvas. Shared by the node, Start and End inspectors. */
+function InspectorFrame({
   id,
-  node,
-  nodeType,
-  catalogUnavailable = false,
-  runView,
-  readOnly,
-  onChange,
-  organizationId,
-  projectId,
+  labelledBy,
+  focusKey,
+  variant,
   onDeselect,
-  variant = 'card',
-  issues,
-  nodeIndex,
-}: NodeInspectorProps) {
-  const headingId = useId();
+  children,
+}: {
+  id: string;
+  labelledBy: string;
+  /** A new key moves focus into the frame and scrolls it to the top. */
+  focusKey: string;
+  variant: 'card' | 'panel';
+  onDeselect?: () => void;
+  children: React.ReactNode;
+}) {
   const sectionRef = useRef<HTMLElement>(null);
-  const selectedNodeId = node.id;
-
   useDeselectOnEscape(true, onDeselect);
-
   useEffect(() => {
     const section = sectionRef.current;
     if (section === null) return;
     section.scrollTop = 0;
     section.focus({ preventScroll: true });
-  }, [selectedNodeId]);
-
+  }, [focusKey]);
   return (
     <section
       ref={sectionRef}
       id={id}
       tabIndex={-1}
-      aria-labelledby={headingId}
+      aria-labelledby={labelledBy}
       className={cn(
         'border-border flex h-full max-h-[70dvh] min-h-0 w-full flex-col gap-4 overflow-y-auto p-4 outline-none lg:max-h-none',
         variant === 'card'
@@ -324,6 +574,41 @@ export function NodeInspector({
             // stack, beside it from `lg` up.
             'bg-background border-t lg:border-t-0 lg:border-l',
       )}
+    >
+      {children}
+    </section>
+  );
+}
+
+/**
+ * The inspector beside the canvas, for the node picked on it.
+ *
+ * Clicking a box opens this panel with that node's fields; clicking the same
+ * box again, Close, Escape (when not typing), or the empty canvas closes it
+ * and hands the width back to the canvas — the automation's own settings
+ * (trigger, projects) are its General tab. Focus moves into this panel on
+ * select so Tab reaches the fields next.
+ *
+ * It edits the document, not a model of it: the id and type identify the node,
+ * the control-flow fields are the engine's own declarative branching and
+ * iteration, and the remaining fields are exactly the ones the node type
+ * declares. When a run is overlaid the same panel shows what that run did here.
+ */
+export function NodeInspector({
+  id,
+  node,
+  variant = 'card',
+  onDeselect,
+  ...rest
+}: NodeInspectorProps) {
+  const headingId = useId();
+  return (
+    <InspectorFrame
+      id={id}
+      labelledBy={headingId}
+      focusKey={node.id}
+      variant={variant}
+      {...(onDeselect !== undefined && { onDeselect })}
     >
       <NodeFields
         // Each node opens on its own fields: its disclosures start from its
@@ -331,27 +616,21 @@ export function NodeInspector({
         key={node.id}
         headingId={headingId}
         node={node}
-        nodeType={nodeType}
-        catalogUnavailable={catalogUnavailable}
-        runView={runView}
-        readOnly={readOnly}
-        onChange={onChange}
-        organizationId={organizationId}
-        {...(projectId !== undefined && { projectId })}
         {...(onDeselect !== undefined && { onDeselect })}
-        {...(issues !== undefined && { issues })}
-        {...(nodeIndex !== undefined && { nodeIndex })}
+        {...rest}
       />
-    </section>
+    </InspectorFrame>
   );
 }
 
+export type InspectorTab = 'fields' | 'shape' | 'run';
+
 export interface NodeFieldsProps {
   headingId: string;
   node: NodeDef;
   nodeType: NodeTypeSummary | undefined;
-  catalogUnavailable: boolean;
-  runView: NodeRunView | undefined;
+  catalogUnavailable?: boolean;
+  runView?: NodeRunView | undefined;
   readOnly: boolean;
   onChange: (patch: Partial<NodeDef>) => void;
   organizationId: string;
@@ -361,26 +640,116 @@ export interface NodeFieldsProps {
   issues?: readonly AutomationIssueView[];
   /** The node's position in the document — its problems' pointers name it. */
   nodeIndex?: number;
+  context: InspectorContext;
+  defaultTab?: InspectorTab;
 }
 
 const NO_ISSUE_VIEWS: readonly AutomationIssueView[] = [];
 
+/** The tab bar of an inspector: Fields, Shape (while the check can say),
+ *  Last run (while a run is laid over the canvas). */
+function useInspectorTab(
+  hasShape: boolean,
+  hasRun: boolean,
+  defaultTab: InspectorTab = 'fields',
+): [InspectorTab, (tab: InspectorTab) => void] {
+  const [tab, setTab] = useState<InspectorTab>(defaultTab);
+  const shown: InspectorTab =
+    (tab === 'shape' && !hasShape) || (tab === 'run' && !hasRun)
+      ? 'fields'
+      : tab;
+  return [shown, setTab];
+}
+
+function isInspectorTab(value: string): value is InspectorTab {
+  return value === 'fields' || value === 'shape' || value === 'run';
+}
+
+/** The three tabs, with each panel kept mounted so a half-typed field
+ *  survives a look at the shapes. */
+function InspectorTabs({
+  tab,
+  onTabChange,
+  fields,
+  shape,
+  run,
+}: {
+  tab: InspectorTab;
+  onTabChange: (tab: InspectorTab) => void;
+  fields: React.ReactNode;
+  shape?: React.ReactNode;
+  run?: React.ReactNode;
+}) {
+  const { t } = useT('automations');
+  const panel = (content: React.ReactNode) => (
+    <div className="flex flex-col gap-3 pt-3">{content}</div>
+  );
+  return (
+    <Tabs
+      variant="underline"
+      keepMounted
+      value={tab}
+      onValueChange={(next) => {
+        if (isInspectorTab(next)) onTabChange(next);
+      }}
+      listClassName="gap-3"
+      items={[
+        {
+          value: 'fields',
+          label: t('editor.inspector.tabs.fields'),
+          content: panel(fields),
+        },
+        ...(shape === undefined
+          ? []
+          : [
+              {
+                value: 'shape',
+                label: t('editor.inspector.tabs.shape'),
+                content: panel(shape),
+              },
+            ]),
+        ...(run === undefined
+          ? []
+          : [
+              {
+                value: 'run',
+                label: t('editor.inspector.tabs.run'),
+                content: panel(run),
+              },
+            ]),
+      ]}
+    />
+  );
+}
+
+/** The check's state as the code editor marks it. */
+type FieldMarks = {
+  diagnostics: readonly CodeEditorDiagnostic[];
+  diagnosticsFor: string;
+};
+
 /**
  * The node's own fields, with no outer chrome — `NodeInspector`'s `card` and
  * `panel` variants wrap this in a bordered section; the Editor tab's mobile
  * sheet (`AutomationEditor`) renders it directly inside a `ResponsiveDialog`
  * instead, since a sheet's chrome is the dialog's, not this component's.
  *
+ * The header names the node, says what kind it is and gives its id to
+ * copy; "When it runs" says how often it runs and what happens when it
+ * fails. Then three tabs: the fields, the shapes the check worked out,
+ * and what the overlaid run did here.
+ *
  * Problems the editor's check found show where they are fixed: under the
- * field's control, or — for a part of the node without a box of its own (a
- * model picker, an unknown field, the node as a whole) — in a list at the
- * top. Each control registers where "go to" a problem lands.
+ * field's control and at their characters in a code field, or — for a part
+ * of the node without a box of its own (a model picker, an unknown field,
+ * the node as a whole) — in a list at the top. Each control registers where
+ * "go to" a problem lands.
  */
 export function NodeFields({
   headingId,
   node,
   nodeType,
-  catalogUnavailable,
+  catalogUnavailable = false,
   runView,
   readOnly,
   onChange,
@@ -389,30 +758,43 @@ export function NodeFields({
   onDeselect,
   issues = NO_ISSUE_VIEWS,
   nodeIndex,
+  context,
+  defaultTab,
 }: NodeFieldsProps) {
   const { t } = useT('automations');
   const { t: tCommon } = useT('common');
+  const { locale } = useLocale();
   const isAgent = node.type === 'agent';
-  const isLlm = node.type === 'llm';
   const declaredFields = declaredInspectorFields(
     node,
     nodeType?.allowedFields ?? [],
   );
+  const controlFlowFields = shownControlFlowFields(node);
   const required = new Set(nodeType?.requiredFields ?? []);
-  const issuesByField = useMemo(() => {
-    const byField = new Map<string, FieldIssue[]>();
+  const fieldViews = useMemo(() => {
+    const byField = new Map<string, AutomationIssueView[]>();
     for (const view of issues) {
       if (view.navigation.kind !== 'field') continue;
       const list = byField.get(view.navigation.field) ?? [];
-      list.push({
-        id: view.issue.id,
-        severity: view.issue.level,
-        message: fieldIssueMessage(view, t),
-      });
+      list.push(view);
       byField.set(view.navigation.field, list);
     }
     return byField;
-  }, [issues, t]);
+  }, [issues]);
+  const issuesByField = useMemo(() => {
+    const byField = new Map<string, FieldIssue[]>();
+    for (const [field, views] of fieldViews) {
+      byField.set(
+        field,
+        views.map((view) => ({
+          id: view.issue.id,
+          severity: view.issue.level,
+          message: fieldIssueMessage(view, t),
+        })),
+      );
+    }
+    return byField;
+  }, [fieldViews, t]);
   const nodeIssues = useMemo(
     () =>
       issues.flatMap((view) =>
@@ -420,10 +802,27 @@ export function NodeFields({
       ),
     [issues],
   );
-  const hasControlFlow = CONTROL_FLOW_FIELDS.some(
+  const hasControlFlow = controlFlowFields.some(
     (field) =>
-      (node[field] ?? '') !== '' || (issuesByField.get(field)?.length ?? 0) > 0,
+      readNodeField(node, field) !== undefined ||
+      (issuesByField.get(field)?.length ?? 0) > 0,
+  );
+  const [tab, setTab] = useInspectorTab(
+    context.shapeStatus !== 'off',
+    runView !== undefined,
+    defaultTab,
   );
+  const controlFlowRef = useRef<HTMLDetailsElement>(null);
+  /** Opens the tab and the disclosure a field sits in. */
+  const revealOf = (field: string) => () => {
+    setTab('fields');
+    if (
+      (controlFlowFields as readonly string[]).includes(field) &&
+      controlFlowRef.current !== null
+    ) {
+      controlFlowRef.current.open = true;
+    }
+  };
   /** Where "go to" lands for a problem in `field` (or inside it). */
   const anchorOf = (field: string): string | null =>
     nodeIndex === undefined ? null : ptr('nodes', nodeIndex, field);
@@ -436,149 +835,287 @@ export function NodeFields({
   );
   const nodeIssuesTitleId = useId();
 
-  return (
-    <div className="flex flex-col gap-3">
-      <SectionHeader
-        as="h3"
-        size="sm"
-        title={
-          <span
-            ref={headingRef}
-            id={headingId}
-            tabIndex={-1}
-            className="focus-visible:ring-ring block truncate rounded-sm outline-none focus-visible:ring-2"
-          >
-            {node.id}
-          </span>
-        }
-        {...(nodeType === undefined && {
-          description: t('editor.unknownType', { type: node.type }),
-        })}
-        action={
-          <span className="flex items-center gap-1">
-            <Badge
-              variant="slate"
-              {...(nodeType?.description !== undefined && {
-                title: nodeType.description,
-              })}
-            >
-              {node.type}
-            </Badge>
-            {onDeselect !== undefined && (
-              <IconButton
-                icon={X}
-                size="sm"
-                aria-label={tCommon('aria.close')}
-                onClick={onDeselect}
-              />
-            )}
-          </span>
-        }
-      />
+  const { doc, types, settled, catalog } = context;
+  const faceContext = useMemo(
+    () => ({
+      t,
+      locale,
+      catalog,
+      ...(context.modelLabel !== undefined && {
+        modelLabel: context.modelLabel,
+      }),
+      returns: { status: 'off' as const, outputs: null },
+    }),
+    [t, locale, catalog, context.modelLabel],
+  );
+  const face = nodeFace(node, faceContext);
+  const conditionContext = useMemo(
+    () => ({ t, locale, nodeLabel: nodeTitle }),
+    [t, locale],
+  );
+  const readers = useMemo(
+    () =>
+      deriveEdges(doc.nodes)
+        .filter((edge) => edge.kind === 'data' && edge.source === node.id)
+        .map((edge) => edge.target),
+    [doc.nodes, node.id],
+  );
+  const readByOutput = useMemo(
+    () => outputReaders(doc).includes(node.id),
+    [doc, node.id],
+  );
 
-      {catalogUnavailable && (
-        <Alert
-          variant="warning"
-          icon={AlertTriangle}
-          description={t('editor.catalogUnavailable')}
-        />
-      )}
+  /** One field's problems as marks at their characters. */
+  const marksOf = (field: string, kind: FieldTextKind): FieldMarks => {
+    const value = settledField(settled, nodeIndex, node, field);
+    const text =
+      kind === 'string'
+        ? typeof value === 'string'
+          ? value
+          : ''
+        : jsonFieldText(value);
+    const views = fieldViews.get(field) ?? [];
+    return {
+      diagnostics:
+        nodeIndex === undefined || views.length === 0
+          ? []
+          : fieldDiagnostics({
+              views,
+              fieldPointer: ptr('nodes', nodeIndex, field),
+              text,
+              kind,
+              t,
+            }),
+      diagnosticsFor: text,
+    };
+  };
+  const providersOf = (
+    source: Parameters<typeof automationProviders>[0]['field'],
+  ): CodeEditorProviders =>
+    automationProviders({
+      doc,
+      node,
+      field: source,
+      types,
+      ...(context.sampleOf !== undefined && { sampleOf: context.sampleOf }),
+    });
 
-      {nodeIssues.length > 0 && (
-        <Card padding="none">
-          {/* Under the inspector's own h3, at the size of the rows it heads. */}
-          <h4
-            id={nodeIssuesTitleId}
-            className="text-foreground px-3 pt-3 text-sm font-medium"
-          >
-            {t('problems.nodeTitle')}
-          </h4>
-          <IssueList
-            issues={nodeIssues}
-            density="compact"
-            aria-labelledby={nodeIssuesTitleId}
-          />
-        </Card>
-      )}
+  /** The live sentence under a condition, or its static description. */
+  const explainOf = (field: string, value: string): string | undefined => {
+    const descriptionKey = CONDITION_DESCRIPTIONS[field];
+    const staticDescription =
+      descriptionKey === undefined ? undefined : t(descriptionKey);
+    if (value.trim() === '') return staticDescription;
+    switch (field) {
+      case 'when': {
+        const condition = conditionText(value, conditionContext);
+        return condition === null
+          ? t('editor.explain.whenRaw')
+          : t('editor.explain.when', { condition });
+      }
+      case 'repeatUntil': {
+        const condition = conditionText(value, conditionContext);
+        return condition === null
+          ? staticDescription
+          : t('editor.explain.repeatUntil', {
+              condition,
+              max: node.maxRepeats ?? 5,
+            });
+      }
+      case 'forEach': {
+        const list = describeList(value);
+        return list === null
+          ? staticDescription
+          : t('editor.explain.forEach', {
+              list: renderOperand(list, conditionContext),
+            });
+      }
+      default:
+        return staticDescription;
+    }
+  };
 
-      {declaredFields.map((fieldName) => {
-        const control = FIELD_CONTROL[fieldName] ?? 'text';
-        const label = t(`editor.fields.${fieldName}`, {
-          defaultValue: fieldName,
-        });
-        if (control === 'json') {
-          const value = readNodeField(node, fieldName);
-          const field = (
-            <JsonField
-              key={fieldName}
-              label={label}
-              value={value}
-              anchor={anchorOf(fieldName)}
-              issues={issuesByField.get(fieldName)}
-              readOnly={readOnly}
-              onCommit={(parsed) => {
-                onChange({
-                  [fieldName]:
-                    parsed !== null && typeof parsed === 'object'
-                      ? parsed
-                      : undefined,
-                });
-              }}
-            />
-          );
-          // Unused optional JSON (staged files, output schema) is a disclosure
-          // so an empty box does not sit between the prompt and the model.
-          if (
-            (fieldName === 'files' || fieldName === 'outputSchema') &&
-            (value === undefined || value === '')
-          ) {
-            return (
-              <CollapsibleDetails
-                key={fieldName}
-                summary={label}
-                variant="compact"
-              >
-                <div className="mt-3">{field}</div>
-              </CollapsibleDetails>
-            );
-          }
-          return field;
-        }
-        const raw = readNodeField(node, fieldName);
-        if (isLlm && fieldName === 'model') {
-          // The models the organization serves, not a free box — the run
-          // would refuse anything else, and only at the first live run.
+  const renderField = (fieldName: string) => {
+    const value = readNodeField(node, fieldName);
+    const editor = fieldEditor(node, fieldName, value);
+    const label = t(`editor.fields.${fieldName}`, { defaultValue: fieldName });
+    const anchor = anchorOf(fieldName);
+    const issueLines = issuesByField.get(fieldName);
+    const reveal = revealOf(fieldName);
+    const isControlFlow = (controlFlowFields as readonly string[]).includes(
+      fieldName,
+    );
+    switch (editor.kind) {
+      case 'code': {
+        const text = typeof value === 'string' ? value : '';
+        const marks = marksOf(fieldName, 'string');
+        const description = isControlFlow
+          ? explainOf(fieldName, text)
+          : undefined;
+        return (
+          <CodeField
+            key={fieldName}
+            label={label}
+            {...(description !== undefined && { description })}
+            {...(required.has(fieldName) && { required: true })}
+            editor={editor}
+            value={text}
+            readOnly={readOnly}
+            onChange={(next) => {
+              onChange({
+                [fieldName]: isControlFlow && next === '' ? undefined : next,
+              });
+            }}
+            anchor={anchor}
+            issues={issueLines}
+            reveal={reveal}
+            diagnostics={marks.diagnostics}
+            diagnosticsFor={marks.diagnosticsFor}
+            diagnosticsStatus={context.diagnosticsStatus}
+            providers={providersOf(editor.source)}
+          />
+        );
+      }
+      case 'json': {
+        const marks = marksOf(fieldName, 'json');
+        const field = (
+          <JsonCodeField
+            key={fieldName}
+            label={label}
+            {...(fieldName === 'input' && {
+              description: t('editor.fields.inputDescription'),
+            })}
+            value={value}
+            expect={editor.expect}
+            templates={editor.source !== null}
+            {...(editor.source !== null && {
+              templateScanner: engineTemplateScan,
+              providers: providersOf(editor.source),
+            })}
+            onCommit={(next) => {
+              onChange({ [fieldName]: next });
+            }}
+            anchor={anchor}
+            issueReveal={reveal}
+            issues={issueLines}
+            diagnostics={marks.diagnostics}
+            diagnosticsFor={marks.diagnosticsFor}
+            diagnosticsStatus={context.diagnosticsStatus}
+            readOnly={readOnly}
+            minRows={editor.minRows}
+            maxRows={editor.maxRows}
+          />
+        );
+        // Unused optional JSON (staged files, output schema) is a disclosure
+        // so an empty box does not sit between the prompt and the model.
+        if (
+          (fieldName === 'files' || fieldName === 'outputSchema') &&
+          value === undefined
+        ) {
           return (
-            <LlmModelField
+            <CollapsibleDetails
               key={fieldName}
-              organizationId={organizationId}
-              model={typeof raw === 'string' ? raw : ''}
-              required={required.has(fieldName)}
-              readOnly={readOnly}
-              onChange={(next) => {
-                onChange({ model: next });
-              }}
-            />
+              summary={label}
+              variant="compact"
+              defaultOpen={(issueLines?.length ?? 0) > 0}
+            >
+              <div className="mt-3">{field}</div>
+            </CollapsibleDetails>
           );
         }
+        return field;
+      }
+      case 'readonlyJson': {
+        return (
+          <ReadOnlyJsonField
+            key={fieldName}
+            label={label}
+            value={value}
+            anchor={anchor}
+            reveal={reveal}
+          />
+        );
+      }
+      case 'model':
+        // The models the organization serves, not a free box — the run
+        // would refuse anything else, and only at the first live run.
+        return (
+          <LlmModelField
+            key={fieldName}
+            organizationId={organizationId}
+            model={typeof value === 'string' ? value : ''}
+            required={required.has(fieldName)}
+            readOnly={readOnly}
+            onChange={(next) => {
+              onChange({ model: next });
+            }}
+          />
+        );
+      case 'maxRepeats':
+        return (
+          <MaxRepeatsField
+            key={fieldName}
+            value={typeof value === 'number' ? value : undefined}
+            readOnly={readOnly}
+            onChange={(next) => {
+              onChange({ maxRepeats: next });
+            }}
+            anchor={anchor}
+            issues={issueLines}
+            reveal={reveal}
+          />
+        );
+      case 'elseOf':
+        return (
+          <ElseOfField
+            key={fieldName}
+            node={node}
+            doc={doc}
+            readOnly={readOnly}
+            onChange={(next) => {
+              onChange({ elseOf: next });
+            }}
+            anchor={anchor}
+            issues={issueLines}
+            reveal={reveal}
+          />
+        );
+      case 'onError':
+        return (
+          <OnErrorField
+            key={fieldName}
+            value={node.onError}
+            readOnly={readOnly}
+            onChange={(next) => {
+              onChange({ onError: next });
+            }}
+            anchor={anchor}
+            issues={issueLines}
+            reveal={reveal}
+          />
+        );
+      default:
         return (
           <TextField
             key={fieldName}
             label={label}
             required={required.has(fieldName)}
-            multiline={control === 'multiline'}
-            monospace={fieldName === 'code'}
-            rows={fieldName === 'code' ? 6 : 3}
-            value={typeof raw === 'string' ? raw : ''}
-            anchor={anchorOf(fieldName)}
-            issues={issuesByField.get(fieldName)}
+            value={typeof value === 'string' ? value : ''}
+            anchor={anchor}
+            issues={issueLines}
+            reveal={reveal}
             readOnly={readOnly}
             onChange={(next) => {
               onChange({ [fieldName]: next });
             }}
           />
         );
-      })}
+    }
+  };
+
+  const fields = (
+    <>
+      {declaredFields.map(renderField)}
 
       {isAgent && (
         <AgentNodeFields
@@ -590,25 +1127,10 @@ export function NodeFields({
         />
       )}
 
-      <JsonField
-        label={t('editor.fields.input')}
-        title={t('editor.fields.inputDescription')}
-        value={node.input}
-        anchor={anchorOf('input')}
-        issues={issuesByField.get('input')}
-        readOnly={readOnly}
-        onCommit={(parsed) => {
-          onChange({
-            input:
-              parsed !== null && typeof parsed === 'object'
-                ? // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an input mapping is a JSON object by the document grammar
-                  (parsed as Record<string, unknown>)
-                : undefined,
-          });
-        }}
-      />
+      {renderField('input')}
 
       <CollapsibleDetails
+        ref={controlFlowRef}
         summary={t('editor.controlFlowTitle')}
         // Set control flow is part of what the node does, so it opens on it
         // — as it does on a problem in it; unused, it stays folded under the
@@ -616,27 +1138,148 @@ export function NodeFields({
         defaultOpen={hasControlFlow}
       >
         <div className="mt-3 flex flex-col gap-3">
-          {CONTROL_FLOW_FIELDS.map((fieldName) => (
-            <TextField
-              key={fieldName}
-              label={t(`editor.fields.${fieldName}`)}
-              value={node[fieldName] ?? ''}
-              anchor={anchorOf(fieldName)}
-              issues={issuesByField.get(fieldName)}
-              readOnly={readOnly}
-              onChange={(next) => {
-                onChange({ [fieldName]: next === '' ? undefined : next });
-              }}
-            />
-          ))}
+          {controlFlowFields.map(renderField)}
         </div>
       </CollapsibleDetails>
+    </>
+  );
 
-      {runView && (
-        <div className="border-border border-t pt-4">
-          <RunStepDetail runView={runView} heading={t('editor.runTitle')} />
-        </div>
+  const shapeStatus = context.shapeStatus;
+  const connector =
+    nodeType?.connector === undefined
+      ? undefined
+      : connectorName(nodeType.connector, catalog, locale);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-col gap-1">
+        <SectionHeader
+          as="h3"
+          size="sm"
+          title={
+            <span
+              ref={headingRef}
+              id={headingId}
+              tabIndex={-1}
+              className="focus-visible:ring-ring block truncate rounded-sm outline-none focus-visible:ring-2"
+            >
+              {nodeTitle(node.id)}
+            </span>
+          }
+          description={
+            nodeType === undefined
+              ? t('editor.unknownType', { type: node.type })
+              : catalogLabel(node, faceContext)
+          }
+          {...(onDeselect !== undefined && {
+            action: (
+              <IconButton
+                icon={X}
+                size="sm"
+                aria-label={tCommon('aria.close')}
+                onClick={onDeselect}
+              />
+            ),
+          })}
+        />
+        <NodeIdRow nodeId={node.id} />
+      </div>
+
+      {catalogUnavailable && (
+        <Alert
+          variant="warning"
+          icon={AlertTriangle}
+          description={t('editor.catalogUnavailable')}
+        />
+      )}
+
+      {nodeIssues.length > 0 && (
+        <Card padding="none">
+          {/* Under the inspector's own h3, at the size of the rows it heads. */}
+          <h4
+            id={nodeIssuesTitleId}
+            className="text-foreground px-3 pt-3 text-sm font-medium"
+          >
+            {t('problems.nodeTitle')}
+          </h4>
+          <IssueList
+            issues={nodeIssues}
+            density="compact"
+            aria-labelledby={nodeIssuesTitleId}
+          />
+        </Card>
       )}
+
+      <NodeFlowSummary
+        node={node}
+        flow={context.flow}
+        {...(context.analysis !== null &&
+          Object.hasOwn(context.analysis.nodes, node.id) && {
+            failureReasons: context.analysis.nodes[node.id]?.failureReasons,
+          })}
+        readerCount={readers.length}
+        marks={face.markers.flatMap((marker) =>
+          marker.id === 'unpinnedModel' ? [] : [marker.label],
+        )}
+      />
+
+      <InspectorTabs
+        tab={tab}
+        onTabChange={setTab}
+        fields={fields}
+        {...(shapeStatus !== 'off' && {
+          shape: (
+            <NodeShapePanel
+              node={node}
+              types={types}
+              status={shapeStatus}
+              words={{
+                ...(connector !== undefined && { connector }),
+                type: coreTypeWord(node.type, t),
+              }}
+              readers={readers}
+              readByOutput={readByOutput}
+              {...(context.onSelect !== undefined && {
+                onSelect: context.onSelect,
+              })}
+              endId={END_ID}
+            />
+          ),
+        })}
+        {...(runView !== undefined && {
+          run: <RunStepDetail runView={runView} />,
+        })}
+      />
     </div>
   );
 }
+
+/** A value of a field this build has no control for, shown as JSON: it
+ *  stays in the document as it is. */
+function ReadOnlyJsonField({
+  label,
+  value,
+  anchor,
+  reveal,
+}: {
+  label: string;
+  value: unknown;
+  anchor: string | null;
+  reveal: () => void;
+}) {
+  const id = useId();
+  return (
+    <Field label={label} htmlFor={id}>
+      <CodeEditor
+        id={id}
+        value={jsonFieldText(value)}
+        language="json"
+        readOnly
+        minRows={1}
+        maxRows={8}
+        issueAnchor={anchor}
+        issueReveal={reveal}
+      />
+    </Field>
+  );
+}
diff --git a/services/platform/app/features/automations/components/node-shape-panel.test.tsx b/services/platform/app/features/automations/components/node-shape-panel.test.tsx
new file mode 100644
index 0000000000..eccf3d8273
--- /dev/null
+++ b/services/platform/app/features/automations/components/node-shape-panel.test.tsx
@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { NodeDef } from '@/lib/engine/core/types';
+import type {
+  TypesView,
+  WireShape,
+} from '@/lib/shared/schemas/automation-issues';
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen, within } from '@/tests/utils/render';
+
+import { NodeShapePanel, type ShapeStatus } from './node-shape-panel';
+
+const issues: WireShape = {
+  type: 'object',
+  properties: {
+    issues: { type: 'array', items: { type: 'object' } },
+    total: { type: 'number' },
+  },
+  required: ['issues'],
+};
+
+function typesWith(node: string, output: WireShape, extra = {}): TypesView {
+  return {
+    inputs: {},
+    nodes: { [node]: { output, ...extra } },
+    output: {},
+  };
+}
+
+function panel(
+  node: NodeDef,
+  types: TypesView | null,
+  {
+    status = 'ready',
+    readers = [],
+    readByOutput = false,
+    onSelect = vi.fn(),
+  }: {
+    status?: ShapeStatus;
+    readers?: string[];
+    readByOutput?: boolean;
+    onSelect?: (id: string) => void;
+  } = {},
+) {
+  return render(
+    <NodeShapePanel
+      node={node}
+      types={types}
+      status={status}
+      words={{ connector: 'GitHub', type: 'Language model' }}
+      readers={readers}
+      readByOutput={readByOutput}
+      onSelect={onSelect}
+      endId="__end"
+    />,
+  );
+}
+
+describe('NodeShapePanel', () => {
+  const fetch = { id: 'fetch', type: 'github.list_issues' };
+
+  it('shows what a node returns, with where the shape comes from', () => {
+    panel(fetch, typesWith('fetch', { ...issues, 'x-origin': 'signature' }));
+    const returns = screen.getByRole('region', { name: 'Returns' });
+    expect(within(returns).getByText('As GitHub describes it')).toBeVisible();
+    expect(within(returns).getByText('issues')).toBeVisible();
+    expect(within(returns).getByText('total')).toBeVisible();
+    expect(within(returns).getByText('Show as TypeScript')).toBeVisible();
+  });
+
+  it.each([
+    ['declared', 'From its output schema'],
+    ['inferred', 'Worked out from its code'],
+    ['fixed', 'Every node of this type (Language model) returns this'],
+  ] as const)('names the %s origin', (origin, words) => {
+    panel(fetch, typesWith('fetch', { ...issues, 'x-origin': origin }));
+    expect(screen.getByText(words)).toBeVisible();
+  });
+
+  it('names the automation a subautomation returns from', () => {
+    panel(
+      { id: 'child', type: 'subautomation', automation: 'support/triage_mail' },
+      typesWith('child', { ...issues, 'x-origin': 'child' }),
+    );
+    expect(screen.getByText('What Triage mail returns')).toBeVisible();
+  });
+
+  it('says when nothing tells what a node returns', () => {
+    panel(fetch, typesWith('fetch', {}));
+    expect(
+      screen.getByText(
+        "Tale can't tell what this returns. A test run shows the real data.",
+      ),
+    ).toBeVisible();
+  });
+
+  it('shows what transform code reads as input, and each item under For each', () => {
+    panel(
+      { id: 'score', type: 'transform', forEach: '{{ nodes.fetch.output }}' },
+      typesWith('score', issues, {
+        input: { type: 'object', properties: { text: { type: 'string' } } },
+        item: { type: 'object', properties: { title: { type: 'string' } } },
+      }),
+    );
+    expect(
+      screen.getByRole('region', { name: 'What its code reads as input' }),
+    ).toBeVisible();
+    expect(screen.getByRole('region', { name: 'Each item' })).toBeVisible();
+  });
+
+  it('selects a reader, or End for the output', async () => {
+    const onSelect = vi.fn();
+    const { user } = panel(fetch, typesWith('fetch', issues), {
+      readers: ['open_issues'],
+      readByOutput: true,
+      onSelect,
+    });
+    await user.click(screen.getByRole('button', { name: 'Open issues' }));
+    expect(onSelect).toHaveBeenLastCalledWith('open_issues');
+    await user.click(
+      screen.getByRole('button', { name: 'The automation output' }),
+    );
+    expect(onSelect).toHaveBeenLastCalledWith('__end');
+  });
+
+  it('says when nothing reads the output', () => {
+    panel(fetch, typesWith('fetch', issues));
+    expect(screen.getByText('Nothing reads its output.')).toBeVisible();
+  });
+
+  it('keeps the last shapes while a check runs, and says so', () => {
+    const { container } = panel(fetch, typesWith('fetch', issues), {
+      status: 'checking',
+    });
+    expect(screen.getByRole('status')).toHaveTextContent('Updating…');
+    expect(container.firstElementChild).toHaveAttribute('aria-busy', 'true');
+    expect(screen.getByText('issues')).toBeVisible();
+  });
+
+  it('says the shapes could not be worked out when the check failed', () => {
+    panel(fetch, null, { status: 'failed' });
+    expect(
+      screen.getByText(
+        "Couldn't work out the shapes. They appear after the next successful check.",
+      ),
+    ).toBeVisible();
+  });
+
+  it('passes an axe audit', async () => {
+    const { container } = panel(fetch, typesWith('fetch', issues), {
+      readers: ['open_issues'],
+    });
+    await checkAccessibility(container);
+  });
+});
diff --git a/services/platform/app/features/automations/components/node-shape-panel.tsx b/services/platform/app/features/automations/components/node-shape-panel.tsx
new file mode 100644
index 0000000000..aa274db0ed
--- /dev/null
+++ b/services/platform/app/features/automations/components/node-shape-panel.tsx
@@ -0,0 +1,209 @@
+'use client';
+
+import { Button } from '@tale/ui/button';
+import { cn } from '@tale/ui/cn';
+import { SchemaTree } from '@tale/ui/schema-tree';
+import { useId, type ReactNode } from 'react';
+
+import type { NodeDef } from '@/lib/engine/core/types';
+import { isUnknown, toTs } from '@/lib/engine/core/typing/shape';
+import { useT } from '@/lib/i18n/client';
+import type {
+  TypesView,
+  WireShape,
+} from '@/lib/shared/schemas/automation-issues';
+
+import { nodeTitle } from '../lib/node-face';
+
+/** Where the check stands: shapes on screen may be from the last answer. */
+export type ShapeStatus = 'pending' | 'checking' | 'ready' | 'failed';
+
+/** A shape with its TypeScript behind "Show as TypeScript". */
+function ShapeBlock({
+  title,
+  shape,
+  children,
+}: {
+  title: string;
+  shape: WireShape;
+  /** A line between the title and the fields: where the shape comes from. */
+  children?: ReactNode;
+}) {
+  const titleId = useId();
+  return (
+    <section aria-labelledby={titleId} className="flex flex-col gap-1.5">
+      <h4 id={titleId} className="text-foreground text-sm font-medium">
+        {title}
+      </h4>
+      {children}
+      <SchemaTree
+        schema={shape}
+        density="comfortable"
+        aria-label={title}
+        {...(!isUnknown(shape) && { typeScript: toTs(shape) })}
+      />
+    </section>
+  );
+}
+
+/** The words for where a node's output shape comes from. */
+function originText(
+  node: NodeDef,
+  shape: WireShape,
+  t: ReturnType<typeof useT>['t'],
+  words: { connector?: string; type: string },
+): string {
+  if (isUnknown(shape)) return t('editor.shape.origin.unknown');
+  switch (shape['x-origin']) {
+    case 'declared':
+      return t('editor.shape.origin.declared');
+    case 'signature':
+      return t('editor.shape.origin.signature', {
+        connector: words.connector ?? node.type,
+      });
+    case 'fixed':
+      return t('editor.shape.origin.fixed', { type: words.type });
+    case 'child':
+      return t('editor.shape.origin.child', {
+        automation:
+          typeof node.automation === 'string'
+            ? nodeTitle(node.automation.split('/').at(-1) ?? node.automation)
+            : node.type,
+      });
+    default:
+      return t('editor.shape.origin.inferred');
+  }
+}
+
+/** A line saying the shapes on screen are being brought up to date, or
+ *  could not be worked out. */
+function ShapeStatusLine({ status }: { status: ShapeStatus }) {
+  const { t } = useT('automations');
+  if (status === 'failed') {
+    return (
+      <p className="text-muted-foreground text-xs">
+        {t('editor.shape.unavailable')}
+      </p>
+    );
+  }
+  return (
+    <p className="text-muted-foreground text-xs" role="status">
+      {status === 'checking' || status === 'pending'
+        ? t('editor.shape.checking')
+        : null}
+    </p>
+  );
+}
+
+export interface NodeShapePanelProps {
+  node: NodeDef;
+  /** The draft check's shapes; null until it answered. */
+  types: TypesView | null;
+  status: ShapeStatus;
+  /** The connector's name and the node type's word, for the origin line. */
+  words: { connector?: string; type: string };
+  /** The nodes that read this node's output, in run order. */
+  readers: readonly string[];
+  /** The automation's output reads this node. */
+  readByOutput: boolean;
+  /** Selects a node, or End, on the canvas. */
+  onSelect?: (id: string) => void;
+  /** End's id on the canvas. */
+  endId: string;
+}
+
+/**
+ * The Shape tab: what a node receives (each item too, under For each),
+ * what it returns and where that shape comes from, and which nodes read
+ * it — the draft check's inferred shapes, shown as fields with their
+ * kinds and, behind a disclosure, as TypeScript.
+ */
+export function NodeShapePanel({
+  node,
+  types,
+  status,
+  words,
+  readers,
+  readByOutput,
+  onSelect,
+  endId,
+}: NodeShapePanelProps) {
+  const { t } = useT('automations');
+  const readByTitleId = useId();
+  const info =
+    types !== null && Object.hasOwn(types.nodes, node.id)
+      ? types.nodes[node.id]
+      : undefined;
+  const stale = status === 'checking' || status === 'pending';
+  return (
+    <div className="flex flex-col gap-4" {...(stale && { 'aria-busy': true })}>
+      <ShapeStatusLine status={status} />
+      <div
+        className={cn(
+          'flex flex-col gap-4 transition-opacity duration-[var(--duration-short)] motion-reduce:transition-none',
+          stale && info !== undefined && 'opacity-60',
+        )}
+      >
+        {info?.input !== undefined && (
+          <ShapeBlock
+            title={
+              node.type === 'transform'
+                ? t('editor.shape.receivesCode')
+                : t('editor.shape.receives')
+            }
+            shape={info.input}
+          />
+        )}
+        {info?.item !== undefined && typeof node.forEach === 'string' && (
+          <ShapeBlock title={t('editor.shape.item')} shape={info.item} />
+        )}
+        {info !== undefined && (
+          <ShapeBlock title={t('editor.shape.returns')} shape={info.output}>
+            <p className="text-muted-foreground text-xs">
+              {originText(node, info.output, t, words)}
+            </p>
+          </ShapeBlock>
+        )}
+      </div>
+      <section aria-labelledby={readByTitleId} className="flex flex-col gap-1">
+        <h4 id={readByTitleId} className="text-foreground text-sm font-medium">
+          {t('editor.shape.readBy')}
+        </h4>
+        {readers.length === 0 && !readByOutput ? (
+          <p className="text-muted-foreground text-xs">
+            {t('editor.shape.notRead')}
+          </p>
+        ) : (
+          <ul className="flex flex-wrap gap-1">
+            {readers.map((id) => (
+              <li key={id}>
+                <Button
+                  type="button"
+                  variant="secondary"
+                  size="sm"
+                  disabled={onSelect === undefined}
+                  onClick={() => onSelect?.(id)}
+                >
+                  {nodeTitle(id)}
+                </Button>
+              </li>
+            ))}
+            {readByOutput && (
+              <li>
+                <Button
+                  type="button"
+                  variant="secondary"
+                  size="sm"
+                  disabled={onSelect === undefined}
+                  onClick={() => onSelect?.(endId)}
+                >
+                  {t('editor.shape.readByOutput')}
+                </Button>
+              </li>
+            )}
+          </ul>
+        )}
+      </section>
+    </div>
+  );
+}
diff --git a/services/platform/app/features/automations/components/run-detail.tsx b/services/platform/app/features/automations/components/run-detail.tsx
index 22b1ff2651..ec255c4251 100644
--- a/services/platform/app/features/automations/components/run-detail.tsx
+++ b/services/platform/app/features/automations/components/run-detail.tsx
@@ -18,6 +18,7 @@ import { useCallback, useId, useMemo, useRef, useState } from 'react';
 
 import { failureDetail } from '@/app/lib/backend/adapters';
 import { readStateOf } from '@/app/lib/backend/read-state';
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
 import { useT } from '@/lib/i18n/client';
 import { automationDisplayName } from '@/lib/shared/schemas/automation_presentation';
 
@@ -57,7 +58,7 @@ import { AutomationCanvas, type CanvasRun } from './automation-canvas';
 import { EffectList } from './effect-list';
 import { IssueImportContinuation } from './issue-import-continuation';
 import { IssueImportResult } from './issue-import-result';
-import { NodeInspector } from './node-inspector';
+import { NodeInspector, type InspectorContext } from './node-inspector';
 import { approvalIdFromDetail, RunApprovalCard } from './run-approval-card';
 import { RunAskCard } from './run-ask-card';
 import { RunInDoubtCard } from './run-in-doubt-card';
@@ -234,6 +235,27 @@ function RunDetailBody({
     }
   }, []);
 
+  // What the inspector reads besides the node: no check runs on a run's
+  // page, so it opens on what the run did and has no Shape tab.
+  const inspectorContext = useMemo<InspectorContext | null>(
+    () =>
+      automation === null
+        ? null
+        : {
+            doc: automation,
+            flow: analyzeFlow(automation.nodes),
+            analysis: null,
+            types: null,
+            shapeStatus: 'off',
+            diagnosticsStatus: 'ready',
+            settled: null,
+            catalog,
+            onSelect: (id) => selectOnCanvas(id),
+            sampleOf: (nodeId) => projection.byNode.get(nodeId)?.output,
+          },
+    [automation, catalog, selectOnCanvas, projection],
+  );
+
   const runMissing = isMissingAutomationRead({
     data: runQuery.data,
     isError: runQuery.isError || runRead.unavailable,
@@ -511,7 +533,7 @@ function RunDetailBody({
             )
           )}
         </div>
-        {selectedNode !== null && (
+        {selectedNode !== null && inspectorContext !== null && (
           <NodeInspector
             id={inspectorId}
             node={selectedNode}
@@ -524,6 +546,8 @@ function RunDetailBody({
             }}
             organizationId={organizationId}
             onDeselect={deselectNode}
+            context={inspectorContext}
+            defaultTab="run"
           />
         )}
       </div>
diff --git a/services/platform/app/features/automations/components/run-step-detail.tsx b/services/platform/app/features/automations/components/run-step-detail.tsx
index 0071a85536..9f67076fff 100644
--- a/services/platform/app/features/automations/components/run-step-detail.tsx
+++ b/services/platform/app/features/automations/components/run-step-detail.tsx
@@ -27,8 +27,9 @@ export function RunStepDetail({
   badge,
 }: {
   runView: NodeRunView;
-  /** Section title; the inspector says "Run", the run dialog names the step. */
-  heading: string;
+  /** Section title: the run dialog names the step. The inspector's Last
+   *  run tab already says what this is, so it gives none. */
+  heading?: string;
   /** Extra mark beside the status — the run dialog uses it to say THIS is the
    * step the run is on, so the reader knows the detail below is live. */
   badge?: string;
@@ -37,7 +38,9 @@ export function RunStepDetail({
   return (
     <Stack gap={3}>
       <div className="flex flex-wrap items-center gap-2">
-        <SectionHeader as="h4" size="sm" title={heading} />
+        {heading !== undefined && (
+          <SectionHeader as="h4" size="sm" title={heading} />
+        )}
         <RunStatusBadge status={runView.status} />
         {badge !== undefined && (
           <Badge variant="outline" className="text-[10px]">
diff --git a/services/platform/app/features/automations/lib/flow-graph.ts b/services/platform/app/features/automations/lib/flow-graph.ts
index 6dd52d96c6..94c0a224af 100644
--- a/services/platform/app/features/automations/lib/flow-graph.ts
+++ b/services/platform/app/features/automations/lib/flow-graph.ts
@@ -187,6 +187,13 @@ function outputReadsOf(
   return { all, byField };
 }
 
+/** The nodes the document's `output` reads, in reading order: what End
+ *  returns comes from them. */
+export function outputReaders(doc: Automation): string[] {
+  const known = new Set(doc.nodes.map((node) => node.id));
+  return outputReadsOf(doc.output, known).all;
+}
+
 /** The top-level output field a source sits in: `/output/summary/…` →
  *  `summary`; the whole output → `''`. */
 function fieldOf(source: ExprSource): string {
diff --git a/services/platform/app/features/automations/lib/inspector-fields.ts b/services/platform/app/features/automations/lib/inspector-fields.ts
index 763045e2e9..8fce453f09 100644
--- a/services/platform/app/features/automations/lib/inspector-fields.ts
+++ b/services/platform/app/features/automations/lib/inspector-fields.ts
@@ -2,8 +2,13 @@
  * Which of a node's fields the inspector edits, and with what. One answer for
  * the inspector, which renders the fields, and for the Problems panel, which
  * needs to know whether a problem has a field to go to or only its node.
+ *
+ * Every field that holds code, a template or JSON is edited in the code
+ * editor, in the language the engine reads it as; the few fields with a
+ * fixed set of values get a control that offers exactly those.
  */
 
+import type { SourceField } from '@/lib/engine/core/syntax/globals';
 import type { NodeDef } from '@/lib/engine/core/types';
 
 /** The control-flow fields every node type accepts, in reading order. */
@@ -12,8 +17,12 @@ export const CONTROL_FLOW_FIELDS = [
   'elseOf',
   'forEach',
   'repeatUntil',
+  'maxRepeats',
+  'onError',
 ] as const;
 
+export type ControlFlowField = (typeof CONTROL_FLOW_FIELDS)[number];
+
 /** The agent node's own pickers (`AgentNodeFields`); the inspector's generic
  * field loop must not render them a second time. */
 const AGENT_EQUIPMENT_FIELDS: ReadonlySet<string> = new Set([
@@ -26,6 +35,132 @@ const AGENT_EQUIPMENT_FIELDS: ReadonlySet<string> = new Set([
   'secrets',
 ]);
 
+/** How one field is edited. */
+export type FieldEditor =
+  | {
+      kind: 'code';
+      language: 'javascript' | 'markdown' | 'expression' | 'template';
+      /** The expression scope the engine gives the field. */
+      source: SourceField;
+      templates: boolean;
+      font: 'mono' | 'prose';
+      singleLine: boolean;
+      minRows: number;
+      maxRows: number;
+      lineNumbers: boolean;
+      expandable: boolean;
+    }
+  | {
+      kind: 'json';
+      expect: 'object' | 'array';
+      /** Templates in its strings, read in this scope; none for a schema. */
+      source: SourceField | null;
+      minRows: number;
+      maxRows: number;
+    }
+  /** A value this build has no control for, shown as JSON. */
+  | { kind: 'readonlyJson' }
+  | { kind: 'text' }
+  /** The llm node's picker of served models. */
+  | { kind: 'model' }
+  | { kind: 'maxRepeats' }
+  | { kind: 'elseOf' }
+  | { kind: 'onError' };
+
+const CODE_DEFAULTS = {
+  kind: 'code',
+  templates: false,
+  font: 'mono',
+  singleLine: false,
+  minRows: 3,
+  maxRows: 14,
+  lineNumbers: false,
+  expandable: false,
+} as const;
+
+/** A condition is one bare expression until it holds `{{`; then it is a
+ *  template, read as the engine reads it (`conditionKind`). */
+function conditionEditor(
+  source: 'when' | 'repeatUntil' | 'forEach',
+  value: unknown,
+): FieldEditor {
+  const template =
+    source === 'forEach' || (typeof value === 'string' && value.includes('{{'));
+  return {
+    ...CODE_DEFAULTS,
+    language: template ? 'template' : 'expression',
+    source,
+    templates: template,
+    singleLine: true,
+    minRows: 1,
+    maxRows: 4,
+  };
+}
+
+/** The control for `field` of `node`, whose value is `value`. */
+export function fieldEditor(
+  node: NodeDef,
+  field: string,
+  value: unknown,
+): FieldEditor {
+  switch (field) {
+    case 'code':
+      return {
+        ...CODE_DEFAULTS,
+        language: 'javascript',
+        source: 'code',
+        minRows: 6,
+        maxRows: 20,
+        lineNumbers: true,
+        expandable: true,
+      };
+    case 'prompt':
+    case 'system':
+      return {
+        ...CODE_DEFAULTS,
+        language: 'markdown',
+        source: field,
+        templates: true,
+        font: 'prose',
+        maxRows: 12,
+        expandable: true,
+      };
+    case 'input':
+    case 'files':
+      return {
+        kind: 'json',
+        expect: 'object',
+        source: field,
+        minRows: 3,
+        maxRows: 14,
+      };
+    case 'outputSchema':
+      return {
+        kind: 'json',
+        expect: 'object',
+        source: null,
+        minRows: 3,
+        maxRows: 14,
+      };
+    case 'when':
+    case 'repeatUntil':
+    case 'forEach':
+      return conditionEditor(field, value);
+    case 'maxRepeats':
+      return { kind: 'maxRepeats' };
+    case 'elseOf':
+      return { kind: 'elseOf' };
+    case 'onError':
+      return { kind: 'onError' };
+    case 'model':
+      return node.type === 'llm' ? { kind: 'model' } : { kind: 'text' };
+    default:
+      return value === undefined || typeof value === 'string'
+        ? { kind: 'text' }
+        : { kind: 'readonlyJson' };
+  }
+}
+
 /**
  * The declared fields the inspector's generic loop renders, in the node
  * type's order: everything the type allows except its input mapping (always
@@ -42,17 +177,28 @@ export function declaredInspectorFields(
   );
 }
 
+/** The control-flow fields the inspector shows for `node`: Maximum
+ *  repeats only beside a Repeat until, or when it holds a value. */
+export function shownControlFlowFields(node: NodeDef): ControlFlowField[] {
+  return CONTROL_FLOW_FIELDS.filter(
+    (field) =>
+      field !== 'maxRepeats' ||
+      typeof node.repeatUntil === 'string' ||
+      node.maxRepeats !== undefined,
+  );
+}
+
 /**
  * The fields whose control shows a problem's message under it and can take
- * the reader there: the text and JSON boxes, the input mapping and the
- * control-flow fields. A model picker or an agent's equipment shows its
+ * the reader there: the code, text and JSON fields, the input mapping and
+ * the control-flow fields. A model picker or an agent's equipment shows its
  * problems in the node's own list at the top of the inspector instead.
  */
 export function fieldsWithIssueControl(
   node: NodeDef,
   allowedFields: readonly string[],
 ): ReadonlySet<string> {
-  const fields = new Set<string>(['input', ...CONTROL_FLOW_FIELDS]);
+  const fields = new Set<string>(['input', ...shownControlFlowFields(node)]);
   for (const field of declaredInspectorFields(node, allowedFields)) {
     // The llm node's Model is a picker of served models, not a text box.
     if (node.type === 'llm' && field === 'model') continue;
diff --git a/services/platform/app/features/automations/lib/node-face.ts b/services/platform/app/features/automations/lib/node-face.ts
index 6cf89bb620..76629129c7 100644
--- a/services/platform/app/features/automations/lib/node-face.ts
+++ b/services/platform/app/features/automations/lib/node-face.ts
@@ -131,7 +131,7 @@ function connectorParts(
 }
 
 /** A connector's name in the reader's language. */
-function connectorName(
+export function connectorName(
   slug: string,
   catalog: NodeCatalogView,
   locale: string,
@@ -153,7 +153,7 @@ export function nodeIcon(node: NodeDef, catalog: NodeCatalogView): FlowIcon {
 }
 
 /** A core type's word: "Transform", "Language model", "Agent". */
-function coreTypeWord(type: string, t: ConditionTranslate): string {
+export function coreTypeWord(type: string, t: ConditionTranslate): string {
   switch (type) {
     case 'llm':
       return t('canvas.node.catalog.llm');
diff --git a/services/platform/app/features/automations/lib/paths.ts b/services/platform/app/features/automations/lib/paths.ts
index deff493a38..19bed0a207 100644
--- a/services/platform/app/features/automations/lib/paths.ts
+++ b/services/platform/app/features/automations/lib/paths.ts
@@ -40,7 +40,7 @@ import { nodeTitle } from './node-face';
 /** What can make a node fail, as the server's check names it, in words;
  *  null for a reason a newer server names and this build has no words
  *  for. */
-function failureReasonWords(
+export function failureReasonWords(
   reason: string,
   t: ConditionTranslate,
 ): string | null {
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index a3b5b3f9c6..60b0c9c399 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -290,6 +290,49 @@ editor:
     du trotzdem.
   invalidJson: Das ist noch kein gültiges JSON, deshalb wurde die Node nicht geändert.
   fixSuggestion: 'Durch {name} ersetzen'
+  jsonMustBeObject: Das muss ein JSON-Objekt in geschweiften Klammern sein.
+  jsonMustBeList: Das muss eine JSON-Liste in eckigen Klammern sein.
+  inspector:
+    copyId: Node-ID kopieren
+    tabs:
+      fields: Felder
+      shape: Struktur
+      run: Letzter Lauf
+  flow:
+    title: Wann sie läuft
+    always: Bei jedem Lauf
+    some: 'Auf {count} von {total} Pfaden'
+    never: 'Nie: Keine Kombination von Bedingungen lässt sie laufen'
+    skipWhen: Übersprungen, wenn ihre Bedingung nicht zutrifft
+    skipElse: 'Übersprungen, wenn {node} läuft'
+    skipUpstream: 'Übersprungen, wenn {node} übersprungen wird'
+    skipError: Übersprungen, wenn sie fehlschlägt
+    failHalts: Schlägt sie fehl, stoppt der Lauf mit ihrem Fehler.
+    failContinues: '{count, plural, =0 {Schlägt sie fehl, läuft der Lauf ohne sie weiter.} one {Schlägt sie fehl, läuft der Lauf ohne sie weiter und überspringt # Node, die sie liest.} other {Schlägt sie fehl, läuft der Lauf ohne sie weiter und überspringt # Nodes, die sie lesen.}}'
+    failsWhen: 'Schlägt fehl, wenn {reasons}.'
+  explain:
+    when: 'Läuft nur, wenn {condition}. Sonst wird sie übersprungen, ebenso jede Node, die ihre Ausgabe liest.'
+    whenRaw: 'Läuft nur, wenn diese Bedingung zutrifft. Sonst wird sie übersprungen, ebenso jede Node, die ihre Ausgabe liest.'
+    forEach: 'Läuft einmal für jedes Element von {list}. Ihre Ausgabe ist die Liste der Ergebnisse.'
+    repeatUntil: 'Läuft erneut, bis {condition}, insgesamt höchstens {max}-mal.'
+    elseOf: 'Läuft nur, wenn {node} durch ihre eigene Bedingung übersprungen wird.'
+  shape:
+    receives: Erhält
+    receivesCode: Was ihr Code als input liest
+    item: Jedes Element
+    returns: Gibt zurück
+    readBy: Gelesen von
+    readByOutput: Die Ausgabe der Automatisierung
+    notRead: Nichts liest ihre Ausgabe.
+    checking: Wird aktualisiert…
+    unavailable: Die Strukturen konnten nicht ermittelt werden. Sie erscheinen nach der nächsten erfolgreichen Prüfung.
+    origin:
+      declared: Aus ihrem Ausgabeschema
+      signature: 'Wie {connector} es beschreibt'
+      inferred: Aus ihrem Code abgeleitet
+      fixed: 'Jede Node dieses Typs ({type}) gibt das zurück'
+      child: 'Was {automation} zurückgibt'
+      unknown: Tale kann nicht erkennen, was sie zurückgibt. Ein Testlauf zeigt die echten Daten.
   versionNotFound:
     title: 'Version {version} gibt es nicht'
     description: Diese Automatisierung hat keine Version mit dieser Nummer — der Link ist vielleicht veraltet oder die Nummer vertippt.
@@ -312,7 +355,6 @@ editor:
     typeUnlisted: Ein Modell eingeben, das nicht aufgeführt ist
     modelIdLabel: Modell-ID
     modelIdHint: Genau so, wie der Anbieter sie schreibt, z. B. anbieter/modellname.
-  runTitle: In diesem Lauf
   resolvedInput: Aufgelöste Eingabe
   output: Ausgabe
   fields:
@@ -345,6 +387,13 @@ editor:
     repeatUntilDescription: Diese Node wiederholen, bis der Ausdruck wahr ist.
     maxRepeats: Maximale Wiederholungen
     onError: Bei Fehler
+    onErrorStop: Lauf stoppen
+    onErrorContinue: Ohne sie weiterlaufen
+    onErrorDescription: Was passiert, wenn diese Node fehlschlägt. Läuft der Lauf weiter, wird jede Node übersprungen, die ihre Ausgabe liest.
+    maxRepeatsDescription: Höchstens so viele Durchläufe, von 1 bis 20. Leer bedeutet 5.
+    maxRepeatsRange: Gib eine ganze Zahl von 1 bis 20 ein.
+    elseOfNone: Keine
+    elseOfEmpty: Keine andere Node hat eine Bedingung.
     output: Ausgabe
     type: Typ
     id: ID
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index d08b5f8d30..5a0fab3d92 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -283,6 +283,49 @@ editor:
   catalogUnavailable: Couldn't load the node-type catalog — only built-in types are described. The node's fields are still shown.
   invalidJson: This is not valid JSON yet, so the node was not changed.
   fixSuggestion: 'Replace with {name}'
+  jsonMustBeObject: This must be a JSON object, in curly braces.
+  jsonMustBeList: This must be a JSON list, in square brackets.
+  inspector:
+    copyId: Copy node ID
+    tabs:
+      fields: Fields
+      shape: Shape
+      run: Last run
+  flow:
+    title: When it runs
+    always: On every run
+    some: 'On {count} of {total} paths'
+    never: 'Never: no combination of conditions lets it run'
+    skipWhen: Skipped when its condition is false
+    skipElse: 'Skipped when {node} runs'
+    skipUpstream: 'Skipped when {node} is skipped'
+    skipError: Skipped when it fails
+    failHalts: If it fails, the run stops with its error.
+    failContinues: '{count, plural, =0 {If it fails, the run goes on without it.} one {If it fails, the run goes on without it and skips # node that reads it.} other {If it fails, the run goes on without it and skips # nodes that read it.}}'
+    failsWhen: 'Fails when {reasons}.'
+  explain:
+    when: "Runs only if {condition}. Otherwise it's skipped, and so is every node that reads its output."
+    whenRaw: "Runs only if this condition holds. Otherwise it's skipped, and so is every node that reads its output."
+    forEach: 'Runs once for each item of {list}. Its output is the list of results.'
+    repeatUntil: 'Runs again until {condition}, at most {max} times in all.'
+    elseOf: 'Runs only when {node} is skipped by its own condition.'
+  shape:
+    receives: Receives
+    receivesCode: What its code reads as input
+    item: Each item
+    returns: Returns
+    readBy: Read by
+    readByOutput: The automation output
+    notRead: Nothing reads its output.
+    checking: Updating…
+    unavailable: "Couldn't work out the shapes. They appear after the next successful check."
+    origin:
+      declared: From its output schema
+      signature: 'As {connector} describes it'
+      inferred: Worked out from its code
+      fixed: 'Every node of this type ({type}) returns this'
+      child: 'What {automation} returns'
+      unknown: "Tale can't tell what this returns. A test run shows the real data."
   versionNotFound:
     title: "Version {version} doesn't exist"
     description: This automation has no version with that number — the link may be stale, or the number mistyped.
@@ -304,7 +347,6 @@ editor:
     typeUnlisted: Type a model that is not listed
     modelIdLabel: Model id
     modelIdHint: Exactly as the provider spells it, e.g. vendor/model-name.
-  runTitle: In this run
   resolvedInput: Resolved input
   output: Output
   fields:
@@ -335,6 +377,13 @@ editor:
     repeatUntilDescription: Re-run this node until the expression is truthy.
     maxRepeats: Maximum repeats
     onError: On error
+    onErrorStop: Stop the run
+    onErrorContinue: Continue without it
+    onErrorDescription: What happens when this node fails. Continuing skips every node that reads its output.
+    maxRepeatsDescription: At most this many passes, from 1 to 20. Empty means 5.
+    maxRepeatsRange: Enter a whole number from 1 to 20.
+    elseOfNone: None
+    elseOfEmpty: No other node has a condition.
     output: Output
     type: Type
     id: ID
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index 52541e9fc3..c29160dcac 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -289,6 +289,49 @@ editor:
     les types intégrés sont décrits. Les champs de ce nœud restent affichés.
   invalidJson: Ce n’est pas encore du JSON valide, le nœud n’a donc pas été modifié.
   fixSuggestion: 'Remplacer par {name}'
+  jsonMustBeObject: Ce doit être un objet JSON, entre accolades.
+  jsonMustBeList: Ce doit être une liste JSON, entre crochets.
+  inspector:
+    copyId: Copier l’ID du nœud
+    tabs:
+      fields: Champs
+      shape: Structure
+      run: Dernière exécution
+  flow:
+    title: Quand il s’exécute
+    always: À chaque exécution
+    some: 'Sur {count} des {total} chemins'
+    never: 'Jamais : aucune combinaison de conditions ne le permet'
+    skipWhen: Ignoré quand sa condition n’est pas remplie
+    skipElse: 'Ignoré quand {node} s’exécute'
+    skipUpstream: 'Ignoré quand {node} est ignoré'
+    skipError: Ignoré quand il échoue
+    failHalts: S’il échoue, l’exécution s’arrête avec son erreur.
+    failContinues: '{count, plural, =0 {S’il échoue, l’exécution continue sans lui.} one {S’il échoue, l’exécution continue sans lui et ignore # nœud qui le lit.} other {S’il échoue, l’exécution continue sans lui et ignore # nœuds qui le lisent.}}'
+    failsWhen: 'Échoue si {reasons}.'
+  explain:
+    when: 'S’exécute seulement si {condition}. Sinon, il est ignoré, ainsi que chaque nœud qui lit sa sortie.'
+    whenRaw: 'S’exécute seulement si cette condition est remplie. Sinon, il est ignoré, ainsi que chaque nœud qui lit sa sortie.'
+    forEach: 'S’exécute une fois pour chaque élément de {list}. Sa sortie est la liste des résultats.'
+    repeatUntil: 'S’exécute à nouveau jusqu’à ce que la condition soit remplie ({condition}), {max} fois au plus.'
+    elseOf: 'S’exécute seulement quand {node} est ignoré par sa propre condition.'
+  shape:
+    receives: Reçoit
+    receivesCode: Ce que son code lit comme input
+    item: Chaque élément
+    returns: Renvoie
+    readBy: Lu par
+    readByOutput: La sortie de l’automatisation
+    notRead: Rien ne lit sa sortie.
+    checking: Mise à jour…
+    unavailable: Impossible de déterminer les structures. Elles apparaîtront après la prochaine vérification réussie.
+    origin:
+      declared: D’après son schéma de sortie
+      signature: 'Tel que {connector} le décrit'
+      inferred: Déduit de son code
+      fixed: 'Chaque nœud de ce type ({type}) renvoie ceci'
+      child: 'Ce que renvoie {automation}'
+      unknown: Tale ne peut pas déterminer ce qu’il renvoie. Une exécution de test montre les vraies données.
   versionNotFound:
     title: 'La version {version} n’existe pas'
     description: Cette automatisation n’a aucune version portant ce numéro — le lien est peut-être périmé, ou le numéro mal saisi.
@@ -312,7 +355,6 @@ editor:
     typeUnlisted: Saisir un modèle qui n’est pas listé
     modelIdLabel: Identifiant du modèle
     modelIdHint: Exactement tel que le fournisseur l’écrit, p. ex. fournisseur/nom-du-modele.
-  runTitle: Dans cette exécution
   resolvedInput: Entrée résolue
   output: Sortie
   fields:
@@ -346,6 +388,13 @@ editor:
     repeatUntilDescription: Relancer ce nœud jusqu’à ce que l’expression soit vraie.
     maxRepeats: Répétitions maximales
     onError: En cas d’erreur
+    onErrorStop: Arrêter l’exécution
+    onErrorContinue: Continuer sans lui
+    onErrorDescription: Ce qui se passe quand ce nœud échoue. Continuer ignore chaque nœud qui lit sa sortie.
+    maxRepeatsDescription: Au plus ce nombre de passages, de 1 à 20. Vide signifie 5.
+    maxRepeatsRange: Saisis un nombre entier de 1 à 20.
+    elseOfNone: Aucun
+    elseOfEmpty: Aucun autre nœud n’a de condition.
     output: Sortie
     type: Type
     id: Identifiant
diff --git a/services/platform/tests/setup-ui.ts b/services/platform/tests/setup-ui.ts
index e93619de5d..88d79325de 100644
--- a/services/platform/tests/setup-ui.ts
+++ b/services/platform/tests/setup-ui.ts
@@ -6,6 +6,11 @@ afterEach(() => {
   cleanup();
 });
 
+// jsdom has no layout, so CodeMirror cannot be driven here: every jsdom
+// suite edits code fields through a text box with the editor's contract.
+// The real editor is proven in Chromium (`*.browser.test.tsx`).
+vi.mock('@tale/ui/code-editor', () => import('./utils/code-editor-stand-in'));
+
 // Mock ResizeObserver as a proper class constructor
 class MockResizeObserver {
   observe = vi.fn();
diff --git a/services/platform/tests/utils/code-editor-stand-in.tsx b/services/platform/tests/utils/code-editor-stand-in.tsx
new file mode 100644
index 0000000000..850acb89c6
--- /dev/null
+++ b/services/platform/tests/utils/code-editor-stand-in.tsx
@@ -0,0 +1,173 @@
+/**
+ * `@tale/ui/code-editor` as the jsdom suites see it: a plain text box with
+ * the editor's contract — the same props, the value as its own state while
+ * mounted (an external value replaces it), Field labelling through
+ * `aria-labelledby`, and "go to" a problem selecting its range, or the part
+ * of a JSON or YAML value a request names.
+ *
+ * jsdom has no layout, so CodeMirror cannot be driven there; the real
+ * editor is proven in Chromium (`*.browser.test.tsx`). What a host passes
+ * the editor — language, diagnostics, providers — is on the box as data
+ * attributes, for a suite to read.
+ */
+
+import type { CodeEditorHandle, CodeEditorProps } from '@tale/ui/code-editor';
+import {
+  locateJsonPointer,
+  locateYamlPointer,
+} from '@tale/ui/code-editor/locate';
+import { useIssueFocusTarget, type IssueFocusPart } from '@tale/ui/issue-focus';
+import {
+  forwardRef,
+  useEffect,
+  useCallback,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ForwardRefExoticComponent,
+  type RefAttributes,
+} from 'react';
+
+export type {
+  CodeEditorDiagnostic,
+  CodeEditorDiagnosticsStatus,
+  CodeEditorHandle,
+  CodeEditorProps,
+  CodeLanguage,
+} from '@tale/ui/code-editor';
+
+function partRange(
+  props: CodeEditorProps,
+  text: string,
+  part: IssueFocusPart | undefined,
+): readonly [number, number] | undefined {
+  if (part === undefined) return undefined;
+  const options = part.range === undefined ? {} : { range: part.range };
+  const located =
+    props.language === 'json'
+      ? locateJsonPointer(text, part.rest, options)
+      : props.language === 'yaml'
+        ? locateYamlPointer(text, part.rest, options)
+        : null;
+  return located === null ? undefined : [located.from, located.to];
+}
+
+const CodeEditorStandIn = forwardRef<CodeEditorHandle, CodeEditorProps>(
+  function CodeEditorStandIn(props, ref) {
+    const { value, onChange, singleLine = false } = props;
+    const [text, setText] = useState(value);
+    const shown = useRef(value);
+    useEffect(() => {
+      if (value !== shown.current) {
+        shown.current = value;
+        setText(value);
+      }
+    }, [value]);
+    const boxRef = useRef<HTMLTextAreaElement & HTMLInputElement>(null);
+
+    const latest = useRef(props);
+    useLayoutEffect(() => {
+      latest.current = props;
+    });
+    const focus = useCallback(
+      (range?: readonly [number, number], part?: IssueFocusPart): void => {
+        const box = boxRef.current;
+        if (box === null) return;
+        box.focus({ preventScroll: true });
+        const target = range ?? partRange(latest.current, box.value, part);
+        if (target !== undefined) box.setSelectionRange(target[0], target[1]);
+      },
+      [],
+    );
+    useIssueFocusTarget(
+      props.issueAnchor ?? null,
+      { focus },
+      props.issueReveal === undefined
+        ? undefined
+        : { reveal: props.issueReveal },
+    );
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: (range) => focus(range),
+        getSelection: () => {
+          const box = boxRef.current;
+          return box === null
+            ? null
+            : [box.selectionStart ?? 0, box.selectionEnd ?? 0];
+        },
+        openCompletion: () => undefined,
+        nextDiagnostic: () => undefined,
+        view: null,
+      }),
+      [focus],
+    );
+
+    const common = {
+      id: props.id,
+      'aria-label': props['aria-label'],
+      'aria-labelledby': props['aria-labelledby'],
+      'aria-describedby': props['aria-describedby'],
+      'aria-invalid': props['aria-invalid'],
+      'aria-required': props.required,
+      'aria-readonly': props.readOnly,
+      readOnly: props.readOnly === true || props.disabled === true,
+      placeholder: props.placeholder,
+      value: text,
+      className: props.className,
+      'data-code-editor': '',
+      'data-language': props.language,
+      'data-templates': props.templates === true ? '' : undefined,
+      'data-diagnostics': JSON.stringify(
+        (props.diagnostics ?? []).map((diagnostic) => ({
+          id: diagnostic.id,
+          severity: diagnostic.severity,
+          message: diagnostic.message,
+          range: diagnostic.range,
+          fixes: diagnostic.fixes?.map((fix) => fix.label),
+        })),
+      ),
+      'data-diagnostics-status': props.diagnosticsStatus,
+      onFocus: props.onFocus,
+      onBlur: props.onBlur,
+    };
+    const edit = (next: string): void => {
+      shown.current = next;
+      setText(next);
+      onChange?.(next);
+    };
+    return singleLine ? (
+      <input
+        ref={boxRef}
+        {...common}
+        onChange={(event) => edit(event.target.value.replaceAll('\n', ' '))}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') props.onSubmit?.(text);
+        }}
+      />
+    ) : (
+      <textarea
+        ref={boxRef}
+        {...common}
+        rows={props.minRows ?? 3}
+        onChange={(event) => edit(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+            props.onSubmit?.(text);
+          }
+        }}
+      />
+    );
+  },
+);
+
+export const CodeEditor: ForwardRefExoticComponent<
+  CodeEditorProps & RefAttributes<CodeEditorHandle>
+> & { fieldLabelling: 'labelledby' } = Object.assign(CodeEditorStandIn, {
+  fieldLabelling: 'labelledby' as const,
+});
+
+export function preloadCodeEditor(): void {
+  // Nothing to load: the stand-in is the whole editor.
+}
diff --git a/services/platform/vitest.config.ts b/services/platform/vitest.config.ts
index e6afb7dd5d..c1be4f7ef2 100644
--- a/services/platform/vitest.config.ts
+++ b/services/platform/vitest.config.ts
@@ -32,6 +32,21 @@ export default defineConfig({
   optimizeDeps: {
     entries: ['**/*.browser.test.{ts,tsx}'],
     include: [
+      // The code editor loads CodeMirror behind a dynamic import; found
+      // only when a test opens a code field, it would re-optimise mid-run
+      // and load a second React.
+      '@codemirror/autocomplete',
+      '@codemirror/commands',
+      '@codemirror/lang-javascript',
+      '@codemirror/lang-json',
+      '@codemirror/lang-yaml',
+      '@codemirror/language',
+      '@codemirror/search',
+      '@codemirror/state',
+      '@codemirror/view',
+      '@lezer/common',
+      '@lezer/highlight',
+      '@lezer/markdown',
       '@milkdown/kit/plugin/listener',
       '@radix-ui/react-toast',
       '@radix-ui/react-toggle-group',

From 8df00183531e9bd3f0932c326fdeb07c75d73a29 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:33:12 +0200
Subject: [PATCH 48/78] feat(platform): open Start, End and the source of an
 automation

Start and End are now boxes the reader opens like a node. Start says
what starts a run, with the way to change it in General, and edits the
run input's JSON Schema beside the tree of its fields; End says how a
run ends, each node whose failure stops it a way to that node, and
edits the output with completion and types in its templates. Both have
the Shape and Last run tabs a node has, and open from a ?node= link.

The editor gains a Source view (?view=source): the whole document as
read-only YAML with line numbers, folding and search, every problem
marked at the place it names, and Copy and Download.

Going to a problem now lands everywhere it can: the run input's schema
on Start, the output on End, and the tests, the name or the document
as a whole on its line in the Source view. Only a problem in a node
the draft no longer has still cannot be gone to.
---
 .../components/automation-editor.test.tsx     | 235 ++++++++-
 .../components/automation-editor.tsx          | 487 +++++++++++-------
 .../automation-source-view.test.tsx           | 159 ++++++
 .../components/automation-source-view.tsx     | 168 ++++++
 .../components/document-inspector-parts.tsx   | 230 +++++++++
 .../components/document-inspectors.test.tsx   | 199 +++++++
 .../automations/components/end-inspector.tsx  | 235 +++++++++
 .../automations/components/node-inspector.tsx |   6 +-
 .../components/node-shape-panel.tsx           |   4 +-
 .../components/start-inspector.tsx            | 209 ++++++++
 .../automations/lib/editor-search.test.ts     |   8 +-
 .../features/automations/lib/editor-search.ts |   7 +-
 .../features/automations/lib/flow-graph.ts    |  47 +-
 .../features/automations/lib/issues.test.ts   | 100 +++-
 .../app/features/automations/lib/issues.ts    |  90 +++-
 .../automations/lib/yaml-source.test.ts       |  89 ++++
 .../features/automations/lib/yaml-source.ts   |  49 ++
 services/platform/messages/de/automations.yml |  19 +
 services/platform/messages/en/automations.yml |  19 +
 services/platform/messages/fr/automations.yml |  19 +
 20 files changed, 2148 insertions(+), 231 deletions(-)
 create mode 100644 services/platform/app/features/automations/components/automation-source-view.test.tsx
 create mode 100644 services/platform/app/features/automations/components/automation-source-view.tsx
 create mode 100644 services/platform/app/features/automations/components/document-inspector-parts.tsx
 create mode 100644 services/platform/app/features/automations/components/document-inspectors.test.tsx
 create mode 100644 services/platform/app/features/automations/components/end-inspector.tsx
 create mode 100644 services/platform/app/features/automations/components/start-inspector.tsx
 create mode 100644 services/platform/app/features/automations/lib/yaml-source.test.ts
 create mode 100644 services/platform/app/features/automations/lib/yaml-source.ts

diff --git a/services/platform/app/features/automations/components/automation-editor.test.tsx b/services/platform/app/features/automations/components/automation-editor.test.tsx
index 5b4391a354..40dd3b3332 100644
--- a/services/platform/app/features/automations/components/automation-editor.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.test.tsx
@@ -251,6 +251,13 @@ vi.mock('../hooks/queries', async (importOriginal) => {
       ],
     }),
     useAutomationRuns: () => ({ data: runsData }),
+    // A run's own read: what Start's and End's Last run tabs show.
+    useAutomationRun: (_organizationId: string, runId?: string) => ({
+      data:
+        runId === undefined
+          ? undefined
+          : { id: runId, input: { owner: 'acme' }, output: { sent: 2 } },
+    }),
     useAutomationProjects: () => ({ data: projectsData.bound }),
     useNodeTypeCatalog: () => ({ data: undefined, isError: false }),
     useAutomationTriggers: () => ({ data: [] }),
@@ -350,6 +357,12 @@ vi.mock('./automation-canvas', () => ({
             {`select the condition of ${node.id}`}
           </button>
         ))}
+      <button type="button" onClick={() => onSelect('__start')}>
+        select Start
+      </button>
+      <button type="button" onClick={() => onSelect('__end')}>
+        select End
+      </button>
       <button type="button" onClick={() => onSelect(null)}>
         deselect
       </button>
@@ -814,6 +827,25 @@ function inspector(): HTMLElement | null {
   return id === undefined ? null : document.getElementById(id);
 }
 
+/** The open inspector; fails the test when none is. */
+function openInspector(): HTMLElement {
+  const found = inspector();
+  if (found === null) throw new Error('No inspector is open');
+  return found;
+}
+
+/** Replace a code field's whole text, as a paste over a selection does. */
+async function replaceText(
+  user: ReturnType<typeof renderPage>['user'],
+  box: HTMLElement,
+  text: string,
+): Promise<void> {
+  if (!(box instanceof HTMLTextAreaElement)) throw new Error('Not a text box');
+  await user.click(box);
+  act(() => box.setSelectionRange(0, box.value.length));
+  await user.paste(text);
+}
+
 describe('AutomationEditor', () => {
   it('never falls back into the editor when the version tab target is absent', () => {
     render(
@@ -2039,13 +2071,14 @@ describe('AutomationEditor problems', () => {
     expect(screen.queryByText(/automation failed validation/)).toBeNull();
   });
 
-  it("says why a problem outside the nodes can't be gone to", async () => {
+  it("says why a problem in a node the draft no longer has can't be gone to", async () => {
+    // The check answered for an older draft that had a second node.
     validationMock.errors = withIssueIds([
       {
         level: 'error' as const,
-        code: 'OUTPUT_MISSING',
-        message: 'the automation has no output',
-        at: { pointer: '/output', subject: 'missing' },
+        code: 'REF_UNKNOWN_NODE',
+        message: 'nodes.nope does not exist',
+        at: { pointer: '/nodes/3/prompt' },
         params: {},
       },
     ]);
@@ -2234,3 +2267,197 @@ describe('AutomationEditor canvas', () => {
     ).toBeNull();
   });
 });
+
+describe('Start, End and the Source view', () => {
+  const documentWithInputs = {
+    name: 'billing/dunning',
+    inputs: {
+      type: 'object',
+      properties: { owner: { type: 'string' } },
+      required: ['owner'],
+    },
+    nodes: [{ id: 'summary', type: 'llm', prompt: 'Hi {{ input.owner }}' }],
+    output: '{{ nodes.summary.output }}',
+    tests: [{ name: 'smoke', input: { owner: 'acme' } }],
+  };
+
+  it('opens Start, edits the run input schema and saves it with the document', async () => {
+    state.document = documentWithInputs;
+    const onSearchChange = vi.fn();
+    const { user } = renderPage({ onSearchChange });
+    await user.click(screen.getByRole('button', { name: 'select Start' }));
+    expect(onSearchChange).toHaveBeenLastCalledWith({ node: '__start' });
+    const panel = openInspector();
+    expect(within(panel).getByRole('heading', { name: 'Start' })).toBeVisible();
+    expect(
+      within(panel).getByText('Only by hand, the API or MCP — no trigger'),
+    ).toBeVisible();
+    expect(
+      within(panel).getByRole('link', { name: 'Change in General' }),
+    ).toHaveAttribute(
+      'href',
+      '/dashboard/org-1/automations/billing__dunning/general',
+    );
+    // The fields of the run input, as a tree.
+    expect(within(panel).getByText('owner')).toBeVisible();
+
+    const schema = within(panel).getByRole('textbox', { name: 'Input schema' });
+    await replaceText(user, schema, '{"type":"object"}');
+    const checked = validationMock.calls.at(-1)?.document;
+    expect(checked).toEqual({
+      ...documentWithInputs,
+      inputs: { type: 'object' },
+    });
+    await user.click(saveButton());
+    await user.click(screen.getByRole('button', { name: 'Save version' }));
+    await waitFor(() => {
+      expect(saveMutation.mutateAsync).toHaveBeenCalledTimes(1);
+    });
+    expect(saveMutation.mutateAsync.mock.calls[0]?.[0].automation).toEqual(
+      checked,
+    );
+  });
+
+  it('opens End, edits the output and goes to a node whose failure stops the run', async () => {
+    state.document = documentWithInputs;
+    const { user } = renderPage({ node: '__end' });
+    const panel = openInspector();
+    expect(within(panel).getByRole('heading', { name: 'End' })).toBeVisible();
+    expect(
+      within(panel).getByRole('list', { name: 'How a run ends' }),
+    ).toBeVisible();
+    const output = within(panel).getByRole('textbox', { name: 'Output' });
+    expect(output).toHaveValue('"{{ nodes.summary.output }}"');
+    await replaceText(user, output, '{"text":"{{ nodes.summary.output }}"}');
+    expect(validationMock.calls.at(-1)?.document).toEqual({
+      ...documentWithInputs,
+      output: { text: '{{ nodes.summary.output }}' },
+    });
+
+    await user.click(within(panel).getByRole('button', { name: 'Summary' }));
+    expect(
+      within(openInspector()).getByRole('heading', { name: 'Summary' }),
+    ).toBeVisible();
+  });
+
+  it('shows the input and the output of the run on the canvas', async () => {
+    state.document = documentWithInputs;
+    runsData.push({
+      id: 'run-1',
+      name: 'billing/dunning',
+      version: 3,
+      status: 'success',
+      mode: 'mock',
+      startedBy: 'user:a',
+      startedAt: 1_700_000_000_000,
+    });
+    const { user } = renderPage({ node: '__start' });
+    await user.click(
+      within(openInspector()).getByRole('tab', { name: 'Last run' }),
+    );
+    expect(within(openInspector()).getByTestId('json')).toHaveTextContent(
+      '{"owner":"acme"}',
+    );
+    await user.click(screen.getByRole('button', { name: 'select End' }));
+    await user.click(
+      within(openInspector()).getByRole('tab', { name: 'Last run' }),
+    );
+    expect(within(openInspector()).getByTestId('json')).toHaveTextContent(
+      '{"sent":2}',
+    );
+  });
+
+  it('goes to a problem in the run input, the output and the tests', async () => {
+    state.document = documentWithInputs;
+    validationMock.errors = withIssueIds([
+      {
+        level: 'error',
+        code: 'SCHEMA_X',
+        message: 'owner is wrong',
+        at: { pointer: '/inputs/properties/owner' },
+      },
+      {
+        level: 'error',
+        code: 'OUTPUT_X',
+        message: 'output is wrong',
+        at: { pointer: '/output' },
+      },
+      {
+        level: 'error',
+        code: 'TEST_X',
+        message: 'the test is wrong',
+        at: { pointer: '/tests/0/name' },
+      },
+    ]);
+    const onSearchChange = vi.fn();
+    const { user } = renderPage({ onSearchChange });
+    const problems = screen.getByRole('button', { name: /^Problems/ });
+    const goTo = async (location: RegExp) => {
+      if (problems.getAttribute('aria-expanded') !== 'true') {
+        await user.click(problems);
+      }
+      const dock = screen.getByRole('region', { name: 'Problems' });
+      await user.click(within(dock).getByRole('button', { name: location }));
+    };
+
+    await goTo(/Inputs › properties › owner/);
+    const schema = await within(
+      openInspector(),
+    ).findByRole<HTMLTextAreaElement>('textbox', { name: 'Input schema' });
+    await waitFor(() => expect(schema).toHaveFocus());
+    expect(schema.value.slice(schema.selectionStart, schema.selectionEnd)).toBe(
+      '{\n      "type": "string"\n    }',
+    );
+
+    await goTo(/Output/);
+    const output = await within(openInspector()).findByRole('textbox', {
+      name: 'Output',
+    });
+    await waitFor(() => expect(output).toHaveFocus());
+
+    await goTo(/Tests › 1 › name/);
+    expect(onSearchChange).toHaveBeenLastCalledWith({ view: 'source' });
+    const source = await screen.findByRole<HTMLTextAreaElement>('textbox', {
+      name: 'Source of this automation (YAML)',
+    });
+    await waitFor(() => expect(source).toHaveFocus());
+    expect(source.value.slice(source.selectionStart, source.selectionEnd)).toBe(
+      'smoke',
+    );
+    // Every problem is marked in the source, at the place it names.
+    expect(
+      JSON.parse(source.dataset.diagnostics ?? '[]').map(
+        (mark: { id: string }) => mark.id,
+      ),
+    ).toHaveLength(3);
+  });
+
+  it('shows the whole document as read-only YAML in the Source view', async () => {
+    state.document = documentWithInputs;
+    const { user } = renderPage();
+    await user.click(
+      within(screen.getByTestId('canvas-top-start')).getByRole('radio', {
+        name: 'Source',
+      }),
+    );
+    expect(screen.queryByTestId('canvas')).toBeNull();
+    const source = screen.getByRole('textbox', {
+      name: 'Source of this automation (YAML)',
+    });
+    expect(source).toHaveAttribute('aria-readonly', 'true');
+    expect(source).toHaveAttribute('data-language', 'yaml');
+    expect((source as HTMLTextAreaElement).value).toContain(
+      'tests:\n  - name: smoke',
+    );
+    expect(
+      screen.getByText(
+        'To change the document, use the fields or your coding agent.',
+      ),
+    ).toBeVisible();
+    expect(
+      screen.getByRole('button', { name: 'Edit with your coding agent' }),
+    ).toBeVisible();
+    await user.click(screen.getByRole('radio', { name: 'Canvas' }));
+    expect(screen.getByTestId('canvas')).toBeInTheDocument();
+  });
+});
diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 66db90184c..6e15d1b314 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -6,6 +6,7 @@ import { Button } from '@tale/ui/button';
 import { CatalogLoadError } from '@tale/ui/catalog/catalog-view';
 import { cn } from '@tale/ui/cn';
 import type { CodeEditorDiagnosticsStatus } from '@tale/ui/code-editor';
+import { locateYamlPointer } from '@tale/ui/code-editor/locate';
 import { ContentArea } from '@tale/ui/content-area';
 import { ConfirmDialog } from '@tale/ui/dialog/confirm-dialog';
 import { Dialog } from '@tale/ui/dialog/dialog';
@@ -81,6 +82,7 @@ import {
 import {
   useAutomation,
   useAutomationProjects,
+  useAutomationRun,
   useAutomationRuns,
   useAutomationTriggers,
   useNodeTypeCatalog,
@@ -95,8 +97,10 @@ import { automationDetailPathname } from '../lib/detail-paths';
 import { DOCUMENT_DIRTY_KEY } from '../lib/dirty-keys';
 import { readDocument } from '../lib/document';
 import {
+  applyDocumentPatch,
   applyNodePatch,
   rawDocumentOf,
+  type DocumentPatch,
   type RawDocument,
 } from '../lib/draft-document';
 import type { AutomationEditorView } from '../lib/editor-search';
@@ -108,7 +112,7 @@ import {
   isMissingAutomationRead,
   type AutomationErrorIssues,
 } from '../lib/errors';
-import { flowGraphTarget } from '../lib/flow-ids';
+import { END_ID, START_ID, flowGraphTarget } from '../lib/flow-ids';
 import { fieldsWithIssueControl } from '../lib/inspector-fields';
 import {
   issueCountsByNode,
@@ -132,6 +136,7 @@ import {
   AUTOMATION_WORKBENCH_COMPACT_QUERY,
   AUTOMATION_WORKBENCH_INSPECTOR_COLUMNS,
 } from '../lib/workbench';
+import { SOURCE_ISSUE_ANCHOR, yamlSource } from '../lib/yaml-source';
 import { AutomationCanvas, type CanvasRun } from './automation-canvas';
 import { AutomationEditorActions } from './automation-editor-actions';
 import {
@@ -143,14 +148,17 @@ import {
   AutomationRunDialog,
   type AutomationRunRequest,
 } from './automation-run-dialog';
+import { AutomationSourceView } from './automation-source-view';
 import { AutomationVersionPicker } from './automation-version-picker';
 import { CodingAgentButton } from './coding-agent-entry';
+import { EndFields, EndInspector } from './end-inspector';
 import {
   NodeFields,
   NodeInspector,
   type InspectorContext,
 } from './node-inspector';
 import type { ShapeStatus } from './node-shape-panel';
+import { StartFields, StartInspector } from './start-inspector';
 
 /** The run-scope Select's "organization-wide" choice. A Radix Select item
  * cannot carry an empty value, so the org-wide option needs a real sentinel
@@ -284,29 +292,29 @@ function AutomationEditorScope({
   // saving, deploying, triggering, and LIVE runs demand the
   // `developerSettings` ability — hiding what would only fail server-side.
   const canAuthor = ability.can('read', 'developerSettings');
-  // A `?node=` link opens its node on load. Start and End have no inspector
-  // of their own yet, so a link to them opens nothing.
-  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(() =>
-    nodeParam === undefined || flowGraphTarget(nodeParam).kind !== 'node'
+  /** The box open in the inspector: a node's id, Start or End. A `?node=`
+   * link opens its box on load. */
+  const [selectedId, setSelectedId] = useState<string | null>(() =>
+    nodeParam === undefined || flowGraphTarget(nodeParam).kind === 'gate'
       ? null
       : nodeParam,
   );
   // The open node follows into the URL (`?node=`), replacing the entry.
-  const writtenNodeRef = useRef<string | null>(selectedNodeId);
+  const writtenNodeRef = useRef<string | null>(selectedId);
   useEffect(() => {
-    if (writtenNodeRef.current === selectedNodeId) return;
-    writtenNodeRef.current = selectedNodeId;
-    onSearchChange?.({ node: selectedNodeId });
-  }, [selectedNodeId, onSearchChange]);
+    if (writtenNodeRef.current === selectedId) return;
+    writtenNodeRef.current = selectedId;
+    onSearchChange?.({ node: selectedId });
+  }, [selectedId, onSearchChange]);
   const deselectNode = useCallback(() => {
-    const id = selectedNodeId;
-    setSelectedNodeId(null);
+    const id = selectedId;
+    setSelectedId(null);
     if (id !== null) {
       queueMicrotask(() => {
         focusAutomationNode(id);
       });
     }
-  }, [selectedNodeId]);
+  }, [selectedId]);
   /** The draft: the raw document with the author's edits (see
    * `../lib/draft-document`) — what the check, a save and the Source view
    * read. The canvas and the inspector read its narrowed view. */
@@ -448,6 +456,17 @@ function AutomationEditorScope({
 
   const runs = runsQuery.data ?? [];
   const lastRun = runs[0];
+  // Start's and End's Last run tabs show the run's input and output, which
+  // only the run's own read carries: it is asked for while one is open.
+  const runDetailQuery = useAutomationRun(
+    organizationId,
+    showLastRun &&
+      lastRun !== undefined &&
+      (selectedId === START_ID || selectedId === END_ID)
+      ? lastRun.id
+      : undefined,
+  );
+  const shownRunDetail = runDetailQuery.data ?? undefined;
   const lastRunProjection = useMemo(
     () => projectRun(showLastRun ? lastRun : null),
     [showLastRun, lastRun],
@@ -599,22 +618,20 @@ function AutomationEditorScope({
   );
   const layoutKey = `${automationSlug}:${version ?? 'latest'}`;
 
-  /** A box picked on the canvas: a node opens its inspector, a condition
-   * opens its node at the condition's field. Start and End have no
-   * inspector of their own yet. */
+  /** A box picked on the canvas: a node, Start or End opens its inspector,
+   * a condition opens its node at the condition's field. */
   const selectOnCanvas = useCallback(
     (id: string | null) => {
       if (id === null) {
-        setSelectedNodeId(null);
+        setSelectedId(null);
         return;
       }
       const target = flowGraphTarget(id);
-      if (target.kind === 'node') {
-        setSelectedNodeId(target.nodeId);
+      if (target.kind !== 'gate') {
+        setSelectedId(id);
         return;
       }
-      if (target.kind !== 'gate') return;
-      setSelectedNodeId(target.nodeId);
+      setSelectedId(target.nodeId);
       const index =
         automation?.nodes.findIndex((node) => node.id === target.nodeId) ?? -1;
       if (index >= 0) requestIssueFocus(ptr('nodes', index, 'when'));
@@ -695,6 +712,7 @@ function AutomationEditorScope({
     viewChoice === 'list' || (viewChoice === undefined && narrowCanvas)
       ? ('list' as const)
       : ('chart' as const);
+  const showSource = viewChoice === 'source';
   const changeView = useCallback(
     (next: AutomationEditorView) => {
       setViewChoice(next);
@@ -748,19 +766,18 @@ function AutomationEditorScope({
     });
     const said = [t('canvas.updated', { version: shownVersion })];
     if (
-      selectedNodeId !== null &&
-      !stored.nodes.some((node) => node.id === selectedNodeId)
+      selectedId !== null &&
+      flowGraphTarget(selectedId).kind === 'node' &&
+      !stored.nodes.some((node) => node.id === selectedId)
     ) {
-      said.push(
-        t('canvas.selectionRemoved', { node: nodeTitle(selectedNodeId) }),
-      );
-      setSelectedNodeId(null);
+      said.push(t('canvas.selectionRemoved', { node: nodeTitle(selectedId) }));
+      setSelectedId(null);
     }
     setCanvasNews((previous) => ({
       text: said.join(' '),
       key: previous.key + 1,
     }));
-  }, [shownVersion, version, stored, draft, selectedNodeId, t]);
+  }, [shownVersion, version, stored, draft, selectedId, t]);
   const newerVersion =
     draft !== null &&
     version === undefined &&
@@ -771,15 +788,24 @@ function AutomationEditorScope({
       ? shownVersion
       : null;
 
-  const selectedNodeIssues = useMemo(
-    () =>
-      issueViews.filter(
-        (view) =>
-          view.navigation.kind !== 'unavailable' &&
-          view.navigation.nodeId === selectedNodeId,
-      ),
-    [issueViews, selectedNodeId],
-  );
+  /** The problems the open inspector shows: a node's, or Start's (the
+   * run input's schema), or End's (the output). */
+  const selectedIssues = useMemo(() => {
+    if (selectedId === null) return [];
+    const target = flowGraphTarget(selectedId);
+    return issueViews.filter(({ navigation }) => {
+      switch (navigation.kind) {
+        case 'start':
+        case 'end':
+          return navigation.kind === target.kind;
+        case 'field':
+        case 'node':
+          return target.kind === 'node' && navigation.nodeId === selectedId;
+        default:
+          return false;
+      }
+    });
+  }, [issueViews, selectedId]);
   const [problemsOpen, setProblemsOpen] = useState(false);
   /** Which problems the panel shows; every open and every refusal starts
    * on all of them, so no filter hides what the reader came for. */
@@ -790,8 +816,8 @@ function AutomationEditorScope({
   /** The phone's node sheet is closing onto the Problems sheet. */
   const [nodeSheetHandsOn, setNodeSheetHandsOn] = useState(false);
   useEffect(() => {
-    if (selectedNodeId !== null) setNodeSheetHandsOn(false);
-  }, [selectedNodeId]);
+    if (selectedId !== null) setNodeSheetHandsOn(false);
+  }, [selectedId]);
   /** Focus the list once the panel has opened: on its current row, or on
    * the first error when a refusal opened it. */
   const [focusProblems, setFocusProblems] = useState<
@@ -899,55 +925,91 @@ function AutomationEditorScope({
    * toolbar's button lists: close the node, open the list on its errors. */
   const showProblemsFromNode = (): void => {
     setNodeSheetHandsOn(true);
-    setSelectedNodeId(null);
+    setSelectedId(null);
     setHandingOn(false);
     setProblemsFilter('all');
     setProblemsOpen(true);
     setFocusProblems('firstError');
   };
-  /** "Go to": pick the node, then focus the field and select the text. */
+  /** "Go to": open the box (a node, Start, End) or the Source view, then
+   * focus the field and select the text. */
   const goToIssue = (item: IssueItem): void => {
     const view = issueViews.find((candidate) => candidate.issue.id === item.id);
     if (view === undefined || view.navigation.kind === 'unavailable') return;
     const { navigation } = view;
     setActiveIssueId(item.id);
     if (isWorkbenchCompact) {
-      // The node's own sheet takes over from this one.
+      // The box's own sheet, or the Source view, takes over from this one.
       setHandingOn(true);
       setProblemsOpen(false);
     }
-    setSelectedNodeId(navigation.nodeId);
-    if (navigation.kind === 'field') {
-      requestIssueFocus(navigation.anchor, navigation.range);
-    } else {
-      requestIssueFocus(ptr('nodes', navigation.nodeIndex));
+    switch (navigation.kind) {
+      case 'source': {
+        changeView('source');
+        // The range in the YAML the Source view shows: the text on screen
+        // now, so it is the one the request's offsets index into.
+        const located =
+          rawDocument === null
+            ? null
+            : locateYamlPointer(yamlSource(rawDocument), navigation.pointer, {
+                ...(navigation.range !== undefined && {
+                  range: navigation.range,
+                }),
+                ...(navigation.subject !== undefined && {
+                  subject: navigation.subject,
+                }),
+              });
+        requestIssueFocus(
+          SOURCE_ISSUE_ANCHOR,
+          located === null ? undefined : [located.from, located.to],
+        );
+        return;
+      }
+      case 'start':
+      case 'end':
+        setSelectedId(navigation.kind === 'start' ? START_ID : END_ID);
+        requestIssueFocus(navigation.anchor, navigation.range);
+        return;
+      case 'field':
+        setSelectedId(navigation.nodeId);
+        requestIssueFocus(navigation.anchor, navigation.range);
+        return;
+      default:
+        setSelectedId(navigation.nodeId);
+        requestIssueFocus(ptr('nodes', navigation.nodeIndex));
     }
   };
 
-  const onChangeNode = useCallback(
-    (patch: Partial<NodeDef>) => {
-      if (!automation || rawDocument === null || selectedNodeId === null) {
-        return;
-      }
-      // The base is pinned on the draft's FIRST edit: the detail query
-      // follows every version another tab saves (its hint invalidates the
-      // read), so reading the version at save time would name the one that
-      // overtook the draft, not the one it was built on.
+  /** The draft after one more edit. Its base is pinned on its FIRST edit:
+   * the detail query follows every version another tab saves (its hint
+   * invalidates the read), so reading the version at save time would name
+   * the one that overtook the draft, not the one it was built on. */
+  const editDraft = useCallback(
+    (edit: (raw: RawDocument) => RawDocument) => {
+      if (!automation || rawDocument === null) return;
       if (draft === null) {
         draftBaseRef.current = automationQuery.data?.version;
         setDraftBase(automationQuery.data?.version);
         setDraftOrigin(automation);
         draftEpochRef.current += 1;
       }
-      setDraft(applyNodePatch(rawDocument, selectedNodeId, patch));
+      setDraft(edit(rawDocument));
     },
-    [
-      automation,
-      rawDocument,
-      selectedNodeId,
-      draft,
-      automationQuery.data?.version,
-    ],
+    [automation, rawDocument, draft, automationQuery.data?.version],
+  );
+  const onChangeNode = useCallback(
+    (patch: Partial<NodeDef>) => {
+      if (selectedId === null) return;
+      editDraft((raw) => applyNodePatch(raw, selectedId, patch));
+    },
+    [editDraft, selectedId],
+  );
+  /** Start edits the run input's schema, End the output. */
+  const onChangeDocument = useCallback(
+    (patch: DocumentPatch) => {
+      editDraft((raw) => applyDocumentPatch(raw, patch));
+    },
+    [editDraft],
   );
 
   const isDirty = draft !== null;
@@ -1143,10 +1205,19 @@ function AutomationEditorScope({
   const lookingIsLive =
     lookingVersion !== undefined && lookingVersion === meta?.deployedVersion;
   const selectedNode =
-    automation.nodes.find((node) => node.id === selectedNodeId) ?? null;
+    automation.nodes.find((node) => node.id === selectedId) ?? null;
   const selectedNodeIndex = automation.nodes.findIndex(
-    (node) => node.id === selectedNodeId,
+    (node) => node.id === selectedId,
   );
+  /** What the inspector shows: a node, Start or End; null while closed. */
+  const inspected =
+    selectedNode !== null
+      ? ('node' as const)
+      : selectedId === START_ID
+        ? ('start' as const)
+        : selectedId === END_ID
+          ? ('end' as const)
+          : null;
   /** Append the draft as a version built on `baseVersion` (none: append
    * whatever the latest is), then show the version that landed. */
   const submitSave = async (baseVersion: number | undefined): Promise<void> => {
@@ -1439,6 +1510,73 @@ function AutomationEditorScope({
     </>
   );
 
+  /** The open box's inspector: beside the canvas in its frame (`panel`),
+   * or bare inside the phone's sheet, which has a frame of its own. */
+  const inspector = (
+    context: InspectorContext,
+    place: 'panel' | 'sheet',
+  ): React.ReactNode => {
+    const shared = {
+      readOnly: !canAuthor,
+      onDeselect: deselectNode,
+      issues: selectedIssues,
+      context,
+    };
+    if (inspected === 'start') {
+      const props = {
+        ...shared,
+        triggers: triggerRowsShown,
+        generalHref: `${automationDetailPathname({
+          organizationId,
+          automationSlug,
+          ...(projectId !== undefined && { projectId }),
+        })}/general`,
+        onChange: onChangeDocument,
+        ...(shownRunDetail !== undefined && {
+          run: { input: shownRunDetail.input },
+        }),
+      };
+      return place === 'panel' ? (
+        <StartInspector id={inspectorId} variant="panel" {...props} />
+      ) : (
+        <StartFields headingId={inspectorId} {...props} />
+      );
+    }
+    if (inspected === 'end') {
+      const props = {
+        ...shared,
+        onChange: onChangeDocument,
+        ...(shownRunDetail !== undefined && {
+          run: { output: shownRunDetail.output },
+        }),
+      };
+      return place === 'panel' ? (
+        <EndInspector id={inspectorId} variant="panel" {...props} />
+      ) : (
+        <EndFields headingId={inspectorId} {...props} />
+      );
+    }
+    if (selectedNode === null) return null;
+    const props = {
+      ...shared,
+      node: selectedNode,
+      nodeType: nodeTypes.find((def) => def.type === selectedNode.type),
+      catalogUnavailable: catalogQuery.isError,
+      runView: showLastRun
+        ? lastRunProjection.byNode.get(selectedNode.id)
+        : undefined,
+      onChange: onChangeNode,
+      organizationId,
+      ...(projectId !== undefined && { projectId }),
+      nodeIndex: selectedNodeIndex,
+    };
+    return place === 'panel' ? (
+      <NodeInspector id={inspectorId} variant="panel" {...props} />
+    ) : (
+      <NodeFields headingId={inspectorId} {...props} />
+    );
+  };
+
   const editorActions = (
     <div className="flex flex-wrap items-center justify-center gap-2 md:justify-end">
       {automationActions}
@@ -1448,15 +1586,26 @@ function AutomationEditorScope({
   const viewSwitch = (
     <SegmentedControl
       aria-label={t('canvas.view.label')}
-      value={canvasView === 'list' ? 'list' : 'canvas'}
-      onValueChange={(next) => changeView(next === 'list' ? 'list' : 'canvas')}
+      value={showSource ? 'source' : canvasView === 'list' ? 'list' : 'canvas'}
+      onValueChange={(next) =>
+        changeView(
+          next === 'source' ? 'source' : next === 'list' ? 'list' : 'canvas',
+        )
+      }
       options={[
         { value: 'canvas', label: t('canvas.view.canvas') },
         { value: 'list', label: t('canvas.view.list') },
+        { value: 'source', label: t('canvas.view.source') },
       ]}
       className="bg-background shadow-sm"
     />
   );
+  const codingAgentButton = canAuthor ? (
+    <CodingAgentButton
+      organizationId={organizationId}
+      automationSlug={automationSlug}
+    />
+  ) : null;
   const canvasToolbarActions = (
     <div className="flex flex-wrap items-center justify-center gap-2 md:justify-end">
       {automationActions}
@@ -1568,75 +1717,86 @@ function AutomationEditorScope({
         <div
           className={cn(
             AUTOMATION_EDITOR_WORKBENCH_GRID,
-            selectedNode !== null && AUTOMATION_WORKBENCH_INSPECTOR_COLUMNS,
+            inspected !== null && AUTOMATION_WORKBENCH_INSPECTOR_COLUMNS,
           )}
         >
           <div className={AUTOMATION_WORKBENCH_CANVAS_SLOT}>
-            {canvasDocument !== null && (
-              <AutomationCanvas
-                automation={canvasDocument}
-                layoutKey={layoutKey}
-                catalog={catalog}
-                modelLabel={modelLabel}
-                triggers={triggerRowsShown}
-                check={canvasCheck}
-                startNotice={startNotice}
-                issueCounts={countsByNode}
-                selectedId={selectedNodeId}
-                onSelect={selectOnCanvas}
-                revealId={selectedNodeId}
-                inspectorId={inspectorId}
-                {...(canvasRun !== undefined && { run: canvasRun })}
-                {...(canvasChange !== undefined && { changed: canvasChange })}
-                framed={false}
-                view={canvasView}
-                onViewChange={(next) =>
-                  changeView(next === 'list' ? 'list' : 'canvas')
-                }
-                topStart={viewSwitch}
-                topEnd={
-                  <>
-                    {lastRun ? (
-                      <Button
-                        variant="secondary"
-                        size="icon-sm"
-                        aria-pressed={showLastRun}
-                        title={
-                          showLastRun
-                            ? t('detail.hideLastRun')
-                            : t('detail.showLastRun')
-                        }
-                        tooltipSide="bottom"
-                        onClick={() => {
-                          setShowLastRun((shown) => !shown);
-                        }}
-                      >
-                        {showLastRun ? (
-                          <EyeOff className="size-4" aria-hidden="true" />
-                        ) : (
-                          <Eye className="size-4" aria-hidden="true" />
-                        )}
-                      </Button>
-                    ) : null}
-                    {canAuthor && (
+            {showSource && rawDocument !== null ? (
+              <AutomationSourceView
+                document={rawDocument}
+                settled={settledDocument}
+                issues={issueViews}
+                diagnosticsStatus={diagnosticsStatus}
+                automationSlug={automationSlug}
+                version={lookingVersion}
+                isDraft={isDirty}
+                viewSwitch={viewSwitch}
+                actions={codingAgentButton}
+                {...(isMobile && { toolbar: canvasToolbarActions })}
+                showEditHint={canAuthor}
+              />
+            ) : (
+              canvasDocument !== null && (
+                <AutomationCanvas
+                  automation={canvasDocument}
+                  layoutKey={layoutKey}
+                  catalog={catalog}
+                  modelLabel={modelLabel}
+                  triggers={triggerRowsShown}
+                  check={canvasCheck}
+                  startNotice={startNotice}
+                  issueCounts={countsByNode}
+                  selectedId={selectedId}
+                  onSelect={selectOnCanvas}
+                  revealId={selectedId}
+                  inspectorId={inspectorId}
+                  {...(canvasRun !== undefined && { run: canvasRun })}
+                  {...(canvasChange !== undefined && { changed: canvasChange })}
+                  framed={false}
+                  view={canvasView}
+                  onViewChange={(next) =>
+                    changeView(next === 'list' ? 'list' : 'canvas')
+                  }
+                  topStart={viewSwitch}
+                  topEnd={
+                    <>
+                      {lastRun ? (
+                        <Button
+                          variant="secondary"
+                          size="icon-sm"
+                          aria-pressed={showLastRun}
+                          title={
+                            showLastRun
+                              ? t('detail.hideLastRun')
+                              : t('detail.showLastRun')
+                          }
+                          tooltipSide="bottom"
+                          onClick={() => {
+                            setShowLastRun((shown) => !shown);
+                          }}
+                        >
+                          {showLastRun ? (
+                            <EyeOff className="size-4" aria-hidden="true" />
+                          ) : (
+                            <Eye className="size-4" aria-hidden="true" />
+                          )}
+                        </Button>
+                      ) : null}
+                      {codingAgentButton}
+                    </>
+                  }
+                  {...(isMobile && { toolbar: canvasToolbarActions })}
+                  {...(canAuthor && {
+                    emptyAction: (
                       <CodingAgentButton
                         organizationId={organizationId}
                         automationSlug={automationSlug}
+                        variant="primary"
                       />
-                    )}
-                  </>
-                }
-                {...(isMobile && { toolbar: canvasToolbarActions })}
-                {...(canAuthor && {
-                  emptyAction: (
-                    <CodingAgentButton
-                      organizationId={organizationId}
-                      automationSlug={automationSlug}
-                      variant="primary"
-                    />
-                  ),
-                })}
-              />
+                    ),
+                  })}
+                />
+              )
             )}
             {/* Under the canvas, spanning its column only, so the inspector
                 beside it keeps its full height. Below `lg` the list opens
@@ -1661,32 +1821,9 @@ function AutomationEditorScope({
               (`lg` up) it opens there; below that there is no panel to
               stack against, so it opens in the sheet below instead — never
               both, `isWorkbenchCompact` picks exactly one. */}
-          {selectedNode !== null &&
-            inspectorContext !== null &&
-            !isWorkbenchCompact && (
-              <NodeInspector
-                id={inspectorId}
-                variant="panel"
-                node={selectedNode}
-                nodeType={nodeTypes.find(
-                  (def) => def.type === selectedNode.type,
-                )}
-                catalogUnavailable={catalogQuery.isError}
-                runView={
-                  showLastRun
-                    ? lastRunProjection.byNode.get(selectedNode.id)
-                    : undefined
-                }
-                readOnly={!canAuthor}
-                onChange={onChangeNode}
-                organizationId={organizationId}
-                {...(projectId !== undefined && { projectId })}
-                onDeselect={deselectNode}
-                issues={selectedNodeIssues}
-                nodeIndex={selectedNodeIndex}
-                context={inspectorContext}
-              />
-            )}
+          {inspectorContext !== null &&
+            !isWorkbenchCompact &&
+            inspector(inspectorContext, 'panel')}
         </div>
       </div>
 
@@ -1741,7 +1878,7 @@ function AutomationEditorScope({
           sheet is scrolled. */}
       {isWorkbenchCompact && (
         <ResponsiveDialog
-          open={selectedNode !== null}
+          open={inspected !== null}
           onOpenChange={(open) => {
             if (!open) deselectNode();
           }}
@@ -1752,35 +1889,23 @@ function AutomationEditorScope({
             // Closing onto the Problems sheet: its list takes focus.
             preventCloseAutoFocus={nodeSheetHandsOn}
           >
-            {selectedNode !== null && inspectorContext !== null && (
+            {inspected !== null && inspectorContext !== null && (
               <>
                 <ResponsiveDialogTitle className="sr-only">
-                  {nodeTitle(selectedNode.id)}
+                  {inspected === 'start'
+                    ? t('editor.start.title')
+                    : inspected === 'end'
+                      ? t('editor.end.title')
+                      : nodeTitle(selectedNode?.id ?? '')}
                 </ResponsiveDialogTitle>
                 <ResponsiveDialogDescription className="sr-only">
-                  {t('editor.nodeSheetDescription')}
+                  {inspected === 'start'
+                    ? t('editor.start.description')
+                    : inspected === 'end'
+                      ? t('editor.end.description')
+                      : t('editor.nodeSheetDescription')}
                 </ResponsiveDialogDescription>
-                <NodeFields
-                  headingId={inspectorId}
-                  node={selectedNode}
-                  nodeType={nodeTypes.find(
-                    (def) => def.type === selectedNode.type,
-                  )}
-                  catalogUnavailable={catalogQuery.isError}
-                  runView={
-                    showLastRun
-                      ? lastRunProjection.byNode.get(selectedNode.id)
-                      : undefined
-                  }
-                  readOnly={!canAuthor}
-                  onChange={onChangeNode}
-                  organizationId={organizationId}
-                  {...(projectId !== undefined && { projectId })}
-                  onDeselect={deselectNode}
-                  issues={selectedNodeIssues}
-                  nodeIndex={selectedNodeIndex}
-                  context={inspectorContext}
-                />
+                {inspector(inspectorContext, 'sheet')}
                 {canAuthor && (
                   <div className="bg-background border-border sticky bottom-0 z-10 -mb-6 flex flex-wrap items-center justify-end gap-2 border-t pt-3 pb-6">
                     {/* The problems that hold Save back may sit in other
diff --git a/services/platform/app/features/automations/components/automation-source-view.test.tsx b/services/platform/app/features/automations/components/automation-source-view.test.tsx
new file mode 100644
index 0000000000..7188ed7f41
--- /dev/null
+++ b/services/platform/app/features/automations/components/automation-source-view.test.tsx
@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { parse } from 'yaml';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { readDocument } from '../lib/document';
+import { toIssueView, withIssueIds } from '../lib/issues';
+import { AutomationSourceView } from './automation-source-view';
+
+const DOCUMENT = {
+  name: 'support/triage',
+  nodes: [
+    {
+      id: 'reply',
+      type: 'llm',
+      prompt: 'Answer {{ nodes.nope.output }}',
+      credential: 'kept-as-written',
+    },
+  ],
+  tests: [{ name: 'smoke', input: {} }],
+};
+
+const t = i18n.getFixedT('en', 'automations');
+
+function issues() {
+  const view = readDocument(DOCUMENT);
+  if (view === null) throw new Error('not a document');
+  return withIssueIds([
+    {
+      level: 'error',
+      code: 'REF_UNKNOWN_NODE',
+      message: 'nodes.nope does not exist',
+      at: { pointer: '/nodes/0/prompt', range: [10, 15] },
+      params: { ref: 'nope', suggestion: 'reply' },
+    },
+    {
+      level: 'warning',
+      code: 'TEST_X',
+      message: 'the test is odd',
+      at: { pointer: '/tests/0/name' },
+    },
+  ]).map((issue) =>
+    toIssueView(issue, view, {
+      locale: 'en',
+      t,
+      controlsOf: () => new Set(['prompt']),
+    }),
+  );
+}
+
+function renderView(props: { isDraft?: boolean; showEditHint?: boolean } = {}) {
+  return render(
+    <AutomationSourceView
+      document={DOCUMENT}
+      settled={DOCUMENT}
+      issues={issues()}
+      diagnosticsStatus="ready"
+      automationSlug="support/triage"
+      version={7}
+      isDraft={props.isDraft ?? false}
+      viewSwitch={<span>views</span>}
+      showEditHint={props.showEditHint ?? true}
+    />,
+  );
+}
+
+const sourceBox = () =>
+  screen.getByRole<HTMLTextAreaElement>('textbox', {
+    name: 'Source of this automation (YAML)',
+  });
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('AutomationSourceView', () => {
+  it('shows the document as read-only YAML, every key kept', () => {
+    renderView();
+    const box = sourceBox();
+    expect(box).toHaveAttribute('aria-readonly', 'true');
+    expect(box).toHaveAttribute('data-language', 'yaml');
+    expect(box).toHaveAttribute('data-templates', '');
+    expect(parse(box.value)).toEqual(DOCUMENT);
+  });
+
+  it('marks every problem at the place it names, without a fix to apply', () => {
+    renderView();
+    const box = sourceBox();
+    const marks = JSON.parse(box.dataset.diagnostics ?? '[]') as Array<{
+      severity: string;
+      range?: [number, number];
+      fixes?: string[];
+    }>;
+    expect(marks).toHaveLength(2);
+    const [reference, test] = marks;
+    expect(box.value.slice(reference?.range?.[0], reference?.range?.[1])).toBe(
+      'nodes',
+    );
+    expect(reference?.fixes).toBeUndefined();
+    expect(test?.severity).toBe('warning');
+    expect(box.value.slice(test?.range?.[0], test?.range?.[1])).toBe('smoke');
+  });
+
+  it('copies the YAML and says so', async () => {
+    const { user } = renderView();
+    await user.click(screen.getByRole('button', { name: 'Copy YAML' }));
+    await expect(navigator.clipboard.readText()).resolves.toBe(
+      sourceBox().value,
+    );
+    await waitFor(() => {
+      expect(screen.getByRole('status')).toHaveTextContent('Copied');
+    });
+  });
+
+  it('downloads the YAML named after the automation, its version and a draft', async () => {
+    const created = vi.fn((_blob: Blob) => 'blob:source');
+    Object.assign(URL, { createObjectURL: created, revokeObjectURL: vi.fn() });
+    const names: string[] = [];
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(
+      function (this: HTMLAnchorElement) {
+        names.push(this.download);
+      },
+    );
+    const { user, unmount } = renderView();
+    await user.click(screen.getByRole('button', { name: 'Download YAML' }));
+    expect(names).toEqual(['support__triage-v7.yml']);
+    const blob = created.mock.calls[0]?.[0];
+    expect(await blob?.text()).toBe(sourceBox().value);
+    unmount();
+    const draft = renderView({ isDraft: true });
+    await draft.user.click(
+      screen.getByRole('button', { name: 'Download YAML' }),
+    );
+    expect(names.at(-1)).toBe('support__triage-v7-draft.yml');
+  });
+
+  it('tells an author how to change the document, and a reader nothing', () => {
+    const { unmount } = renderView();
+    expect(
+      screen.getByText(
+        'To change the document, use the fields or your coding agent.',
+      ),
+    ).toBeVisible();
+    unmount();
+    renderView({ showEditHint: false });
+    expect(
+      screen.queryByText(
+        'To change the document, use the fields or your coding agent.',
+      ),
+    ).toBeNull();
+  });
+
+  it('passes an axe audit', async () => {
+    const { container } = renderView();
+    await checkAccessibility(container);
+  });
+});
diff --git a/services/platform/app/features/automations/components/automation-source-view.tsx b/services/platform/app/features/automations/components/automation-source-view.tsx
new file mode 100644
index 0000000000..6cb1b6b7dc
--- /dev/null
+++ b/services/platform/app/features/automations/components/automation-source-view.tsx
@@ -0,0 +1,168 @@
+'use client';
+
+import { Button } from '@tale/ui/button';
+import {
+  CodeEditor,
+  type CodeEditorDiagnostic,
+  type CodeEditorDiagnosticsStatus,
+} from '@tale/ui/code-editor';
+import { useCopyButton } from '@tale/ui/use-copy';
+import { Check, Copy, Download } from 'lucide-react';
+import { useMemo, type ReactNode } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+import { fieldDiagnostics } from '../lib/code-diagnostics';
+import type { RawDocument } from '../lib/draft-document';
+import type { AutomationIssueView } from '../lib/issues';
+import { engineTemplateScan } from '../lib/template-scanner';
+import {
+  SOURCE_ISSUE_ANCHOR,
+  sourceFileName,
+  yamlSource,
+} from '../lib/yaml-source';
+
+/** Saves the text as a YAML file under `name`. */
+function downloadYaml(text: string, name: string): void {
+  const blob = new Blob([text], { type: 'application/yaml;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = name;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}
+
+export interface AutomationSourceViewProps {
+  /** The document on screen: the draft, or the version shown. */
+  document: RawDocument;
+  /** The document the check answered for: its problems' places are in it. */
+  settled: RawDocument | null;
+  /** Every problem the check found, each marked at the place it names. */
+  issues: readonly AutomationIssueView[];
+  diagnosticsStatus: CodeEditorDiagnosticsStatus;
+  automationSlug: string;
+  /** The version on screen, for the downloaded file's name. */
+  version: number | undefined;
+  /** The text holds edits not saved yet. */
+  isDraft: boolean;
+  /** The view switch, top left as on the canvas. */
+  viewSwitch: ReactNode;
+  /** Verbs after Copy and Download (the coding-agent entry). */
+  actions?: ReactNode;
+  /** The automation's verbs, under the text on a phone as on the canvas. */
+  toolbar?: ReactNode;
+  /** Says how to change the document: the reader may edit it. */
+  showEditHint: boolean;
+}
+
+/**
+ * The Source view: the whole document as YAML, read-only — highlighted,
+ * with line numbers, folding and search, and every problem the check found
+ * marked at the place it names, so a problem without a field of its own
+ * (the tests, the name) has a place to be read. It is copied or downloaded
+ * from here; it is changed through the fields or a coding agent.
+ */
+export function AutomationSourceView({
+  document,
+  settled,
+  issues,
+  diagnosticsStatus,
+  automationSlug,
+  version,
+  isDraft,
+  viewSwitch,
+  actions,
+  toolbar,
+  showEditHint,
+}: AutomationSourceViewProps) {
+  const { t } = useT('automations');
+  const { t: tCommon } = useT('common');
+  const text = useMemo(() => yamlSource(document), [document]);
+  const marks = useMemo<{
+    diagnostics: CodeEditorDiagnostic[];
+    diagnosticsFor: string;
+  }>(() => {
+    const checked = settled === null ? text : yamlSource(settled);
+    return {
+      diagnosticsFor: checked,
+      // A read-only text takes no one-click fix.
+      diagnostics: fieldDiagnostics({
+        views: issues,
+        fieldPointer: '',
+        text: checked,
+        kind: 'yaml',
+        t,
+      }).map(({ fixes: _fixes, ...mark }) => mark),
+    };
+  }, [settled, text, issues, t]);
+  const { copied, onClick: copy } = useCopyButton(text);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col" data-slot="source-view">
+      <div className="flex flex-wrap items-center justify-between gap-2 p-3">
+        {viewSwitch}
+        <div className="flex flex-wrap items-center gap-2">
+          <Button
+            type="button"
+            variant="secondary"
+            size="sm"
+            icon={copied ? Check : Copy}
+            collapseLabel
+            onClick={copy}
+          >
+            {t('source.copy')}
+          </Button>
+          <Button
+            type="button"
+            variant="secondary"
+            size="sm"
+            icon={Download}
+            collapseLabel
+            onClick={() => {
+              downloadYaml(
+                text,
+                sourceFileName(automationSlug, version, isDraft),
+              );
+            }}
+          >
+            {t('source.download')}
+          </Button>
+          {actions}
+        </div>
+      </div>
+      {showEditHint && (
+        <p className="text-muted-foreground px-3 pb-2 text-xs">
+          {t('source.readOnlyHint')}
+        </p>
+      )}
+      <div className="flex min-h-0 flex-1 flex-col px-3 pb-3">
+        <CodeEditor
+          value={text}
+          language="yaml"
+          templates
+          templateScanner={engineTemplateScan}
+          readOnly
+          lineNumbers
+          fold
+          search
+          size="md"
+          fillHeight
+          aria-label={t('source.ariaLabel')}
+          diagnostics={marks.diagnostics}
+          diagnosticsFor={marks.diagnosticsFor}
+          diagnosticsStatus={diagnosticsStatus}
+          issueAnchor={SOURCE_ISSUE_ANCHOR}
+        />
+      </div>
+      {toolbar !== undefined && (
+        <div className="flex justify-center px-3 pb-3">{toolbar}</div>
+      )}
+      <span className="sr-only" role="status" aria-live="polite">
+        {copied ? tCommon('actions.copied') : ''}
+      </span>
+    </div>
+  );
+}
diff --git a/services/platform/app/features/automations/components/document-inspector-parts.tsx b/services/platform/app/features/automations/components/document-inspector-parts.tsx
new file mode 100644
index 0000000000..27f5a06c59
--- /dev/null
+++ b/services/platform/app/features/automations/components/document-inspector-parts.tsx
@@ -0,0 +1,230 @@
+'use client';
+
+import { Badge } from '@tale/ui/badge';
+import { cn } from '@tale/ui/cn';
+import type { CodeEditorProviders } from '@tale/ui/code-editor/providers';
+import type { FlowRow } from '@tale/ui/flow/types';
+import { IconButton } from '@tale/ui/icon-button';
+import { SectionHeader } from '@tale/ui/section-header';
+import { X } from 'lucide-react';
+import { useMemo, type ReactNode } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+import { fieldDiagnostics } from '../lib/code-diagnostics';
+import type { RawDocument } from '../lib/draft-document';
+import { fieldIssueMessage, type AutomationIssueView } from '../lib/issues';
+import { engineTemplateScan } from '../lib/template-scanner';
+import {
+  JsonCodeField,
+  jsonFieldText,
+  type JsonExpect,
+} from './json-code-field';
+import type { InspectorContext } from './node-inspector';
+
+/**
+ * The parts Start's and End's inspectors share: their header, their rows
+ * of words (triggers, the ways a run ends) and the document field each
+ * edits — the run input's schema, the output.
+ */
+
+/** The inspector's title, what it is about, and Close. */
+export function DocumentInspectorHeader({
+  headingId,
+  title,
+  description,
+  onDeselect,
+}: {
+  headingId: string;
+  title: string;
+  description: string;
+  onDeselect?: () => void;
+}) {
+  const { t: tCommon } = useT('common');
+  return (
+    <SectionHeader
+      as="h3"
+      size="sm"
+      title={
+        <span
+          id={headingId}
+          tabIndex={-1}
+          className="focus-visible:ring-ring block truncate rounded-sm outline-none focus-visible:ring-2"
+        >
+          {title}
+        </span>
+      }
+      description={description}
+      {...(onDeselect !== undefined && {
+        action: (
+          <IconButton
+            icon={X}
+            size="sm"
+            aria-label={tCommon('aria.close')}
+            onClick={onDeselect}
+          />
+        ),
+      })}
+    />
+  );
+}
+
+/** Rows of words with an icon each, as Start and End show them on the
+ *  canvas: a trigger with its next run and state, a way a run ends. */
+export function InspectorRows({
+  rows,
+  labelledBy,
+  children,
+}: {
+  rows: readonly FlowRow[];
+  labelledBy: string;
+  /** Content under a row, by its id (End lists the halting nodes under
+   *  Failed). */
+  children?: (row: FlowRow) => ReactNode;
+}) {
+  return (
+    <ul aria-labelledby={labelledBy} className="flex flex-col gap-2">
+      {rows.map((row) => {
+        const Icon = row.icon;
+        return (
+          <li key={row.id} className="flex min-w-0 flex-col gap-1.5">
+            <div className="flex min-w-0 items-start gap-2 text-xs">
+              {Icon !== undefined && (
+                <span
+                  aria-hidden="true"
+                  className="text-muted-foreground mt-0.5 shrink-0"
+                >
+                  <Icon className="size-3.5" />
+                </span>
+              )}
+              <div className="min-w-0 flex-1">
+                <span
+                  className={cn(
+                    'text-foreground break-words',
+                    row.code === true && 'font-mono',
+                  )}
+                >
+                  {row.label}
+                </span>
+                {row.detail !== undefined && (
+                  <span className="text-muted-foreground">
+                    {' · '}
+                    {row.detail}
+                  </span>
+                )}
+                {row.note !== undefined && (
+                  <p className="text-muted-foreground">{row.note}</p>
+                )}
+              </div>
+              {row.badge !== undefined && (
+                <Badge
+                  variant={row.badge.tone === 'warning' ? 'yellow' : 'outline'}
+                  className="shrink-0"
+                >
+                  {row.badge.label}
+                </Badge>
+              )}
+            </div>
+            {children?.(row)}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/** A top-level field of the document Start or End edits. */
+export type DocumentField = 'inputs' | 'output';
+
+/**
+ * The run input's schema or the output, edited as JSON in the code editor,
+ * with the check's problems under it and at their characters in it.
+ */
+export function DocumentJsonField({
+  field,
+  label,
+  description,
+  expect,
+  value,
+  issues,
+  context,
+  readOnly,
+  onCommit,
+  reveal,
+  providers,
+}: {
+  field: DocumentField;
+  label: string;
+  description: string;
+  expect: JsonExpect;
+  value: unknown;
+  /** The problems "go to" brings here: their pointers are under the field. */
+  issues: readonly AutomationIssueView[];
+  context: InspectorContext;
+  readOnly: boolean;
+  onCommit: (next: unknown) => void;
+  /** Opens the tab the field sits in before a "go to". */
+  reveal: () => void;
+  /** Completion and types inside the field's templates; none for a field
+   *  without templates. */
+  providers?: CodeEditorProviders;
+}) {
+  const { t } = useT('automations');
+  const pointer = `/${field}`;
+  const lines = useMemo(
+    () =>
+      issues.map((view) => ({
+        id: view.issue.id,
+        severity: view.issue.level,
+        message: fieldIssueMessage(view, t),
+      })),
+    [issues, t],
+  );
+  const marks = useMemo(() => {
+    const text = jsonFieldText(settledValue(context.settled, field, value));
+    return {
+      diagnosticsFor: text,
+      diagnostics:
+        issues.length === 0
+          ? []
+          : fieldDiagnostics({
+              views: issues,
+              fieldPointer: pointer,
+              text,
+              kind: 'json',
+              t,
+            }),
+    };
+  }, [context.settled, field, value, issues, pointer, t]);
+  return (
+    <JsonCodeField
+      label={label}
+      description={description}
+      value={value}
+      expect={expect}
+      templates={providers !== undefined}
+      {...(providers !== undefined && {
+        templateScanner: engineTemplateScan,
+        providers,
+      })}
+      onCommit={onCommit}
+      anchor={pointer}
+      issueReveal={reveal}
+      issues={lines}
+      diagnostics={marks.diagnostics}
+      diagnosticsFor={marks.diagnosticsFor}
+      diagnosticsStatus={context.diagnosticsStatus}
+      readOnly={readOnly}
+    />
+  );
+}
+
+/** The field's value in the document the check answered for: its ranges
+ *  index into that text. */
+function settledValue(
+  settled: RawDocument | null,
+  field: DocumentField,
+  shown: unknown,
+): unknown {
+  return settled === null ? shown : settled[field];
+}
diff --git a/services/platform/app/features/automations/components/document-inspectors.test.tsx b/services/platform/app/features/automations/components/document-inspectors.test.tsx
new file mode 100644
index 0000000000..2cd6bb0de0
--- /dev/null
+++ b/services/platform/app/features/automations/components/document-inspectors.test.tsx
@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { analyzeFlow } from '@/lib/engine/core/analysis/flow';
+import type { Automation } from '@/lib/engine/core/types';
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { i18n } from '@/tests/utils/i18n-all-languages';
+import { render, screen, within } from '@/tests/utils/render';
+
+import { coreNodeTypes } from '../hooks/backend';
+import { toIssueView, withIssueIds } from '../lib/issues';
+import { nodeCatalogView } from '../lib/node-face';
+import { EndInspector } from './end-inspector';
+import type { InspectorContext } from './node-inspector';
+import { StartInspector } from './start-inspector';
+
+vi.mock('@tanstack/react-router', async () => {
+  const { forwardRef } = await import('react');
+  return {
+    Link: forwardRef<
+      HTMLAnchorElement,
+      React.AnchorHTMLAttributes<HTMLAnchorElement> & { to?: string }
+    >(function Link({ to, children, ...rest }, ref) {
+      return (
+        <a ref={ref} href={to ?? '#'} {...rest}>
+          {children}
+        </a>
+      );
+    }),
+  };
+});
+
+const DOC: Automation = {
+  name: 'support/triage',
+  nodes: [
+    { id: 'fetch_issues', type: 'transform', code: 'return [];' },
+    {
+      id: 'notify',
+      type: 'transform',
+      code: 'return 1;',
+      onError: 'continue',
+      input: { list: '{{ nodes.fetch_issues.output }}' },
+    },
+  ],
+  output: '{{ nodes.notify.output }}',
+};
+
+function contextFor(doc: Automation): InspectorContext {
+  return {
+    doc,
+    flow: analyzeFlow(doc.nodes),
+    analysis: {
+      nodes: {},
+      paths: {
+        count: 1,
+        truncated: false,
+        halts: [{ nodeId: 'fetch_issues', reasons: ['code'] }],
+      },
+      output: { reads: ['notify'], maybeEmpty: true },
+    },
+    types: {
+      inputs: { type: 'object', properties: { owner: { type: 'string' } } },
+      nodes: {},
+      output: { type: 'number' },
+    },
+    shapeStatus: 'ready',
+    diagnosticsStatus: 'ready',
+    settled: null,
+    catalog: nodeCatalogView(coreNodeTypes()),
+  };
+}
+
+const t = i18n.getFixedT('en', 'automations');
+
+describe('StartInspector', () => {
+  it('says any input is taken when the document declares none', () => {
+    render(
+      <StartInspector
+        id="start"
+        triggers={[]}
+        readOnly={false}
+        onChange={vi.fn()}
+        context={contextFor(DOC)}
+      />,
+    );
+    expect(screen.getByText('Any JSON input')).toBeVisible();
+    expect(screen.getByRole('textbox', { name: 'Input schema' })).toHaveValue(
+      '',
+    );
+  });
+
+  it('shows a refused trigger under the input schema, and passes axe', async () => {
+    const doc: Automation = {
+      ...DOC,
+      inputs: { type: 'object', required: ['owner'] },
+    };
+    const issues = withIssueIds([
+      {
+        level: 'error',
+        code: 'TRIGGER_INPUT_MISMATCH',
+        message: 'the schedule starts runs without owner',
+        at: { pointer: '' },
+      },
+    ]).map((issue) =>
+      toIssueView(issue, doc, {
+        locale: 'en',
+        t,
+        controlsOf: () => new Set(),
+      }),
+    );
+    const { container } = render(
+      <StartInspector
+        id="start"
+        triggers={[]}
+        readOnly={false}
+        onChange={vi.fn()}
+        issues={issues}
+        context={contextFor(doc)}
+      />,
+    );
+    expect(
+      screen.getByRole('textbox', { name: 'Input schema' }),
+    ).toHaveAttribute('aria-invalid', 'true');
+    await checkAccessibility(container);
+  });
+
+  it('shows the shape every run receives', async () => {
+    const { user } = render(
+      <StartInspector
+        id="start"
+        triggers={[]}
+        readOnly
+        onChange={vi.fn()}
+        context={contextFor(DOC)}
+      />,
+    );
+    await user.click(screen.getByRole('tab', { name: 'Shape' }));
+    expect(
+      within(screen.getByRole('tabpanel', { name: 'Shape' })).getByRole(
+        'heading',
+        {
+          name: 'Receives',
+        },
+      ),
+    ).toBeVisible();
+  });
+});
+
+describe('EndInspector', () => {
+  it('lists the nodes whose failure stops the run, with why, and picks one', async () => {
+    const onSelect = vi.fn();
+    const { user } = render(
+      <EndInspector
+        id="end"
+        readOnly={false}
+        onChange={vi.fn()}
+        context={{ ...contextFor(DOC), onSelect }}
+      />,
+    );
+    const ends = screen.getByRole('list', { name: 'How a run ends' });
+    expect(within(ends).getByText(/when 1 node fails/)).toBeVisible();
+    // Notify goes on without itself; only Fetch issues stops the run.
+    await user.click(
+      screen.getByRole('button', {
+        name: 'Fetch issues fails when its code throws an error',
+      }),
+    );
+    expect(onSelect).toHaveBeenCalledWith('fetch_issues');
+  });
+
+  it('commits an output of any kind and clears it when blank', async () => {
+    const onChange = vi.fn();
+    const { user } = render(
+      <EndInspector
+        id="end"
+        readOnly={false}
+        onChange={onChange}
+        context={contextFor(DOC)}
+      />,
+    );
+    const output = screen.getByRole('textbox', { name: 'Output' });
+    expect(output).toHaveAttribute('data-templates', '');
+    await user.clear(output);
+    expect(onChange).toHaveBeenLastCalledWith({ output: undefined });
+    await user.type(output, '42');
+    expect(onChange).toHaveBeenLastCalledWith({ output: 42 });
+  });
+
+  it('passes an axe audit', async () => {
+    const { container } = render(
+      <EndInspector
+        id="end"
+        readOnly={false}
+        onChange={vi.fn()}
+        context={contextFor(DOC)}
+      />,
+    );
+    await checkAccessibility(container);
+  });
+});
diff --git a/services/platform/app/features/automations/components/end-inspector.tsx b/services/platform/app/features/automations/components/end-inspector.tsx
new file mode 100644
index 0000000000..e8af3d71d9
--- /dev/null
+++ b/services/platform/app/features/automations/components/end-inspector.tsx
@@ -0,0 +1,235 @@
+'use client';
+
+import { Button } from '@tale/ui/button';
+import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { JsonViewer } from '@tale/ui/json-viewer';
+import { useId, useMemo } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+import { automationProviders } from '../lib/code-providers';
+import type { DocumentPatch } from '../lib/draft-document';
+import { endOutcomes } from '../lib/flow-graph';
+import { END_ID } from '../lib/flow-ids';
+import type { AutomationIssueView } from '../lib/issues';
+import { nodeTitle } from '../lib/node-face';
+import { failureReasonWords } from '../lib/paths';
+import {
+  DocumentInspectorHeader,
+  DocumentJsonField,
+  InspectorRows,
+} from './document-inspector-parts';
+import {
+  InspectorFrame,
+  InspectorTabs,
+  useInspectorTab,
+  type InspectorContext,
+  type InspectorTab,
+} from './node-inspector';
+import { ShapeBlock, ShapeStatusLine } from './node-shape-panel';
+
+const NO_ISSUES: readonly AutomationIssueView[] = [];
+
+export interface EndFieldsProps {
+  headingId: string;
+  readOnly: boolean;
+  onChange: (patch: DocumentPatch) => void;
+  /** The problems "go to" brings to End: the output's. */
+  issues?: readonly AutomationIssueView[];
+  context: InspectorContext;
+  /** The output of the run laid over the canvas, when one is. */
+  run?: { output: unknown };
+  onDeselect?: () => void;
+  defaultTab?: InspectorTab;
+}
+
+/**
+ * End's inspector, without a frame (the phone's sheet has its own): how a
+ * run ends — with the nodes whose failure stops it, each a way to that
+ * node — and what a successful run returns: the output to edit, with
+ * completion and types in its templates, the shape the check worked out,
+ * and the output of the run on the canvas.
+ */
+export function EndFields({
+  headingId,
+  readOnly,
+  onChange,
+  issues = NO_ISSUES,
+  context,
+  run,
+  onDeselect,
+  defaultTab,
+}: EndFieldsProps) {
+  const { t } = useT('automations');
+  const { locale } = useLocale();
+  const outcomesTitleId = useId();
+  const haltsTitleId = useId();
+  const [tab, setTab] = useInspectorTab(
+    context.shapeStatus !== 'off',
+    run !== undefined,
+    defaultTab,
+  );
+  const { doc, flow, analysis, types, sampleOf, onSelect } = context;
+  const halts = useMemo(() => {
+    const reasonsOf = new Map(
+      (analysis?.paths.halts ?? []).map((halt) => [halt.nodeId, halt.reasons]),
+    );
+    const either = new Intl.ListFormat(locale, { type: 'disjunction' });
+    return (flow?.halts ?? []).map(({ nodeId }) => {
+      const words = (reasonsOf.get(nodeId) ?? []).flatMap((reason) => {
+        const text = failureReasonWords(reason, t);
+        return text === null ? [] : [text];
+      });
+      const node = nodeTitle(nodeId);
+      return {
+        nodeId,
+        label:
+          words.length === 0
+            ? node
+            : t('paths.halts.row', { node, reasons: either.format(words) }),
+      };
+    });
+  }, [analysis, flow, locale, t]);
+  const providers = useMemo(
+    () =>
+      automationProviders({
+        doc,
+        field: 'output',
+        types,
+        ...(sampleOf !== undefined && { sampleOf }),
+      }),
+    [doc, types, sampleOf],
+  );
+  const shapeStatus = context.shapeStatus;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <DocumentInspectorHeader
+        headingId={headingId}
+        title={t('editor.end.title')}
+        description={t('editor.end.description')}
+        {...(onDeselect !== undefined && { onDeselect })}
+      />
+
+      <section
+        aria-labelledby={outcomesTitleId}
+        className="flex flex-col gap-2"
+      >
+        <h4
+          id={outcomesTitleId}
+          className="text-foreground text-sm font-medium"
+        >
+          {t('editor.end.outcomes')}
+        </h4>
+        <InspectorRows
+          rows={endOutcomes(t, halts.length)}
+          labelledBy={outcomesTitleId}
+        >
+          {(row) =>
+            row.id === 'failed' && halts.length > 0 ? (
+              <div className="flex flex-col gap-1 pl-5.5">
+                <p id={haltsTitleId} className="text-muted-foreground text-xs">
+                  {t('paths.halts.title')}
+                </p>
+                <ul
+                  aria-labelledby={haltsTitleId}
+                  className="flex flex-wrap gap-1"
+                >
+                  {halts.map((halt) => (
+                    <li key={halt.nodeId} className="min-w-0">
+                      <Button
+                        type="button"
+                        variant="secondary"
+                        size="sm"
+                        className="h-auto min-h-7 max-w-full text-left whitespace-normal"
+                        disabled={onSelect === undefined}
+                        onClick={() => onSelect?.(halt.nodeId)}
+                      >
+                        {halt.label}
+                      </Button>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ) : null
+          }
+        </InspectorRows>
+      </section>
+
+      <InspectorTabs
+        tab={tab}
+        onTabChange={setTab}
+        fields={
+          <DocumentJsonField
+            field="output"
+            label={t('editor.fields.output')}
+            description={t('editor.end.outputDescription')}
+            expect="any"
+            value={doc.output}
+            issues={issues}
+            context={context}
+            readOnly={readOnly}
+            onCommit={(next) => {
+              onChange({ output: next });
+            }}
+            reveal={() => setTab('fields')}
+            providers={providers}
+          />
+        }
+        {...(shapeStatus !== 'off' && {
+          shape: (
+            <div className="flex flex-col gap-4">
+              <ShapeStatusLine status={shapeStatus} />
+              {types !== null && (
+                <ShapeBlock
+                  title={t('editor.shape.returns')}
+                  shape={types.output}
+                />
+              )}
+            </div>
+          ),
+        })}
+        {...(run !== undefined && {
+          run: (
+            <div className="flex flex-col gap-1">
+              <h4 className="text-foreground text-sm font-medium">
+                {t('runs.outputTitle')}
+              </h4>
+              <JsonViewer data={run.output} collapsed={1} />
+            </div>
+          ),
+        })}
+      />
+    </div>
+  );
+}
+
+/** End's inspector beside the canvas: `EndFields` in the inspector's
+ *  frame. */
+export function EndInspector({
+  id,
+  variant = 'card',
+  onDeselect,
+  ...rest
+}: Omit<EndFieldsProps, 'headingId'> & {
+  /** The region id End's box on the canvas points at. */
+  id: string;
+  variant?: 'card' | 'panel';
+}) {
+  const headingId = useId();
+  return (
+    <InspectorFrame
+      id={id}
+      labelledBy={headingId}
+      focusKey={END_ID}
+      variant={variant}
+      {...(onDeselect !== undefined && { onDeselect })}
+    >
+      <EndFields
+        headingId={headingId}
+        {...(onDeselect !== undefined && { onDeselect })}
+        {...rest}
+      />
+    </InspectorFrame>
+  );
+}
diff --git a/services/platform/app/features/automations/components/node-inspector.tsx b/services/platform/app/features/automations/components/node-inspector.tsx
index 086dadc609..bdacaf7e17 100644
--- a/services/platform/app/features/automations/components/node-inspector.tsx
+++ b/services/platform/app/features/automations/components/node-inspector.tsx
@@ -536,7 +536,7 @@ export interface NodeInspectorProps {
 
 /** The inspector's frame: a card in a page inset, or a panel flush
  *  against the canvas. Shared by the node, Start and End inspectors. */
-function InspectorFrame({
+export function InspectorFrame({
   id,
   labelledBy,
   focusKey,
@@ -648,7 +648,7 @@ const NO_ISSUE_VIEWS: readonly AutomationIssueView[] = [];
 
 /** The tab bar of an inspector: Fields, Shape (while the check can say),
  *  Last run (while a run is laid over the canvas). */
-function useInspectorTab(
+export function useInspectorTab(
   hasShape: boolean,
   hasRun: boolean,
   defaultTab: InspectorTab = 'fields',
@@ -667,7 +667,7 @@ function isInspectorTab(value: string): value is InspectorTab {
 
 /** The three tabs, with each panel kept mounted so a half-typed field
  *  survives a look at the shapes. */
-function InspectorTabs({
+export function InspectorTabs({
   tab,
   onTabChange,
   fields,
diff --git a/services/platform/app/features/automations/components/node-shape-panel.tsx b/services/platform/app/features/automations/components/node-shape-panel.tsx
index aa274db0ed..c2deca2f3c 100644
--- a/services/platform/app/features/automations/components/node-shape-panel.tsx
+++ b/services/platform/app/features/automations/components/node-shape-panel.tsx
@@ -19,7 +19,7 @@ import { nodeTitle } from '../lib/node-face';
 export type ShapeStatus = 'pending' | 'checking' | 'ready' | 'failed';
 
 /** A shape with its TypeScript behind "Show as TypeScript". */
-function ShapeBlock({
+export function ShapeBlock({
   title,
   shape,
   children,
@@ -77,7 +77,7 @@ function originText(
 
 /** A line saying the shapes on screen are being brought up to date, or
  *  could not be worked out. */
-function ShapeStatusLine({ status }: { status: ShapeStatus }) {
+export function ShapeStatusLine({ status }: { status: ShapeStatus }) {
   const { t } = useT('automations');
   if (status === 'failed') {
     return (
diff --git a/services/platform/app/features/automations/components/start-inspector.tsx b/services/platform/app/features/automations/components/start-inspector.tsx
new file mode 100644
index 0000000000..94749a4eeb
--- /dev/null
+++ b/services/platform/app/features/automations/components/start-inspector.tsx
@@ -0,0 +1,209 @@
+'use client';
+
+import { buttonVariants } from '@tale/ui/button';
+import type { FlowRow } from '@tale/ui/flow/types';
+import { JsonViewer } from '@tale/ui/json-viewer';
+import { SchemaTree } from '@tale/ui/schema-tree';
+import { Link } from '@tanstack/react-router';
+import { Settings2 } from 'lucide-react';
+import { useId } from 'react';
+
+import { useT } from '@/lib/i18n/client';
+
+import type { DocumentPatch } from '../lib/draft-document';
+import { START_ID } from '../lib/flow-ids';
+import type { AutomationIssueView } from '../lib/issues';
+import {
+  DocumentInspectorHeader,
+  DocumentJsonField,
+  InspectorRows,
+} from './document-inspector-parts';
+import {
+  InspectorFrame,
+  InspectorTabs,
+  useInspectorTab,
+  type InspectorContext,
+  type InspectorTab,
+} from './node-inspector';
+import { ShapeBlock, ShapeStatusLine } from './node-shape-panel';
+
+const NO_ISSUES: readonly AutomationIssueView[] = [];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export interface StartFieldsProps {
+  headingId: string;
+  /** What starts a run, as Start's rows on the canvas say it. */
+  triggers: readonly FlowRow[];
+  /** The automation's General tab, where its trigger is changed. */
+  generalHref?: string;
+  readOnly: boolean;
+  onChange: (patch: DocumentPatch) => void;
+  /** The problems "go to" brings to Start: the run input's schema. */
+  issues?: readonly AutomationIssueView[];
+  context: InspectorContext;
+  /** The input of the run laid over the canvas, when one is. */
+  run?: { input: unknown };
+  onDeselect?: () => void;
+  defaultTab?: InspectorTab;
+}
+
+/**
+ * Start's inspector, without a frame (the phone's sheet has its own): what
+ * starts a run, with the way to change it, and what every run receives —
+ * the fields of the run input as a tree and its JSON Schema to edit, the
+ * shape the check worked out, and the input of the run on the canvas.
+ */
+export function StartFields({
+  headingId,
+  triggers,
+  generalHref,
+  readOnly,
+  onChange,
+  issues = NO_ISSUES,
+  context,
+  run,
+  onDeselect,
+  defaultTab,
+}: StartFieldsProps) {
+  const { t } = useT('automations');
+  const triggerTitleId = useId();
+  const inputsTitleId = useId();
+  const [tab, setTab] = useInspectorTab(
+    context.shapeStatus !== 'off',
+    run !== undefined,
+    defaultTab,
+  );
+  const inputs = context.doc.inputs;
+  const shapeStatus = context.shapeStatus;
+  const { types } = context;
+
+  const fields = (
+    <>
+      <section aria-labelledby={inputsTitleId} className="flex flex-col gap-1">
+        <h4 id={inputsTitleId} className="text-foreground text-sm font-medium">
+          {t('editor.start.inputs')}
+        </h4>
+        {isRecord(inputs) ? (
+          <SchemaTree
+            // An author's JSON Schema: the tree reads the keywords it knows
+            // and ignores the rest.
+            schema={inputs}
+            density="comfortable"
+            aria-labelledby={inputsTitleId}
+          />
+        ) : (
+          <p className="text-muted-foreground text-xs">
+            {t('canvas.start.anyInput')}
+          </p>
+        )}
+      </section>
+      <DocumentJsonField
+        field="inputs"
+        label={t('editor.start.schema')}
+        description={t('editor.start.inputsDescription')}
+        expect="object"
+        value={inputs}
+        issues={issues}
+        context={context}
+        readOnly={readOnly}
+        onCommit={(next) => {
+          onChange({ inputs: next });
+        }}
+        reveal={() => setTab('fields')}
+      />
+    </>
+  );
+
+  return (
+    <div className="flex flex-col gap-3">
+      <DocumentInspectorHeader
+        headingId={headingId}
+        title={t('editor.start.title')}
+        description={t('editor.start.description')}
+        {...(onDeselect !== undefined && { onDeselect })}
+      />
+
+      <section aria-labelledby={triggerTitleId} className="flex flex-col gap-2">
+        <h4 id={triggerTitleId} className="text-foreground text-sm font-medium">
+          {t('editor.start.trigger')}
+        </h4>
+        <InspectorRows rows={triggers} labelledBy={triggerTitleId} />
+        {generalHref !== undefined && (
+          <Link
+            to={generalHref}
+            className={buttonVariants({
+              variant: 'secondary',
+              size: 'sm',
+              className: 'self-start',
+            })}
+          >
+            <Settings2 className="mr-2 size-4" aria-hidden="true" />
+            {t('editor.start.editTrigger')}
+          </Link>
+        )}
+      </section>
+
+      <InspectorTabs
+        tab={tab}
+        onTabChange={setTab}
+        fields={fields}
+        {...(shapeStatus !== 'off' && {
+          shape: (
+            <div className="flex flex-col gap-4">
+              <ShapeStatusLine status={shapeStatus} />
+              {types !== null && (
+                <ShapeBlock
+                  title={t('editor.shape.receives')}
+                  shape={types.inputs}
+                />
+              )}
+            </div>
+          ),
+        })}
+        {...(run !== undefined && {
+          run: (
+            <div className="flex flex-col gap-1">
+              <h4 className="text-foreground text-sm font-medium">
+                {t('runs.inputTitle')}
+              </h4>
+              <JsonViewer data={run.input} collapsed={1} />
+            </div>
+          ),
+        })}
+      />
+    </div>
+  );
+}
+
+/** Start's inspector beside the canvas: `StartFields` in the inspector's
+ *  frame. */
+export function StartInspector({
+  id,
+  variant = 'card',
+  onDeselect,
+  ...rest
+}: Omit<StartFieldsProps, 'headingId'> & {
+  /** The region id Start's box on the canvas points at. */
+  id: string;
+  variant?: 'card' | 'panel';
+}) {
+  const headingId = useId();
+  return (
+    <InspectorFrame
+      id={id}
+      labelledBy={headingId}
+      focusKey={START_ID}
+      variant={variant}
+      {...(onDeselect !== undefined && { onDeselect })}
+    >
+      <StartFields
+        headingId={headingId}
+        {...(onDeselect !== undefined && { onDeselect })}
+        {...rest}
+      />
+    </InspectorFrame>
+  );
+}
diff --git a/services/platform/app/features/automations/lib/editor-search.test.ts b/services/platform/app/features/automations/lib/editor-search.test.ts
index 577b8392e0..eae2aa95d5 100644
--- a/services/platform/app/features/automations/lib/editor-search.test.ts
+++ b/services/platform/app/features/automations/lib/editor-search.test.ts
@@ -8,6 +8,12 @@ import { automationEditorSearchSchema } from './editor-search';
  * automation.
  */
 describe('automationEditorSearchSchema', () => {
+  it('opens the Source view', () => {
+    expect(automationEditorSearchSchema.parse({ view: 'source' })).toEqual({
+      view: 'source',
+    });
+  });
+
   it('reads the version, the view and the open node', () => {
     expect(
       automationEditorSearchSchema.parse({
@@ -31,7 +37,7 @@ describe('automationEditorSearchSchema', () => {
     expect(
       automationEditorSearchSchema.parse({
         version: 0,
-        view: 'source',
+        view: 'yaml',
         node: 'Not a node id',
       }),
     ).toEqual({});
diff --git a/services/platform/app/features/automations/lib/editor-search.ts b/services/platform/app/features/automations/lib/editor-search.ts
index ebf678fc53..c2101324eb 100644
--- a/services/platform/app/features/automations/lib/editor-search.ts
+++ b/services/platform/app/features/automations/lib/editor-search.ts
@@ -2,15 +2,16 @@ import { z } from 'zod';
 
 /**
  * The Editor tab's search params: `?version=<n>` shows that stored version on
- * the canvas, absent means the latest; `?view=` picks the chart or the List
- * view; `?node=<id>` opens a node (or `__start`, `__end`) on load, so a link
+ * the canvas, absent means the latest; `?view=` picks the chart, the List
+ * view or the Source view; `?node=<id>` opens a node (or `__start`,
+ * `__end`) on load, so a link
  * lands on it. A malformed value reads as absent rather than failing the
  * route — a bad link should still open the automation.
  */
 export const automationEditorSearchSchema = z.object({
   history: z.boolean().optional().catch(undefined),
   version: z.number().int().positive().optional().catch(undefined),
-  view: z.enum(['canvas', 'list']).optional().catch(undefined),
+  view: z.enum(['canvas', 'list', 'source']).optional().catch(undefined),
   node: z
     .string()
     .regex(/^(?:__start|__end|[a-z][a-z0-9_]{0,49})$/)
diff --git a/services/platform/app/features/automations/lib/flow-graph.ts b/services/platform/app/features/automations/lib/flow-graph.ts
index 94c0a224af..b6dd93a350 100644
--- a/services/platform/app/features/automations/lib/flow-graph.ts
+++ b/services/platform/app/features/automations/lib/flow-graph.ts
@@ -60,6 +60,7 @@ import {
   renderCondition,
   renderOperand,
   type ConditionTextContext,
+  type ConditionTranslate,
 } from './condition-text';
 import { END_ID, START_ID, decisionKeyOf, gateIdOf } from './flow-ids';
 import { orderedNodes } from './graph';
@@ -283,6 +284,31 @@ function startNode(doc: Automation, ctx: FlowGraphContext): FlowEntryNode {
   };
 }
 
+/** The three ways a run ends, as End and its inspector say them:
+ *  `halts` is how many nodes stop the run when they fail. */
+export function endOutcomes(t: ConditionTranslate, halts: number): FlowRow[] {
+  return [
+    {
+      id: 'succeeded',
+      icon: CircleCheck,
+      label: t('runs.status.success'),
+      detail: t('canvas.end.succeeded'),
+    },
+    {
+      id: 'failed',
+      icon: CircleX,
+      label: t('runs.status.failed'),
+      detail: t('canvas.end.failed', { count: halts }),
+    },
+    {
+      id: 'stopped',
+      icon: Ban,
+      label: t('runs.status.cancelled'),
+      detail: t('canvas.end.stopped'),
+    },
+  ];
+}
+
 /** End: what a successful run returns, and the three ways a run ends. */
 function endNode(
   doc: Automation,
@@ -369,26 +395,7 @@ function endNode(
       outputsEmpty: t('canvas.end.returnsNothing'),
     }),
     ...(shape !== undefined && { shape }),
-    outcomes: [
-      {
-        id: 'succeeded',
-        icon: CircleCheck,
-        label: t('runs.status.success'),
-        detail: t('canvas.end.succeeded'),
-      },
-      {
-        id: 'failed',
-        icon: CircleX,
-        label: t('runs.status.failed'),
-        detail: t('canvas.end.failed', { count: flow?.halts.length ?? 0 }),
-      },
-      {
-        id: 'stopped',
-        icon: Ban,
-        label: t('runs.status.cancelled'),
-        detail: t('canvas.end.stopped'),
-      },
-    ],
+    outcomes: endOutcomes(t, flow?.halts.length ?? 0),
     ...(someEmpty && {
       notice: { tone: 'info', text: t('canvas.end.someEmpty') },
     }),
diff --git a/services/platform/app/features/automations/lib/issues.test.ts b/services/platform/app/features/automations/lib/issues.test.ts
index 1b459dfe5c..fe6c2b8390 100644
--- a/services/platform/app/features/automations/lib/issues.test.ts
+++ b/services/platform/app/features/automations/lib/issues.test.ts
@@ -213,12 +213,68 @@ describe('issueNavigation', () => {
     ).toEqual({ kind: 'node', nodeId: 'fetch_issues', nodeIndex: 0 });
   });
 
-  it('cannot go to a place the editor does not edit', () => {
-    for (const pointer of ['/output', '/inputs', '/tests/0', '/name', '']) {
+  it('goes to Start for the run input and a trigger it refuses', () => {
+    expect(
+      issueNavigation(
+        issue({
+          code: 'X',
+          at: { pointer: '/inputs/properties/owner', range: [0, 3] },
+        }),
+        DOC,
+        controlsOf,
+      ),
+    ).toEqual({
+      kind: 'start',
+      anchor: '/inputs/properties/owner',
+      range: [0, 3],
+    });
+    // The schedule's wrapper is refused by the schema: fixed in the schema.
+    expect(
+      issueNavigation(
+        issue({ code: 'TRIGGER_INPUT_MISMATCH', at: { pointer: '' } }),
+        DOC,
+        controlsOf,
+      ),
+    ).toEqual({ kind: 'start', anchor: '/inputs' });
+  });
+
+  it('goes to End for the output, even when the issue names a node', () => {
+    expect(
+      issueNavigation(
+        issue({
+          code: 'X',
+          nodeId: 'draft_reply',
+          at: { pointer: '/output/summary' },
+        }),
+        DOC,
+        controlsOf,
+      ),
+    ).toEqual({ kind: 'end', anchor: '/output/summary' });
+  });
+
+  it('goes to the Source view for a place without a control', () => {
+    for (const pointer of ['/tests/0', '/name', '', '/nodes']) {
       expect(
         issueNavigation(issue({ code: 'X', at: { pointer } }), DOC, controlsOf),
-      ).toEqual({ kind: 'unavailable' });
+      ).toEqual({ kind: 'source', pointer });
     }
+    expect(
+      issueNavigation(
+        issue({
+          code: 'X',
+          at: { pointer: '/tests/0/expect', subject: 'missing' },
+        }),
+        DOC,
+        controlsOf,
+      ),
+    ).toEqual({
+      kind: 'source',
+      pointer: '/tests/0/expect',
+      subject: 'missing',
+    });
+  });
+
+  it('cannot go to a node the document on screen no longer has', () => {
     // A pointer past the nodes of the document on screen (an older check).
     expect(
       issueNavigation(
@@ -303,15 +359,26 @@ describe('toIssueView', () => {
     expect(view.item.unavailableReason).toBeUndefined();
   });
 
-  it('says why a problem outside the nodes cannot be gone to', () => {
+  it('says why a problem in a node that is gone cannot be gone to', () => {
     const [found] = withIssueIds([
-      issue({ code: 'OUTPUT_MISSING', at: { pointer: '/output' } }),
+      issue({ code: 'X', at: { pointer: '/nodes/7/code' } }),
     ]);
     if (found === undefined) throw new Error('no issue');
     const view = toIssueView(found, DOC, { locale: 'en', t, controlsOf });
     expect(view.navigation).toEqual({ kind: 'unavailable' });
     expect(view.item.unavailableReason).toBe(t('problems.notEditableHere'));
   });
+
+  it('goes to a problem outside the nodes, at Start, End or in the source', () => {
+    const found = withIssueIds([
+      issue({ code: 'OUTPUT_MISSING', at: { pointer: '/output' } }),
+      issue({ code: 'X', at: { pointer: '/tests/0' } }),
+    ]);
+    for (const each of found) {
+      const view = toIssueView(each, DOC, { locale: 'en', t, controlsOf });
+      expect(view.item.unavailableReason).toBeUndefined();
+    }
+  });
 });
 
 describe('fieldIssueMessage', () => {
@@ -332,6 +399,29 @@ describe('fieldIssueMessage', () => {
     expect(message).toContain(typeof cause === 'string' ? cause : '');
   });
 
+  it('leads with the key inside the output and the run input', () => {
+    const found = withIssueIds([
+      issue({
+        code: 'REF_UNKNOWN_NODE',
+        at: { pointer: '/output/summary' },
+        params: { ref: 'nope' },
+      }),
+      issue({
+        code: 'X',
+        message: 'a newer code',
+        at: { pointer: '/inputs/properties' },
+      }),
+    ]);
+    const [output, inputs] = found.map((each) =>
+      fieldIssueMessage(
+        toIssueView(each, DOC, { locale: 'en', t, controlsOf }),
+        t,
+      ),
+    );
+    expect(output?.startsWith('summary: ')).toBe(true);
+    expect(inputs?.startsWith('properties: ')).toBe(true);
+  });
+
   it('does not lead with the key when the cause already names it', () => {
     const [found] = withIssueIds([
       issue({
diff --git a/services/platform/app/features/automations/lib/issues.ts b/services/platform/app/features/automations/lib/issues.ts
index 322dfb6be8..0240bd12f6 100644
--- a/services/platform/app/features/automations/lib/issues.ts
+++ b/services/platform/app/features/automations/lib/issues.ts
@@ -6,9 +6,9 @@
  * An issue says where it is with an RFC 6901 pointer into the document
  * (`at.pointer`, `/nodes/2/input/to`) and, for a string, the offending range
  * inside it. Node problems are reached through the canvas and the inspector;
- * a problem elsewhere in the document (the output, the inputs schema, the
- * tests) has no control in the editor, so its row says so instead of going
- * anywhere.
+ * the run input's schema through Start, the output through End; a problem
+ * anywhere else in the document (the tests, the name) in the Source view, at
+ * the place it names.
  */
 
 import type { IssueItem } from '@tale/ui/issue-list';
@@ -42,6 +42,23 @@ export type IssueNavigation =
       range?: readonly [number, number];
     }
   | { kind: 'node'; nodeId: string; nodeIndex: number }
+  /** The run input's schema, in Start's inspector, or the output, in
+   *  End's: `anchor` is the issue's pointer under `/inputs` or `/output`. */
+  | {
+      kind: 'start' | 'end';
+      anchor: string;
+      range?: readonly [number, number];
+    }
+  /** A part of the document without a control (the tests, the name): the
+   *  Source view, at the place `pointer` names. */
+  | {
+      kind: 'source';
+      pointer: string;
+      range?: readonly [number, number];
+      subject?: 'value' | 'key' | 'missing';
+    }
+  /** A node the document on screen no longer has (the check is older than
+   *  the edit that removed it): there is nowhere to go. */
   | { kind: 'unavailable' };
 
 /** One issue as every surface of the editor needs it. */
@@ -208,20 +225,58 @@ export function issueCountsByNode(
 }
 
 /**
- * Where "go to" takes the reader: the field's control when the inspector has
- * one for it, else the node (its own list of problems sits at the top of the
- * inspector), and nowhere for a part of the document the editor does not
- * edit. A member name that should not be there (an unknown field) has no
- * control by definition, so it goes to the node.
+ * Where "go to" takes the reader: Start's inspector for the run input's
+ * schema, End's for the output; in a node, the field's control when the
+ * inspector has one for it, else the node (its own list of problems sits at
+ * the top of the inspector); and the Source view for every other part of
+ * the document. A member name that should not be there (an unknown field)
+ * has no control by definition, so it goes to the node.
  */
 export function issueNavigation(
   issue: WireAutomationIssue,
   doc: Automation,
   controlsOf: FieldControls,
 ): IssueNavigation {
+  const pointer = pointerOf(issue);
+  const [section] = pointerTokens(pointer);
+  const range = issue.at?.range;
+  // The run input's schema is edited on Start, and a schedule whose input
+  // the schema refuses is fixed there too.
+  if (section === 'inputs' || issue.code === 'TRIGGER_INPUT_MISMATCH') {
+    return {
+      kind: 'start',
+      anchor: section === 'inputs' ? pointer : '/inputs',
+      ...(range !== undefined && { range }),
+    };
+  }
+  if (section === 'output') {
+    return {
+      kind: 'end',
+      anchor: pointer,
+      ...(range !== undefined && { range }),
+    };
+  }
   const found = nodeOf(issue, doc);
-  if (found === null) return NO_NAVIGATION;
-  const { node, index } = found;
+  if (found !== null) return nodeNavigation(issue, found, controlsOf);
+  const tokens = pointerTokens(pointer);
+  // A node the document on screen does not have at that place: the check
+  // answered for an older draft, and its pointer names nothing here.
+  if (section === 'nodes' && tokens.length > 1) return NO_NAVIGATION;
+  const subject = issue.at?.subject;
+  return {
+    kind: 'source',
+    pointer,
+    ...(range !== undefined && { range }),
+    ...(subject !== undefined && { subject }),
+  };
+}
+
+/** Where "go to" takes the reader for a problem in or about a node. */
+function nodeNavigation(
+  issue: WireAutomationIssue,
+  { node, index }: { node: NodeDef; index: number },
+  controlsOf: FieldControls,
+): IssueNavigation {
   const pointer = pointerOf(issue);
   const tokens = pointerTokens(pointer);
   const inNode =
@@ -351,8 +406,19 @@ export function fieldIssueMessage(
       : typeof explanation === 'string'
         ? explanation
         : '';
-  if (view.navigation.kind !== 'field') return cause;
-  const [, , , ...rest] = pointerTokens(view.navigation.anchor);
+  const { navigation } = view;
+  if (
+    navigation.kind !== 'field' &&
+    navigation.kind !== 'start' &&
+    navigation.kind !== 'end'
+  ) {
+    return cause;
+  }
+  // The keys below the field: under `/nodes/<i>/<field>`, or under
+  // `/inputs` and `/output`.
+  const rest = pointerTokens(navigation.anchor).slice(
+    navigation.kind === 'field' ? 3 : 1,
+  );
   if (rest.length === 0) return cause;
   const part = rest.join('.');
   // "The input "to" of …" says the key itself; "to: " before it would say
diff --git a/services/platform/app/features/automations/lib/yaml-source.test.ts b/services/platform/app/features/automations/lib/yaml-source.test.ts
new file mode 100644
index 0000000000..c282fd6a95
--- /dev/null
+++ b/services/platform/app/features/automations/lib/yaml-source.test.ts
@@ -0,0 +1,89 @@
+import { locateYamlPointer } from '@tale/ui/code-editor/locate';
+import { describe, expect, it } from 'vitest';
+import { parse } from 'yaml';
+
+import { sourceFileName, yamlSource } from './yaml-source';
+
+const DOCUMENT = {
+  version: 1,
+  name: 'support/triage',
+  description: 'Sorts the inbox: "urgent" first.',
+  inputs: {
+    type: 'object',
+    properties: { owner: { type: 'string' } },
+    required: ['owner'],
+  },
+  nodes: [
+    {
+      id: 'score',
+      type: 'transform',
+      code: 'const n = input.items.length;\nreturn { n };\n',
+      input: { items: '{{ nodes.fetch.output }}' },
+      // A key this build has no control for stays where it was written.
+      credential: 'github-main',
+    },
+    {
+      id: 'reply',
+      type: 'llm',
+      prompt: 'Line one\n  indented line\n\nLast: {{ nodes.score.output.n }}',
+      when: '{{ nodes.score.output.n > 0 }}',
+    },
+  ],
+  output: { summary: '{{ nodes.reply.output }}', empty: null, flags: [] },
+  tests: [{ name: 'empty inbox', input: { owner: 'acme' } }],
+  ui: { positions: { score: { x: 0, y: 0 } } },
+};
+
+describe('yamlSource', () => {
+  it('reads back as the document, key for key and value for value', () => {
+    expect(parse(yamlSource(DOCUMENT))).toEqual(DOCUMENT);
+  });
+
+  it('gives the same text for the same document every time', () => {
+    expect(yamlSource(DOCUMENT)).toBe(yamlSource(structuredClone(DOCUMENT)));
+  });
+
+  it('keeps the stored key order and every key, ui and tests included', () => {
+    const text = yamlSource(DOCUMENT);
+    const topLevel = [...text.matchAll(/^([a-z]+):/gm)].map(
+      (match) => match[1],
+    );
+    expect(topLevel).toEqual(Object.keys(DOCUMENT));
+    expect(text).toContain('credential: github-main');
+  });
+
+  it('writes multi-line code and prompts as literal blocks, never folded', () => {
+    const text = yamlSource(DOCUMENT);
+    expect(text).toContain('code: |\n');
+    expect(text).toContain('      const n = input.items.length;\n');
+    const long = {
+      name: 'a',
+      nodes: [{ id: 'x', type: 'llm', prompt: 'word '.repeat(60).trim() }],
+    };
+    const line = yamlSource(long)
+      .split('\n')
+      .find((each) => each.includes('prompt:'));
+    expect(line).toBe(`    prompt: ${'word '.repeat(60).trim()}`);
+  });
+
+  it('places a problem at the characters it names', () => {
+    const text = yamlSource(DOCUMENT);
+    const located = locateYamlPointer(text, '/nodes/1/when', { range: [3, 8] });
+    expect(located).not.toBeNull();
+    expect(text.slice(located?.from, located?.to)).toBe('nodes');
+    const test = locateYamlPointer(text, '/tests/0/name');
+    expect(text.slice(test?.from, test?.to)).toBe('empty inbox');
+  });
+});
+
+describe('sourceFileName', () => {
+  it('names the file after the automation, its version and a draft', () => {
+    expect(sourceFileName('support/triage', 4, false)).toBe(
+      'support__triage-v4.yml',
+    );
+    expect(sourceFileName('support/triage', 4, true)).toBe(
+      'support__triage-v4-draft.yml',
+    );
+    expect(sourceFileName('triage', undefined, true)).toBe('triage-draft.yml');
+  });
+});
diff --git a/services/platform/app/features/automations/lib/yaml-source.ts b/services/platform/app/features/automations/lib/yaml-source.ts
new file mode 100644
index 0000000000..dffddc07b1
--- /dev/null
+++ b/services/platform/app/features/automations/lib/yaml-source.ts
@@ -0,0 +1,49 @@
+/**
+ * The Source view's text: the document as YAML, the way an author or a
+ * coding agent writes it — every key in the order it is stored, `ui` and
+ * `tests` included, multi-line code and prompts as literal blocks, no line
+ * ever folded. The same document always gives the same text, so a problem's
+ * pointer is found in it (`locateYamlPointer`) at the same place on every
+ * render, and the text parses back to the document.
+ */
+
+import { stringify } from 'yaml';
+
+import { automationSlugToParam } from '@/lib/automations/slug';
+
+import type { RawDocument } from './draft-document';
+
+/**
+ * Where "go to" lands in the Source view. Apart from the inspector's
+ * anchors (document pointers, `/nodes/2/prompt`) so a problem in a field
+ * never goes to the Source view's text instead of the field's control.
+ */
+export const SOURCE_ISSUE_ANCHOR = '#source';
+
+/** The document as the Source view shows it. */
+export function yamlSource(document: RawDocument): string {
+  return stringify(document, {
+    schema: 'core',
+    indent: 2,
+    lineWidth: 0,
+    blockQuote: 'literal',
+    // A value the document repeats is written out each time, never as an
+    // anchor and alias the author did not write.
+    aliasDuplicateObjects: false,
+  });
+}
+
+/**
+ * The name a downloaded Source gets: the automation's name with its folders
+ * joined by `__` (as in its address), the version, and `-draft` when the
+ * text holds unsaved edits.
+ */
+export function sourceFileName(
+  automationSlug: string,
+  version: number | undefined,
+  isDraft: boolean,
+): string {
+  const base = automationSlugToParam(automationSlug);
+  const versioned = version === undefined ? base : `${base}-v${version}`;
+  return `${versioned}${isDraft ? '-draft' : ''}.yml`;
+}
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index 60b0c9c399..77abf7c688 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -215,6 +215,7 @@ canvas:
     label: Ansicht
     canvas: Canvas
     list: Liste
+    source: Quelltext
   legend:
     data: 'Durchgezogene Linie: liest die Ausgabe der Node darüber'
     control: 'Gestrichelte Linie: läuft danach, ohne ihre Ausgabe zu lesen'
@@ -298,6 +299,19 @@ editor:
       fields: Felder
       shape: Struktur
       run: Letzter Lauf
+  start:
+    title: Start
+    description: Was diese Automatisierung startet und was jeder Lauf erhält.
+    trigger: Trigger
+    editTrigger: In Allgemein ändern
+    inputs: Eingaben
+    schema: Eingabeschema
+    inputsDescription: Die Daten, die jeder Lauf erhält, als JSON-Schema. Ein Lauf mit unpassender Eingabe wird abgelehnt, bevor eine Node läuft.
+  end:
+    title: Ende
+    description: Was ein erfolgreicher Lauf zurückgibt und wie ein Lauf enden kann.
+    outputDescription: Ein JSON-Wert. Lies Node-Ausgaben mit Templates, etwa '{{' nodes.report.output '}}'.
+    outcomes: Wie ein Lauf endet
   flow:
     title: Wann sie läuft
     always: Bei jedem Lauf
@@ -726,6 +740,11 @@ failureReason:
   iteration: ihre Liste nicht durchlaufen werden kann
   inputContract: ihre Eingabe abgelehnt wird
   subautomation: die aufgerufene Automatisierung fehlschlägt
+source:
+  ariaLabel: Quelltext dieser Automatisierung (YAML)
+  copy: YAML kopieren
+  download: YAML herunterladen
+  readOnlyHint: Um das Dokument zu ändern, nutze die Felder oder deinen Coding-Agent.
 codingAgent:
   button: Mit deinem Coding-Agent bearbeiten
   body: Coding-Agents wie Claude Code, Codex und Cursor ändern Automatisierungen über den MCP-Server von Tale. Sie lesen diese Automatisierung, ändern und prüfen sie und speichern eine neue Version, die dann hier erscheint.
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index 5a0fab3d92..5276b2fd3e 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -211,6 +211,7 @@ canvas:
     label: View
     canvas: Canvas
     list: List
+    source: Source
   legend:
     data: 'Solid line: reads the output of the node above'
     control: 'Dashed line: runs after it, without reading its output'
@@ -291,6 +292,19 @@ editor:
       fields: Fields
       shape: Shape
       run: Last run
+  start:
+    title: Start
+    description: What starts this automation and what each run receives.
+    trigger: Trigger
+    editTrigger: Change in General
+    inputs: Inputs
+    schema: Input schema
+    inputsDescription: "The data each run receives, as a JSON Schema. A run whose input doesn't match is refused before any node runs."
+  end:
+    title: End
+    description: What a successful run returns, and how a run can end.
+    outputDescription: A JSON value. Read node outputs with templates, such as '{{' nodes.report.output '}}'.
+    outcomes: How a run ends
   flow:
     title: When it runs
     always: On every run
@@ -716,6 +730,11 @@ failureReason:
   iteration: "its list can't be gone through"
   inputContract: its input is refused
   subautomation: the automation it calls fails
+source:
+  ariaLabel: Source of this automation (YAML)
+  copy: Copy YAML
+  download: Download YAML
+  readOnlyHint: To change the document, use the fields or your coding agent.
 codingAgent:
   button: Edit with your coding agent
   body: Coding agents such as Claude Code, Codex and Cursor change automations through Tale's MCP server. They read this automation, change and check it, and save a new version, which then appears here.
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index c29160dcac..1a1bc1f858 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -215,6 +215,7 @@ canvas:
     label: Vue
     canvas: Canevas
     list: Liste
+    source: Source
   legend:
     data: 'Trait plein : lit la sortie du nœud au-dessus'
     control: 'Trait tireté : s’exécute après lui, sans lire sa sortie'
@@ -297,6 +298,19 @@ editor:
       fields: Champs
       shape: Structure
       run: Dernière exécution
+  start:
+    title: Début
+    description: Ce qui démarre cette automatisation et ce que reçoit chaque exécution.
+    trigger: Déclencheur
+    editTrigger: Modifier dans Général
+    inputs: Entrées
+    schema: Schéma d’entrée
+    inputsDescription: Les données que reçoit chaque exécution, sous forme de schéma JSON. Une exécution dont l’entrée ne correspond pas est refusée avant qu’un nœud ne s’exécute.
+  end:
+    title: Fin
+    description: Ce que renvoie une exécution réussie, et comment une exécution peut se terminer.
+    outputDescription: Une valeur JSON. Lis les sorties des nœuds avec des templates, par exemple '{{' nodes.report.output '}}'.
+    outcomes: Comment une exécution se termine
   flow:
     title: Quand il s’exécute
     always: À chaque exécution
@@ -728,6 +742,11 @@ failureReason:
   iteration: sa liste ne peut pas être parcourue
   inputContract: son entrée est refusée
   subautomation: l’automatisation appelée échoue
+source:
+  ariaLabel: Source de cette automatisation (YAML)
+  copy: Copier le YAML
+  download: Télécharger le YAML
+  readOnlyHint: Pour modifier le document, utilise les champs ou ton agent de code.
 codingAgent:
   button: Modifier avec ton agent de code
   body: Les agents de code comme Claude Code, Codex et Cursor modifient les automatisations via le serveur MCP de Tale. Ils lisent cette automatisation, la modifient, la vérifient et enregistrent une nouvelle version, qui apparaît ensuite ici.

From 42e935dc1f370e87dc397b846ddfd297d0ecb5ad Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:34:54 +0200
Subject: [PATCH 49/78] refactor(platform): label Start's schema field as the
 run dialog does

Start's JSON Schema field and the run dialog's schema disclosure name the same thing; they now share one string in every language instead of two that had drifted apart in French.
---
 .../app/features/automations/components/start-inspector.tsx     | 2 +-
 services/platform/messages/de/automations.yml                   | 1 -
 services/platform/messages/en/automations.yml                   | 1 -
 services/platform/messages/fr/automations.yml                   | 1 -
 4 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/services/platform/app/features/automations/components/start-inspector.tsx b/services/platform/app/features/automations/components/start-inspector.tsx
index 94749a4eeb..d20d9070da 100644
--- a/services/platform/app/features/automations/components/start-inspector.tsx
+++ b/services/platform/app/features/automations/components/start-inspector.tsx
@@ -102,7 +102,7 @@ export function StartFields({
       </section>
       <DocumentJsonField
         field="inputs"
-        label={t('editor.start.schema')}
+        label={t('detail.runInput.schema')}
         description={t('editor.start.inputsDescription')}
         expect="object"
         value={inputs}
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index 77abf7c688..04e7959a62 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -305,7 +305,6 @@ editor:
     trigger: Trigger
     editTrigger: In Allgemein ändern
     inputs: Eingaben
-    schema: Eingabeschema
     inputsDescription: Die Daten, die jeder Lauf erhält, als JSON-Schema. Ein Lauf mit unpassender Eingabe wird abgelehnt, bevor eine Node läuft.
   end:
     title: Ende
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index 5276b2fd3e..8f0006b7a1 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -298,7 +298,6 @@ editor:
     trigger: Trigger
     editTrigger: Change in General
     inputs: Inputs
-    schema: Input schema
     inputsDescription: "The data each run receives, as a JSON Schema. A run whose input doesn't match is refused before any node runs."
   end:
     title: End
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index 1a1bc1f858..f23cb06c67 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -304,7 +304,6 @@ editor:
     trigger: Déclencheur
     editTrigger: Modifier dans Général
     inputs: Entrées
-    schema: Schéma d’entrée
     inputsDescription: Les données que reçoit chaque exécution, sous forme de schéma JSON. Une exécution dont l’entrée ne correspond pas est refusée avant qu’un nœud ne s’exécute.
   end:
     title: Fin

From 7ce5726f4659fb6141cbdb498e607d0c32a39322 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:37:05 +0200
Subject: [PATCH 50/78] feat(platform): type a run's input in the code editor

The run dialog's JSON input is the code editor: highlighted, marked
where it stops being JSON, offering the fields the version's input
schema declares as their keys are typed, each with its kind, and
starting the run on Mod-Enter once the input is one the run takes.
The schema under it reads as a tree of fields instead of raw JSON.
---
 .../components/automation-run-dialog.test.tsx | 53 +++++++++++++
 .../components/automation-run-dialog.tsx      | 52 ++++++++++---
 .../lib/run-input-completion.test.ts          | 76 +++++++++++++++++++
 .../automations/lib/run-input-completion.ts   | 76 +++++++++++++++++++
 4 files changed, 245 insertions(+), 12 deletions(-)
 create mode 100644 services/platform/app/features/automations/lib/run-input-completion.test.ts
 create mode 100644 services/platform/app/features/automations/lib/run-input-completion.ts

diff --git a/services/platform/app/features/automations/components/automation-run-dialog.test.tsx b/services/platform/app/features/automations/components/automation-run-dialog.test.tsx
index 0b827896ca..b90d058132 100644
--- a/services/platform/app/features/automations/components/automation-run-dialog.test.tsx
+++ b/services/platform/app/features/automations/components/automation-run-dialog.test.tsx
@@ -256,3 +256,56 @@ it('keeps a custom required cursor editable through the generic JSON form', () =
     screen.getByRole('textbox', { name: 'Run input (JSON)' }),
   ).toBeVisible();
 });
+
+it('takes the run input in the code editor and starts the run on Mod-Enter', async () => {
+  const onConfirm = vi.fn();
+  const { user } = render(
+    <AutomationRunDialog
+      request={{
+        mode: 'mock',
+        version: 3,
+        scopeText: 'Organization-wide',
+        schema: {
+          type: 'object',
+          properties: { owner: { type: 'string' } },
+          required: ['owner'],
+        },
+      }}
+      onClose={() => {}}
+      onConfirm={onConfirm}
+    />,
+  );
+  const input = screen.getByRole('textbox', { name: 'Run input (JSON)' });
+  expect(input).toHaveAttribute('data-language', 'json');
+  // Not yet what the schema takes: Mod-Enter starts nothing.
+  await user.click(input);
+  await user.keyboard('{Control>}{Enter}{/Control}');
+  expect(onConfirm).not.toHaveBeenCalled();
+  await user.clear(input);
+  await user.type(input, '{{"owner": "acme"}');
+  await user.keyboard('{Control>}{Enter}{/Control}');
+  expect(onConfirm).toHaveBeenCalledWith({ owner: 'acme' });
+});
+
+it('shows the input schema as a tree of its fields', async () => {
+  const { user } = render(
+    <AutomationRunDialog
+      request={{
+        mode: 'mock',
+        version: 3,
+        scopeText: 'Organization-wide',
+        schema: {
+          type: 'object',
+          properties: { owner: { type: 'string' } },
+          required: ['owner'],
+        },
+      }}
+      onClose={() => {}}
+      onConfirm={() => {}}
+    />,
+  );
+  await user.click(screen.getByText('Input schema'));
+  const tree = screen.getByRole('list', { name: 'Input schema' });
+  expect(tree).toHaveTextContent('owner');
+  expect(tree).toHaveTextContent('required');
+});
diff --git a/services/platform/app/features/automations/components/automation-run-dialog.tsx b/services/platform/app/features/automations/components/automation-run-dialog.tsx
index dbcd4757ab..956b04cc25 100644
--- a/services/platform/app/features/automations/components/automation-run-dialog.tsx
+++ b/services/platform/app/features/automations/components/automation-run-dialog.tsx
@@ -1,17 +1,20 @@
 'use client';
 
 import { Alert } from '@tale/ui/alert';
+import { CodeEditor } from '@tale/ui/code-editor';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
 import { ConfirmDialog } from '@tale/ui/dialog/confirm-dialog';
 import { Field } from '@tale/ui/field';
+import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { SchemaTree, schemaKindLabel } from '@tale/ui/schema-tree';
 import { Text } from '@tale/ui/text';
-import { Textarea } from '@tale/ui/textarea';
 import { useId, useMemo, useState } from 'react';
 import { z } from 'zod';
 
 import { useT } from '@/lib/i18n/client';
 
 import { guidedIssueSource } from '../lib/issue-import';
+import { runInputProviders } from '../lib/run-input-completion';
 import {
   IssueImportFields,
   type IssueImportProject,
@@ -47,6 +50,8 @@ export function AutomationRunDialog({
   onConfirm: (input: unknown) => void;
 }) {
   const { t } = useT('automations');
+  const { t: tSchema } = useT('schemaTree');
+  const { locale } = useLocale();
   const inputId = useId();
   const [text, setText] = useState(() =>
     JSON.stringify(request.initialInput ?? {}, null, 2),
@@ -71,11 +76,22 @@ export function AutomationRunDialog({
       return null;
     }
   }, [request.schema]);
+  // The fields the schema declares, offered where a key of the input is
+  // typed, each with its kind.
+  const providers = useMemo(
+    () =>
+      runInputProviders(request.schema, (field) =>
+        schemaKindLabel(tSchema, field, locale),
+      ),
+    [request.schema, tSchema, locale],
+  );
   const parsed = useMemo(() => {
     let input: unknown;
     try {
       input = source === null ? JSON.parse(text) : values;
     } catch {
+      // The editor marks where the text stops being JSON; this line says
+      // nothing can start until it is.
       return { valid: false as const, error: t('detail.runInput.invalidJson') };
     }
     const checked = schema?.safeParse(input);
@@ -98,6 +114,9 @@ export function AutomationRunDialog({
     return { valid: true as const, input };
   }, [schema, text, source, values, t]);
 
+  const confirmText =
+    request.mode === 'live' ? t('detail.runLive') : t('detail.runMock');
+
   return (
     <ConfirmDialog
       open
@@ -110,9 +129,7 @@ export function AutomationRunDialog({
           ? t('detail.runLiveBody')
           : t('detail.runInput.mockDescription')
       }
-      confirmText={
-        request.mode === 'live' ? t('detail.runLive') : t('detail.runMock')
-      }
+      confirmText={confirmText}
       disableConfirm={!parsed.valid}
       isLoading={pending}
       onConfirm={() => {
@@ -157,19 +174,30 @@ export function AutomationRunDialog({
               })}
               error={parsed.valid ? undefined : parsed.error}
             >
-              <Textarea
+              <CodeEditor
                 id={inputId}
-                rows={6}
-                className="font-mono text-xs"
+                language="json"
                 value={text}
-                onChange={(event) => setText(event.target.value)}
-                spellCheck={false}
+                onChange={setText}
+                minRows={6}
+                maxRows={14}
+                providers={providers}
+                // Mod-Enter starts the run, as the dialog's button does —
+                // once the input is one the run takes.
+                onSubmit={() => {
+                  if (parsed.valid && !pending) onConfirm(parsed.input);
+                }}
+                submitLabel={confirmText}
+                describeDiagnostics={false}
               />
             </Field>
             <CollapsibleDetails summary={t('detail.runInput.schema')}>
-              <pre className="bg-muted mt-2 max-h-48 overflow-auto rounded-md p-3 text-xs">
-                {JSON.stringify(request.schema, null, 2)}
-              </pre>
+              <SchemaTree
+                schema={request.schema}
+                density="comfortable"
+                aria-label={t('detail.runInput.schema')}
+                className="mt-2"
+              />
             </CollapsibleDetails>
           </div>
         )
diff --git a/services/platform/app/features/automations/lib/run-input-completion.test.ts b/services/platform/app/features/automations/lib/run-input-completion.test.ts
new file mode 100644
index 0000000000..f25de3be18
--- /dev/null
+++ b/services/platform/app/features/automations/lib/run-input-completion.test.ts
@@ -0,0 +1,76 @@
+import type { CodeCompletionContext } from '@tale/ui/code-editor/providers';
+import { describe, expect, it } from 'vitest';
+
+import { runInputProviders } from './run-input-completion';
+
+const SCHEMA = {
+  type: 'object',
+  properties: {
+    owner: { type: 'string', description: 'The GitHub organization' },
+    limit: { type: 'integer' },
+    labels: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['owner'],
+};
+
+function at(
+  region: CodeCompletionContext['region'],
+  pointer: string | undefined,
+): CodeCompletionContext {
+  return {
+    text: '{ "o": 1 }',
+    pos: 4,
+    language: 'json',
+    region,
+    path: null,
+    prefix: 'o',
+    from: 3,
+    to: 4,
+    ...(pointer !== undefined && { pointer }),
+    explicit: false,
+    signal: new AbortController().signal,
+  };
+}
+
+const kindOf = (field: Record<string, unknown>) => `kind:${String(field.type)}`;
+
+describe('runInputProviders', () => {
+  it('offers the declared fields where a key of the input is typed', async () => {
+    const { completion } = runInputProviders(SCHEMA, kindOf);
+    const answer = await completion?.(at('key', ''));
+    expect(answer?.items).toEqual([
+      {
+        label: 'owner',
+        kind: 'input',
+        valueType: 'string',
+        detail: 'kind:string',
+        optional: false,
+        info: { description: 'The GitHub organization' },
+      },
+      {
+        label: 'limit',
+        kind: 'input',
+        valueType: 'integer',
+        detail: 'kind:integer',
+        optional: true,
+      },
+      {
+        label: 'labels',
+        kind: 'input',
+        valueType: 'array',
+        detail: 'kind:array',
+        optional: true,
+      },
+    ]);
+  });
+
+  it('offers nothing inside a value, a nested object or without fields', async () => {
+    const { completion } = runInputProviders(SCHEMA, kindOf);
+    expect(await completion?.(at('string', '/owner'))).toBeNull();
+    expect(await completion?.(at('key', '/labels'))).toBeNull();
+    const empty = runInputProviders({ type: 'object' }, kindOf);
+    expect(await empty.completion?.(at('key', ''))).toBeNull();
+    const none = runInputProviders(undefined, kindOf);
+    expect(await none.completion?.(at('key', ''))).toBeNull();
+  });
+});
diff --git a/services/platform/app/features/automations/lib/run-input-completion.ts b/services/platform/app/features/automations/lib/run-input-completion.ts
new file mode 100644
index 0000000000..10e7971491
--- /dev/null
+++ b/services/platform/app/features/automations/lib/run-input-completion.ts
@@ -0,0 +1,76 @@
+/**
+ * Completion in a run's input: the fields the version's input schema
+ * declares, offered where a key of the input object is typed. Apart from
+ * the editor's code assistance (`./code-providers`), so the run dialog
+ * never loads the canvas's modules.
+ */
+
+import type {
+  CodeCompletionItem,
+  CodeEditorProviders,
+  CodeValueType,
+} from '@tale/ui/code-editor/providers';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The kind a JSON Schema field declares, for the icon beside its name. */
+function schemaValueType(field: Record<string, unknown>): CodeValueType {
+  const type = field.type;
+  switch (type) {
+    case 'string':
+    case 'number':
+    case 'integer':
+    case 'boolean':
+    case 'object':
+    case 'array':
+    case 'null':
+      return type;
+    default:
+      return 'unknown';
+  }
+}
+
+/**
+ * Completion in a run's input, a JSON object: at its top level, the fields
+ * the version's input schema declares, each with its kind (`kindOf`, in the
+ * reader's words) and its description; one the schema does not require is
+ * marked optional.
+ */
+export function runInputProviders(
+  schema: unknown,
+  kindOf: (field: Record<string, unknown>) => string,
+): CodeEditorProviders {
+  const properties =
+    isRecord(schema) && isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(
+    isRecord(schema) && Array.isArray(schema.required)
+      ? schema.required.filter((key) => typeof key === 'string')
+      : [],
+  );
+  const items = Object.entries(properties).map(
+    ([name, value]): CodeCompletionItem => {
+      const field = isRecord(value) ? value : {};
+      const item: CodeCompletionItem = {
+        label: name,
+        kind: 'input',
+        valueType: schemaValueType(field),
+        detail: kindOf(field),
+        optional: !required.has(name),
+      };
+      if (typeof field.description === 'string') {
+        item.info = { description: field.description };
+      }
+      return item;
+    },
+  );
+  return {
+    completion: (context) =>
+      context.region === 'key' &&
+      (context.pointer ?? '') === '' &&
+      items.length > 0
+        ? { items }
+        : null,
+  };
+}

From 2e4442d55fb5327c3f76b39fd789b87d13d5db8a Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:40:46 +0200
Subject: [PATCH 51/78] build(platform): load only the code editor's packages
 with it

vendor-codemirror took every CodeMirror module in node_modules,
including every language Milkdown's code blocks reach through
@codemirror/language-data (21 grammars and the legacy modes), so the
first code field loaded 547 KB gzip of them. It now takes only what
@tale/ui/code-editor imports (the core, the JavaScript, JSON, YAML and
Markdown grammars and their helpers): 185 KB. Every other language
keeps its own lazy chunk and loads with a code block in it.

The budget check now holds the editor to that: what its view chunk
loads beyond the cold load and the chunk that imports it stays within
230 KB gzip (202 KB today), carries no HTML, CSS or legacy grammar nor
the language table, and builds no code from strings. The cold load may
no longer carry the editor's view, its syntax trees or those languages.
---
 .../scripts/check-entry-budget.test.ts        | 157 ++++++++++++-
 .../platform/scripts/check-entry-budget.ts    | 210 +++++++++++++++++-
 services/platform/vite.config.ts              |  15 +-
 3 files changed, 370 insertions(+), 12 deletions(-)

diff --git a/services/platform/scripts/check-entry-budget.test.ts b/services/platform/scripts/check-entry-budget.test.ts
index d1c56dd641..c351079dcd 100644
--- a/services/platform/scripts/check-entry-budget.test.ts
+++ b/services/platform/scripts/check-entry-budget.test.ts
@@ -1,10 +1,19 @@
-import { describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
 
 import {
+  checkLazyChunk,
+  dynamicImportersOf,
   findForbiddenPreloads,
   forbiddenPackagesIn,
   forbiddenSourcesIn,
   parsePreloadedScripts,
+  staticClosure,
+  staticImportsOf,
+  type LazyBudget,
 } from './check-entry-budget.ts';
 
 const HTML = `<!doctype html><html><head>
@@ -89,6 +98,26 @@ describe('forbiddenPackagesIn', () => {
     ]);
   });
 
+  it("names the code editor's view and syntax trees, and the languages only code blocks read", () => {
+    expect(
+      forbiddenPackagesIn([
+        '../../../../node_modules/@codemirror/view/dist/index.js',
+        '../../../../node_modules/@lezer/common/dist/index.js',
+        '../../../../node_modules/@codemirror/lang-html/dist/index.js',
+        '../../../../node_modules/@codemirror/legacy-modes/mode/shell.js',
+        '../../../../node_modules/@codemirror/language-data/dist/index.js',
+        // The highlight tags the read-only code blocks share are fine.
+        '../../../../node_modules/@lezer/highlight/dist/index.js',
+      ]),
+    ).toEqual([
+      '@codemirror/view',
+      '@lezer/common',
+      '@codemirror/lang-html',
+      '@codemirror/legacy-modes',
+      '@codemirror/language-data',
+    ]);
+  });
+
   it('passes a chunk that only shares their names or helpers', () => {
     expect(
       forbiddenPackagesIn([
@@ -142,3 +171,129 @@ describe('forbiddenSourcesIn', () => {
     ).toEqual([]);
   });
 });
+
+describe('staticImportsOf', () => {
+  it('reads the static imports and re-exports of a built chunk, not its dynamic ones', () => {
+    const source = [
+      'import{t as e}from"./vendor-core-abc.js";',
+      'import"./side-effect-def.js";',
+      'export{a as b}from"../assets/re-export-ghi.js";',
+      'import * as n from "./namespace-jkl.js"',
+      'const later=()=>import("./lazy-mno.js");',
+    ].join('');
+    expect(staticImportsOf(source, 'assets/code-editor-view-x.js')).toEqual([
+      'assets/vendor-core-abc.js',
+      'assets/side-effect-def.js',
+      'assets/re-export-ghi.js',
+      'assets/namespace-jkl.js',
+    ]);
+  });
+});
+
+describe('staticClosure', () => {
+  it('follows every static import once, the start first', () => {
+    const files: Record<string, string> = {
+      'assets/a.js': 'import"./b.js";import"./c.js";',
+      'assets/b.js': 'import"./c.js";',
+      'assets/c.js': 'import"./a.js";const x=()=>import("./d.js");',
+    };
+    expect(staticClosure('assets/a.js', (url) => files[url] ?? '')).toEqual([
+      'assets/a.js',
+      'assets/b.js',
+      'assets/c.js',
+    ]);
+  });
+});
+
+describe('dynamicImportersOf', () => {
+  it('names the chunks that load one with import(), whatever their quotes', () => {
+    const files: Record<string, string> = {
+      'assets/a.js': 'const v=()=>h(()=>import(`./view-x.js`),[]);',
+      'assets/b.js': "import('./view-x.js')",
+      'assets/c.js': 'import"./view-x.js";',
+      'assets/view-x.js': '',
+    };
+    expect(
+      dynamicImportersOf(
+        'assets/view-x.js',
+        Object.keys(files),
+        (url) => files[url] ?? '',
+      ),
+    ).toEqual(['assets/a.js', 'assets/b.js']);
+  });
+});
+
+describe('checkLazyChunk', () => {
+  const dists: string[] = [];
+  afterEach(() => {
+    for (const dist of dists.splice(0)) rmSync(dist, { recursive: true });
+  });
+
+  /** A built dist with these chunks and source maps. */
+  function distWith(files: Record<string, string>): string {
+    const dist = mkdtempSync(join(tmpdir(), 'entry-budget-'));
+    dists.push(dist);
+    mkdirSync(join(dist, 'assets'));
+    for (const [path, text] of Object.entries(files)) {
+      writeFileSync(join(dist, path), text);
+    }
+    return dist;
+  }
+
+  const budget: LazyBudget = {
+    name: 'code-editor-view',
+    maxGzip: 2048,
+    packages: ['@codemirror/language-data'],
+    text: ['eval(', 'new Function('],
+  };
+
+  it('counts what the chunk adds to the cold load and to its importer, and passes a clean one', () => {
+    const dist = distWith({
+      // The light editor's chunk loads the view, and has the helpers both
+      // read already.
+      'assets/inspector-d4.js':
+        'import"./helpers-e5.js";const v=()=>import(`./code-editor-view-a1.js`);',
+      'assets/helpers-e5.js': 'export const locate=1;',
+      'assets/code-editor-view-a1.js':
+        'import"./vendor-codemirror-b2.js";import"./vendor-core-c3.js";import"./helpers-e5.js";',
+      'assets/vendor-codemirror-b2.js': 'export const view=1;',
+      'assets/vendor-core-c3.js': 'export const react=1;',
+    });
+    const report = checkLazyChunk(dist, ['assets/vendor-core-c3.js'], budget);
+    expect(report.chunks).toEqual([
+      'assets/code-editor-view-a1.js',
+      'assets/vendor-codemirror-b2.js',
+    ]);
+    expect(report.gzip).toBeGreaterThan(0);
+    expect(report.problems).toEqual([]);
+  });
+
+  it('names a size over the budget, a forbidden package and code built from strings', () => {
+    const big = Array.from({ length: 4000 }, (_, index) => `v${index * 7919}`);
+    const dist = distWith({
+      'assets/code-editor-view-a1.js': `import"./vendor-codemirror-b2.js";const x=${JSON.stringify(big)};`,
+      'assets/vendor-codemirror-b2.js': 'const f=new Function("return 1");',
+      'assets/vendor-codemirror-b2.js.map': JSON.stringify({
+        sources: [
+          '../../../../node_modules/@codemirror/language-data/dist/index.js',
+        ],
+      }),
+    });
+    const { problems } = checkLazyChunk(dist, [], budget);
+    expect(problems).toHaveLength(3);
+    expect(problems[0]).toMatch(/KB gzip, over its 2 KB/);
+    expect(problems).toContain(
+      'assets/vendor-codemirror-b2.js holds new Function(',
+    );
+    expect(problems).toContain(
+      'assets/vendor-codemirror-b2.js carries @codemirror/language-data',
+    );
+  });
+
+  it('says so when the chunk was not built', () => {
+    const dist = distWith({ 'assets/index-a1.js': '' });
+    expect(checkLazyChunk(dist, [], budget).problems).toEqual([
+      'no code-editor-view chunk was built',
+    ]);
+  });
+});
diff --git a/services/platform/scripts/check-entry-budget.ts b/services/platform/scripts/check-entry-budget.ts
index c47334c3b9..7653dbde39 100644
--- a/services/platform/scripts/check-entry-budget.ts
+++ b/services/platform/scripts/check-entry-budget.ts
@@ -13,11 +13,15 @@
  * route's code loads with its route (`ENTRY_ROUTES` in `vite.config.ts`), and
  * a static import from the entry would bring one back to every page.
  *
+ * The code editor is held to a budget of its own: what its lazy view chunk
+ * loads beyond the cold load (`LAZY_BUDGETS`) — the editor's packages and
+ * nothing more, no other language's grammar, no code built from strings.
+ *
  * Usage (from `services/platform`): `bun scripts/check-entry-budget.ts [dist]`
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { gzipSync } from 'node:zlib';
 
 /** Vendor chunks that must never be in the cold-load preload set. */
@@ -42,6 +46,14 @@ export const FORBIDDEN_PRELOADS = [
  * the entry fails the build.
  */
 export const FORBIDDEN_PACKAGES = [
+  // The code editor: its view and the syntax trees load with the first
+  // code field, and the languages only the message editor's code blocks
+  // read load with a block in that language.
+  '@codemirror/view',
+  '@lezer/common',
+  '@codemirror/lang-html',
+  '@codemirror/legacy-modes',
+  '@codemirror/language-data',
   'recharts',
   '@xyflow/react',
   'elkjs',
@@ -98,13 +110,21 @@ export function findForbiddenPreloads(urls: string[]): string[] {
   return matching(urls, FORBIDDEN_PRELOADS);
 }
 
-/** The forbidden packages a source map's `sources` name, each once. */
-export function forbiddenPackagesIn(sources: readonly string[]): string[] {
-  return FORBIDDEN_PACKAGES.filter((name) =>
+/** Which of `names` a source map's `sources` name, each once. */
+function packagesIn(
+  sources: readonly string[],
+  names: readonly string[],
+): string[] {
+  return names.filter((name) =>
     sources.some((source) => source.includes(`node_modules/${name}/`)),
   );
 }
 
+/** The forbidden packages a source map's `sources` name, each once. */
+export function forbiddenPackagesIn(sources: readonly string[]): string[] {
+  return packagesIn(sources, FORBIDDEN_PACKAGES);
+}
+
 /**
  * The forbidden sources a source map names: its `sources` resolve from the
  * map's folder, the forbidden paths from the service root.
@@ -154,6 +174,167 @@ export function gzipTotal(dist: string, urls: string[]): number {
   return total;
 }
 
+/** A lazy chunk whose static closure is held to a size and a content. */
+export interface LazyBudget {
+  /** The chunk's name, as the build prefixes its file (`code-editor-view-…`). */
+  name: string;
+  /** Gzip bytes it may load beyond the cold load. */
+  maxGzip: number;
+  /** Packages none of its chunks may carry. */
+  packages: readonly string[];
+  /** Text none of its chunks may hold. */
+  text: readonly string[];
+}
+
+export const LAZY_BUDGETS: readonly LazyBudget[] = [
+  {
+    // The code editor: CodeMirror's core, its JavaScript, JSON and YAML
+    // grammars, and the view module.
+    name: 'code-editor-view',
+    maxGzip: 230 * 1024,
+    // Languages only the message editor's code blocks read, and the table
+    // that imports every one of them.
+    packages: [
+      '@codemirror/lang-html',
+      '@codemirror/lang-css',
+      '@codemirror/legacy-modes',
+      '@codemirror/language-data',
+    ],
+    // The production CSP has no `unsafe-eval`.
+    text: ['eval(', 'new Function('],
+  },
+];
+
+/**
+ * The chunks a built chunk imports statically (`import … from "./x.js"`,
+ * `import "./x.js"`, `export … from "./x.js"`), as paths from `dist`; a
+ * dynamic `import("./x.js")` loads later and is not one of them.
+ */
+export function staticImportsOf(source: string, url: string): string[] {
+  const dir = dirname(url);
+  const found = new Set<string>();
+  for (const match of source.matchAll(
+    /(?:^|[;\s}])(?:import|export)\s*(?:[\w$*{}\s,]*?\bfrom\s*)?["'](\.{1,2}\/[^"']+)["']/g,
+  )) {
+    const path = match[1];
+    if (path !== undefined) found.add(join(dir, path));
+  }
+  return [...found];
+}
+
+/** `start` and every chunk it imports statically, each once, `start` first. */
+export function staticClosure(
+  start: string,
+  read: (url: string) => string,
+): string[] {
+  const seen = new Set<string>([start]);
+  const queue = [start];
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    for (const url of staticImportsOf(read(next), next)) {
+      if (seen.has(url)) continue;
+      seen.add(url);
+      queue.push(url);
+    }
+  }
+  return [...seen];
+}
+
+/** The chunks that load `url` with a dynamic `import()`. */
+export function dynamicImportersOf(
+  url: string,
+  files: readonly string[],
+  read: (url: string) => string,
+): string[] {
+  const name = url.slice(url.lastIndexOf('/') + 1);
+  const forms = ['`', "'", '"'].map(
+    (quote) => `import(${quote}./${name}${quote})`,
+  );
+  return files.filter((file) => {
+    if (file === url) return false;
+    const text = read(file);
+    return forms.some((form) => text.includes(form));
+  });
+}
+
+/** What a lazy chunk loads beyond the cold load, and what is wrong with it. */
+export interface LazyReport {
+  name: string;
+  /** Its chunks that neither the cold load nor the chunks importing it
+   *  have already loaded. */
+  chunks: string[];
+  gzip: number;
+  problems: string[];
+}
+
+/**
+ * Hold one lazy chunk to its budget: the chunks its static closure adds to
+ * what is loaded by the time it is asked for — the cold load (`preloaded`)
+ * and whatever every chunk that imports it brings — their gzip size, the
+ * packages their source maps name and the text they hold.
+ */
+export function checkLazyChunk(
+  dist: string,
+  preloaded: readonly string[],
+  budget: LazyBudget,
+): LazyReport {
+  const files = readdirSync(resolve(dist, 'assets'))
+    .filter((file) => file.endsWith('.js'))
+    .map((file) => `assets/${file}`);
+  const start = files.filter((file) =>
+    file.startsWith(`assets/${budget.name}-`),
+  );
+  const [first] = start;
+  if (first === undefined || start.length > 1) {
+    return {
+      name: budget.name,
+      chunks: [],
+      gzip: 0,
+      problems: [
+        first === undefined
+          ? `no ${budget.name} chunk was built`
+          : `more than one ${budget.name} chunk: ${start.join(', ')}`,
+      ],
+    };
+  }
+  const read = (url: string) => readFileSync(resolve(dist, url), 'utf8');
+  // Loaded already, whichever chunk asks for it: what every importer
+  // needs before it can.
+  const importerClosures = dynamicImportersOf(first, files, read).map(
+    (importer) => new Set(staticClosure(importer, read)),
+  );
+  const [firstClosure, ...otherClosures] = importerClosures;
+  const loaded = new Set(
+    [...(firstClosure ?? [])].filter((url) =>
+      otherClosures.every((closure) => closure.has(url)),
+    ),
+  );
+  const chunks = staticClosure(first, read).filter(
+    (url) => !preloaded.includes(url) && !loaded.has(url),
+  );
+  const gzip = gzipTotal(dist, chunks);
+  const problems: string[] = [];
+  if (gzip > budget.maxGzip) {
+    problems.push(
+      `${(gzip / 1024).toFixed(0)} KB gzip, over its ${(budget.maxGzip / 1024).toFixed(0)} KB`,
+    );
+  }
+  for (const url of chunks) {
+    const text = read(url);
+    for (const needle of budget.text) {
+      if (text.includes(needle)) problems.push(`${url} holds ${needle}`);
+    }
+    const mapPath = resolve(dist, `${url}.map`);
+    if (!existsSync(mapPath)) continue;
+    const map = JSON.parse(readFileSync(mapPath, 'utf8')) as {
+      sources?: string[];
+    };
+    for (const name of packagesIn(map.sources ?? [], budget.packages)) {
+      problems.push(`${url} carries ${name}`);
+    }
+  }
+  return { name: budget.name, chunks, gzip, problems };
+}
+
 if (import.meta.main) {
   const dist = resolve(process.argv[2] ?? 'dist');
   const urls = parsePreloadedScripts(
@@ -171,11 +352,28 @@ if (import.meta.main) {
   console.log(
     `Cold-load JS: ${urls.length} preloaded modules, ${(total / 1024).toFixed(0)} KB gzip`,
   );
+  let failed = false;
   if (forbidden.length > 0) {
     console.error(
       'Chunks that must stay behind a dynamic import are preloaded:',
     );
     for (const url of forbidden) console.error(`  - ${url}`);
-    process.exit(1);
+    failed = true;
+  }
+  for (const budget of LAZY_BUDGETS) {
+    const report = checkLazyChunk(dist, urls, budget);
+    console.log(
+      `Lazy ${report.name}: ${report.chunks.length} chunks beyond what loads it, ${(report.gzip / 1024).toFixed(0)} KB gzip (budget ${(budget.maxGzip / 1024).toFixed(0)} KB)`,
+    );
+    for (const url of report.chunks) {
+      const size = gzipTotal(dist, [url]);
+      console.log(`  ${url} ${(size / 1024).toFixed(1)} KB`);
+    }
+    if (report.problems.length > 0) {
+      console.error(`${report.name} is over its budget:`);
+      for (const problem of report.problems) console.error(`  - ${problem}`);
+      failed = true;
+    }
   }
+  if (failed) process.exit(1);
 }
diff --git a/services/platform/vite.config.ts b/services/platform/vite.config.ts
index f054447f98..c0b006bb67 100644
--- a/services/platform/vite.config.ts
+++ b/services/platform/vite.config.ts
@@ -138,6 +138,10 @@ function coreChunk(id: string): string | null {
   return null;
 }
 
+/** What `@tale/ui/code-editor` loads, and nothing else of CodeMirror's. */
+const CODE_EDITOR_PACKAGES =
+  /\/node_modules\/(?:@codemirror\/(?:state|view|language|commands|autocomplete|lint|search|lang-javascript|lang-json|lang-yaml)|@lezer\/(?:common|highlight|lr|javascript|json|yaml|markdown)|style-mod|w3c-keyname|crelt|@marijn\/find-cluster-break)\//;
+
 /** The vendor chunk a dependency belongs to; `null` leaves it to the default chunking. */
 function vendorChunk(id: string): string | null {
   if (!id.includes('node_modules')) {
@@ -166,11 +170,12 @@ function vendorChunk(id: string): string | null {
   if (id.includes('/node_modules/katex/')) {
     return 'vendor-katex';
   }
-  if (
-    id.includes('codemirror') ||
-    id.includes('@codemirror') ||
-    id.includes('@lezer')
-  ) {
+  // The code editor's own packages: CodeMirror's core, the grammars the
+  // editor reads (JavaScript, JSON, YAML, Markdown) and their helpers. The
+  // other languages (Milkdown's code blocks reach every one through
+  // `@codemirror/language-data`) keep the default chunking, one lazy chunk
+  // per language; grouped here, the first code field loaded them all.
+  if (CODE_EDITOR_PACKAGES.test(id)) {
     return 'vendor-codemirror';
   }
   if (id.includes('lucide-react')) {

From 5a6d26a899ebc07f7a3214d9e7db2ddb9f377f6f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:47:11 +0200
Subject: [PATCH 52/78] test(platform): prove code fields, Start, End and
 Source in Chromium

The editor's real code editor, laid out by a browser: a code field
offers only the nodes that run before it, Expand brings an edit back
to the field, and on a phone Escape closes the suggestions, then arms
leaving, then the node sheet. Start's schema and End's output are
edited and saved with the document, a problem in the document's name
is gone to on its line in the Source view, and the view switch keeps
its three choices at least 24px wide on a phone.
---
 .../automation-editor.browser.test.tsx        | 188 +++++++++++++++++-
 1 file changed, 186 insertions(+), 2 deletions(-)

diff --git a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
index 01feab58ed..938937d9e3 100644
--- a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
@@ -37,7 +37,7 @@ import '@/app/globals.css';
  * cuts those controls off first.
  */
 
-const { automation, check } = vi.hoisted(() => {
+const { automation, check, saved } = vi.hoisted(() => {
   const nodes: {
     id: string;
     type: string;
@@ -72,6 +72,8 @@ const { automation, check } = vi.hoisted(() => {
       errors: [] as Array<Record<string, unknown> & { id: string }>,
       warnings: [] as Array<Record<string, unknown> & { id: string }>,
     },
+    /** Every version a save appends. */
+    saved: vi.fn(async () => ({ name: 'pr-digest', version: 3 })),
   };
 });
 
@@ -177,6 +179,7 @@ vi.mock('../hooks/queries', async (importOriginal) => ({
     ],
   }),
   useAutomationRuns: () => ({ data: [] }),
+  useAutomationRun: () => ({ data: undefined }),
   useAutomationProjects: () => ({ data: [] }),
   useAutomationTriggers: () => ({ data: [] }),
   useNodeTypeCatalog: () => ({ data: undefined, isError: false }),
@@ -184,7 +187,7 @@ vi.mock('../hooks/queries', async (importOriginal) => ({
 
 vi.mock('../hooks/mutations', async (importOriginal) => ({
   ...(await importOriginal<typeof import('../hooks/mutations')>()),
-  useSaveAutomation: () => ({ mutateAsync: vi.fn(), isPending: false }),
+  useSaveAutomation: () => ({ mutateAsync: saved, isPending: false }),
   useStartAutomationRun: () => ({ mutate: vi.fn(), isPending: false }),
   useDeployAutomation: () => ({ mutate: vi.fn(), isPending: false }),
 }));
@@ -218,6 +221,7 @@ afterEach(() => {
   cleanup();
   check.errors = [];
   check.warnings = [];
+  saved.mockClear();
   document.documentElement.classList.remove('dark');
 });
 
@@ -1034,6 +1038,7 @@ describe('automation editor paths in Chromium', () => {
         const verbs = [
           screen.getByRole('radio', { name: 'Canvas' }),
           screen.getByRole('radio', { name: 'List' }),
+          screen.getByRole('radio', { name: 'Source' }),
           screen.getByRole('button', { name: '2 paths' }),
           screen.getByRole('button', { name: 'Edit with your coding agent' }),
           screen.getByRole('button', { name: 'Test run' }),
@@ -1047,3 +1052,182 @@ describe('automation editor paths in Chromium', () => {
       }),
   );
 });
+
+describe('automation editor code fields, Start, End and Source in Chromium', () => {
+  const MOD = navigator.platform.toLowerCase().includes('mac')
+    ? 'Meta'
+    : 'Control';
+
+  /** The open completion list, once it takes keys (CodeMirror ignores
+   *  them for its first 75 ms). */
+  async function listbox(): Promise<HTMLElement> {
+    const list = await screen.findByRole('listbox', {}, { timeout: 5000 });
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    return list;
+  }
+
+  function optionLabels(list: HTMLElement): (string | null | undefined)[] {
+    return [...list.querySelectorAll('[role="option"]')].map(
+      (option) => option.querySelector('.cm-completionLabel')?.textContent,
+    );
+  }
+
+  /** A box on the canvas by its graph id, clicked by a real pointer. */
+  async function clickBox(id: string) {
+    const canvas = await expectLaidOut();
+    const box = canvas.querySelector<HTMLElement>(
+      `[data-flow-node="${CSS.escape(id)}"]`,
+    );
+    if (box === null) throw new Error(`no ${id} box`);
+    await userEvent.click(box);
+  }
+
+  it('completes only the nodes that run before a code field, and Expand brings an edit back', async () => {
+    await page.viewport(1280, 800);
+    renderEditorTab();
+    await selectNode('summary');
+    const code = await screen.findByRole(
+      'textbox',
+      { name: 'Code' },
+      { timeout: 10_000 },
+    );
+    await userEvent.click(code);
+    await userEvent.keyboard(`{${MOD}>}{End}{/${MOD}}{Enter}nodes.`);
+    const list = await listbox();
+    await vi.waitFor(() =>
+      expect(optionLabels(list)).toEqual(['pulls', 'diff']),
+    );
+    await userEvent.keyboard('{Escape}');
+    await vi.waitFor(() => expect(screen.queryByRole('listbox')).toBeNull());
+
+    const frame = code.closest<HTMLElement>('[data-code-editor]');
+    if (frame === null) throw new Error('no code editor frame');
+    await userEvent.click(
+      within(frame).getByRole('button', { name: 'Expand editor' }),
+    );
+    const dialog = await screen.findByRole('dialog');
+    const big = await within(dialog).findByRole(
+      'textbox',
+      {},
+      { timeout: 5000 },
+    );
+    await vi.waitFor(() => expect(big).toHaveFocus());
+    await userEvent.keyboard(`{${MOD}>}{End}{/${MOD}}diff`);
+    await userEvent.click(
+      within(dialog).getByRole('button', { name: 'Back to the field' }),
+    );
+    await vi.waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+    await vi.waitFor(() => expect(code).toHaveFocus());
+    expect(code.textContent).toContain('nodes.diff');
+    // The edit is the draft's: Save can act on it.
+    expect(screen.getByRole('button', { name: 'Save' })).toBeEnabled();
+  });
+
+  it('closes the suggestions, then arms leaving, then the node sheet on a phone', async () => {
+    await page.viewport(390, 844);
+    renderEditorTab();
+    await selectNode('diff');
+    const sheet = await screen.findByRole('dialog', { name: 'Diff' });
+    const code = await within(sheet).findByRole(
+      'textbox',
+      { name: 'Code' },
+      { timeout: 10_000 },
+    );
+    await userEvent.click(code);
+    await userEvent.keyboard(`{${MOD}>}{End}{/${MOD}}{Enter}nodes.`);
+    const list = await listbox();
+    await vi.waitFor(() => expect(optionLabels(list)).toEqual(['pulls']));
+    // The list sits inside the sheet.
+    const sheetBox = sheet.getBoundingClientRect();
+    expect(list.getBoundingClientRect().bottom).toBeLessThanOrEqual(
+      sheetBox.bottom + 1,
+    );
+    await userEvent.keyboard('{Escape}');
+    await vi.waitFor(() => expect(screen.queryByRole('listbox')).toBeNull());
+    expect(screen.getByRole('dialog', { name: 'Diff' })).toBeVisible();
+    await userEvent.keyboard('{Escape}');
+    expect(screen.getByRole('dialog', { name: 'Diff' })).toBeVisible();
+    await userEvent.keyboard('{Escape}');
+    await vi.waitFor(() =>
+      expect(screen.queryByRole('dialog', { name: 'Diff' })).toBeNull(),
+    );
+  });
+
+  it('edits the run input on Start and the output on End, and saves both', async () => {
+    await page.viewport(1280, 800);
+    renderEditorTab();
+    await clickBox('__start');
+    const schema = await screen.findByRole(
+      'textbox',
+      { name: 'Input schema' },
+      { timeout: 10_000 },
+    );
+    await userEvent.click(schema);
+    await userEvent.keyboard(`{${MOD}>}a{/${MOD}}{{}`);
+    await vi.waitFor(() => expect(schema.textContent).toBe('{}'));
+
+    await clickBox('__end');
+    const output = await screen.findByRole(
+      'textbox',
+      { name: 'Output' },
+      { timeout: 10_000 },
+    );
+    await userEvent.click(output);
+    await userEvent.keyboard(`{${MOD}>}a{/${MOD}}42`);
+    await vi.waitFor(() => expect(output.textContent).toBe('42'));
+
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }));
+    await userEvent.click(
+      await screen.findByRole('button', { name: 'Save version' }),
+    );
+    await vi.waitFor(() => expect(saved).toHaveBeenCalledTimes(1));
+    const [request] = saved.mock.calls[0] ?? [];
+    expect(request).toMatchObject({
+      automation: { inputs: {}, output: 42 },
+    });
+  });
+
+  it('goes to a problem in the document on its line in the Source view', async () => {
+    check.errors = [
+      {
+        id: 'error|NAME_X|/name|',
+        level: 'error',
+        code: 'NAME_X',
+        message: 'the name is odd',
+        at: { pointer: '/name' },
+      },
+    ];
+    await page.viewport(1280, 800);
+    renderEditorTab();
+    await userEvent.click(
+      await screen.findByRole('button', { name: 'Problems: 1 error' }),
+    );
+    const dock = await screen.findByRole('region', { name: 'Problems' });
+    const row = within(dock).getByRole('button', { name: /Error:/ });
+    await vi.waitFor(() => expect(row).toHaveFocus());
+    await userEvent.keyboard('{Enter}');
+
+    const source = await screen.findByRole(
+      'textbox',
+      { name: 'Source of this automation (YAML)' },
+      { timeout: 10_000 },
+    );
+    expect(screen.getByRole('radio', { name: 'Source' })).toHaveAttribute(
+      'aria-checked',
+      'true',
+    );
+    await vi.waitFor(() => expect(source).toHaveFocus());
+    await vi.waitFor(() =>
+      expect(document.getSelection()?.toString()).toBe('pr-digest'),
+    );
+    expect(source).toHaveAttribute('aria-readonly', 'true');
+    // Line numbers, and the problem marked where it is.
+    const editor = source.closest('.cm-editor');
+    expect(editor?.querySelector('.cm-lineNumbers')).not.toBeNull();
+    await vi.waitFor(() =>
+      expect(editor?.querySelector('.cm-diagnostic-error')?.textContent).toBe(
+        'pr-digest',
+      ),
+    );
+  });
+});

From e66963cb7cc8511508969cf091814665bc8de063 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Thu, 8 Oct 2026 23:53:24 +0200
Subject: [PATCH 53/78] test(platform): type the save spy the editor's browser
 test reads

The spy took no argument, so reading the save request off its first call did not typecheck.
---
 .../components/automation-editor.browser.test.tsx            | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
index 938937d9e3..f3a5e8d175 100644
--- a/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.browser.test.tsx
@@ -73,7 +73,10 @@ const { automation, check, saved } = vi.hoisted(() => {
       warnings: [] as Array<Record<string, unknown> & { id: string }>,
     },
     /** Every version a save appends. */
-    saved: vi.fn(async () => ({ name: 'pr-digest', version: 3 })),
+    saved: vi.fn(async (_request: unknown) => ({
+      name: 'pr-digest',
+      version: 3,
+    })),
   };
 });
 

From 937904989bedb9c2fa9f3f778a2b4b26a2681a0f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:08:09 +0200
Subject: [PATCH 54/78] fix(platform): word the canvas strings naturally in
 German and French
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

German: a run that goes on after a failure 'geht weiter' rather than 'läuft der Lauf weiter', a line 'überträgt' its fields, a node 'läuft erfolgreich', and a node reads 'die Laufeingabe'. French: a live run is 'une exécution réelle' and a test run 'un essai', as elsewhere in the catalog; a node reads 'l’entrée'; Paths asks the reader to point at one of them.
---
 services/platform/messages/de/automations.yml | 12 ++++++------
 services/platform/messages/fr/automations.yml | 10 +++++-----
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index 04e7959a62..38676ad107 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -241,13 +241,13 @@ canvas:
       withModel: '{type} · {model}'
       unknown: 'Unbekannter Typ {type}'
     source:
-      input: 'Laufeingabe ({keys})'
-      inputAll: Laufeingabe
+      input: 'die Laufeingabe ({keys})'
+      inputAll: die Laufeingabe
       item: jedes Element
   gate:
     asCode: Als Code geschrieben
   edge:
-    carries: 'Trägt {fields}'
+    carries: 'Überträgt {fields}'
   controlFlow:
     forEach: 'Für jedes Element von {list}'
     forEachRaw: Für jedes Element ihrer Liste
@@ -321,7 +321,7 @@ editor:
     skipUpstream: 'Übersprungen, wenn {node} übersprungen wird'
     skipError: Übersprungen, wenn sie fehlschlägt
     failHalts: Schlägt sie fehl, stoppt der Lauf mit ihrem Fehler.
-    failContinues: '{count, plural, =0 {Schlägt sie fehl, läuft der Lauf ohne sie weiter.} one {Schlägt sie fehl, läuft der Lauf ohne sie weiter und überspringt # Node, die sie liest.} other {Schlägt sie fehl, läuft der Lauf ohne sie weiter und überspringt # Nodes, die sie lesen.}}'
+    failContinues: '{count, plural, =0 {Schlägt sie fehl, geht der Lauf ohne sie weiter.} one {Schlägt sie fehl, geht der Lauf ohne sie weiter und überspringt # Node, die sie liest.} other {Schlägt sie fehl, geht der Lauf ohne sie weiter und überspringt # Nodes, die sie lesen.}}'
     failsWhen: 'Schlägt fehl, wenn {reasons}.'
   explain:
     when: 'Läuft nur, wenn {condition}. Sonst wird sie übersprungen, ebenso jede Node, die ihre Ausgabe liest.'
@@ -402,7 +402,7 @@ editor:
     onError: Bei Fehler
     onErrorStop: Lauf stoppen
     onErrorContinue: Ohne sie weiterlaufen
-    onErrorDescription: Was passiert, wenn diese Node fehlschlägt. Läuft der Lauf weiter, wird jede Node übersprungen, die ihre Ausgabe liest.
+    onErrorDescription: Was passiert, wenn diese Node fehlschlägt. Geht der Lauf weiter, wird jede Node übersprungen, die ihre Ausgabe liest.
     maxRepeatsDescription: Höchstens so viele Durchläufe, von 1 bis 20. Leer bedeutet 5.
     maxRepeatsRange: Gib eine ganze Zahl von 1 bis 20 ein.
     elseOfNone: Keine
@@ -719,7 +719,7 @@ paths:
     runs: '{node} läuft'
     skipped: '{node} wird übersprungen'
     fails: '{node} schlägt fehl, der Lauf geht weiter'
-    succeeds: '{node} gelingt'
+    succeeds: '{node} läuft erfolgreich'
   more: '{count, plural, one {# weiterer Pfad ist nicht aufgeführt} other {# weitere Pfade sind nicht aufgeführt}}'
   truncated: Diese Automatisierung hat {count} Bedingungen – zu viele, um jeden Pfad aufzuführen. Jede Node zeigt trotzdem, wann sie läuft.
   halts:
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index f23cb06c67..9b75b8a777 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -229,7 +229,7 @@ canvas:
   node:
     returnsUnknown: Structure connue après une exécution
     returns: 'Renvoie {shape}'
-    writes: Modifie des données dans {connector}. Une exécution en service peut attendre une approbation.
+    writes: Modifie des données dans {connector}. Une exécution réelle peut attendre une approbation.
     asks: Peut poser une question et attendre la réponse.
     catalog:
       transform: Transformation
@@ -241,8 +241,8 @@ canvas:
       withModel: '{type} · {model}'
       unknown: 'Type inconnu {type}'
     source:
-      input: 'entrée ({keys})'
-      inputAll: entrée
+      input: 'l’entrée ({keys})'
+      inputAll: l’entrée
       item: chaque élément
   gate:
     asCode: Écrite en code
@@ -344,7 +344,7 @@ editor:
       inferred: Déduit de son code
       fixed: 'Chaque nœud de ce type ({type}) renvoie ceci'
       child: 'Ce que renvoie {automation}'
-      unknown: Tale ne peut pas déterminer ce qu’il renvoie. Une exécution de test montre les vraies données.
+      unknown: Tale ne peut pas déterminer ce qu’il renvoie. Un essai montre les vraies données.
   versionNotFound:
     title: 'La version {version} n’existe pas'
     description: Cette automatisation n’a aucune version portant ce numéro — le lien est peut-être périmé, ou le numéro mal saisi.
@@ -713,7 +713,7 @@ condition:
 paths:
   button: '{count, plural, one {# chemin} other {# chemins}}'
   title: Chemins possibles
-  description: Chaque chemin qu’une exécution réussie peut prendre. Survole-en un ou sélectionne-le pour le voir sur le canevas.
+  description: Chaque chemin qu’une exécution réussie peut prendre. Pointe sur l’un d’eux ou sélectionne-le pour le voir sur le canevas.
   single: 'Chaque exécution suit le même chemin : {count, plural, one {son # nœud s’exécute} other {les # nœuds s’exécutent}}.'
   row: 'Chemin {index}'
   rowRuns: '{ran, plural, one {# nœud sur {total} s’exécute} other {# nœuds sur {total} s’exécutent}}'

From 27d550a87e2f498282e1a4786113b4553458fd75 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:08:12 +0200
Subject: [PATCH 55/78] fix(ui): name the Home key Origine in the French flow
 canvas help

---
 packages/ui/src/i18n/messages/fr.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index 8de97c7837..5113f3ccef 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -526,7 +526,7 @@ schemaTree:
 flow:
   canvas:
     roleDescription: diagramme de flux
-    keyboardHelp: Utilise les flèches pour suivre les liens entre les nœuds, Début et Fin pour aller au début et à la fin, et Entrée pour ouvrir un nœud.
+    keyboardHelp: Utilise les flèches pour suivre les liens entre les nœuds, Origine et Fin pour aller au début et à la fin, et Entrée pour ouvrir un nœud.
     arranging: Disposition des nœuds…
     arrangeFailed: Impossible de disposer les nœuds, ils sont donc affichés en une colonne.
     touchHint: Utilise deux doigts pour déplacer le diagramme

From c86ef9e31e5c0f8a4caf53ce8dc53a96990d62e0 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:08:15 +0200
Subject: [PATCH 56/78] test(ui): add the automation canvas terms to the
 glossary

Node, path, Source, coding agent, Start, End and condition, with their German and French forms and where each check would misfire.
---
 .../ui/src/i18n/tests/glossary/glossary.yml   | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/packages/ui/src/i18n/tests/glossary/glossary.yml b/packages/ui/src/i18n/tests/glossary/glossary.yml
index de487ef8da..75ce11ca35 100644
--- a/packages/ui/src/i18n/tests/glossary/glossary.yml
+++ b/packages/ui/src/i18n/tests/glossary/glossary.yml
@@ -343,6 +343,75 @@ terms:
     de: Automatisierungen
     fr: Automatisations
     _note: Plural — the hub view. Matches UI label `navigation.automations`.
+  - key: feature_automationNode
+    category: feature
+    en: Node
+    fr: Nœud
+    _lintExclude:
+      fr: true
+    _note: 'One step of an automation, on the canvas and in every message about
+      it (`automations.canvas.*`, `automationIssues.*`). EN lowercase in prose
+      (node); DE the loanword `die Node`, plural `die Nodes`, never `Knoten` in
+      the automation pages and catalogs; FR `le nœud`, so French state words
+      that agree with it are masculine (ignoré, réussi). The run timeline still
+      says step / Schritt / étape. Not enforced in FR because `Node` there is
+      also the Node.js runtime.'
+  - key: feature_automationPath
+    category: feature
+    en: Path
+    de: Pfad
+    fr: Chemin
+    _lintExclude:
+      de: true
+      fr: true
+    _note: 'One way a successful run can go through an automation''s conditions
+      (`automations.paths.*`, "Possible paths"). DE `der Pfad`, FR `le chemin`.
+      Not enforced: German keeps `Path-Style`, the S3 addressing term, and the
+      marketing site''s French code samples call Python''s `Path`.'
+  - key: feature_automationSource
+    category: feature
+    en: Source
+    de: Quelltext
+    _lintExclude:
+      de: true
+    _note: 'The read-only YAML view of an automation (`automations.canvas.view.source`).
+      DE `der Quelltext`; FR keeps `la source`. Not enforced in DE, where
+      `Open Source` stays English.'
+  - key: feature_codingAgent
+    category: feature
+    en: Coding agent
+    de: Coding-Agent
+    fr: Agent de code
+    _note: 'A tool such as Claude Code, Codex or Cursor that changes
+      automations through the MCP server (`automations.codingAgent.*`). DE
+      `der Coding-Agent`, plural `die Coding-Agents`; FR `l’agent de code`.
+      Distinct from an `agent` node, which works during a run.'
+  - key: feature_automationStart
+    category: feature
+    en: Start
+    fr: Début
+    _note: 'The box at the top of the automation canvas: what starts a run and
+      what it receives (`flow.node.entry`, `automations.editor.start.title`).
+      DE keeps `Start`.'
+  - key: feature_automationEnd
+    category: feature
+    en: End
+    de: Ende
+    fr: Fin
+    _lintExclude:
+      de: true
+    _note: 'The box at the bottom of the automation canvas: what a run returns
+      and how it ends (`flow.node.exit`, `automations.editor.end.title`). Not
+      enforced in DE, where `End-Session` names an OAuth endpoint; the End key
+      is `Ende` in German too.'
+  - key: feature_condition
+    category: feature
+    en: Condition
+    de: Bedingung
+    fr: Condition
+    _note: 'A node''s `when`, drawn as a pill above it in words
+      (`automations.canvas.legend.gate`, `flow.gate.*`); its branches answer
+      Yes / Ja / Oui and No / Nein / Non.'
   - key: feature_connector
     category: feature
     en: Connector

From 7bf673fe4900bb6c527fd03dc631441c21bc020e Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:20:30 +0200
Subject: [PATCH 57/78] docs: describe the automation canvas, paths and code
 fields

The editor guide in English, German and French now reads the canvas as it ships: Start and End, node faces, conditions with Yes and No, frames and line kinds, the List view and keyboard, versions that arrive live, the Paths list, the inspector's When it runs and Fields, Shape and Last run tabs, the code editor, Start inputs and End output, the read-only Source view and the coding-agent entry. Problems in the inputs, output and tests now open Start, End and Source.

Concepts explains the paths a run can take and how the canvas draws control flow; execution logs describes the failed-run focus and the canvas's state words; the authoring page makes the coding agent the way in. German pages say die Node instead of Knoten.
---
 .../automations/approvals-in-workflows.md     |  12 +-
 docs/de/platform/automations/assistant.md     |  26 ++--
 docs/de/platform/automations/concepts.md      |  10 +-
 docs/de/platform/automations/editor.md        | 124 +++++++++++++++---
 .../de/platform/automations/execution-logs.md |   8 +-
 .../editor/workflow-with-approvals.md         |   6 +-
 docs/en/platform/automations/assistant.md     |  22 ++--
 docs/en/platform/automations/concepts.md      |  10 +-
 docs/en/platform/automations/editor.md        | 116 ++++++++++++++--
 .../en/platform/automations/execution-logs.md |   8 +-
 .../editor/workflow-with-approvals.md         |   2 +-
 docs/fr/platform/automations/assistant.md     |  22 ++--
 docs/fr/platform/automations/concepts.md      |  10 +-
 docs/fr/platform/automations/editor.md        | 124 +++++++++++++++---
 .../fr/platform/automations/execution-logs.md |   8 +-
 .../editor/workflow-with-approvals.md         |   2 +-
 services/docs/app/content/frontmatter.json    |  14 +-
 17 files changed, 406 insertions(+), 118 deletions(-)

diff --git a/docs/de/platform/automations/approvals-in-workflows.md b/docs/de/platform/automations/approvals-in-workflows.md
index 390fb8f46c..a9927e2560 100644
--- a/docs/de/platform/automations/approvals-in-workflows.md
+++ b/docs/de/platform/automations/approvals-in-workflows.md
@@ -3,7 +3,7 @@ title: Auf einen wartenden Workflow reagieren
 description: Finde einen pausierten Automationslauf, prüfe einen geplanten Schreibzugriff oder beantworte eine Rückfrage des Agenten.
 ---
 
-Ein Lauf kann auf eine Entscheidung vor einem Connector-Schreibzugriff warten oder auf Informationen, die ein Agent zum Fortfahren braucht. In den Laufdetails siehst du, welche Antwort nötig ist. Ein wartender Lauf ist noch nicht abgeschlossen, auch wenn vorherige Knoten erfolgreich waren.
+Ein Lauf kann auf eine Entscheidung vor einem Connector-Schreibzugriff warten oder auf Informationen, die ein Agent zum Fortfahren braucht. In den Laufdetails siehst du, welche Antwort nötig ist. Ein wartender Lauf ist noch nicht abgeschlossen, auch wenn vorherige Nodes erfolgreich waren.
 
 ## Den wartenden Lauf finden
 
@@ -15,19 +15,19 @@ Eine Freigabekarte nennt eine Connector-Aktion und zeigt ihre geplanten Eingaben
 
 Lies die Aktion und die Angaben unter **Der Schritt würde aufrufen mit** genau. Prüfe Empfänger oder Ziel, den Inhalt und alle Kennungen, die bestimmen, was geändert wird.
 
-Wähle **Freigeben**, um die Aktion zu erlauben. Der Lauf wird fortgesetzt und versucht den Schreibzugriff; kontrolliere danach Knotenergebnis und Auswirkungen. Wähle **Ablehnen**, wenn die Anfrage falsch ist oder nicht ausgeführt werden soll. Die Ablehnung verhindert diese Aktion und lässt den Lauf fehlschlagen.
+Wähle **Freigeben**, um die Aktion zu erlauben. Der Lauf wird fortgesetzt und versucht den Schreibzugriff; kontrolliere danach das Ergebnis der Node und die Auswirkungen. Wähle **Ablehnen**, wenn die Anfrage falsch ist oder nicht ausgeführt werden soll. Die Ablehnung verhindert diese Aktion und lässt den Lauf fehlschlagen.
 
 Auch wenn etwas schiefgeht, zeigt die Karte, wo der Lauf steht. Lässt sich die Freigabe nicht laden, sagt die Karte das und bietet **Erneut versuchen** an; der Lauf wartet weiter, bis jemand entscheidet. Wurde deine Entscheidung nicht gespeichert, meldet die Karte das und behält **Freigeben** und **Ablehnen**, damit du noch einmal wählen kannst. Hat jemand anderes zuerst entschieden, zeigt die Karte die gespeicherte Entscheidung.
 
-Ein Live-Lauf prüft vor der Freigabeanfrage, ob der Connector ein nutzbares Credential hat: Ist keines konfiguriert, schlägt der Knoten mit diesem Grund fehl, statt auf eine Entscheidung zu warten.
+Ein Live-Lauf prüft vor der Freigabeanfrage, ob der Connector ein nutzbares Credential hat: Ist keines konfiguriert, schlägt die Node mit diesem Grund fehl, statt auf eine Entscheidung zu warten.
 
 Auf der Freigabekarte kannst du keine Parameter ändern. Lehne eine falsche Anfrage ab, korrigiere den Workflow oder seine Eingaben und teste die Änderung vor einem neuen Live-Lauf. Änderungen an der Freigaberichtlinie geben eine bereits offene Karte nicht frei. [Freigabekonzepte](/de/platform/approvals/concepts) erklärt den Ablauf; die [Konfiguration der Freigaberichtlinie](/de/self-hosted/configuration/approvals) beschreibt die Regeln für den Betrieb.
 
 ## Eine Rückfrage des Agenten beantworten
 
-Nutzt ein Agent-Knoten `ask_human`, zeigen die Laufdetails **Der Agent braucht deine Antwort, um weiterzumachen**. Beantworte vorgegebene Auswahlfragen direkt auf der Karte. Bei einer offenen Frage schreibst du unter **Deine Antwort** einen Text und klickst auf **Antwort senden & fortsetzen**.
+Nutzt eine Agent-Node `ask_human`, zeigen die Laufdetails **Der Agent braucht deine Antwort, um weiterzumachen**. Beantworte vorgegebene Auswahlfragen direkt auf der Karte. Bei einer offenen Frage schreibst du unter **Deine Antwort** einen Text und klickst auf **Antwort senden & fortsetzen**.
 
-Gib die fehlende Information möglichst konkret an. Fragt der Agent nach einem Dokument, nenne das Dokument oder seine Kennung, statt ihn nur zum Fortfahren aufzufordern. Der wartende Knoten wird mit deiner Antwort fortgesetzt. Später kann der Lauf eine weitere Antwort oder eine Freigabe benötigen. Inhaber, Admins und Entwickler antworten in den Laufdetails. Bearbeitet der Lauf eine Aufgabe, erscheint die Rückfrage auch in der Aufgabe, und dort antwortet jede Person, die die Aufgabe öffnen kann.
+Gib die fehlende Information möglichst konkret an. Fragt der Agent nach einem Dokument, nenne das Dokument oder seine Kennung, statt ihn nur zum Fortfahren aufzufordern. Die wartende Node wird mit deiner Antwort fortgesetzt. Später kann der Lauf eine weitere Antwort oder eine Freigabe benötigen. Inhaber, Admins und Entwickler antworten in den Laufdetails. Bearbeitet der Lauf eine Aufgabe, erscheint die Rückfrage auch in der Aufgabe, und dort antwortet jede Person, die die Aufgabe öffnen kann.
 
 ## Den Workflow korrigieren und testen
 
@@ -35,7 +35,7 @@ Eine Workflow-Definition zu ändern ist ein anderer Vorgang als auf ihren laufen
 
 <Frame caption="Bearbeite den Workflow auf der Zeichenfläche; prüfe wartende Ausführungen in ihren Laufdetails.">
 
-![Der Workflow-Editor zeigt den Automationsgraphen und einen Bereich zum Konfigurieren des ausgewählten Knotens.](/images/platform/automation-editor-canvas.webp)
+![Der Workflow-Editor zeigt den Graphen der Automatisierung und einen Bereich zum Konfigurieren der ausgewählten Node.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
diff --git a/docs/de/platform/automations/assistant.md b/docs/de/platform/automations/assistant.md
index 22efabdd4a..8723c0fd2e 100644
--- a/docs/de/platform/automations/assistant.md
+++ b/docs/de/platform/automations/assistant.md
@@ -1,30 +1,30 @@
 ---
-title: Den Weg zur Automation wählen
-description: Bearbeite Workflows direkt im visuellen Editor oder verbinde einen externen Assistenten über MCP mit Tale.
+title: Den Weg zur Automatisierung wählen
+description: Ändere Felder einer Automatisierung im Editor, oder lass einen Coding-Agent sie über MCP erstellen und ändern.
 ---
 
-Bearbeite eine Automation direkt auf ihrer Arbeitsfläche oder verbinde einen externen Assistenten über MCP mit den Werkzeugen von Tale. Beide Wege speichern Versionen desselben Workflows und nutzen dieselben Prüf- und Bereitstellungsregeln. Zum Erstellen und Bereitstellen brauchst du Entwicklerrechte.
+Ändere die Felder einer Automatisierung direkt im Editor, oder lass einen Coding-Agent wie Claude Code, Codex oder Cursor sie über MCP erstellen und ändern. Beide Wege speichern Versionen desselben Workflows und nutzen dieselben Prüf- und Bereitstellungsregeln. Zum Erstellen und Bereitstellen brauchst du Entwicklerrechte.
 
-## Eine Änderung im visuellen Editor vornehmen
+## Eine Änderung im Editor vornehmen
 
-Öffne **Automatisierungen** und wähle den Workflow. Klicke auf einen Knoten, um Eingaben, Modell, Code oder andere Einstellungen zu prüfen. Speichere die Änderung mit einer Versionsnachricht, führe einen Test aus und stelle nach bestandenen Prüfungen die gewünschte Version bereit.
+Öffne **Automatisierungen** und wähle den Workflow. Wähle eine Node, um Eingabe, Modell, Code oder andere Einstellungen zu prüfen, und ändere das Feld, das du brauchst. Speichere die Änderung mit einer Versionsnachricht, führe einen Test aus und stelle nach bestandenen Prüfungen die gewünschte Version bereit. Der Canvas ordnet sich anhand der Referenzen zwischen den Nodes selbst an; du fügst darin keine Nodes hinzu und zeichnest keine Verbindungen.
 
-<Frame caption="Ein ausgewählter Knoten zeigt seine Konfiguration neben dem Workflow-Graphen.">
+<Frame caption="Eine ausgewählte Node zeigt ihre Konfiguration neben dem Workflow-Graphen.">
 
-![Der Automation-Editor zeigt den Workflow-Graphen und die Eingabefelder des ausgewählten Knotens in einer Seitenleiste.](/images/platform/automation-editor-canvas.webp)
+![Der Automatisierungs-Editor zeigt den Workflow zwischen Start und Ende und die Felder der ausgewählten Node in einer Seitenleiste.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
-[Der Workflow-Editor](/de/platform/automations/editor) erklärt diese Schritte, die Prüfung eines Laufs und die Rückkehr zu einer früheren Version. Die Arbeitsfläche enthält keinen Chat-Assistenten.
+[Der Workflow-Editor](/de/platform/automations/editor) erklärt diese Schritte, das Lesen des Canvas, die Prüfung eines Laufs und die Rückkehr zu einer früheren Version. Der Canvas enthält keinen Chat-Assistenten.
 
-## Einen externen Assistenten über MCP nutzen
+## Mit deinem Coding-Agent ändern
 
-Richte deinen Client mit dem Endpunkt unter **Einstellungen > API > MCP** und einem passenden Organisations-API-Schlüssel ein. Beschreibe Eingaben, gewünschte Ausgabe und die Systeme, die der Workflow verändern darf. Lass den Client vorhandene Automationen und Funktionen prüfen, bevor er eine weitere erstellt.
+Der Weg dorthin ist **Mit deinem Coding-Agent bearbeiten**, die letzte Schaltfläche oben rechts im Canvas des Editors. Ihr Dialog zeigt den Namen der Automatisierung, den du dem Agent gibst, **MCP einrichten**, das **Einstellungen > API > MCP** öffnet, und einen Link zur Anleitung, mit der du einen Coding-Agent verbindest. Richte deinen Client mit diesem Endpunkt und einem passenden Organisations-API-Schlüssel ein. Beschreibe Eingaben, gewünschte Ausgabe und die Systeme, die der Workflow verändern darf, und lass den Agent vorhandene Automatisierungen und Funktionen prüfen, bevor er eine weitere erstellt.
 
-Der [MCP-Endpunkt](/de/develop/mcp-endpoint) bietet Tools für Dokumentation, Validierung, Speichern, Testen und Bereitstellen. Prüfe den entstandenen Workflow und die Testergebnisse vor der Bereitstellung. Ein Speichervorgang erstellt eine Version, schaltet sie aber nicht live.
+Der [MCP-Endpoint](/de/develop/mcp-endpoint) bietet Tools für Dokumentation, Validierung, Speichern, Testen und Bereitstellen. Eine Version, die der Agent speichert, erscheint im Canvas, während du die Automatisierung ansiehst. Prüfe den entstandenen Workflow und die Testergebnisse vor der Bereitstellung. Ein Speichervorgang erstellt eine Version, schaltet sie aber nicht live.
 
 ## Entscheidungen während eines Laufs unterscheiden
 
-Ein Agentenknoten arbeitet während eines Automation-Laufs. Er ist nicht der Client, mit dem du den Workflow schreibst. Ebenso genehmigt eine [Freigabe](/de/platform/approvals/concepts) eine ausstehende Operation während der Ausführung und keine vorgeschlagene Änderung an der Workflow-Definition.
+Eine Agent-Node arbeitet während eines Laufs der Automatisierung. Sie ist nicht der Coding-Agent, mit dem du den Workflow schreibst. Ebenso genehmigt eine [Freigabe](/de/platform/approvals/concepts) eine ausstehende Operation während der Ausführung und keine vorgeschlagene Änderung an der Workflow-Definition.
 
-Nutze [den Editor](/de/platform/automations/editor) für direkte Änderungen oder [MCP](/de/develop/mcp-endpoint) für deinen eigenen Client. Beginne mit [einer vorhandenen Automation](/de/platform/automations/catalog), wenn bereits eine passende verfügbar ist.
+Nutze [den Editor](/de/platform/automations/editor) für direkte Änderungen oder [MCP](/de/develop/mcp-endpoint) für die Arbeit mit deinem Coding-Agent. Beginne mit [einer vorhandenen Automatisierung](/de/platform/automations/catalog), wenn bereits eine passende verfügbar ist.
diff --git a/docs/de/platform/automations/concepts.md b/docs/de/platform/automations/concepts.md
index c959839f55..0b7b48ff3f 100644
--- a/docs/de/platform/automations/concepts.md
+++ b/docs/de/platform/automations/concepts.md
@@ -46,13 +46,13 @@ Tale ordnet den Canvas anhand der Verweise zwischen den Nodes an, niemand platzi
 
 ### Kanten entstehen, sie werden nicht deklariert
 
-Es gibt keine Kantenliste. Eine Node liest eine andere, indem sie sie referenziert — `{{ nodes.invoice.output.id }}` —, und genau diese Referenz _ist_ die Kante, die der Canvas zeichnet. Die Reihenfolge ergibt sich aus einer topologischen Sortierung über diese abgeleiteten Kanten. Deshalb verschwindet mit einer gelöschten Referenz auch ein Pfeil, und deshalb weist die Plattform zwei Nodes zurück, die einander lesen.
+Es gibt keine Kantenliste. Eine Node liest eine andere, indem sie sie referenziert — `{{ nodes.invoice.output.id }}` —, und genau diese Referenz _ist_ die Kante, die der Canvas zeichnet. Die Reihenfolge ergibt sich aus einer topologischen Sortierung über diese abgeleiteten Kanten. Deshalb verschwindet mit einer gelöschten Referenz auch eine Linie, und deshalb weist die Plattform zwei Nodes zurück, die einander lesen.
 
 Templates nutzen eine einzige `{{ }}`-Grammatik aus JavaScript-Ausdrücken über `input`, `nodes.<id>.output` und, innerhalb einer iterierenden Node, `item` und `index`.
 
 ### Die Ablaufsteuerung sitzt an der Node
 
-Verzweigen und Wiederholen sind Felder an einer Node statt eigener Schritttypen. Der Canvas zeigt sie deshalb als Badges an genau der Box, die sie betreffen.
+Verzweigen und Wiederholen sind Felder an einer Node statt eigener Schritttypen. Der Canvas zeichnet jedes davon dort, wo es wirkt: Aus `when` wird eine Bedingung über ihrer Node, eine Alternative per `elseOf` hängt als Zweig **Nein** an dieser Bedingung, `forEach` und `repeatUntil` setzen die Node in einen Rahmen, und `onError: continue` gibt ihr einen Chip.
 
 | Feld                         | Wirkung                                                                                 |
 | ---------------------------- | --------------------------------------------------------------------------------------- |
@@ -80,6 +80,12 @@ Eine **strukturierte** Ausgabe hat benannte Felder, die du über `nodes.<id>.out
 
 Ein Werkzeug ohne Ausgabeschema liefert unstrukturierte Ausgabe. Soll daraus strukturierte Eingabe für weitere Schritte entstehen, nutze eine `llm`-Node mit `outputSchema`. Die Validierung nennt bei einem Fehler die ungültige Referenz und die zulässigen Felder oder Kontexte. Korrigiere die Referenz, bevor du erneut speicherst.
 
+## Pfade, die ein Lauf nehmen kann {#paths}
+
+Jede Bedingung und jede Node, die fehlschlagen darf, während der Lauf weitergeht, eröffnet einem Lauf zwei Möglichkeiten. Tale probiert jede Kombination davon aus und behält die unterschiedlichen Wege, die ein erfolgreicher Lauf nehmen kann; jeder davon ist ein Pfad. Ein Pfad nennt die Bedingungen, die über ihn entscheiden, etwa welche Nodes laufen, welche übersprungen werden und welche fehlschlagen, während der Lauf weitergeht, und die Nodes, die auf ihm laufen. Eine Node, die auf jedem Pfad läuft, läuft immer; eine Node, die auf keinem läuft, kann nie laufen, und Tale warnt davor.
+
+Tale führt bis zu 32 Pfade auf und zählt die übrigen. Bei mehr als 12 Bedingungen und hingenommenen Fehlern sind die Kombinationen zu viele zum Durchgehen, deshalb führt Tale dann keinen Pfad auf; es sagt aber weiterhin bei jeder Node, wann sie läuft. Außerdem nennt Tale die Nodes, deren Fehler den Lauf beendet, und was jede von ihnen fehlschlagen lassen kann. Der Editor zeigt die Pfade im Canvas, wie [Den möglichen Pfaden folgen](/de/platform/automations/editor#paths) beschreibt; ein Client des [MCP-Endpoints](/de/develop/mcp-endpoint) liest dieselben Pfade aus `analysis.paths`.
+
 ## Was Tale vor einem Lauf prüft {#checks}
 
 Tale prüft das ganze Dokument, wenn du es speicherst, wenn du eine Version bereitstellst und wann immer ein Client `validate_automation` aufruft. Ein **Fehler** beschreibt etwas, das sicher scheitert, oder Code, der die Analysegrenzen überschreitet. Er verhindert Speichern wie Bereitstellen. Eine **Warnung** zeigt auf etwas, das scheitern kann oder nichts Nützliches tut. Sie verhindert weder Speichern noch Bereitstellen; du entscheidest selbst, ob du etwas änderst. Jedes Problem nennt seine Node und sein Feld und, in einem Template, einer Bedingung oder in Code, den genauen Ausdruck.
diff --git a/docs/de/platform/automations/editor.md b/docs/de/platform/automations/editor.md
index 4d35471157..68f8c8efa8 100644
--- a/docs/de/platform/automations/editor.md
+++ b/docs/de/platform/automations/editor.md
@@ -1,25 +1,25 @@
 ---
 title: Der Workflow-Editor
-description: Prüfe und ändere Knoten, gib Testdaten ein, speichere eine Version und schalte sie live oder kehre zu einer früheren zurück.
+description: Lies eine Automatisierung im Canvas, folge ihren möglichen Pfaden, ändere Felder einer Node, speichere eine Version und schalte sie live oder kehre zu einer früheren zurück.
 ---
 
-Im Workflow-Editor änderst du den Ablauf einer Automatisierung und wählst die gespeicherte Version für Live-Läufe. Änderungen brauchen Entwickler-, Admin- oder Inhaberrechte. Speichern, Testen und Bereitstellen sind getrennte Schritte: Die Arbeit an einem Entwurf lässt die bereitgestellte Version bestehen.
+Im Workflow-Editor liest du, was eine Automatisierung tut, änderst ihre Felder und wählst die gespeicherte Version für Live-Läufe. Größere Änderungen, etwa neue Nodes, kommen von einem Coding-Agent über MCP. Änderungen brauchen Entwickler-, Admin- oder Inhaberrechte. Speichern, Testen und Bereitstellen sind getrennte Schritte: Die Arbeit an einem Entwurf lässt die bereitgestellte Version bestehen.
 
 Öffne **Automatisierungen** und wähle einen Eintrag. Er öffnet sich im Tab **Editor**. Öffnest du eine Automatisierung im Tab **Automatisierungen** eines Projekts, beginnt der Navigationspfad mit diesem Projekt: Wähle den Projektnamen, um zum Projekt zurückzukehren, oder **Automatisierungen**, um zu seinen Automatisierungen zurückzukehren. Ob du eine Automatisierung in einem Projekt oder in der Liste öffnest, die Navigationsleiste markiert **Automatisierungen**. Für einen neuen Ablauf beginne mit [Automatisierungen erstellen oder importieren](/de/platform/automations/catalog).
 
 | Tab | Wofür du ihn nutzt |
 | --- | --- |
-| **Editor** | Den Workflow ändern, eine gespeicherte Version testen und die Live-Version wählen. |
+| **Editor** | Den Workflow lesen und ändern, eine gespeicherte Version testen und die Live-Version wählen. |
 | **Allgemein** | Festlegen, was die Automatisierung startet und welche Projekte sie nutzen können. |
 | **Läufe** | Die letzten Ausführungen prüfen und den vollständigen Datensatz eines Laufs öffnen. |
 
 Die Auswahl **Version** bleibt auf Desktop und Smartphone rechts neben den Tabs Editor, Allgemein und Läufe. Sie zeigt Versionsnachrichten, Datum, Testergebnisse und die Live-Markierung. Wähle eine Zeile, um diese Version zu öffnen. Am Desktop stehen die Laufaktionen neben den Tabs, zusammen mit **Speichern** und **Verwerfen**; unter **Allgemein** stehen dort nur **Speichern** und **Verwerfen**. Ein Punkt an einem Tab kennzeichnet dessen ungespeicherte Änderungen. Beim Verlassen des Tabs oder einem Versionswechsel fragt Tale, wie du damit fortfahren möchtest.
 
-Auf dem Smartphone startet eine geöffnete Automatisierung mit kompakter Navigation. Die Arbeitsfläche des Editors nutzt die verfügbare Höhe. Lauf- und Bereitstellungsaktionen befinden sich innerhalb der Arbeitsfläche neben den Zoom-Steuerelementen. Wenn du einen Knoten auswählst, öffnen sich seine Felder — mit Speichern und Verwerfen — in einem Bereich am unteren Bildschirmrand.
+Auf dem Smartphone startet eine geöffnete Automatisierung mit kompakter Navigation. Der Canvas des Editors nutzt die verfügbare Höhe, und Lauf- und Bereitstellungsaktionen stehen in einer Leiste am unteren Rand des Canvas. Wenn du eine Node auswählst, öffnen sich ihre Felder — mit Speichern und Verwerfen — in einem Bereich am unteren Bildschirmrand.
 
-<Frame caption="Wähle auf einem breiten Bildschirm einen Knoten, um seine Felder neben dem Canvas zu prüfen.">
+<Frame caption="Wähle auf einem breiten Bildschirm eine Node, um ihre Felder neben dem Canvas zu prüfen.">
 
-![Der Workflow-Editor zeigt verbundene Knoten und die Felder des ausgewählten Knotens neben dem Canvas.](/images/platform/automation-editor-canvas.webp)
+![Der Workflow-Editor zeigt die Nodes von Gmail triage inbox zwischen Start und Ende, eine in Worten formulierte Bedingung über einer Node und die Felder der ausgewählten Node neben dem Canvas.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
@@ -27,25 +27,113 @@ Zum Wechseln musst du nicht zur Liste zurück: Klick im Navigationspfad auf den
 
 ## Den Canvas lesen
 
-Jeder Kasten ist ein Knoten. Seine Beschriftung nennt Schritt und Typ; **Liest** zeigt verwendete Ausgaben anderer Knoten. Pfeile entstehen aus Referenzen wie `{{ nodes.draft.output.text }}`. Ändere die Referenz, um eine Abhängigkeit zu ändern. Das Zeichnen eines Pfeils erstellt keine Abhängigkeit.
+Tale zeichnet den Canvas aus dem Dokument der Automatisierung und ordnet ihn selbst an: **Start** steht oben, **Ende** unten, und jede Node steht unter den Nodes, die sie liest. So liest sich der Canvas von oben nach unten in der Reihenfolge, in der ein Lauf vorgeht. Niemand platziert einen Kasten, und Zeichnen verbindet nichts. Eine Linie entsteht aus einer Referenz wie `{{ nodes.draft.output.text }}`; um zu ändern, was eine Node liest, änderst du die Referenz.
 
-Kennzeichnungen zeigen Bedingungen und Schleifen wie `when`, `else of`, `for each`, `repeat until` und `continue on error`. Eine Zykluswarnung bedeutet, dass mehrere Knoten voneinander abhängen. Entferne die kreisförmige Referenz, bevor du eine ausführbare Version speicherst.
+### Start und Ende
 
-## Einen Knoten bearbeiten
+**Start** zeigt, was einen Lauf startet und was er erhält. Unter **Startet** steht der Trigger in Worten, etwa ein Zeitplan mit Zeitzone und nächstem Lauf, und ob der Trigger aus ist oder auf eine Live-Version wartet. Danach folgt **Von Hand, über die API oder MCP**, denn diese Starts sind immer möglich. Unter **Eingabe** stehen die Felder der Laufeingabe mit ihrem Typ und der Angabe, ob sie Pflicht sind. Würde der Trigger Läufe mit einer Eingabe starten, die die Automatisierung ablehnt, sagt Start das.
 
-Wähle einen Kasten, um seine Felder zu öffnen. Auf einem breiten Bildschirm erscheint der Bereich neben dem Canvas; ohne ausgewählten Knoten nutzt der Canvas die ganze Breite. Auf schmaleren Bildschirmen öffnen sich die Felder in einem Dialog über dem Canvas. Ein `transform` hat **Code**, ein `llm` Felder für Prompt, Modell und Ausgabeschema. Ein `agent` ergänzt Agent-Laufzeit und Ausstattung. Die **Modell**-Auswahl einer `llm`- oder `agent`-Node listet die Modelle, die die verbundenen Anbieter deiner Organisation bedienen; ein nicht aufgeführtes Modell lässt sich eingeben, doch **Probleme** warnt dann, dass ein Live-Lauf an dieser Node fehlschlägt, bis sein Anbieter verbunden ist. **Eingabe** enthält JSON-Werte und Referenzen für diesen Knoten. Unvollständiges JSON wird gemeldet und ändert den Knoten nicht.
+**Ende** zeigt, was ein erfolgreicher Lauf zurückgibt und wie ein Lauf enden kann. Unter **Gibt zurück** steht die Ausgabe, etwa **Die Ausgabe von Report**, oder ihre Felder mit den Nodes, aus denen sie stammen; ein Feld, das bei manchen Läufen leer bleibt, trägt **kann leer sein**. Unter **Endet** stehen die drei Ausgänge: **Erfolgreich** gibt die Ausgabe zurück, **Fehlgeschlagen** tritt ein, wenn eine der Nodes fehlschlägt, die den Lauf stoppen, und **Gestoppt**, wenn jemand den Lauf stoppt.
 
-Öffne **Ablaufsteuerung** für Bedingungen und Wiederholungen. Hat der Knoten welche, ist der Abschnitt schon offen. Mit **Schließen** kehrst du zum Canvas zurück. Auf einem breiten Bildschirm schließt sich der Bereich auch, wenn du auf den leeren Canvas klickst oder Escape außerhalb eines Textfelds drückst. Trigger und Projekteinstellungen der Automatisierung findest du im Tab **Allgemein**. [Automatisierungsgrundlagen](/de/platform/automations/concepts) erklärt Knotentypen und Ausdrücke.
+### Nodes
+
+Jede Node ist ein Kasten. Die erste Zeile zeigt ihr Symbol und ihren Titel, der aus ihrer ID entsteht: Aus `open_issues` wird **Open issues**. Die nächste Zeile nennt die Art der Node: Connector und Aktion, etwa **GitHub · Issues auflisten**, **Transformation**, **Sprachmodell** oder **Agent** mit ihrem Modell oder die Automatisierung, die sie aufruft. Weiß Tale, was die Node zurückgibt, zeigt eine Zeile die Struktur, etwa `{ issues: object[] }`. Die unterste Zeile sagt, was die Node liest, etwa **Liest Issues und die Laufeingabe (owner, repo)**, oder **Liest keine andere Node**.
+
+Chips und kleine Symbole ergänzen, was die Anordnung nicht zeigen kann. **Läuft bei Fehler weiter** markiert eine Node, deren Fehler der Lauf hinnimmt, und **Läuft nie** eine Node, die keine Kombination von Bedingungen erreicht. Ein Schild markiert eine Node, die Daten in einem verbundenen Dienst ändert; dort kann ein Live-Lauf auf eine Freigabe warten. Eine Sprechblase markiert einen Agent, der eine Frage stellen kann, und eine durchgestrichene Nadel ein Modell ohne festen Anbieter. Zeig auf ein Symbol, um seinen Satz zu lesen; ein Screenreader hört ihn mit dem Kasten. Ein Kasten mit Problemen zeigt ihre Anzahl in seiner ersten Zeile.
+
+### Bedingungen und Zweige
+
+Die Bedingung einer Node (`when`) steht als Pille über ihr und sagt die Bedingung in Worten, etwa „total von Score größer als 1.000 ist“. Die Node darunter läuft nur, wenn die Bedingung zutrifft. Ist eine andere Node ihre Alternative (`elseOf`), teilt sich die Bedingung in zwei Linien: **Ja** führt zur Node links, die läuft, wenn die Bedingung zutrifft, und **Nein** zu ihrer Alternative rechts. Eine Bedingung, die Tale nicht in Worte fassen kann, zeigt den Ausdruck selbst in Codeschrift.
+
+```yaml
+nodes:
+  - id: escalate
+    type: transform
+    when: '{{ nodes.score.output.total > 1000 }}'
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "Escalate " + input.total };'
+  - id: file
+    type: transform
+    elseOf: escalate
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "File " + input.total };'
+```
+
+In diesem Ausschnitt lautet die Bedingung über Escalate „total von Score größer als 1.000 ist“, **Ja** führt zu Escalate und **Nein** zu File. Zeig auf eine Bedingung oder auf ihr **Ja** oder **Nein**, um die Pfade hervorzuheben, die durch sie führen.
+
+### Linien, Rahmen und gestrichelte Kästen
+
+Eine durchgezogene Linie bedeutet, dass die untere Node die Ausgabe der oberen liest. Eine gestrichelte Linie bedeutet, dass die untere Node nach der oberen läuft, ohne ihre Ausgabe zu lesen, etwa weil ihre Bedingung sie liest. Eine gepunktete Linie zu Ende verlässt die letzte Node eines Laufs, deren Ausgabe Ende nicht zurückgibt. Die Linien **Ja** und **Nein** haben eigene Farben.
+
+Ein Rahmen um eine Node zeigt, dass sie mehrmals läuft: einmal für jedes Element einer Liste (**Für jedes Element von …**) oder erneut, bis eine Bedingung zutrifft (**Wiederholt sich, bis …, höchstens 5×**). Ein gestrichelter Kasten ist eine Node, die vielleicht nicht läuft; nach einem Lauf ist es eine Node, die nicht gelaufen ist. **Legende** neben den Zoom-Steuerelementen erklärt jede Art von Linie und Kasten.
+
+### Tastatur und Listenansicht
+
+Das Diagramm ist ein einziger Halt in der Tab-Reihenfolge. Springst du mit Tab hinein, landet der Fokus auf Start; die Pfeiltasten folgen den Linien von Kasten zu Kasten und entlang einer Reihe, Pos1 und Ende springen zu Start und Ende, und die Eingabetaste öffnet den Kasten im Fokus. Ein Screenreader liest zu jedem Kasten Titel, Art und was er liest; bei einer Bedingung hört er, über welche Node sie entscheidet.
+
+Mit dem Ansichtsschalter oben links im Canvas wechselst du zwischen **Canvas**, **Liste** und **Quelltext**. **Liste** zeigt dieselben Nodes in der Reihenfolge des Laufs, jede mit dem, was sie liest, und mit ihrer Bedingung in Worten; auch dort öffnet die Eingabetaste eine Node. Ist der Canvas sehr schmal, beginnt er mit **Liste**. Die Adresse behält die Ansicht und die geöffnete Node, sodass ein geteilter Link beides wieder öffnet.
+
+### Wenn eine neue Version eintrifft {#new-versions}
+
+Während du die Automatisierung ansiehst, kann jemand eine neue Version speichern, etwa ein Coding-Agent über MCP. Siehst du die neueste Version an und hast keine ungespeicherten Änderungen, wechselt der Canvas zur neuen: Die Kästen gleiten an ihre neuen Plätze, neue Kästen blenden sich ein, geänderte erhalten einmal einen Ring, und ein Screenreader hört „Jetzt wird v6 angezeigt.“. Die geöffnete Node bleibt offen, solange es sie noch gibt. Hast du ungespeicherte Änderungen, bewegt sich nichts. Ein Hinweis über dem Canvas meldet **Eine neuere Version wurde gespeichert**, und **v6 zeigen und Entwurf verwerfen** wechselt zu ihr.
+
+## Den möglichen Pfaden folgen {#paths}
+
+Die Bedingungen eines Laufs entscheiden, welche Nodes laufen. Die Pfad-Schaltfläche oben rechts im Canvas zählt die Wege, die ein erfolgreicher Lauf nehmen kann, etwa **3 Pfade**, und öffnet **Mögliche Pfade**. Jeder Pfad nennt die Bedingungen, die über ihn entscheiden, etwa „Triage läuft“ oder „Propose schlägt fehl, der Lauf geht weiter“, und wie viele Nodes auf ihm laufen.
+
+Zeig auf einen Pfad oder wechsle mit den Pfeiltasten zu ihm, um ihn im Canvas als Vorschau zu sehen. Klick ihn an oder drück die Eingabetaste, damit er angezeigt bleibt: Nodes abseits des Pfads werden gestrichelt und sagen, warum sie nicht laufen, Ende markiert die Ausgaben, die auf diesem Pfad leer bleiben, und ein Screenreader hört, welcher Pfad angezeigt wird. **Alle zeigen** oder Esc zeigt wieder jede Node. Die Liste bleibt offen, während du Nodes auswählst, damit du einen Pfad mit den Feldern einer Node vergleichen kannst.
+
+Unter **Beendet den Lauf, wenn sie fehlschlägt** nennt die Liste die Nodes, deren Fehler den Lauf stoppt, und was jede von ihnen fehlschlagen lassen kann. Zeig auf eine davon, um alle rot einzukreisen; wähle eine aus, um sie zu öffnen.
+
+Auf dem Smartphone öffnet sich die Liste in einem Bereich am unteren Bildschirmrand. Wählst du einen Pfad, schließt sich der Bereich, und oben im Canvas bleibt eine Pille mit dem Namen des Pfads und **Alle zeigen**. Nimmt jeder Lauf denselben Pfad, sagt die Liste das. Bei mehr als 12 Bedingungen und hingenommenen Fehlern gibt es zu viele Pfade für eine Liste; **Wann sie läuft** sagt trotzdem bei jeder Node, wann sie läuft. Ein Canvas mit einem Zyklus hat keine Pfad-Schaltfläche. [Pfade, die ein Lauf nehmen kann](/de/platform/automations/concepts#paths) erklärt, wie Tale die Pfade ermittelt.
+
+## Eine Node bearbeiten
+
+Wähle einen Kasten, um ihn zu öffnen. Auf einem breiten Bildschirm öffnet sich der Inspektor neben dem Canvas; ohne ausgewählte Node nutzt der Canvas die ganze Breite. Auf schmaleren Bildschirmen öffnet er sich in einem Bereich über dem Canvas. Sein Kopf zeigt den Titel der Node, ihre Art und ihre ID mit **Node-ID kopieren**; darunter stehen die Probleme, die zu ihr gehören. **Wann sie läuft** fasst zusammen, welchen Platz die Node im Ablauf hat: bei jedem Lauf, auf einigen Pfaden oder nie, warum sie übersprungen werden kann und was passiert, wenn sie fehlschlägt, etwa „Schlägt sie fehl, stoppt der Lauf mit ihrem Fehler.“
+
+Danach folgen drei Tabs:
+
+- **Felder** enthält, was du ändern kannst. Ein `transform` hat **Code**, ein `llm` **Prompt**, **System-Prompt**, **Modell** und **Ausgabeschema**, ein `agent` zusätzlich Agent-Laufzeit und Ausstattung. **Eingabe** enthält die JSON-Werte und Referenzen, die die Node erhält.
+- **Struktur** zeigt, was die Node erhält und zurückgibt, woher Tale diese Struktur kennt und welche Nodes ihre Ausgabe lesen. Wähle eine lesende Node, um sie zu öffnen. **Als TypeScript zeigen** zeigt dieselbe Struktur als Typ.
+- **Letzter Lauf** zeigt **Aufgelöste Eingabe**, **Ausgabe** und Effekte der Node in dem Lauf, den der Canvas zeigt. Der Tab erscheint, solange der Canvas einen Lauf zeigt.
+
+Die **Modell**-Auswahl einer `llm`- oder `agent`-Node listet die Modelle, die die verbundenen Anbieter deiner Organisation bedienen; ein nicht aufgeführtes Modell lässt sich eingeben, doch **Probleme** warnt dann, dass ein Live-Lauf an dieser Node fehlschlägt, bis sein Anbieter verbunden ist.
+
+Öffne **Ablaufsteuerung** für Bedingung, Wiederholung und Fehlerbehandlung der Node; nutzt die Node eines davon, ist der Abschnitt schon offen. **Wenn**, **Für jedes** und **Wiederholen bis** nehmen Ausdrücke auf. **Sonst zu** bietet nur Nodes mit einer Bedingung an, und **Keine** entfernt die Alternative. **Maximale Wiederholungen** erscheint mit **Wiederholen bis** und nimmt eine ganze Zahl von 1 bis 20. **Bei Fehler** wählt zwischen **Lauf stoppen** und **Ohne sie weiterlaufen**; geht der Lauf weiter, wird jede Node übersprungen, die die Ausgabe der fehlgeschlagenen Node liest. Unter einer Bedingung, einer Liste oder einer Alternative sagt ein Satz in Worten, was die Einstellung bewirkt.
+
+Mit **Schließen** kehrst du zum Canvas zurück. Auf einem breiten Bildschirm schließt sich der Bereich auch, wenn du auf den leeren Canvas klickst oder außerhalb eines Textfelds Esc drückst. Trigger und Projekteinstellungen der Automatisierung findest du im Tab **Allgemein**. [Automatisierungsgrundlagen](/de/platform/automations/concepts) erklärt Node-Typen und Ausdrücke.
+
+### Code, Prompts und JSON
+
+Code, Prompts, Bedingungen und JSON-Felder sind Code-Editoren. Sie färben die Syntax und jedes `{{ }}`-Template ein und kennen die Automatisierung. Tippst du `{{` in einen Prompt, erscheinen die schließenden Klammern mit dem Cursor dazwischen; nach `nodes.` siehst du nur die Nodes, die vorher laufen, und nach `.output.` die Felder dieser Node mit ihren Typen. Strg+Leertaste öffnet die Vorschläge überall. Zeig auf eine Referenz, um ihren Typ zu sehen, oder drück ⌘K ⌘I (Strg+K Strg+I), damit der Typ an der Cursorposition angezeigt und vorgelesen wird.
+
+Kurz nachdem du aufhörst zu tippen, ist ein Problem genau dort unterstrichen, wo es steht. F8 und Umschalt+F8 springen zum nächsten und vorherigen Problem und lesen es vor; ⌘. (Strg+.) wendet eine vorgeschlagene Korrektur an, etwa den ähnlichsten Node-Namen. In einem mehrzeiligen Feld rückt Tab ein; um es mit der Tastatur zu verlassen, drück Esc und dann Tab. **Editor vergrößern** öffnet ein langes Feld in einem größeren Editor, und **Zurück zum Feld** kehrt mit deiner Änderung und deinem Cursor an derselben Stelle zurück.
+
+Ein JSON-Feld wie **Eingabe** ändert die Node erst, wenn sein Text gültiges JSON der richtigen Art ist. Während du tippst, behält die Node ihren letzten gültigen Wert, und das Feld sagt, was fehlt, etwa „Das muss ein JSON-Objekt in geschweiften Klammern sein.“
+
+### Eingaben bei Start, Ausgabe bei Ende
+
+Wähle **Start**, um zu sehen, was die Automatisierung startet. **Trigger** nennt es in Worten; **In Allgemein ändern** öffnet den Tab **Allgemein**, in dem du den Trigger einstellst. Unter **Felder** zeigt **Eingaben** die Felder der Laufeingabe als Baum, und **Eingabeschema** enthält das JSON-Schema dahinter, das du bearbeiten kannst. **Struktur** zeigt die Eingabe so, wie Tale sie liest, und **Letzter Lauf** die Eingabe des angezeigten Laufs.
+
+Wähle **Ende**, um zu sehen, was ein Lauf zurückgibt. **Wie ein Lauf endet** nennt die drei Ausgänge; unter **Fehlgeschlagen** ist jede Node, deren Fehler den Lauf stoppt, eine Schaltfläche, die sie öffnet. Unter **Felder** enthält **Ausgabe** den JSON-Wert, den ein erfolgreicher Lauf zurückgibt, mit Templates wie `{{ nodes.report.output }}`. **Struktur** zeigt die Struktur der Ausgabe und **Letzter Lauf** die Ausgabe des angezeigten Laufs.
+
+## Den Quelltext lesen
+
+Wähle im Ansichtsschalter **Quelltext**, um das ganze Dokument als YAML zu lesen: eingefärbt, mit Zeilennummern, Einklappen und Suche (⌘F oder Strg+F). Jedes Problem, das die Prüfung gefunden hat, ist in der Zeile unterstrichen, die es betrifft. So hat auch ein Problem in einem Teil ohne eigenes Feld, etwa in einem Test oder im Namen, einen Ort, an dem du es liest. Der Quelltext ist schreibgeschützt: **YAML kopieren** kopiert ihn, und **YAML herunterladen** speichert ihn als Datei, die nach Automatisierung und Version benannt ist, etwa `gmail-triage-inbox-v3.yml`; solange du ungespeicherte Änderungen hast, kommt `-draft` dazu. Um das Dokument zu ändern, nutze die Felder oder deinen Coding-Agent.
+
+## Mit deinem Coding-Agent bearbeiten
+
+Größere Änderungen, etwa neue Nodes oder ein umgebauter Ablauf, kommen von einem Coding-Agent wie Claude Code, Codex oder Cursor, der mit dem MCP-Server von Tale verbunden ist. **Mit deinem Coding-Agent bearbeiten** ist in jeder Ansicht die letzte Schaltfläche oben rechts im Canvas und die Hauptaktion einer Automatisierung, die noch keine Nodes hat. Ihr Dialog zeigt den Namen der Automatisierung, den du dem Agent gibst, **MCP einrichten**, das **Einstellungen > API > MCP** öffnet, und **So verbindest du einen Coding-Agent**, das die Anleitung zum [MCP-Endpoint](/de/develop/mcp-endpoint) öffnet. Der Agent liest die Automatisierung, ändert und prüft sie und speichert eine neue Version, die dann im Canvas erscheint, wie [Wenn eine neue Version eintrifft](#new-versions) beschreibt.
 
 ## Probleme finden und beheben
 
-Während du bearbeitest, prüft Tale den Entwurf so, wie es auch jedes Speichern prüft. Kurz nachdem du aufhörst zu tippen, zeigt die Schaltfläche **Probleme** neben **Speichern**, was die Prüfung gefunden hat: ein rotes Fehlersymbol und ein gelbes Warnsymbol, jeweils mit ihrer Anzahl, oder **Keine Probleme**. Auf dem Smartphone sitzt die Schaltfläche in der Leiste über dem Canvas. Ein Fehler ist etwas, woran ein Lauf scheitern würde, etwa eine Referenz auf einen Knoten, den es nicht gibt. Eine Warnung ist etwas, das schiefgehen kann, etwa das Lesen der Ausgabe eines Knotens, der manchmal übersprungen wird. Ein Knoten mit Problemen zeigt dieselben Zahlen auf seinem Kasten, und ein Feld mit einem Problem erklärt es direkt darunter.
+Während du bearbeitest, prüft Tale den Entwurf so, wie es auch jedes Speichern prüft. Kurz nachdem du aufhörst zu tippen, zeigt die Schaltfläche **Probleme** neben **Speichern**, was die Prüfung gefunden hat: ein rotes Fehlersymbol und ein gelbes Warnsymbol, jeweils mit ihrer Anzahl, oder **Keine Probleme**. Auf dem Smartphone sitzt die Schaltfläche in der Leiste über dem Canvas. Ein Fehler ist etwas, woran ein Lauf scheitern würde, etwa eine Referenz auf eine Node, die es nicht gibt. Eine Warnung ist etwas, das schiefgehen kann, etwa das Lesen der Ausgabe einer Node, die manchmal übersprungen wird. Eine Node, eine Bedingung, Start oder Ende mit Problemen zeigt dieselben Zahlen auf ihrem Kasten, und ein Feld mit einem Problem erklärt es direkt darunter.
 
-Klicke auf **Probleme**, um sie aufzulisten. Auf einem breiten Bildschirm öffnet sich die Liste unter dem Canvas, auf schmaleren Bildschirmen in einem eigenen Bereich. Jeder Eintrag sagt, was falsch ist, wo, warum und wie du es behebst. **Technische Details** zeigt die Meldung der Engine selbst, und der Code neben dem Titel hilft dir bei der Suche oder im Support. **Alle**, **Fehler** und **Warnungen** filtern die Liste, Escape schließt sie.
+Klicke auf **Probleme**, um sie aufzulisten. Auf einem breiten Bildschirm öffnet sich die Liste unter dem Canvas, auf schmaleren Bildschirmen in einem eigenen Bereich. Jeder Eintrag sagt, was falsch ist, wo, warum und wie du es behebst. **Technische Details** zeigt die Meldung der Engine selbst, und der Code neben dem Titel hilft dir bei der Suche oder im Support. **Alle**, **Fehler** und **Warnungen** filtern die Liste, Esc schließt sie.
 
-Wähle einen Eintrag oder drücke darauf die Eingabetaste, um dorthin zu gelangen: Der Knoten öffnet sich, sein Feld erhält den Fokus, und wo das Feld den Text so zeigt, wie er gespeichert ist, ist die Stelle markiert, die das Problem verursacht. Ein Problem ohne eigenes Feld, etwa ein Modell, das deine Organisation nicht bereitstellt, steht unter **Probleme in dieser Node** oben in den Feldern des Knotens. Ein Problem in einem Teil der Automatisierung, den der Editor nicht zeigt, etwa in ihrer Ausgabe oder ihren Tests, sagt, dass es sich hier nicht bearbeiten lässt; ändere diesen Teil über MCP, die API oder ein hochgeladenes Paket.
+Wähle einen Eintrag oder drücke darauf die Eingabetaste, um dorthin zu gelangen: Die Node öffnet sich, ihr Feld erhält den Fokus, und die Stelle, die das Problem verursacht, ist markiert. Ein Problem ohne eigenes Feld, etwa ein Modell, das deine Organisation nicht bereitstellt, steht unter **Probleme in dieser Node** oben in den Feldern der Node. Ein Problem in den Eingaben öffnet **Start**, eines in der Ausgabe öffnet **Ende**, und eines in einem anderen Teil des Dokuments, etwa in einem Test oder im Namen, öffnet **Quelltext** an dieser Zeile. Ein Problem in einer Node, die dein Entwurf nicht mehr hat, sagt „Ändere das mit deinem Coding-Agent.“
 
-Solange Fehler bestehen, ist **Speichern** deaktiviert und nennt den Grund, zum Beispiel „Behebe 1 Fehler, um zu speichern“. Auf dem Smartphone steht **Speichern** unter den Feldern eines Knotens; dort öffnet **Probleme anzeigen** neben diesem Grund die Liste. Warnungen verhindern weder das Speichern noch das Bereitstellen. Kann Tale den Entwurf nicht prüfen, etwa weil die Verbindung abgebrochen ist, zeigt die Schaltfläche **Prüfung fehlgeschlagen**, und du kannst trotzdem speichern: Jedes Speichern wird auf dem Server erneut geprüft. Wird ein Speichern oder Bereitstellen wegen Fehlern abgelehnt, öffnet sich die Liste mit den Problemen des Servers und beginnt beim ersten Fehler.
+Solange Fehler bestehen, ist **Speichern** deaktiviert und nennt den Grund, zum Beispiel „Behebe 1 Fehler, um zu speichern“. Auf dem Smartphone steht **Speichern** unter den Feldern einer Node; dort öffnet **Probleme anzeigen** neben diesem Grund die Liste. Warnungen verhindern weder das Speichern noch das Bereitstellen. Kann Tale den Entwurf nicht prüfen, etwa weil die Verbindung abgebrochen ist, zeigt die Schaltfläche **Prüfung fehlgeschlagen**, und du kannst trotzdem speichern: Jedes Speichern wird auf dem Server erneut geprüft. Wird ein Speichern oder Bereitstellen wegen Fehlern abgelehnt, öffnet sich die Liste mit den Problemen des Servers und beginnt beim ersten Fehler.
 
 Die Prüfung läuft nur für Entwickler, Admins und Inhaber, also die Rollen, die speichern dürfen. [Was Tale vor einem Lauf prüft](/de/platform/automations/concepts#checks) erklärt jede Art von Problem.
 
@@ -53,7 +141,7 @@ Die Prüfung läuft nur für Entwickler, Admins und Inhaber, also die Rollen, di
 
 1. Ändere die nötigen Felder und klicke auf **Speichern**.
 2. Erkläre die Änderung in der **Notiz zur Version** und wähle **Version speichern**. Eine neue Version entsteht; frühere Fassungen bleiben erhalten. Hat jemand während deiner Bearbeitung eine andere Version gespeichert, lehnt Tale das Speichern ab und fragt nach: **Meine Änderungen verwerfen und neu laden** zeigt die neuere Version, **Trotzdem speichern** legt deine Version darüber an — die neuere bleibt im Versionsverlauf, die aktuelle Version ist dann aber deine.
-3. Klicke auf **Testlauf**. Hat der Workflow ein Eingabeschema, fülle im Dialog **Eingabe für den Lauf (JSON)** aus. Öffne **Eingabeschema**, um Pflichtfelder und Typen zu prüfen. Ungültiges JSON oder unpassende Werte verhindern den Start.
+3. Klicke auf **Testlauf**. Hat der Workflow ein Eingabeschema, tippe die Eingabe als JSON in **Eingabe für den Lauf (JSON)**; beim Tippen eines Schlüssels schlägt das Feld die Feldnamen des Schemas vor, und ⌘Enter (Strg+Enter) startet den Lauf. Öffne **Eingabeschema**, um Pflichtfelder und Typen zu sehen. Ungültiges JSON oder unpassende Werte verhindern den Start.
 4. Starte den Test, wechsle zum Tab **Läufe** und öffne seinen Eintrag. Vergleiche aufgelöste Eingabe, Ausgabe und geplante Aktionen mit dem erwarteten Ergebnis.
 
 Braucht ein Workflow `owner` und `repo`, könnte seine Eingabe so aussehen:
@@ -71,7 +159,7 @@ Maßgeblich ist das tatsächliche Schema des Workflows. Ein Zahlenfeld braucht e
 
 <Frame caption="Hat der Workflow Eingaben, gib JSON an und prüfe sein Schema vor dem Teststart.">
 
-![Der Testlauf-Dialog zeigt JSON-Werte für owner und repo und das aufgeklappte Eingabeschema.](/images/platform/automation-run-input.webp)
+![Der Testlauf-Dialog zeigt JSON-Werte für owner und repo im Code-Editor und das aufgeklappte Eingabeschema als Liste von Feldern.](/images/platform/automation-run-input.webp)
 
 </Frame>
 
@@ -85,7 +173,7 @@ Ein Trigger nutzt ebenfalls die bereitgestellte Version. Richte ihn ein, wenn wi
 
 ## Ein Ergebnis untersuchen
 
-**Letzten Lauf einblenden** legt Laufzustände über den Canvas. Wähle einen Knoten für die Angaben zu diesem Lauf: aufgelöste Eingabe, Ausgabe und Effekte. Häufig findest du so eine falsche Referenz. Vergleiche die Eingabe des fehlgeschlagenen Knotens mit der Ausgabe seiner Quelle.
+Sobald die Automatisierung gelaufen ist, zeigt der Canvas ihren letzten Lauf: Die unterste Zeile jeder Node sagt, wie sie endete, etwa **Erfolgreich** oder **Übersprungen**, und jede Bedingung zeigt, wie sie entschieden hat, **Ja** oder **Nein**. Die Augen-Schaltfläche oben rechts im Canvas, **Letzten Lauf ausblenden**, nimmt den Lauf vom Canvas, und **Letzten Lauf einblenden** zeigt ihn wieder. Wähle eine Node und öffne **Letzter Lauf**, um ihre **Aufgelöste Eingabe**, **Ausgabe** und Effekte zu sehen. Häufig findest du so eine falsche Referenz: Vergleiche die Eingabe der fehlgeschlagenen Node mit der Ausgabe der Node, die sie liest.
 
 Wechsle zu **Läufe** und öffne den vollständigen Datensatz. Die Tabs bleiben sichtbar; **Läufe** ist aktiv. Mit **Editor** kehrst du zum Workflow zurück. Prüfe Test- oder Live-Modus und bereits ausgeführte Aktionen, bevor du erneut startest. [Ausführungsprotokolle](/de/platform/automations/execution-logs) erklärt Wartezustände, Fehler, automatische Wiederholungen und Abbruch.
 
diff --git a/docs/de/platform/automations/execution-logs.md b/docs/de/platform/automations/execution-logs.md
index 54fdceb852..9c30d6d7f3 100644
--- a/docs/de/platform/automations/execution-logs.md
+++ b/docs/de/platform/automations/execution-logs.md
@@ -7,7 +7,7 @@ description: Verfolge einen Lauf bis zur betroffenen Node, prüfe protokollierte
 
 <Frame caption="Ein abgeschlossener Testlauf: Status, Modus, Version, Starter und Zeiten über dem Workflow, mit dem Ergebnis jeder Node.">
 
-![Die Seite eines Testlaufs von Triage GitHub issues, markiert mit Succeeded, Test und v1 und von dir gestartet, mit Start- und Endzeit über dem Workflow-Graphen, in dem die Nodes issues, open issues, score und report jeweils Ran zeigen; unter dem Graphen beginnt die Liste der Auswirkungen des Laufs.](/images/platform/automation-run-detail.webp)
+![Die Seite eines Testlaufs von Triage GitHub issues, markiert mit Succeeded, Test und v1 und von dir gestartet, mit Start- und Endzeit über dem Workflow-Graphen, in dem die Nodes issues, open issues, score und report jeweils Succeeded zeigen; unter dem Graphen beginnt die Liste der Auswirkungen des Laufs.](/images/platform/automation-run-detail.webp)
 
 </Frame>
 
@@ -36,9 +36,11 @@ Lass den Lauf während der Prüfung zurückgehalten. **Stopp anfordern** bittet
 
 ## Die betroffene Node untersuchen
 
-Wähle eine Node auf dem Canvas des Laufs. **Aufgelöste Eingabe** zeigt die Werte nach der Vorlagenauswertung, **Ausgabe** das Ergebnis des Schritts. So unterscheidest du einen falschen Verweis von einem Dienstausfall.
+Ein fehlgeschlagener Lauf öffnet sich mit der fehlgeschlagenen Node im Blick. Sie ist rot umrahmt, und ihre unterste Zeile zeigt die erste Zeile ihres Fehlers; die Nodes, über die der Lauf zu ihr kam, treten hervor, während die übrigen zurücktreten; und Ende sagt, wo der Lauf fehlschlug, etwa **Fehlgeschlagen bei Propose**.
 
-Node-Zustände sind unter anderem **Gelaufen**, **Übersprungen**, **Fehlgeschlagen**, **Nie erreicht**, **Noch nicht erreicht** und bei einem gestoppten Lauf **Hier gestoppt** für die Node, an der der Lauf beim Stoppen stand. Eine Node kann wegen einer falschen Bedingung, einer Abhängigkeit, eines anderen Zweigs oder einer Weiterlaufregel übersprungen werden. Das ist nicht immer ein Fehler.
+Wähle eine Node auf dem Canvas des Laufs, um ihren Tab **Letzter Lauf** zu öffnen. **Aufgelöste Eingabe** zeigt die Werte nach der Vorlagenauswertung, **Ausgabe** das Ergebnis des Schritts. So unterscheidest du einen falschen Verweis von einem Dienstausfall.
+
+Im Canvas sagt die unterste Zeile jeder Node, wie sie endete: **Erfolgreich**, **Fehlgeschlagen**, **Übersprungen**, **Nicht ausgeführt**, **Noch nicht erreicht** oder bei einem gestoppten Lauf **Hier gestoppt** für die Node, an der der Lauf beim Stoppen stand. Jede Bedingung zeigt, wie sie entschieden hat, **Ja** oder **Nein**. Die Kennzeichnung im Tab **Letzter Lauf** nennt dieselben Zustände **Gelaufen**, **Fehlgeschlagen**, **Übersprungen**, **Nie erreicht**, **Noch nicht erreicht** und **Hier gestoppt**. Eine Node kann wegen einer falschen Bedingung, einer Abhängigkeit, eines anderen Zweigs oder einer Weiterlaufregel übersprungen werden. Das ist nicht immer ein Fehler.
 
 Beispielsweise kann eine Erinnerungs-Node den Kundennamen, aber eine leere Rechnungs-ID erhalten. Prüfe die Ausgabe davor. Verwendet der Datensatz inzwischen ein anderes Feld, korrigiere den Verweis statt der Mail-Zugangsdaten. Prüfe danach die aufgelöste Eingabe in einem neuen Testlauf.
 
diff --git a/docs/de/tutorials/editor/workflow-with-approvals.md b/docs/de/tutorials/editor/workflow-with-approvals.md
index 0e8a1f9fb1..c6db6c3d26 100644
--- a/docs/de/tutorials/editor/workflow-with-approvals.md
+++ b/docs/de/tutorials/editor/workflow-with-approvals.md
@@ -13,7 +13,7 @@ Der Mock-Test braucht keine Postfach-Zugangsdaten. Für einen tatsächlich freig
 
 ## Das Beispiel importieren
 
-Speichere den folgenden Inhalt als `workflow.yml`. Der Knoten `draft` liefert festen Text, damit das Ergebnis leicht prüfbar ist. `send` liest ihn; diese Referenzen erzeugen die Verbindung auf dem Canvas.
+Speichere den folgenden Inhalt als `workflow.yml`. Die Node `draft` liefert festen Text, damit das Ergebnis leicht prüfbar ist. `send` liest ihn; diese Referenzen erzeugen die Verbindung auf dem Canvas.
 
 ```yaml
 version: 1
@@ -60,7 +60,7 @@ Existiert der Name bereits, fügt der Upload eine weitere Version hinzu. Wähle
 
 Klicke im **Editor** auf **Testlauf**. Dieses Beispiel braucht keine Laufzeiteingabe und kann mit einem leeren Objekt laufen. Wechsle zu **Läufe**. Dort sollte ein **Erfolgreich** abgeschlossener Test erscheinen.
 
-Öffne den Lauf und prüfe auf dem Canvas, ob beide Knoten den Status **Gelaufen** zeigen. Wähle `send` und prüfe die aufgelöste Eingabe. Der Empfänger muss `reviewer@example.com` sein, der Betreff `Approval practice` und der Text der Satz aus `draft`. In diesem Modus antwortet ein deterministischer Mock des Connectors. Es wird keine E-Mail gesendet und keine Freigabekarte angezeigt.
+Öffne den Lauf und prüfe auf dem Canvas, ob beide Nodes **Erfolgreich** zeigen. Wähle `send` und prüfe die aufgelöste Eingabe. Der Empfänger muss `reviewer@example.com` sein, der Betreff `Approval practice` und der Text der Satz aus `draft`. In diesem Modus antwortet ein deterministischer Mock des Connectors. Es wird keine E-Mail gesendet und keine Freigabekarte angezeigt.
 
 Der Workflow enthält einen Test, der den Effekt `imap-smtp.send` erwartet. Ein erfolgreicher Mock prüft Ablauf und vorgesehenen Aufruf. Er belegt weder gültige Postfach-Zugangsdaten noch die Zustellung.
 
@@ -68,7 +68,7 @@ Der Workflow enthält einen Test, der den Effekt `imap-smtp.send` erwartet. Ein
 
 Kehre zum **Editor** zurück und klicke auf **v1 live schalten**, um die getestete Version live zu schalten. Lass den Trigger unkonfiguriert; diese Übung startet einmal von Hand.
 
-Wähle **Live ausführen**, lies Bestätigung und Organisationsumfang und bestätige. Wechsle zu **Läufe** und öffne den neuen Lauf mit dem Status **Wartet**. Die Freigabekarte sollte den Titel **Wartet auf deine Freigabe: imap-smtp.send**, den Knoten `send` sowie dessen geplante Eingabe unter **Der Schritt würde aufrufen mit** zeigen. Empfänger, Betreff und Text müssen dem Mock-Test entsprechen.
+Wähle **Live ausführen**, lies Bestätigung und Organisationsumfang und bestätige. Wechsle zu **Läufe** und öffne den neuen Lauf mit dem Status **Wartet**. Die Freigabekarte sollte den Titel **Wartet auf deine Freigabe: imap-smtp.send**, die Node `send` sowie deren geplante Eingabe unter **Der Schritt würde aufrufen mit** zeigen. Empfänger, Betreff und Text müssen dem Mock-Test entsprechen.
 
 Wartet der Lauf nicht, prüfe Status und Richtlinie, bevor du fortfährst. Ein fehlgeschlagener Connector-Aufruf beweist nicht, dass eine Freigabe angefordert wurde.
 
diff --git a/docs/en/platform/automations/assistant.md b/docs/en/platform/automations/assistant.md
index 4ca6ee4345..bc41870e41 100644
--- a/docs/en/platform/automations/assistant.md
+++ b/docs/en/platform/automations/assistant.md
@@ -1,30 +1,30 @@
 ---
 title: Choose how to author an automation
-description: Use the visual editor for direct changes or connect an external assistant to Tale through MCP.
+description: Change an automation's fields in the editor, or have a coding agent build and change it through MCP.
 ---
 
-Edit an automation directly on its canvas, or connect an external assistant through MCP to author it with Tale’s tools. Both routes save versions of the same workflow and use the same validation and deployment rules. You need Developer-level permission to author and deploy automations.
+Change an automation's fields directly in the editor, or have a coding agent such as Claude Code, Codex or Cursor build and change it through MCP. Both routes save versions of the same workflow and use the same validation and deployment rules. You need Developer-level permission to author and deploy automations.
 
-## Make a change in the visual editor
+## Make a change in the editor
 
-Open **Automations** and select the workflow. Select a node to inspect its input, model, code, or other configuration. Save the change with a version message, run a test, and deploy the intended version when its checks pass.
+Open **Automations** and select the workflow. Select a node to inspect its input, model, code, or other configuration, and change the field you need. Save the change with a version message, run a test, and deploy the intended version when its checks pass. The canvas arranges itself from the references between nodes; you don't add nodes or draw connections on it.
 
 <Frame caption="Selecting a node opens its configuration beside the workflow graph.">
 
-![The automation editor shows a workflow graph and the selected node’s input fields in a side panel.](/images/platform/automation-editor-canvas.webp)
+![The automation editor shows the workflow between Start and End and the selected node’s fields in a side panel.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
-[The workflow editor](/platform/automations/editor) covers these steps in detail, including inspecting a run and returning to an earlier version. The canvas does not include a conversational assistant panel.
+[The workflow editor](/platform/automations/editor) covers these steps in detail, including reading the canvas, inspecting a run and returning to an earlier version. The canvas does not include a conversational assistant panel.
 
-## Use an external assistant through MCP
+## Change it with your coding agent
 
-Configure your client with the endpoint under **Settings > API > MCP** and an appropriate organization API key. Give it the desired inputs, output, and the systems the workflow may change. Ask it to inspect existing automations and available capabilities before creating another one.
+**Edit with your coding agent**, the last button at the top right of the editor's canvas, is the way in. Its dialog shows the automation's name to give the agent, **Set up MCP**, which opens **Settings > API > MCP**, and a link to the guide for connecting a coding agent. Configure your client with that endpoint and an appropriate organization API key. Give it the desired inputs, output, and the systems the workflow may change, and ask it to inspect existing automations and available capabilities before creating another one.
 
-The [MCP endpoint](/develop/mcp-endpoint) provides documentation, validation, save, test, and deploy tools. Review the resulting workflow and its test output before deployment. A successful save creates a version; it does not make that version live.
+The [MCP endpoint](/develop/mcp-endpoint) provides documentation, validation, save, test, and deploy tools. A version the agent saves appears on the canvas while you look at the automation. Review the resulting workflow and its test output before deployment. A successful save creates a version; it does not make that version live.
 
 ## Keep runtime decisions separate
 
-An agent node inside an automation performs work during a run. It is separate from the client you use to write the workflow. Similarly, an [approval](/platform/approvals/concepts) authorizes one pending operation during execution; it does not approve a proposed edit to the workflow definition.
+An agent node inside an automation performs work during a run. It is separate from the coding agent you use to write the workflow. Similarly, an [approval](/platform/approvals/concepts) authorizes one pending operation during execution; it does not approve a proposed edit to the workflow definition.
 
-Choose [the editor](/platform/automations/editor) for a change you want to make directly, or [MCP](/develop/mcp-endpoint) for authoring from your own client. Start from [an existing automation](/platform/automations/catalog) when a suitable one is already available.
+Choose [the editor](/platform/automations/editor) for a change you want to make directly, or [MCP](/develop/mcp-endpoint) for authoring with your coding agent. Start from [an existing automation](/platform/automations/catalog) when a suitable one is already available.
diff --git a/docs/en/platform/automations/concepts.md b/docs/en/platform/automations/concepts.md
index 80d3562d32..1418301c5d 100644
--- a/docs/en/platform/automations/concepts.md
+++ b/docs/en/platform/automations/concepts.md
@@ -46,13 +46,13 @@ Tale lays out the canvas from the references between nodes, so nobody places a n
 
 ### Edges are derived, not declared
 
-There is no edge list. One node reads another by referencing it — `{{ nodes.invoice.output.id }}` — and that reference _is_ the edge the canvas draws. Execution order is a topological sort over those derived edges, which is why deleting a reference also removes an arrow, and why two nodes that read each other are refused as a cycle.
+There is no edge list. One node reads another by referencing it — `{{ nodes.invoice.output.id }}` — and that reference _is_ the edge the canvas draws. Execution order is a topological sort over those derived edges, which is why deleting a reference also removes a line, and why two nodes that read each other are refused as a cycle.
 
 Templates use a single `{{ }}` JavaScript-expression grammar over `input`, `nodes.<id>.output`, and, inside an iterating node, `item` and `index`.
 
 ### Control flow rides on the node
 
-Branching and looping are fields on a node rather than separate step types, so the canvas shows them as badges on the box they affect.
+Branching and looping are fields on a node rather than separate step types. The canvas draws each one where it acts: a `when` becomes a condition above its node, an `elseOf` alternative hangs from that condition as its **No** branch, `forEach` and `repeatUntil` put the node in a frame, and `onError: continue` adds a chip to the node.
 
 | Field                        | What it does                                                             |
 | ---------------------------- | ------------------------------------------------------------------------ |
@@ -80,6 +80,12 @@ A **structured** output has named fields that you can reference with `nodes.<id>
 
 A tool without an output schema is unstructured. To turn its text into structured data for later steps, use an `llm` node with an `outputSchema`. Validation errors identify the invalid reference and the fields or context that are allowed. Correct that reference before saving again.
 
+## Paths a run can take {#paths}
+
+Each condition, and each node that may fail while the run goes on, gives a run two ways to continue. Tale tries every combination of them and keeps the distinct ways a successful run can go; each one is a path. A path names the conditions that decide it, such as which nodes run, which are skipped and which fail while the run goes on, and the nodes that run on it. A node that runs on every path always runs; a node that runs on none can never run, and Tale warns about it.
+
+Tale lists up to 32 paths and counts the rest. With more than 12 conditions and tolerated failures, the combinations are too many to go through, so Tale lists no path; it still says for each node when it runs. Separately, Tale names the nodes whose failure ends the run and what can make each one fail. The editor shows the paths on the canvas, as [Follow the possible paths](/platform/automations/editor#paths) describes; a client of the [MCP endpoint](/develop/mcp-endpoint) reads the same paths from `analysis.paths`.
+
 ## What Tale checks before a run {#checks}
 
 Tale checks the whole document when you save it, when you deploy a version, and whenever a client calls `validate_automation`. An **error** describes a definite failure or code that exceeds the analysis limits, and it stops both saving and deploying. A **warning** points at something that can fail or does no useful work; it never stops a save or a deployment, so you decide whether to act on it. Each problem names its node and field and, inside a template, a condition, or code, the exact expression.
diff --git a/docs/en/platform/automations/editor.md b/docs/en/platform/automations/editor.md
index 8cf204ccf2..7ec4585e16 100644
--- a/docs/en/platform/automations/editor.md
+++ b/docs/en/platform/automations/editor.md
@@ -1,25 +1,25 @@
 ---
 title: The workflow editor
-description: Inspect and edit nodes, supply test input, save a version, and deploy or roll back an automation.
+description: Read an automation on its canvas, follow its possible paths, edit node fields, save a version, and deploy or roll back.
 ---
 
-Use the workflow editor to change what an automation does and decide which saved version runs live. You need Developer, Admin, or Owner permissions to make changes. Saving, testing, and deployment are separate steps: editing a draft leaves the deployed version in place.
+Use the workflow editor to read what an automation does, change its fields, and decide which saved version runs live. Larger changes, such as new nodes, come from a coding agent through MCP. You need Developer, Admin, or Owner permissions to make changes. Saving, testing, and deployment are separate steps: editing a draft leaves the deployed version in place.
 
 Open **Automations**, then select an automation. It opens on **Editor**. An automation you open from a project's **Automations** tab shows that project at the start of the breadcrumb trail: choose the project's name to return to the project, or **Automations** to return to its automations. Whether you open an automation from a project or from the automation list, the rail marks **Automations**. To create one first, use [Create or import an automation](/platform/automations/catalog).
 
 | Tab | Use it to |
 | --- | --- |
-| **Editor** | Change the workflow, test a saved version and choose what runs live. |
+| **Editor** | Read and change the workflow, test a saved version and choose what runs live. |
 | **General** | Choose what starts the automation and which projects can use it. |
 | **Runs** | Inspect recent executions and open a run’s full record. |
 
 The **Version** selector stays at the right of the Editor, General and Runs tabs on desktop and mobile. Open it to read version messages, dates, test results and the live marker, then select a row to open that version. On desktop, run actions sit beside the tabs together with **Save** and **Discard**; on **General**, only **Save** and **Discard** sit there. A dot on a tab marks its unsaved changes. Leaving the tab or switching versions asks you to resolve those changes first.
 
-On a phone, opening an automation starts with compact navigation. The editor canvas fills the available height, and its run and deploy controls sit inside the canvas beside the zoom controls. Selecting a node opens its fields — and Save and Discard — in a panel at the bottom of the screen.
+On a phone, opening an automation starts with compact navigation. The editor canvas fills the available height, and its run and deploy controls sit in a toolbar at the bottom of the canvas. Selecting a node opens its fields — and Save and Discard — in a panel at the bottom of the screen.
 
 <Frame caption="On a wide screen, select a node to inspect its fields beside the canvas.">
 
-![The workflow editor shows connected nodes and the selected node’s fields beside the canvas.](/images/platform/automation-editor-canvas.webp)
+![The workflow editor shows the nodes of Gmail triage inbox between Start and End, a condition in words above one node, and the selected node’s fields beside the canvas.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
@@ -27,23 +27,111 @@ To switch without returning to the list, click the current automation's name in
 
 ## Read the canvas
 
-Each box is a node. Its label identifies the step and type; **Reads** lists the nodes whose outputs it uses. Arrows come from references such as `{{ nodes.draft.output.text }}`. Edit the reference to change the dependency. The canvas does not create dependencies by drawing an arrow.
+Tale draws the canvas from the automation's document and arranges it for you: **Start** sits at the top, **End** at the bottom, and every node sits below the nodes it reads, so the canvas reads from top to bottom in the order a run goes. Nobody places a box, and drawing does not connect anything. A line comes from a reference such as `{{ nodes.draft.output.text }}`; to change what a node reads, change the reference.
 
-Badges show conditions and loops: `when`, `else of`, `for each`, `repeat until`, and `continue on error`. A cycle warning means two or more nodes depend on one another; remove the circular reference before saving a runnable version.
+### Start and End
+
+**Start** says what starts a run and what it receives. Under **Starts**, it lists the trigger in words, such as a schedule with its time zone and next run, and says when the trigger is off or waits for a live version. **By hand, the API or MCP** follows, because those starts are always possible. Under **Input**, it lists the fields of the run input with their type and whether they are required. When the trigger would start runs whose input the automation refuses, Start says so.
+
+**End** says what a successful run returns and how a run can end. Under **Returns**, it names the output, such as **The output of Report**, or lists its fields and the nodes they come from; a field that is empty on some runs says **may be empty**. Under **Ends**, it lists the three outcomes: **Succeeded** returns the output, **Failed** happens when one of the nodes that stop the run fails, and **Stopped** happens when someone stops the run.
+
+### Nodes
+
+Each node is a box. Its first line shows the node's icon and its title, made from its ID: `open_issues` reads **Open issues**. The next line says what kind of node it is: the connector and action, such as **GitHub · List issues**, **Transform**, **Language model** or **Agent** with its model, or the automation it calls. When Tale knows what the node returns, a line shows the shape, such as `{ issues: object[] }`. The bottom line says what the node reads, such as **Reads Issues and run input (owner, repo)**, or **Reads no other node**.
+
+Chips and small icons add what the layout cannot show. **Continues on error** marks a node whose failure the run tolerates, and **Never runs** a node that no combination of conditions reaches. A shield marks a node that changes data in a connected service, where a live run may wait for an approval; a speech bubble marks an agent that may ask a question; a crossed-out pin marks a model with no pinned provider. Point at an icon to read its sentence; a screen reader hears it with the box. A box with problems shows their counts in its first line.
+
+### Conditions and branches
+
+A node's condition (`when`) stands above it as a pill that says the condition in words, such as "total of Score is greater than 1,000". The node below runs only if the condition holds. When another node is its alternative (`elseOf`), the condition splits into two lines: **Yes** leads to the node on the left, which runs when the condition holds, and **No** leads to its alternative on the right. A condition that Tale cannot put into words shows the expression itself, in code type.
+
+```yaml
+nodes:
+  - id: escalate
+    type: transform
+    when: '{{ nodes.score.output.total > 1000 }}'
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "Escalate " + input.total };'
+  - id: file
+    type: transform
+    elseOf: escalate
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "File " + input.total };'
+```
+
+In this excerpt, the condition above Escalate reads "total of Score is greater than 1,000", **Yes** leads to Escalate and **No** to File. Point at a condition, or at its **Yes** or **No**, to light up the paths through it.
+
+### Lines, frames and dashed boxes
+
+A solid line means the lower node reads the output of the upper one. A dashed line means the lower node runs after the upper one without reading its output, as when its condition reads it. A dotted line into End leaves the last node of a run whose output End does not return. The **Yes** and **No** lines have their own colours.
+
+A frame around a node says it runs more than once: once per item of a list (**For each item of …**) or again until a condition holds (**Repeats until …, at most 5×**). A dashed box is a node that may not run; after a run, it is a node that didn't run. **Legend**, beside the zoom controls, explains each kind of line and box.
+
+### Keyboard and the List view
+
+The chart is one stop in the Tab order. Tab to it and the focus lands on Start; the arrow keys follow the lines from box to box and move along a row, Home and End jump to Start and End, and Enter opens the box in focus. A screen reader hears each box's title, its kind and what it reads; for a condition, it hears which node the condition decides on.
+
+The view switch at the top left of the canvas changes between **Canvas**, **List** and **Source**. **List** shows the same nodes in run order, each with what it reads and its condition in words, and Enter opens a node from there too. When the canvas is very narrow, it starts in **List**. The address keeps the view and the open node, so a link you share opens both.
+
+### When a new version arrives {#new-versions}
+
+Someone can save a new version while you look at the automation, for example a coding agent through MCP. If you are looking at the latest version and have no unsaved changes, the canvas switches to the new one: boxes glide to their new places, new boxes fade in, changed ones are ringed once, and a screen reader hears "Now showing v6.". The node you had open stays open if it still exists. If you have unsaved changes, nothing moves. A notice above the canvas says **A newer version was saved**, and **Show v6 and discard my draft** switches to it.
+
+## Follow the possible paths {#paths}
+
+A run's conditions decide which nodes run. The paths button at the top right of the canvas counts the ways a successful run can go, such as **3 paths**, and opens **Possible paths**. Each path names the conditions that decide it, such as "Triage runs" or "Propose fails, the run goes on", and how many nodes run on it.
+
+Point at a path, or move to it with the arrow keys, to preview it on the canvas. Click it or press Enter to keep it shown: nodes off the path turn dashed and say why they don't run, End marks the outputs that stay empty on that path, and a screen reader hears which path is shown. **Show all**, or Escape, shows every node again. The list stays open while you select nodes, so you can compare a path with a node's fields.
+
+Under **Ends the run when it fails**, the list names the nodes whose failure stops the run, with what can make each one fail. Point at one to ring all of them in red; select one to open it.
+
+On a phone, the list opens in a panel at the bottom of the screen. Choosing a path closes the panel and leaves a pill at the top of the canvas that names the path, with **Show all**. When every run takes the same path, the list says so. An automation with more than 12 conditions and tolerated failures has too many paths to list; each node's **When it runs** still says when it runs. A canvas with a cycle has no paths button. [Paths a run can take](/platform/automations/concepts#paths) explains how Tale works the paths out.
 
 ## Edit a node
 
-Select a box to open its fields. On a wide screen, the panel opens beside the canvas; until you select a node, the canvas takes the full width. On narrower screens, the fields open in a dialog over the canvas. A `transform` has **Code**; an `llm` has prompt, model, and output-schema fields; an `agent` also has agent runtime and equipment. The **Model** picker of an `llm` or `agent` node lists the models your organization’s connected providers serve; a model that is not listed can still be typed, but **Problems** then warns that a live run would fail at that node until its provider is connected. **Input** contains JSON values and references passed to the node. Incomplete JSON is reported and does not update the node.
+Select a box to open it. On a wide screen, the inspector opens beside the canvas; until you select a node, the canvas takes the full width. On narrower screens, it opens in a panel over the canvas. Its header shows the node's title, its kind, and its ID with **Copy node ID**; problems that belong to the node are listed under it. **When it runs** sums up the node's place in the flow: on every run, on some of the paths or never, why it can be skipped, and what happens when it fails, such as "If it fails, the run stops with its error."
+
+Three tabs follow:
+
+- **Fields** holds what you can change. A `transform` has **Code**; an `llm` has **Prompt**, **System prompt**, **Model** and **Output schema**; an `agent` also has its agent runtime and equipment. **Input** contains the JSON values and references passed to the node.
+- **Shape** shows what the node receives and returns, where Tale got that shape from, and which nodes read its output. Select a reader to open it. **Show as TypeScript** shows the same shape as a type.
+- **Last run** shows the node's **Resolved input**, **Output** and effects in the run shown on the canvas. It appears while the canvas shows a run.
+
+The **Model** picker of an `llm` or `agent` node lists the models your organization’s connected providers serve; a model that is not listed can still be typed, but **Problems** then warns that a live run would fail at that node until its provider is connected.
+
+Open **Control flow** for the node's condition, iteration and failure handling; it is already open on a node that uses one of them. **When**, **For each** and **Repeat until** take expressions. **Else of** offers only nodes that have a condition, and **None** removes the alternative. **Maximum repeats** appears with **Repeat until** and takes a whole number from 1 to 20. **On error** chooses between **Stop the run** and **Continue without it**; continuing skips every node that reads the failed node's output. Under a condition, a list or an alternative, a sentence says in words what the setting does.
+
+Use **Close** to return to the canvas. On a wide screen, clicking the empty canvas or pressing Escape outside a text field also closes the panel. The automation's trigger and project settings are on the **General** tab. [Automation concepts](/platform/automations/concepts) explains the node types and expression rules.
+
+### Code, prompts and JSON
+
+Code, prompts, conditions and JSON fields are code editors. They colour the syntax and every `{{ }}` template, and they know the automation. Type `{{` in a prompt and the closing braces appear with the cursor between them; type `nodes.` to see only the nodes that run earlier, and `.output.` to see that node's fields with their types. Ctrl+Space opens the suggestions anywhere. Point at a reference to see its type, or press ⌘K ⌘I (Ctrl+K Ctrl+I) to have the type at the cursor shown and read out.
+
+A moment after you stop typing, a problem is underlined exactly where it is. F8 and Shift+F8 move to the next and previous problem and read it out; ⌘. (Ctrl+.) applies a suggested fix, such as the closest node name. In a field with several lines, Tab indents; to leave it with the keyboard, press Escape, then Tab. **Expand editor** opens a long field in a larger editor, and **Back to the field** returns to it with your edit and your cursor in place.
+
+A JSON field such as **Input** changes the node only when its text is valid JSON of the right kind. While you type, the node keeps its last valid value and the field says what is missing, such as "This must be a JSON object, in curly braces."
+
+### Start inputs and End output
+
+Select **Start** to see what starts the automation. **Trigger** lists it in words; **Change in General** opens the **General** tab, where you set the trigger. Under **Fields**, **Inputs** shows the fields of the run input as a tree, and **Input schema** holds the JSON Schema behind them, which you can edit. **Shape** shows the input as Tale reads it, and **Last run** the input of the run shown.
+
+Select **End** to see what a run returns. **How a run ends** lists the three outcomes; under **Failed**, each node whose failure stops the run is a button that opens it. Under **Fields**, **Output** holds the JSON value a successful run returns, with templates such as `{{ nodes.report.output }}`. **Shape** shows the output's shape, and **Last run** the output of the run shown.
+
+## Read the source
+
+Choose **Source** in the view switch to read the whole document as YAML, highlighted, with line numbers, folding and search (⌘F or Ctrl+F). Every problem the check found is underlined at the line it concerns, so a problem in a part without a field of its own, such as a test or the name, has a place to be read. The source is read-only: **Copy YAML** copies it, and **Download YAML** saves it as a file named after the automation and version, such as `gmail-triage-inbox-v3.yml`, with `-draft` added while you have unsaved changes. To change the document, use the fields or your coding agent.
+
+## Edit with your coding agent
 
-Open **Control flow** for conditions and iteration; it is already open on a node that has one. Use **Close** to return to the canvas. On a wide screen, clicking the empty canvas or pressing Escape outside a text field also closes the panel. The automation's trigger and project settings are on the **General** tab. [Automation concepts](/platform/automations/concepts) explains the node types and expression rules.
+Larger changes, such as adding nodes or reworking the flow, come from a coding agent such as Claude Code, Codex or Cursor, connected to Tale's MCP server. **Edit with your coding agent** is the last button at the top right of the canvas in every view, and the main action of an automation that has no nodes yet. Its dialog shows the automation's name to give the agent, **Set up MCP**, which opens **Settings > API > MCP**, and **How to connect a coding agent**, which opens the [MCP endpoint](/develop/mcp-endpoint) guide. The agent reads the automation, changes and checks it, and saves a new version, which then appears on the canvas as [When a new version arrives](#new-versions) describes.
 
 ## Find and fix problems
 
-While you edit, Tale checks the draft the same way it checks a save. A moment after you stop typing, the **Problems** button beside **Save** shows what the check found: a red error icon and an amber warning icon, each with its count, or **No problems**. On a phone, the button sits in the toolbar over the canvas. An error is something a run would fail on, such as a reference to a node that does not exist. A warning is something that might go wrong, such as reading the output of a node that is sometimes skipped. A node with problems shows the same counts on its box, and a field with a problem explains it under the field.
+While you edit, Tale checks the draft the same way it checks a save. A moment after you stop typing, the **Problems** button beside **Save** shows what the check found: a red error icon and an amber warning icon, each with its count, or **No problems**. On a phone, the button sits in the toolbar over the canvas. An error is something a run would fail on, such as a reference to a node that does not exist. A warning is something that might go wrong, such as reading the output of a node that is sometimes skipped. A node, a condition, Start or End with problems shows the same counts on its box, and a field with a problem explains it under the field.
 
 Click **Problems** to list them. On a wide screen the list opens under the canvas; on narrower screens it opens in a panel. Each entry says what is wrong, where it is, why, and how to fix it. **Technical details** shows the engine's own message, and the code beside the title helps when you search or ask for support. **All**, **Errors** and **Warnings** filter the list, and Escape closes it.
 
-Select an entry, or press Enter on it, to go there: the node opens, its field takes focus, and where the field shows the text as written, the part that causes the problem is selected. A problem with no field of its own, such as a model the organization does not serve, is listed under **Problems in this node** at the top of the node's fields. A problem in a part of the automation the editor does not show, such as its output or its tests, says that it can't be edited here; change that part through MCP, the API or an uploaded package.
+Select an entry, or press Enter on it, to go there: the node opens, its field takes focus, and the part that causes the problem is selected. A problem with no field of its own, such as a model the organization does not serve, is listed under **Problems in this node** at the top of the node's fields. A problem in the inputs opens **Start**, one in the output opens **End**, and one in any other part of the document, such as a test or the name, opens **Source** at that line. A problem in a node that your draft no longer has says "Change this with your coding agent."
 
 While errors remain, **Save** is disabled and says why, for example "Fix 1 error to save". On a phone, where **Save** sits under a node's fields, **Show problems** beside that reason opens the list. Warnings never block saving or deploying. If Tale can't check the draft, for example because the connection dropped, the button shows **Couldn't check** and you can still save: every save is checked again on the server. When a save or a deploy is refused because of errors, the list opens with the server's problems, starting at the first error.
 
@@ -53,7 +141,7 @@ The check runs only for Developers, Admins and Owners, the roles that can save.
 
 1. Edit the required fields and click **Save**.
 2. Enter a **Version message** that explains the change, then **Save version**. This appends a version and preserves earlier ones. If someone saved another version while you were editing, Tale refuses the save and asks: **Discard my changes and reload** shows the newer version, **Save anyway** appends your version on top of it — the newer one stays in the version history, but the latest version is then yours.
-3. Click **Test run**. If the workflow declares an input schema, fill **Run input (JSON)** in the dialog. Expand **Input schema** to inspect required fields and types. Invalid JSON or a schema mismatch prevents the start.
+3. Click **Test run**. If the workflow declares an input schema, type the input as JSON in **Run input (JSON)**; the field suggests the schema's field names as you type a key, and ⌘Enter (Ctrl+Enter) starts the run. Expand **Input schema** to see the required fields and their types. Invalid JSON or a schema mismatch prevents the start.
 4. Start the test, switch to the **Runs** tab and inspect its row. Open it to compare the resolved input, output, and proposed operations with your expected result.
 
 For a workflow requiring `owner` and `repo`, an input might be:
@@ -71,7 +159,7 @@ Use the workflow's actual schema. A field typed as a number must receive a JSON
 
 <Frame caption="For an input-driven workflow, supply JSON and inspect its schema before starting the test.">
 
-![The Test run dialog shows owner and repo JSON values and the expanded input schema.](/images/platform/automation-run-input.webp)
+![The Test run dialog shows owner and repo JSON values in the code editor and the expanded input schema as a list of fields.](/images/platform/automation-run-input.webp)
 
 </Frame>
 
@@ -85,7 +173,7 @@ A trigger also runs the deployed version. Set it up only when you are ready for
 
 ## Diagnose a result
 
-**Show last run** overlays run states on the canvas. Select a node to see **In this run**, its **Resolved input**, **Output**, and effects. This is often enough to find a wrong reference: compare the input received by the failed node with the output of the node it reads.
+Once the automation has run, the canvas shows its latest run: each node's bottom line says how it ended, such as **Succeeded** or **Skipped**, and each condition shows how it decided, **Yes** or **No**. The eye button at the top right of the canvas, **Hide last run**, removes the run from the canvas, and **Show last run** brings it back. Select a node and open **Last run** to see its **Resolved input**, **Output**, and effects. This is often enough to find a wrong reference: compare the input received by the failed node with the output of the node it reads.
 
 Switch to **Runs** and open a row for the full record. The tabs remain visible with **Runs** active; **Editor** returns to the workflow. Check whether it was a test or live run and inspect already completed operations before starting another run. [Execution logs](/platform/automations/execution-logs) explains waiting, failures, automatic retries, and stopping.
 
diff --git a/docs/en/platform/automations/execution-logs.md b/docs/en/platform/automations/execution-logs.md
index 0528024cb8..921770a446 100644
--- a/docs/en/platform/automations/execution-logs.md
+++ b/docs/en/platform/automations/execution-logs.md
@@ -7,7 +7,7 @@ Open an automation, switch to its **Runs** tab and select a row to understand wh
 
 <Frame caption="A finished test run: its status, mode, version, starter, and times above the workflow, with each node's result.">
 
-![The run page of a test run of Triage GitHub issues, marked Succeeded, Test, and v1 and started by you, with its start and finish times above the workflow graph, where the issues, open issues, score, and report nodes each show Ran; the run's effects list begins below the graph.](/images/platform/automation-run-detail.webp)
+![The run page of a test run of Triage GitHub issues, marked Succeeded, Test, and v1 and started by you, with its start and finish times above the workflow graph, where the issues, open issues, score, and report nodes each show Succeeded; the run's effects list begins below the graph.](/images/platform/automation-run-detail.webp)
 
 </Frame>
 
@@ -36,9 +36,11 @@ Leave the run on hold while you investigate. **Request stop** asks Tale to stop
 
 ## Inspect the node that matters
 
-Select a node on the run’s canvas. **Resolved input** shows the actual values after template evaluation; **Output** shows what the step returned. These fields distinguish a bad reference from a service failure.
+A failed run opens with the node that failed in view. The node is framed in red and its bottom line shows the first line of its error; the nodes the run went through to reach it stand out while the others step back; and End says where the run failed, such as **Failed at Propose**.
 
-Node states include **Ran**, **Skipped**, **Failed**, **Never reached**, **Not reached yet** and, on a stopped run, **Stopped here** for the node the run was on when it was stopped. A skipped node may have a false condition, an unmet dependency, an alternate branch or a failure rule that permits continuation. Do not assume every skipped node is an error.
+Select a node on the run’s canvas to open its **Last run** tab. **Resolved input** shows the actual values after template evaluation; **Output** shows what the step returned. These fields distinguish a bad reference from a service failure.
+
+On the canvas, each node's bottom line says how it ended: **Succeeded**, **Failed**, **Skipped**, **Not run**, **Not reached yet** or, on a stopped run, **Stopped here** for the node the run was on when it was stopped. Each condition shows how it decided, **Yes** or **No**. The badge on the **Last run** tab names the same states **Ran**, **Failed**, **Skipped**, **Never reached**, **Not reached yet** and **Stopped here**. A skipped node may have a false condition, an unmet dependency, an alternate branch or a failure rule that permits continuation. Do not assume every skipped node is an error.
 
 For example, a reminder node may receive a customer name but an empty invoice ID. Inspect its upstream output: if the record now uses another field, correct the reference there rather than replacing the mail credential. Verify the corrected resolved input in a new test run.
 
diff --git a/docs/en/tutorials/editor/workflow-with-approvals.md b/docs/en/tutorials/editor/workflow-with-approvals.md
index a2f2891a03..4d26d2e603 100644
--- a/docs/en/tutorials/editor/workflow-with-approvals.md
+++ b/docs/en/tutorials/editor/workflow-with-approvals.md
@@ -60,7 +60,7 @@ If that name already exists, uploading adds another version. Use a different wor
 
 On **Editor**, click **Test run**. This example has no runtime input, so it can run with an empty object. Switch to **Runs**. The list should show a **Succeeded** test run.
 
-Open the run and check that the canvas shows both nodes as **Ran**. Select `send` and inspect its resolved input. The recipient should be `reviewer@example.com`, the subject `Approval practice`, and the text the sentence from `draft`. The connector uses a deterministic mock in this mode. No email is sent and no approval card appears.
+Open the run and check that the canvas marks both nodes **Succeeded**. Select `send` and inspect its resolved input. The recipient should be `reviewer@example.com`, the subject `Approval practice`, and the text the sentence from `draft`. The connector uses a deterministic mock in this mode. No email is sent and no approval card appears.
 
 The workflow includes a test expecting the `imap-smtp.send` effect. A passing mock confirms the graph and proposed call; it does not prove mailbox credentials or message delivery.
 
diff --git a/docs/fr/platform/automations/assistant.md b/docs/fr/platform/automations/assistant.md
index 42c2a7bc9b..a917f1e066 100644
--- a/docs/fr/platform/automations/assistant.md
+++ b/docs/fr/platform/automations/assistant.md
@@ -1,30 +1,30 @@
 ---
 title: Choisir comment créer une automatisation
-description: Modifie directement le workflow dans l’éditeur visuel ou connecte un assistant externe à Tale avec MCP.
+description: Modifie les champs d’une automatisation dans l’éditeur, ou fais-la créer et modifier par un agent de code via MCP.
 ---
 
-Modifie une automatisation sur son canevas ou connecte un assistant externe avec MCP pour utiliser les outils de Tale. Les deux chemins enregistrent des versions du même workflow et suivent les mêmes règles de validation et de déploiement. Il te faut les droits Développeur pour créer et déployer des automatisations.
+Modifie les champs d’une automatisation directement dans l’éditeur, ou fais-la créer et modifier par un agent de code comme Claude Code, Codex ou Cursor via MCP. Les deux chemins enregistrent des versions du même workflow et suivent les mêmes règles de validation et de déploiement. Il te faut les droits Développeur pour créer et déployer des automatisations.
 
-## Modifier le workflow dans l’éditeur visuel
+## Modifier le workflow dans l’éditeur
 
-Ouvre **Automatisations** et sélectionne le workflow. Choisis un nœud pour examiner ses entrées, son modèle, son code ou ses autres réglages. Enregistre la modification avec un message de version, lance un test, puis déploie la version souhaitée lorsque ses vérifications passent.
+Ouvre **Automatisations** et sélectionne le workflow. Choisis un nœud pour examiner son entrée, son modèle, son code ou ses autres réglages, et modifie le champ voulu. Enregistre la modification avec un message de version, lance un test, puis déploie la version souhaitée lorsque ses vérifications passent. Le canevas se dispose lui-même à partir des références entre les nœuds ; tu n’y ajoutes pas de nœuds et n’y traces pas de liaisons.
 
 <Frame caption="Le nœud sélectionné affiche sa configuration à côté du graphe.">
 
-![L’éditeur d’automatisation montre le graphe du workflow et les champs d’entrée du nœud sélectionné dans un panneau latéral.](/images/platform/automation-editor-canvas.webp)
+![L’éditeur d’automatisation montre le workflow entre Début et Fin et les champs du nœud sélectionné dans un panneau latéral.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
-[L’éditeur de workflow](/fr/platform/automations/editor) détaille ces étapes, l’examen d’une exécution et le retour à une version antérieure. Le canevas n’inclut pas de panneau d’assistant conversationnel.
+[L’éditeur de workflow](/fr/platform/automations/editor) détaille ces étapes, la lecture du canevas, l’examen d’une exécution et le retour à une version antérieure. Le canevas n’inclut pas de panneau d’assistant conversationnel.
 
-## Utiliser un assistant externe avec MCP
+## Modifier avec ton agent de code
 
-Configure ton client avec le point d’accès indiqué sous **Paramètres > API > MCP** et une clé API adaptée. Décris les entrées, la sortie attendue et les systèmes que le workflow peut modifier. Demande au client d’examiner les automatisations et capacités existantes avant d’en créer une autre.
+Le point de départ est **Modifier avec ton agent de code**, le dernier bouton en haut à droite du canevas de l’éditeur. Son dialogue montre le nom de l’automatisation à donner à l’agent, **Configurer MCP**, qui ouvre **Paramètres > API > MCP**, et un lien vers le guide pour connecter un agent de code. Configure ton client avec ce point d’accès et une clé API adaptée. Décris les entrées, la sortie attendue et les systèmes que le workflow peut modifier, et demande à l’agent d’examiner les automatisations et capacités existantes avant d’en créer une autre.
 
-Le [point d’accès MCP](/fr/develop/mcp-endpoint) propose des outils de documentation, validation, enregistrement, test et déploiement. Examine le workflow obtenu et ses résultats de test avant de le déployer. L’enregistrement crée une version, sans la rendre active.
+Le [point d’accès MCP](/fr/develop/mcp-endpoint) propose des outils de documentation, validation, enregistrement, test et déploiement. Une version enregistrée par l’agent apparaît sur le canevas pendant que tu consultes l’automatisation. Examine le workflow obtenu et ses résultats de test avant de le déployer. L’enregistrement crée une version, sans la rendre active.
 
 ## Distinguer les décisions pendant l’exécution
 
-Un nœud agent accomplit du travail pendant une exécution. Il est distinct du client qui t’aide à écrire le workflow. De même, une [approbation](/fr/platform/approvals/concepts) autorise une opération en attente pendant l’exécution ; elle ne valide pas une modification proposée de la définition.
+Un nœud agent accomplit du travail pendant une exécution. Il est distinct de l’agent de code qui t’aide à écrire le workflow. De même, une [approbation](/fr/platform/approvals/concepts) autorise une opération en attente pendant l’exécution ; elle ne valide pas une modification proposée de la définition.
 
-Choisis [l’éditeur](/fr/platform/automations/editor) pour une modification directe ou [MCP](/fr/develop/mcp-endpoint) pour travailler depuis ton client. Pars d’[une automatisation existante](/fr/platform/automations/catalog) lorsqu’une solution adaptée est déjà disponible.
+Choisis [l’éditeur](/fr/platform/automations/editor) pour une modification directe ou [MCP](/fr/develop/mcp-endpoint) pour travailler avec ton agent de code. Pars d’[une automatisation existante](/fr/platform/automations/catalog) lorsqu’une solution adaptée est déjà disponible.
diff --git a/docs/fr/platform/automations/concepts.md b/docs/fr/platform/automations/concepts.md
index 5a1de706fb..36514cede2 100644
--- a/docs/fr/platform/automations/concepts.md
+++ b/docs/fr/platform/automations/concepts.md
@@ -46,13 +46,13 @@ Tale dispose le canevas à partir des références entre les nœuds : personne
 
 ### Les liaisons se déduisent, elles ne se déclarent pas
 
-Il n’y a pas de liste de liaisons. Un nœud en lit un autre en le référençant — `{{ nodes.invoice.output.id }}` — et cette référence _est_ la liaison que trace le canvas. L’ordre d’exécution est un tri topologique sur ces liaisons déduites : supprimer une référence retire donc aussi une flèche, et deux nœuds qui se lisent l’un l’autre sont refusés comme une boucle.
+Il n’y a pas de liste de liaisons. Un nœud en lit un autre en le référençant — `{{ nodes.invoice.output.id }}` — et cette référence _est_ la liaison que trace le canevas. L’ordre d’exécution est un tri topologique sur ces liaisons déduites : supprimer une référence retire donc aussi un trait, et deux nœuds qui se lisent l’un l’autre sont refusés comme une boucle.
 
 Les templates utilisent une seule grammaire `{{ }}` d’expressions JavaScript sur `input`, `nodes.<id>.output` et, à l’intérieur d’un nœud qui itère, `item` et `index`.
 
 ### Le contrôle du flux vit sur le nœud
 
-Brancher et répéter sont des champs du nœud plutôt que des types d’étape à part. Le canvas les montre donc comme des badges sur la boîte qu’ils concernent.
+Brancher et répéter sont des champs du nœud plutôt que des types d’étape à part. Le canevas dessine chacun d’eux là où il agit : un `when` devient une condition au-dessus de son nœud, une alternative `elseOf` part de cette condition comme sa branche **Non**, `forEach` et `repeatUntil` placent le nœud dans un cadre, et `onError: continue` lui ajoute une puce.
 
 | Champ                        | Ce qu’il fait                                                                                 |
 | ---------------------------- | --------------------------------------------------------------------------------------------- |
@@ -80,6 +80,12 @@ Une sortie **structurée** possède des champs nommés, accessibles avec `nodes.
 
 Un outil sans schéma de sortie produit une sortie non structurée. Pour transformer son texte en données structurées utilisables par les étapes suivantes, ajoute un nœud `llm` avec un `outputSchema`. En cas d’erreur, la validation indique la référence incorrecte et les champs ou contextes autorisés. Corrige-la avant d’enregistrer à nouveau.
 
+## Les chemins qu’une exécution peut prendre {#paths}
+
+Chaque condition, et chaque nœud qui peut échouer pendant que l’exécution continue, ouvre deux possibilités à une exécution. Tale essaie chaque combinaison et garde les différentes façons dont une exécution réussie peut se dérouler ; chacune est un chemin. Un chemin nomme les conditions qui le décident, comme les nœuds qui s’exécutent, ceux qui sont ignorés et ceux qui échouent pendant que l’exécution continue, ainsi que les nœuds qui s’exécutent sur ce chemin. Un nœud qui s’exécute sur chaque chemin s’exécute toujours ; un nœud qui ne s’exécute sur aucun ne peut jamais s’exécuter, et Tale le signale par un avertissement.
+
+Tale liste jusqu’à 32 chemins et compte les autres. Au-delà de 12 conditions et échecs tolérés, les combinaisons sont trop nombreuses pour être parcourues : Tale ne liste alors aucun chemin, mais indique toujours, pour chaque nœud, quand il s’exécute. Tale nomme aussi les nœuds dont l’échec termine l’exécution et ce qui peut faire échouer chacun d’eux. L’éditeur montre les chemins sur le canevas, comme le décrit [Suivre les chemins possibles](/fr/platform/automations/editor#paths) ; un client du [point d’accès MCP](/fr/develop/mcp-endpoint) lit les mêmes chemins dans `analysis.paths`.
+
 ## Ce que Tale vérifie avant une exécution {#checks}
 
 Tale vérifie le document entier quand tu l’enregistres, quand tu déploies une version et chaque fois qu’un client appelle `validate_automation`. Une **erreur** décrit un échec certain ou du code qui dépasse les limites d’analyse : elle empêche d’enregistrer comme de déployer. Un **avertissement** signale ce qui peut échouer ou ne sert à rien. Il n’empêche jamais d’enregistrer ni de déployer, c’est donc toi qui décides d’agir. Chaque problème nomme son nœud et son champ et, dans un template, une condition ou du code, l’expression exacte.
diff --git a/docs/fr/platform/automations/editor.md b/docs/fr/platform/automations/editor.md
index 1cbcd5e0bd..ade7d8eb7e 100644
--- a/docs/fr/platform/automations/editor.md
+++ b/docs/fr/platform/automations/editor.md
@@ -1,49 +1,137 @@
 ---
 title: L’éditeur de workflow
-description: Examine et modifie les nœuds, fournis les données de test, puis enregistre, déploie ou rétablis une version.
+description: Lis une automatisation sur son canevas, suis ses chemins possibles, modifie les champs d’un nœud, enregistre une version, puis déploie-la ou rétablis-en une autre.
 ---
 
-L’éditeur de workflow permet de modifier le comportement d’une automatisation et de choisir sa version active. Il faut les droits Développeur, Admin ou Propriétaire pour apporter des changements. Enregistrer, tester et mettre en service sont des étapes distinctes : modifier un brouillon laisse la version déployée en place.
+L’éditeur de workflow permet de lire ce que fait une automatisation, de modifier ses champs et de choisir la version enregistrée qui s’exécute en service. Les changements plus importants, comme de nouveaux nœuds, passent par un agent de code via MCP. Il faut les droits Développeur, Admin ou Propriétaire pour apporter des changements. Enregistrer, tester et mettre en service sont des étapes distinctes : modifier un brouillon laisse la version déployée en place.
 
 Ouvre **Automatisations**, puis sélectionne une automatisation. Elle s’ouvre dans l’onglet **Éditeur**. Une automatisation ouverte depuis l’onglet **Automatisations** d’un projet affiche ce projet au début du fil d’Ariane : choisis le nom du projet pour revenir au projet, ou **Automatisations** pour revenir à ses automatisations. Que tu ouvres une automatisation depuis un projet ou depuis la liste, la barre de navigation met **Automatisations** en évidence. Pour en créer une, consulte [Créer ou importer une automatisation](/fr/platform/automations/catalog).
 
 | Onglet | Utilisation |
 | --- | --- |
-| **Éditeur** | Modifier le workflow, tester une version enregistrée et choisir celle à mettre en service. |
+| **Éditeur** | Lire et modifier le workflow, tester une version enregistrée et choisir celle à mettre en service. |
 | **Général** | Choisir ce qui démarre l’automatisation et les projets qui peuvent l’utiliser. |
 | **Exécutions** | Examiner les derniers lancements et ouvrir le détail d’une exécution. |
 
 Le sélecteur **Version** reste à droite des onglets Éditeur, Général et Exécutions, sur ordinateur comme sur téléphone. Il affiche les messages de version, les dates, les résultats des tests et la version en service. Sélectionne une ligne pour ouvrir cette version. Sur ordinateur, les commandes d’exécution se trouvent à côté des onglets, avec **Enregistrer** et **Abandonner** ; dans **Général**, seuls **Enregistrer** et **Abandonner** y figurent. Un point sur un onglet signale ses modifications non enregistrées. Avant de quitter cet onglet ou de changer de version, Tale te demande quoi en faire.
 
-Sur téléphone, la navigation est compacte à l’ouverture d’une automatisation. Le canevas de l’éditeur occupe la hauteur disponible. Les commandes d’exécution et de mise en service se trouvent dans le canevas, à côté du zoom. Sélectionne un nœud pour ouvrir ses champs — avec Enregistrer et Abandonner — dans un panneau au bas de l’écran.
+Sur téléphone, la navigation est compacte à l’ouverture d’une automatisation. Le canevas de l’éditeur occupe la hauteur disponible, et les commandes d’exécution et de mise en service se trouvent dans une barre au bas du canevas. Sélectionne un nœud pour ouvrir ses champs — avec Enregistrer et Abandonner — dans un panneau au bas de l’écran.
 
-<Frame caption="Sur un écran large, sélectionne un nœud pour examiner ses champs à côté du canvas.">
+<Frame caption="Sur un écran large, sélectionne un nœud pour examiner ses champs à côté du canevas.">
 
-![L’éditeur montre les nœuds connectés et les champs du nœud sélectionné à côté du canvas.](/images/platform/automation-editor-canvas.webp)
+![L’éditeur montre les nœuds de Gmail triage inbox entre Début et Fin, une condition formulée en mots au-dessus d’un nœud et les champs du nœud sélectionné à côté du canevas.](/images/platform/automation-editor-canvas.webp)
 
 </Frame>
 
 Pour passer à une autre automatisation sans revenir à la liste, clique sur le nom de celle qui est ouverte dans le fil d’Ariane. Le menu garde toutes les automatisations de l’organisation, même après un changement de projet, sauf celles associées uniquement à des projets que tu ne peux pas ouvrir. Celles qui ne sont rattachées à aucun projet apparaissent en premier, puis viennent celles liées à des projets. Une ligne horizontale sépare les deux groupes. Cherche par nom ou par slug, puis sélectionne une entrée. Tu conserves l’onglet ouvert. Depuis le détail d’une exécution, tu arrives sur la liste **Exécutions** de l’autre automatisation. Le numéro de version sélectionné n’est pas repris : **Éditeur** affiche la dernière version enregistrée de cette autre automatisation.
 
-## Lire le canvas
+## Lire le canevas
 
-Chaque bloc est un nœud. Son libellé indique l’étape et le type ; **Lit** désigne les nœuds dont il utilise la sortie. Les flèches viennent des références, comme `{{ nodes.draft.output.text }}`. Modifie la référence pour changer la dépendance ; dessiner une flèche ne crée pas de dépendance.
+Tale dessine le canevas à partir du document de l’automatisation et le dispose lui-même : **Début** se trouve en haut, **Fin** en bas, et chaque nœud se place sous les nœuds qu’il lit. Le canevas se lit donc de haut en bas, dans l’ordre que suit une exécution. Personne ne place un bloc, et dessiner ne relie rien. Un trait vient d’une référence comme `{{ nodes.draft.output.text }}` ; pour changer ce qu’un nœud lit, modifie la référence.
 
-Les badges indiquent les conditions et boucles : `when`, `else of`, `for each`, `repeat until` et `continue on error`. Un avertissement de cycle signifie que plusieurs nœuds dépendent les uns des autres. Supprime la référence circulaire avant d’enregistrer une version exécutable.
+### Début et Fin
+
+**Début** indique ce qui démarre une exécution et ce qu’elle reçoit. Sous **Démarre**, il décrit le déclencheur en mots, par exemple une planification avec son fuseau horaire et sa prochaine exécution, et précise si le déclencheur est désactivé ou attend une version en service. Vient ensuite **À la main, via l’API ou MCP**, car ces démarrages sont toujours possibles. Sous **Entrée**, il liste les champs de l’entrée de l’exécution, avec leur type et leur caractère obligatoire. Quand le déclencheur lancerait des exécutions dont l’automatisation refuse l’entrée, Début le signale.
+
+**Fin** indique ce que renvoie une exécution réussie et comment une exécution peut se terminer. Sous **Renvoie**, elle nomme la sortie, par exemple **La sortie de Report**, ou liste ses champs et les nœuds dont ils viennent ; un champ vide lors de certaines exécutions porte **peut être vide**. Sous **Se termine**, elle liste les trois issues : **Réussie** renvoie la sortie, **En échec** survient quand l’un des nœuds qui arrêtent l’exécution échoue, et **Arrêtée** quand quelqu’un arrête l’exécution.
+
+### Nœuds
+
+Chaque nœud est un bloc. Sa première ligne montre son icône et son titre, tiré de son ID : `open_issues` devient **Open issues**. La ligne suivante indique de quel type de nœud il s’agit : le connecteur et l’action, comme **GitHub · Lister les issues**, **Transformation**, **Modèle de langage** ou **Agent** avec son modèle, ou l’automatisation qu’il appelle. Quand Tale sait ce que le nœud renvoie, une ligne en montre la structure, par exemple `{ issues: object[] }`. La ligne du bas indique ce que le nœud lit, par exemple **Lit Issues et l’entrée (owner, repo)**, ou **Ne lit aucun autre nœud**.
+
+Des puces et de petites icônes ajoutent ce que la disposition ne montre pas. **Continue en cas d’erreur** marque un nœud dont l’exécution tolère l’échec, et **Ne s'exécute jamais** un nœud qu’aucune combinaison de conditions n’atteint. Un bouclier marque un nœud qui modifie des données dans un service connecté, où une exécution réelle peut attendre une approbation ; une bulle marque un agent qui peut poser une question ; une épingle barrée marque un modèle sans fournisseur fixé. Pointe sur une icône pour lire sa phrase ; un lecteur d’écran l’entend avec le bloc. Un bloc qui a des problèmes en affiche le nombre sur sa première ligne.
+
+### Conditions et branches
+
+La condition d’un nœud (`when`) se place au-dessus de lui, dans une pastille qui la formule en mots, par exemple « total de Score est supérieur à 1 000 ». Le nœud du dessous ne s’exécute que si la condition est remplie. Quand un autre nœud est son alternative (`elseOf`), la condition se divise en deux traits : **Oui** mène au nœud de gauche, qui s’exécute quand la condition est remplie, et **Non** à son alternative, à droite. Une condition que Tale ne peut pas formuler en mots affiche l’expression elle-même, en police de code.
+
+```yaml
+nodes:
+  - id: escalate
+    type: transform
+    when: '{{ nodes.score.output.total > 1000 }}'
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "Escalate " + input.total };'
+  - id: file
+    type: transform
+    elseOf: escalate
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "File " + input.total };'
+```
+
+Dans cet extrait, la condition au-dessus d’Escalate indique « total de Score est supérieur à 1 000 », **Oui** mène à Escalate et **Non** à File. Pointe sur une condition, ou sur son **Oui** ou son **Non**, pour mettre en évidence les chemins qui passent par elle.
+
+### Traits, cadres et blocs tiretés
+
+Un trait plein signifie que le nœud du dessous lit la sortie de celui du dessus. Un trait tireté signifie que le nœud du dessous s’exécute après celui du dessus sans lire sa sortie, par exemple parce que sa condition la lit. Un trait pointillé vers Fin part du dernier nœud d’une exécution dont Fin ne renvoie pas la sortie. Les traits **Oui** et **Non** ont leurs propres couleurs.
+
+Un cadre autour d’un nœud indique qu’il s’exécute plusieurs fois : une fois par élément d’une liste (**Pour chaque élément de …**) ou à nouveau jusqu’à ce qu’une condition soit remplie (**Se répète jusqu’à : …, 5 fois au plus**). Un bloc tireté est un nœud qui peut ne pas s’exécuter ; après une exécution, c’est un nœud qui ne s’est pas exécuté. **Légende**, à côté du zoom, explique chaque type de trait et de bloc.
+
+### Clavier et vue Liste
+
+Le diagramme est un seul arrêt dans l’ordre de tabulation. Atteins-le avec Tab et le focus se pose sur Début ; les flèches suivent les traits de bloc en bloc et le long d’une rangée, Origine et Fin sautent à Début et à Fin, et Entrée ouvre le bloc qui a le focus. Un lecteur d’écran annonce pour chaque bloc son titre, son type et ce qu’il lit ; pour une condition, il annonce le nœud sur lequel elle décide.
+
+Le sélecteur de vue en haut à gauche du canevas passe de **Canevas** à **Liste** et à **Source**. **Liste** montre les mêmes nœuds dans l’ordre de l’exécution, chacun avec ce qu’il lit et sa condition en mots ; Entrée y ouvre aussi un nœud. Quand le canevas est très étroit, il s’ouvre sur **Liste**. L’adresse garde la vue et le nœud ouvert, si bien qu’un lien partagé les rouvre tous les deux.
+
+### Quand une nouvelle version arrive {#new-versions}
+
+Quelqu’un peut enregistrer une nouvelle version pendant que tu consultes l’automatisation, par exemple un agent de code via MCP. Si tu consultes la dernière version sans modifications non enregistrées, le canevas passe à la nouvelle : les blocs glissent vers leur nouvelle place, les nouveaux apparaissent en fondu, ceux qui ont changé s’entourent une fois d’un anneau, et un lecteur d’écran annonce « Affichage de la v6. ». Le nœud ouvert le reste s’il existe encore. Si tu as des modifications non enregistrées, rien ne bouge. Un avis au-dessus du canevas indique **Une version plus récente a été enregistrée**, et **Afficher la v6 et abandonner mon brouillon** y passe.
+
+## Suivre les chemins possibles {#paths}
+
+Les conditions d’une exécution décident des nœuds qui s’exécutent. Le bouton des chemins, en haut à droite du canevas, compte les chemins qu’une exécution réussie peut prendre, par exemple **3 chemins**, et ouvre **Chemins possibles**. Chaque chemin nomme les conditions qui le décident, comme « Triage s’exécute » ou « Propose échoue, l’exécution continue », et le nombre de nœuds qui s’y exécutent.
+
+Pointe sur un chemin, ou atteins-le avec les flèches, pour le prévisualiser sur le canevas. Clique dessus ou appuie sur Entrée pour le garder affiché : les nœuds hors du chemin deviennent tiretés et disent pourquoi ils ne s’exécutent pas, Fin marque les sorties qui restent vides sur ce chemin, et un lecteur d’écran annonce le chemin affiché. **Tout afficher**, ou Échap, affiche de nouveau chaque nœud. La liste reste ouverte pendant que tu sélectionnes des nœuds, pour comparer un chemin avec les champs d’un nœud.
+
+Sous **Arrête l’exécution en cas d’échec**, la liste nomme les nœuds dont l’échec arrête l’exécution, avec ce qui peut faire échouer chacun d’eux. Pointe sur l’un d’eux pour les entourer tous de rouge ; sélectionne-en un pour l’ouvrir.
+
+Sur téléphone, la liste s’ouvre dans un panneau au bas de l’écran. Choisir un chemin ferme le panneau et laisse en haut du canevas une pastille qui nomme le chemin, avec **Tout afficher**. Quand chaque exécution suit le même chemin, la liste le dit. Au-delà de 12 conditions et échecs tolérés, les chemins sont trop nombreux pour être listés ; **Quand il s’exécute** indique toujours, pour chaque nœud, quand il s’exécute. Un canevas qui contient un cycle n’a pas de bouton des chemins. [Les chemins qu’une exécution peut prendre](/fr/platform/automations/concepts#paths) explique comment Tale les détermine.
 
 ## Modifier un nœud
 
-Sélectionne un bloc pour ouvrir ses champs. Sur un écran large, le panneau apparaît à côté du canvas ; sans nœud sélectionné, le canvas occupe toute la largeur. Sur un écran plus étroit, les champs s’ouvrent dans un dialogue au-dessus du canvas. Un `transform` possède du **Code** ; un `llm`, des champs de prompt, modèle et schéma de sortie ; un `agent` ajoute l’environnement d’agent et l’équipement. Le sélecteur **Modèle** d’un nœud `llm` ou `agent` liste les modèles servis par les fournisseurs connectés de ton organisation ; un modèle absent de la liste peut être saisi, mais **Problèmes** avertit alors qu’une exécution en direct échouerait à ce nœud tant que son fournisseur n’est pas connecté. **Entrée** contient les valeurs JSON et références transmises au nœud. Un JSON incomplet est signalé et ne met pas le nœud à jour.
+Sélectionne un bloc pour l’ouvrir. Sur un écran large, l’inspecteur s’ouvre à côté du canevas ; sans nœud sélectionné, le canevas occupe toute la largeur. Sur un écran plus étroit, il s’ouvre dans un panneau au-dessus du canevas. Son en-tête montre le titre du nœud, son type et son ID avec **Copier l’ID du nœud** ; les problèmes propres au nœud sont listés dessous. **Quand il s’exécute** résume la place du nœud dans le flux : à chaque exécution, sur certains chemins ou jamais, pourquoi il peut être ignoré et ce qui se passe s’il échoue, par exemple « S’il échoue, l’exécution s’arrête avec son erreur. »
+
+Trois onglets suivent :
+
+- **Champs** contient ce que tu peux modifier. Un `transform` possède du **Code** ; un `llm`, **Prompt**, **Prompt système**, **Modèle** et **Schéma de sortie** ; un `agent` y ajoute l’environnement d’agent et l’équipement. **Entrée** contient les valeurs JSON et références transmises au nœud.
+- **Structure** montre ce que le nœud reçoit et renvoie, d’où Tale tient cette structure et quels nœuds lisent sa sortie. Sélectionne un lecteur pour l’ouvrir. **Afficher en TypeScript** montre la même structure sous forme de type.
+- **Dernière exécution** montre l’**Entrée résolue**, la **Sortie** et les effets du nœud dans l’exécution affichée sur le canevas. L’onglet apparaît tant que le canevas montre une exécution.
+
+Le sélecteur **Modèle** d’un nœud `llm` ou `agent` liste les modèles servis par les fournisseurs connectés de ton organisation ; un modèle absent de la liste peut être saisi, mais **Problèmes** avertit alors qu’une exécution réelle échouerait à ce nœud tant que son fournisseur n’est pas connecté.
+
+Ouvre **Contrôle du flux** pour la condition, l’itération et la gestion des échecs du nœud ; si le nœud en utilise une, la section est déjà ouverte. **Si**, **Pour chaque** et **Répéter jusqu’à** prennent des expressions. **Sinon de** ne propose que des nœuds qui ont une condition, et **Aucun** retire l’alternative. **Répétitions maximales** apparaît avec **Répéter jusqu’à** et prend un nombre entier de 1 à 20. **En cas d’erreur** choisit entre **Arrêter l’exécution** et **Continuer sans lui** ; continuer ignore chaque nœud qui lit la sortie du nœud en échec. Sous une condition, une liste ou une alternative, une phrase dit en mots ce que fait le réglage.
+
+Utilise **Fermer** pour revenir au canevas. Sur un écran large, tu peux aussi fermer le panneau en cliquant sur le fond du canevas ou en appuyant sur Échap hors d’un champ de texte. Les réglages du déclencheur et des projets se trouvent dans l’onglet **Général**. [Concepts d’automatisation](/fr/platform/automations/concepts) explique les types de nœuds et les expressions.
+
+### Code, prompts et JSON
+
+Le code, les prompts, les conditions et les champs JSON sont des éditeurs de code. Ils colorent la syntaxe et chaque template `{{ }}`, et connaissent l’automatisation. Tape `{{` dans un prompt et les accolades fermantes apparaissent, avec le curseur entre les deux ; tape `nodes.` pour ne voir que les nœuds qui s’exécutent avant, et `.output.` pour voir les champs de ce nœud avec leurs types. Ctrl+Espace ouvre les suggestions partout. Pointe sur une référence pour voir son type, ou appuie sur ⌘K ⌘I (Ctrl+K Ctrl+I) pour afficher et faire lire le type à la position du curseur.
+
+Un instant après ta dernière frappe, un problème est souligné exactement là où il se trouve. F8 et Maj+F8 passent au problème suivant et précédent et le lisent ; ⌘. (Ctrl+.) applique une correction proposée, comme le nom de nœud le plus proche. Dans un champ de plusieurs lignes, Tab indente ; pour le quitter au clavier, appuie sur Échap, puis sur Tab. **Agrandir l'éditeur** ouvre un long champ dans un éditeur plus grand, et **Revenir au champ** t’y ramène avec ta modification et ton curseur au même endroit.
+
+Un champ JSON comme **Entrée** ne modifie le nœud que si son texte est du JSON valide du bon type. Pendant la saisie, le nœud garde sa dernière valeur valide, et le champ indique ce qui manque, par exemple « Ce doit être un objet JSON, entre accolades. »
+
+### Entrées de Début et sortie de Fin
+
+Sélectionne **Début** pour voir ce qui démarre l’automatisation. **Déclencheur** le décrit en mots ; **Modifier dans Général** ouvre l’onglet **Général**, où tu règles le déclencheur. Sous **Champs**, **Entrées** montre les champs de l’entrée de l’exécution sous forme d’arbre, et **Schéma des données** contient le schéma JSON qui les définit, que tu peux modifier. **Structure** montre l’entrée telle que Tale la lit, et **Dernière exécution** l’entrée de l’exécution affichée.
+
+Sélectionne **Fin** pour voir ce que renvoie une exécution. **Comment une exécution se termine** liste les trois issues ; sous **En échec**, chaque nœud dont l’échec arrête l’exécution est un bouton qui l’ouvre. Sous **Champs**, **Sortie** contient la valeur JSON que renvoie une exécution réussie, avec des templates comme `{{ nodes.report.output }}`. **Structure** montre la structure de la sortie, et **Dernière exécution** la sortie de l’exécution affichée.
+
+## Lire la source
+
+Choisis **Source** dans le sélecteur de vue pour lire tout le document en YAML, coloré, avec numéros de ligne, repli et recherche (⌘F ou Ctrl+F). Chaque problème trouvé par la vérification est souligné sur la ligne qu’il concerne : un problème dans une partie sans champ propre, comme un test ou le nom, a ainsi un endroit où le lire. La source est en lecture seule : **Copier le YAML** la copie, et **Télécharger le YAML** l’enregistre dans un fichier nommé d’après l’automatisation et la version, par exemple `gmail-triage-inbox-v3.yml`, avec `-draft` en plus tant que tu as des modifications non enregistrées. Pour modifier le document, utilise les champs ou ton agent de code.
+
+## Modifier avec ton agent de code
 
-Ouvre **Contrôle du flux** pour les conditions et répétitions. Si le nœud en a, la section est déjà ouverte. Utilise **Fermer** pour revenir au canvas. Sur un écran large, tu peux aussi fermer le panneau en cliquant sur le fond du canvas ou en appuyant sur Échap hors d’un champ de texte. Les réglages du déclencheur et des projets se trouvent dans l’onglet **Général**. [Concepts d’automatisation](/fr/platform/automations/concepts) explique les types de nœuds et les expressions.
+Les changements plus importants, comme ajouter des nœuds ou remanier le flux, passent par un agent de code comme Claude Code, Codex ou Cursor, connecté au serveur MCP de Tale. **Modifier avec ton agent de code** est le dernier bouton en haut à droite du canevas, dans chaque vue, et l’action principale d’une automatisation qui n’a pas encore de nœud. Son dialogue montre le nom de l’automatisation à donner à l’agent, **Configurer MCP**, qui ouvre **Paramètres > API > MCP**, et **Connecter un agent de code**, qui ouvre le guide du [point d’accès MCP](/fr/develop/mcp-endpoint). L’agent lit l’automatisation, la modifie, la vérifie et enregistre une nouvelle version, qui apparaît ensuite sur le canevas comme le décrit [Quand une nouvelle version arrive](#new-versions).
 
 ## Trouver et corriger les problèmes
 
-Pendant que tu modifies, Tale vérifie le brouillon comme il vérifie chaque enregistrement. Un instant après ta dernière frappe, le bouton **Problèmes** à côté d’**Enregistrer** montre ce que la vérification a trouvé : une icône d’erreur rouge et une icône d’avertissement orange, chacune avec son nombre, ou **Aucun problème**. Sur un téléphone, le bouton se trouve dans la barre au-dessus du canevas. Une erreur fait échouer une exécution, par exemple une référence à un nœud qui n’existe pas. Un avertissement signale un risque, par exemple la lecture de la sortie d’un nœud parfois ignoré. Un nœud qui a des problèmes affiche les mêmes nombres sur son bloc, et un champ concerné explique le problème juste en dessous.
+Pendant que tu modifies, Tale vérifie le brouillon comme il vérifie chaque enregistrement. Un instant après ta dernière frappe, le bouton **Problèmes** à côté d’**Enregistrer** montre ce que la vérification a trouvé : une icône d’erreur rouge et une icône d’avertissement orange, chacune avec son nombre, ou **Aucun problème**. Sur un téléphone, le bouton se trouve dans la barre au-dessus du canevas. Une erreur fait échouer une exécution, par exemple une référence à un nœud qui n’existe pas. Un avertissement signale un risque, par exemple la lecture de la sortie d’un nœud parfois ignoré. Un nœud, une condition, Début ou Fin qui a des problèmes affiche les mêmes nombres sur son bloc, et un champ concerné explique le problème juste en dessous.
 
-Clique sur **Problèmes** pour les lister. Sur un écran large, la liste s’ouvre sous le canvas ; sur un écran plus étroit, dans un panneau. Chaque entrée indique ce qui ne va pas, où, pourquoi et comment le corriger. **Détails techniques** affiche le message du moteur lui-même, et le code à côté du titre t’aide pour une recherche ou une demande d’assistance. **Tous**, **Erreurs** et **Avertissements** filtrent la liste ; Échap la ferme.
+Clique sur **Problèmes** pour les lister. Sur un écran large, la liste s’ouvre sous le canevas ; sur un écran plus étroit, dans un panneau. Chaque entrée indique ce qui ne va pas, où, pourquoi et comment le corriger. **Détails techniques** affiche le message du moteur lui-même, et le code à côté du titre t’aide pour une recherche ou une demande d’assistance. **Tous**, **Erreurs** et **Avertissements** filtrent la liste ; Échap la ferme.
 
-Sélectionne une entrée, ou appuie sur Entrée dessus, pour t’y rendre : le nœud s’ouvre, son champ reçoit le focus et, si le champ affiche le texte tel qu’il est enregistré, la partie en cause est sélectionnée. Un problème sans champ à lui, par exemple un modèle que ton organisation ne sert pas, figure sous **Problèmes de ce nœud** en haut des champs du nœud. Un problème dans une partie de l’automatisation que l’éditeur n’affiche pas, comme sa sortie ou ses tests, indique qu’elle ne se modifie pas ici ; modifie cette partie via MCP, l’API ou un paquet téléversé.
+Sélectionne une entrée, ou appuie sur Entrée dessus, pour t’y rendre : le nœud s’ouvre, son champ reçoit le focus et la partie en cause est sélectionnée. Un problème sans champ à lui, par exemple un modèle que ton organisation ne sert pas, figure sous **Problèmes de ce nœud** en haut des champs du nœud. Un problème dans les entrées ouvre **Début**, un problème dans la sortie ouvre **Fin**, et un problème dans une autre partie du document, comme un test ou le nom, ouvre **Source** sur cette ligne. Un problème dans un nœud que ton brouillon n’a plus indique « Modifie-le avec ton agent de code. »
 
 Tant qu’il reste des erreurs, **Enregistrer** est désactivé et en donne la raison, par exemple « Corrige 1 erreur pour enregistrer ». Sur un téléphone, où **Enregistrer** se trouve sous les champs d’un nœud, **Afficher les problèmes** à côté de cette raison ouvre la liste. Les avertissements ne bloquent jamais l’enregistrement ni la mise en service. Si Tale ne peut pas vérifier le brouillon, par exemple parce que la connexion a été coupée, le bouton affiche **Vérification impossible** et tu peux quand même enregistrer : chaque enregistrement est vérifié à nouveau sur le serveur. Quand un enregistrement ou une mise en service est refusé à cause d’erreurs, la liste s’ouvre avec les problèmes renvoyés par le serveur, en commençant par la première erreur.
 
@@ -52,8 +140,8 @@ La vérification ne s’exécute que pour les rôles Développeur, Admin et Prop
 ## Enregistrer et tester une version
 
 1. Modifie les champs nécessaires et clique sur **Enregistrer**.
-2. Explique le changement dans la **Note de version**, puis choisis **Enregistrer une version**. Cela ajoute une version et conserve les précédentes. Si quelqu’un a enregistré une autre version pendant ta modification, Tale refuse l’enregistrement et te demande : **Abandonner mes modifications et recharger** affiche la version plus récente, **Enregistrer quand même** ajoute ta version par-dessus — la plus récente reste dans l’historique des versions, mais la dernière version est alors la tienne.
-3. Clique sur **Essai**. Si le workflow déclare un schéma d’entrée, remplis **Données de l’exécution (JSON)** dans le dialogue. Déplie **Schéma des données** pour vérifier les champs obligatoires et leurs types. Un JSON invalide ou non conforme au schéma empêche le démarrage.
+2. Explique le changement dans la **Note de version**, puis choisis **Enregistrer une version**. Cela ajoute une version et conserve les précédentes. Si quelqu’un a enregistré une autre version pendant ta modification, Tale refuse l’enregistrement et te demande : **Abandonner mes modifications et recharger** affiche la version plus récente, **Enregistrer quand même** ajoute ta version par-dessus — la plus récente reste dans l’historique des versions, mais la dernière version est alors la tienne.
+3. Clique sur **Essai**. Si le workflow déclare un schéma d’entrée, saisis l’entrée en JSON dans **Données de l’exécution (JSON)** ; quand tu tapes une clé, le champ propose les noms de champs du schéma, et ⌘Entrée (Ctrl+Entrée) lance l’exécution. Déplie **Schéma des données** pour voir les champs obligatoires et leurs types. Un JSON invalide ou non conforme au schéma empêche le démarrage.
 4. Lance le test, passe à l’onglet **Exécutions** et ouvre sa ligne. Compare les données résolues, la sortie et les opérations prévues au résultat attendu.
 
 Pour un workflow qui exige `owner` et `repo`, les données pourraient être :
@@ -71,7 +159,7 @@ Utilise le schéma réel du workflow. Un champ numérique attend un nombre JSON,
 
 <Frame caption="Pour un workflow avec des données d’entrée, saisis le JSON et vérifie le schéma avant le test.">
 
-![Le dialogue de test montre les valeurs JSON owner et repo et le schéma des données déplié.](/images/platform/automation-run-input.webp)
+![Le dialogue de test montre les valeurs JSON owner et repo dans l’éditeur de code et le schéma des données déplié sous forme de liste de champs.](/images/platform/automation-run-input.webp)
 
 </Frame>
 
@@ -85,7 +173,7 @@ Un déclencheur utilise aussi la version déployée. Configure-le lorsque tu es
 
 ## Examiner un résultat
 
-**Afficher la dernière exécution** superpose les états au canvas. Sélectionne un nœud pour consulter les données de cette exécution : entrée résolue, sortie et effets. Cela suffit souvent à trouver une référence incorrecte. Compare l’entrée du nœud échoué à la sortie de sa source.
+Dès que l’automatisation s’est exécutée, le canevas montre sa dernière exécution : la ligne du bas de chaque nœud indique comment il s’est terminé, par exemple **Réussi** ou **Ignoré**, et chaque condition montre comment elle a décidé, **Oui** ou **Non**. Le bouton en forme d’œil, en haut à droite du canevas, **Masquer la dernière exécution**, retire l’exécution du canevas, et **Afficher la dernière exécution** la fait revenir. Sélectionne un nœud et ouvre **Dernière exécution** pour voir son **Entrée résolue**, sa **Sortie** et ses effets. Cela suffit souvent à trouver une référence incorrecte : compare l’entrée du nœud en échec à la sortie du nœud qu’il lit.
 
 Passe à **Exécutions** et ouvre une ligne pour le détail complet. Les onglets restent visibles, avec **Exécutions** actif. **Éditeur** te ramène au workflow. Vérifie s’il s’agissait d’un test ou d’une exécution réelle et examine les opérations déjà réalisées avant de relancer. [Journaux d’exécution](/fr/platform/automations/execution-logs) explique les attentes, échecs, relances automatiques et arrêts.
 
diff --git a/docs/fr/platform/automations/execution-logs.md b/docs/fr/platform/automations/execution-logs.md
index 62cda9cfa1..e416026427 100644
--- a/docs/fr/platform/automations/execution-logs.md
+++ b/docs/fr/platform/automations/execution-logs.md
@@ -7,7 +7,7 @@ Ouvre une automatisation, passe à son onglet **Exécutions** et choisis une lig
 
 <Frame caption="Une exécution de test terminée : son statut, son mode, sa version, son initiateur et ses horaires au-dessus du workflow, avec le résultat de chaque nœud.">
 
-![La page d’une exécution de test de Triage GitHub issues, marquée Succeeded, Test et v1 et lancée par toi, avec ses heures de début et de fin au-dessus du graphe du workflow, où les nœuds issues, open issues, score et report affichent chacun Ran ; la liste des effets de l’exécution commence sous le graphe.](/images/platform/automation-run-detail.webp)
+![La page d’une exécution de test de Triage GitHub issues, marquée Succeeded, Test et v1 et lancée par toi, avec ses heures de début et de fin au-dessus du graphe du workflow, où les nœuds issues, open issues, score et report affichent chacun Succeeded ; la liste des effets de l’exécution commence sous le graphe.](/images/platform/automation-run-detail.webp)
 
 </Frame>
 
@@ -36,9 +36,11 @@ Laisse l’exécution suspendue pendant tes vérifications. **Demander l’arrê
 
 ## Examiner le nœud concerné
 
-Sélectionne un nœud sur le canvas de l’exécution. **Entrée résolue** montre les valeurs après évaluation des expressions, et **Sortie** le résultat de l’étape. Ces champs distinguent une mauvaise référence d’une défaillance du service.
+Une exécution en échec s’ouvre avec le nœud en échec en vue. Il est encadré de rouge et sa ligne du bas montre la première ligne de son erreur ; les nœuds par lesquels l’exécution est passée pour l’atteindre ressortent, tandis que les autres passent au second plan ; et Fin indique où l’exécution a échoué, par exemple **Échec à Propose**.
 
-Les états comprennent **Exécuté**, **Ignoré**, **En échec**, **Jamais atteint**, **Pas encore atteint** et, pour une exécution arrêtée, **Arrêté ici** pour le nœud sur lequel elle se trouvait au moment de l’arrêt. Une condition fausse, une dépendance, une branche alternative ou une règle de poursuite après erreur peut expliquer un nœud ignoré. Ce n’est pas toujours un problème.
+Sélectionne un nœud sur le canevas de l’exécution pour ouvrir son onglet **Dernière exécution**. **Entrée résolue** montre les valeurs après évaluation des expressions, et **Sortie** le résultat de l’étape. Ces champs distinguent une mauvaise référence d’une défaillance du service.
+
+Sur le canevas, la ligne du bas de chaque nœud indique comment il s’est terminé : **Réussi**, **Échoué**, **Ignoré**, **Non exécuté**, **Pas encore atteint** ou, pour une exécution arrêtée, **Arrêté ici** pour le nœud sur lequel elle se trouvait au moment de l’arrêt. Chaque condition montre comment elle a décidé, **Oui** ou **Non**. Le badge de l’onglet **Dernière exécution** nomme les mêmes états **Exécuté**, **En échec**, **Ignoré**, **Jamais atteint**, **Pas encore atteint** et **Arrêté ici**. Une condition fausse, une dépendance, une branche alternative ou une règle de poursuite après erreur peut expliquer un nœud ignoré. Ce n’est pas toujours un problème.
 
 Par exemple, un rappel peut recevoir le nom du client mais un identifiant de facture vide. Examine la sortie précédente. Si le champ a été renommé, corrige la référence plutôt que les identifiants de messagerie. Vérifie ensuite l’entrée résolue dans un nouvel essai.
 
diff --git a/docs/fr/tutorials/editor/workflow-with-approvals.md b/docs/fr/tutorials/editor/workflow-with-approvals.md
index 00e2024b49..e21c9d3580 100644
--- a/docs/fr/tutorials/editor/workflow-with-approvals.md
+++ b/docs/fr/tutorials/editor/workflow-with-approvals.md
@@ -60,7 +60,7 @@ Si ce nom existe déjà, l’import ajoute une version. Choisis une autre valeur
 
 Dans **Éditeur**, clique sur **Essai**. Cet exemple ne demande aucune donnée d’exécution ; un objet vide suffit. Passe à **Exécutions** : la liste doit afficher une exécution de test au statut **Réussie**.
 
-Ouvre l’exécution et vérifie sur le canvas que les deux nœuds affichent le statut **Exécuté**. Sélectionne `send` et examine ses données résolues. Le destinataire doit être `reviewer@example.com`, l’objet `Approval practice` et le texte la phrase de `draft`. Le connector utilise une simulation déterministe dans ce mode. Aucun e-mail n’est envoyé et aucune carte d’approbation n’apparaît.
+Ouvre l’exécution et vérifie sur le canevas que les deux nœuds affichent **Réussi**. Sélectionne `send` et examine ses données résolues. Le destinataire doit être `reviewer@example.com`, l’objet `Approval practice` et le texte la phrase de `draft`. Le connector utilise une simulation déterministe dans ce mode. Aucun e-mail n’est envoyé et aucune carte d’approbation n’apparaît.
 
 Le workflow comprend un test qui attend l’effet `imap-smtp.send`. Une simulation réussie vérifie le graphe et l’appel prévu. Elle ne prouve ni la validité des identifiants de messagerie ni la livraison du message.
 
diff --git a/services/docs/app/content/frontmatter.json b/services/docs/app/content/frontmatter.json
index 266ea37753..a6c618ba3d 100644
--- a/services/docs/app/content/frontmatter.json
+++ b/services/docs/app/content/frontmatter.json
@@ -464,8 +464,8 @@
     "slug": "platform/automations/assistant",
     "locale": "de",
     "frontmatter": {
-      "title": "Den Weg zur Automation wählen",
-      "description": "Bearbeite Workflows direkt im visuellen Editor oder verbinde einen externen Assistenten über MCP mit Tale."
+      "title": "Den Weg zur Automatisierung wählen",
+      "description": "Ändere Felder einer Automatisierung im Editor, oder lass einen Coding-Agent sie über MCP erstellen und ändern."
     }
   },
   "de:platform/automations/builtin": {
@@ -497,7 +497,7 @@
     "locale": "de",
     "frontmatter": {
       "title": "Der Workflow-Editor",
-      "description": "Prüfe und ändere Knoten, gib Testdaten ein, speichere eine Version und schalte sie live oder kehre zu einer früheren zurück."
+      "description": "Lies eine Automatisierung im Canvas, folge ihren möglichen Pfaden, ändere Felder einer Node, speichere eine Version und schalte sie live oder kehre zu einer früheren zurück."
     }
   },
   "de:platform/automations/execution-logs": {
@@ -1617,7 +1617,7 @@
     "locale": "en",
     "frontmatter": {
       "title": "Choose how to author an automation",
-      "description": "Use the visual editor for direct changes or connect an external assistant to Tale through MCP."
+      "description": "Change an automation's fields in the editor, or have a coding agent build and change it through MCP."
     }
   },
   "en:platform/automations/builtin": {
@@ -1649,7 +1649,7 @@
     "locale": "en",
     "frontmatter": {
       "title": "The workflow editor",
-      "description": "Inspect and edit nodes, supply test input, save a version, and deploy or roll back an automation."
+      "description": "Read an automation on its canvas, follow its possible paths, edit node fields, save a version, and deploy or roll back."
     }
   },
   "en:platform/automations/execution-logs": {
@@ -2769,7 +2769,7 @@
     "locale": "fr",
     "frontmatter": {
       "title": "Choisir comment créer une automatisation",
-      "description": "Modifie directement le workflow dans l’éditeur visuel ou connecte un assistant externe à Tale avec MCP."
+      "description": "Modifie les champs d’une automatisation dans l’éditeur, ou fais-la créer et modifier par un agent de code via MCP."
     }
   },
   "fr:platform/automations/builtin": {
@@ -2801,7 +2801,7 @@
     "locale": "fr",
     "frontmatter": {
       "title": "L’éditeur de workflow",
-      "description": "Examine et modifie les nœuds, fournis les données de test, puis enregistre, déploie ou rétablis une version."
+      "description": "Lis une automatisation sur son canevas, suis ses chemins possibles, modifie les champs d’un nœud, enregistre une version, puis déploie-la ou rétablis-en une autre."
     }
   },
   "fr:platform/automations/execution-logs": {

From e091887187988acd60cba5d0b8c8f19cc296976f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:20:53 +0200
Subject: [PATCH 58/78] docs(designs): state the canvas grammar and the shared
 code palette

app.md gains the automation canvas among the big surfaces: automatic layout, Start and End, conditions with Yes and No, frames, line kinds and dashed boxes, keyboard and List view, built from data with WorkflowCanvas. The Code Block spec colours code with the --code-* palette instead of fixed hex values.
---
 design/docs/app.md                       | 10 ++++++++++
 design/sources/platform/design-system.md |  8 ++++++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/design/docs/app.md b/design/docs/app.md
index cb8e1421a6..fd5bde5e34 100644
--- a/design/docs/app.md
+++ b/design/docs/app.md
@@ -104,6 +104,16 @@ what is there, and the page shows the one thing you opened.
   "improve with AI" rewrite. Specs: `design-system.md` → _Conversations_.
 - **Knowledge** — its pages (Documents/Knowledge entries/Websites/Products/Contacts) as a tab strip
   under the header, each a `DataTable`. Specs: `design-system.md` → _Knowledge_.
+- **Automation canvas** — the layout engine places every box, nobody does: **Start** on top (what
+  starts a run, what it receives), **End** at the bottom (what it returns, how a run ends), each node
+  below the nodes it reads. A condition is a pill in words above its node, splitting into **Yes**
+  (left) and **No** (right) when the node has an alternative; a frame means for-each or repeat; a
+  solid line reads output, a dashed one only orders, a dotted one ends the run; a dashed box may not
+  run. One Tab stop with arrow keys, a List view as the text alternative, the Paths list to light up
+  a path. Build it from data with `@tale/ui/flow/workflow-canvas`; never draw a node by hand. Guides:
+  [`workflow-canvas.md`](../../services/ui-docs/content/components/workflow-canvas.md),
+  [`workflow-paths.md`](../../services/ui-docs/content/components/workflow-paths.md),
+  [`workflow-playback.md`](../../services/ui-docs/content/components/workflow-playback.md).
 - **Auth, settings, automations, agents, onboarding** — each has a `.pen` under `design/sources/platform/`.
 
 ## Interaction conventions (hold these everywhere)
diff --git a/design/sources/platform/design-system.md b/design/sources/platform/design-system.md
index fbc0159217..efbf18a3c3 100644
--- a/design/sources/platform/design-system.md
+++ b/design/sources/platform/design-system.md
@@ -700,7 +700,11 @@ Used in AI chat responses for section hierarchy within rich text output.
 **Code body** (`ny4z0`):
 
 - Vertical layout, `padding: 16`, `gap: 2`, fill `#F9FAFB`
-- Code lines: JetBrains Mono 13px, `#111827`, `lineHeight: 1.6`
+- Code lines: JetBrains Mono 13px, `lineHeight: 1.6`, coloured by the `--code-*` palette in
+  `packages/ui/src/globals.css`: `--code-foreground` for plain text and one `--code-token-*` per
+  syntax role (keyword, string, template expression, constant, function, parameter, comment,
+  punctuation). The palette is AA on the code-block surface in both themes, and every read-only
+  code block and the code editor share it — never colour code with hex values.
 
 **Dark mode overrides:**
 
@@ -708,7 +712,7 @@ Used in AI chat responses for section hierarchy within rich text output.
 - Header bottom border: `#374151`
 - Language label + copy button: `#9CA3AF`
 - Code body fill: `#111827`
-- Code lines: `#E5E7EB`
+- Code lines: the dark values of the same `--code-*` variables
 
 **Behavior:**
 

From 062224dab5ab71cebf72f4b8669cff45db789f59 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 00:26:00 +0200
Subject: [PATCH 59/78] test(manual): check the canvas, paths, code fields and
 Source by hand

AUTO-F70 to F91, B17 to B20 and A11 to A16 cover Start and End, routed lines, node faces with translated action titles, conditions with Yes and No, Continues on error, the paths list and its halting nodes, versions that arrive live, completion, types and fixes in code fields, the control-flow fields, Start and End inspectors, Source, List, the coding-agent entry, ignored positions, the failed-run focus, Expand, three languages, JSON fidelity, offline, a 40-node document, keyboard, phone sheets, reduced motion and screen readers. F12, F13, F14, F18, B6 and A1 now describe the canvas and inspector as they ship. Numbering starts at F70 because an unmerged branch already holds F69.

The automation reference names the specs that own each half, and the readme counts 135 boxes in the suite.
---
 services/platform/tests/manual/readme.md      |   4 +-
 .../tests/manual/reference/automation.md      |   8 +
 .../tests/manual/suites/automations.md        | 283 ++++++++++++++++--
 3 files changed, 263 insertions(+), 32 deletions(-)

diff --git a/services/platform/tests/manual/readme.md b/services/platform/tests/manual/readme.md
index 15c9d82d17..7d6a030e70 100644
--- a/services/platform/tests/manual/readme.md
+++ b/services/platform/tests/manual/readme.md
@@ -29,7 +29,7 @@ tale-project standard ([`AGENTS.md`](../../../../AGENTS.md) "Manual tests"), and
 
 ## The suites
 
-1128 boxes across 21 suites. Every suite declares the ID prefix its
+1197 boxes across 21 suites. Every suite declares the ID prefix its
 boxes carry, in its header blockquote; a box ID is unique across this whole
 directory and greppable as one token.
 
@@ -38,7 +38,7 @@ directory and greppable as one token.
 | [accessibility](suites/accessibility.md) | `A11Y-` | cross-cutting WCAG 2.1 AA sweep | 28 |
 | [approvals](suites/approvals.md) | `APV-` | human-in-the-loop: run approval/ask cards, task review gate, DSAR dual-approval | 22 |
 | [auth](suites/auth.md) | `AUTH-` | login, SSO, 2FA, passkeys, password policy, first-run setup, RBAC | 59 |
-| [automations](suites/automations.md) | `AUTO-` | draft→deploy→version automations: list, builder, upload, trigger, runs, bindings | 80 |
+| [automations](suites/automations.md) | `AUTO-` | draft→deploy→version automations: list, the self-arranging canvas, paths, code fields, Source, upload, trigger, runs, bindings | 135 |
 | [chat](suites/chat.md) | `CHAT-` | messages, attachments, tools + approvals, arena, share, reasoning, the chat header and rows | 104 |
 | [connectors](suites/connectors.md) | `CONN-` | credential table + catalog picker; mailbox (IMAP/SMTP), OAuth, MCP endpoint | 41 |
 | [conversations](suites/conversations.md) | `CONV-` | the shared Inbox: statuses, priority, search, mailbox sync | 63 |
diff --git a/services/platform/tests/manual/reference/automation.md b/services/platform/tests/manual/reference/automation.md
index 067335cbff..b478a4ae31 100644
--- a/services/platform/tests/manual/reference/automation.md
+++ b/services/platform/tests/manual/reference/automation.md
@@ -1098,3 +1098,11 @@ Scroll-responsive navigation is covered by `packages/ui/src/hooks/use-scroll-com
 | [automations](../suites/automations.md) | Public run API projects safe legacy hold facts in organization and project scopes; stop requests require the exact hold identity and acknowledgement, authenticated actor and existing write authority; stale and wrong-scope requests refuse without releasing the hold | 🔶 REST contract and OpenAPI tests; native stop and migration outcomes remain separate integration proofs | `backend/rest/v1-automations.contract.test.ts`, `backend/rest/v1-automations.project-scope.test.ts`, `scripts/openapi/spec.test.ts` |
 | [connectors](../suites/connectors.md) | An agent's connector call through the in-sandbox bridge runs the action's live body in the platform process, like an automation's or chat's call, never as a `node -e` program in the agent's own session (whose command line carried the credential's secrets, readable by every process of that session, and which took one of its live-exec places); the bridge's dispatch carries no session. The bridge runs at most four of a session's calls at once (a further one is refused as busy), gives agent calls no file store, and a body past its time limit can no longer reach the outside system | ✅ backend | `backend/domains/connectors/service.runner.test.ts` (the door hands a live call the in-process runner, and a bridge call no file store), `backend/domains/connectors/bridge-routes.test.ts` (live mode, no session, the four-call cap), `lib/connectors/dispatcher.test.ts` (no host request after the time limit), `backend/core/node_only/sandbox/connectors_bridge.test.ts` (the dispatch's exact arguments), `backend/core/tasks/agent_run_host.connector_caller.test.ts` (a task run's call routed through the real hosts with the door mocked) |
 | [chat](../suites/chat.md) | Attachment permissions are checked before parking and before rebuilding history or regenerating a turn; preflight failures retain text only, metadata uses the current organization and reader, and denied document reads do not queue indexing. Real PostgreSQL probes cover same-organization and cross-organization audio denial through captured model requests, with an allowed own-audio control. | ✅ unit + real PostgreSQL | `backend/domains/chat/attachment-privacy.test.ts`, `deferred-sends.test.ts` and the `checkChatDeferredAuto` lane in `backend/integration-check.ts`; existing REST and arena suites cover surrounding caller contracts; door-level privacy execution remains separate |
+| [automations](../suites/automations.md) | The document-to-chart halves of `AUTO-F13` and `AUTO-F70`–`AUTO-F74`: `toFlowGraph` draws Start and End, one condition per `when` placed right before its node, Yes and No for an `elseOf` pair (else-if chains left to right, no pairing when the alternative reads its partner or sits in a cycle), one frame per iterating node, data, order, entry, exit and completion lines in a stable order, and the same graph whatever `ui` holds; node faces carry the connector's icon and its translated action title (fallback: the connector name and the humanized action), returns rows reserved until the check answers, the Continues on error chip and the writes, asks and unpinned-model markers; Start lists the triggers in words (cron words until schedules land) and the input fields with the trigger wrapper's tagged; conditions read in words in en, de (verb last), fr and de-CH, with locale quotes and numbers, and fall back to code; a run's record becomes the overlay (states, decisions, durations, the failure line, End's outcome) | ✅ unit | `app/features/automations/lib/flow-graph.test.ts`, `node-face.test.ts`, `trigger-summary.test.ts`, `condition-text.test.ts`, `run-overlay.test.ts`, `lib/connectors/action-titles.test.ts`, `backend/domains/automations/routes.catalog.test.ts`; how the faces read in both themes and three languages stays manual |
+| [automations](../suites/automations.md) | The layout halves of `AUTO-F71`, `AUTO-F77`, `AUTO-F88`, `AUTO-A11` and `AUTO-A14`: the shipped automations laid out in Chromium in the ELK worker have no line through a box, a condition, a frame header or a label, axis-aligned routes, Start above and End below every node; five scripted edits relaid live keep every row's order and glide with the motion tokens, an edit made elsewhere rings its nodes once, reduced motion jumps without a ring; the chart is one Tab stop whose arrows follow the lines and Home/End jump to Start and End; 40-node layouts finish in the worker within the budget; the graph never reads a document's positions | ✅ Chromium + unit | `app/features/automations/components/automation-canvas.browser.test.tsx`, `packages/ui/src/components/flow/workflow-canvas.browser.test.tsx`, `workflow-canvas.motion.browser.test.tsx`, `workflow-canvas.run.browser.test.tsx`, `layout/layout-flow-graph.test.ts`, `layout/geometry.test.ts`, `layout/sizes.test.ts`, `interaction/navigation.test.ts`; the live follow of a version saved through MCP in a second window, and judging the glide, stay manual |
+| [automations](../suites/automations.md) | The paths halves of `AUTO-F74`–`AUTO-F76` and `AUTO-B20`: P1's flow facts become path rows (index, nodes run of total, clauses for conditions and tolerated failures in model order), the reasons off-path nodes step back, End's outputs empty on a path, the halting nodes with their failure reasons, one-path, more-than-32 and too-many-conditions answers, no button on a cycle; the list previews on focus, pins on Enter, says the pin once and unpins with Escape or Show all, in a panel and in a sheet with its pill | ✅ unit + Chromium | `app/features/automations/lib/paths.test.ts`, `app/features/automations/components/automation-canvas.browser.test.tsx`, `packages/ui/src/components/flow/flow-path-list.browser.test.tsx`, `packages/ui/src/components/flow/paths/highlight.test.ts` |
+| [automations](../suites/automations.md) | The fidelity and Source halves of `AUTO-F85`, `AUTO-F88` and `AUTO-B19`: the draft is the raw document, so a connector `credential`, unknown node and top-level keys, a node without a type, `ui` and `tests` survive an inspector edit and a save byte for byte; the YAML text is deterministic and parses back to the same JSON; the Source view copies, downloads `<slug>-v<n>[-draft].yml` and marks each problem at its line | ✅ unit + component | `app/features/automations/lib/draft-document.test.ts`, `lib/yaml-source.test.ts`, `components/automation-source-view.test.tsx` |
+| [automations](../suites/automations.md) | The code-field halves of `AUTO-F79`–`AUTO-F81`, `AUTO-F90`, `AUTO-B6` and `AUTO-B17`: completion offers the scope roots per field, only upstream nodes after `nodes.`, only `output` after an ID, typed properties from the check's shapes, `item` only under forEach and never in `when`/`forEach`, `output` in repeatUntil; hover and ⌘K ⌘I share one type text; diagnostics land on exact and deeper pointers (JSON escapes, block scalars) with did-you-mean fixes; the engine's template scanner and the editor's agree on a corpus and 10 000 generated strings; a JSON field never rewrites its text on its own echo and refuses a value of the wrong kind; go-to selects the range in the code editor, Expand keeps the edit and caret, completion lists upstream fields | ✅ unit + component + Chromium | `app/features/automations/lib/code-providers.test.ts`, `lib/code-diagnostics.test.ts`, `lib/template-scan.parity.test.ts`, `components/json-code-field.test.tsx`, `components/node-inspector.test.tsx`, `components/automation-editor.browser.test.tsx`, `packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx`, `providers.test.ts`, `locate.test.ts`, `template-scan.test.ts` |
+| [automations](../suites/automations.md) | The inspector halves of `AUTO-F14`, `AUTO-F82`–`AUTO-F84` and `AUTO-F87`: the header, When it runs from the local flow facts and the server's failure reasons, the Fields, Shape and Last run tabs, On error, Maximum repeats (1 to 20, refused out of range) and Else of (only nodes with a condition) as controls, Start and End inspectors that edit `inputs` and `output`, `?node=` and `?view=` in the URL, problems in the inputs, output and the rest of the document opening Start, End and Source, the coding-agent dialog's name, MCP set-up link and guide link | ✅ unit + component + Chromium | `app/features/automations/lib/issues.test.ts`, `lib/editor-search.test.ts`, `components/node-inspector.test.tsx`, `components/node-shape-panel.test.tsx`, `components/document-inspectors.test.tsx`, `components/coding-agent-entry.test.tsx`, `components/automation-editor.test.tsx`, `components/automation-editor.browser.test.tsx` |
+| [automations](../suites/automations.md) | The package halves of `AUTO-A12` and `AUTO-A13`: in the code editor Tab indents, Escape then Tab leaves, the first Escape in a sheet closes the suggestion list, the legend shows after keyboard focus only, F8 and ⌘. reach and apply a problem's fix, the problem describes the field; the code palette is AA on its surfaces in both themes and matches Shiki's colours character for character; CodeMirror stays out of the light modules | ✅ Chromium + unit | `packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx`, `code-editor.loading.browser.test.tsx`, `code-roles.parity.test.ts`, `light.test.ts`, `packages/ui/src/lib/code-palette.test.ts`; touch selection, the iOS keyboard and a real screen reader stay manual |
+| [automations](../suites/automations.md) | The bundle half of `AUTO-P2`: the cold load carries neither ELK nor CodeMirror, the ELK worker and the editor load lazily, `vendor-codemirror` holds only the editor's packages, and opening the editor stays within its closure budget | ✅ build script | `scripts/check-entry-budget.test.ts` (run `check-entry-budget` after a client build) |
diff --git a/services/platform/tests/manual/suites/automations.md b/services/platform/tests/manual/suites/automations.md
index c8d5a80bcd..f9b3bb9d52 100644
--- a/services/platform/tests/manual/suites/automations.md
+++ b/services/platform/tests/manual/suites/automations.md
@@ -1,6 +1,6 @@
 # Automations
 
-> **Prefix** `AUTO-` · **Reset** none · **Cost** 103 boxes
+> **Prefix** `AUTO-` · **Reset** none · **Cost** 135 boxes
 
 Exercise the draft→deploy→version automation surface: each automation is one
 workflow document under a name, with an append-only version history, at most
@@ -99,6 +99,32 @@ output:
   text: '{{ nodes.greet.output.text }}'
 ```
 
+For the canvas boxes (`AUTO-F73`), a branch probe whose condition hangs
+**Yes** and **No** from one pill:
+
+```yaml
+# workflow.yml
+name: qa/branch-probe
+description: QA probe — a condition with an alternative, no connectors.
+nodes:
+  - id: score
+    type: transform
+    input: { total: 1200 }
+    code: 'return { total: input.total };'
+  - id: escalate
+    type: transform
+    when: '{{ nodes.score.output.total > 1000 }}'
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "escalate " + input.total };'
+  - id: file
+    type: transform
+    elseOf: escalate
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "file " + input.total };'
+output:
+  text: '{{ nodes.escalate.output?.text ?? nodes.file.output?.text }}'
+```
+
 > **Agent note**: run state is Convex-reactive — never poll by reload. A run
 > is **terminal** exactly when its status badge reads **Succeeded** /
 > **Failed** / **Stopped** (`automations.runs.status.*`); equivalently the
@@ -200,17 +226,29 @@ output:
       live**, **Discard**, **Save** — nothing sits in the title row's right
       half. Body: the canvas alone fills the tab edge to edge under the strip
       — with no node selected there is no inspector column at all (AUTO-F37;
-      a selected node's inspector does not grow the canvas); the
+      a selected node's inspector does not grow the canvas). Its top left
+      holds the view switch (`automations.canvas.view.label`: **Canvas**,
+      **List**, **Source**); its top right the paths button
+      (`automations.paths.button`), the last-run eye once the automation has
+      run (`automations.detail.hideLastRun`) and, last, **Edit with your
+      coding agent** (`automations.codingAgent.button`); the zoom controls
+      and **Legend** (`flow.controls.legend`) sit bottom left. The
       trigger and the project bindings are the **General** tab (AUTO-F51),
       version history in the picker and executions in Runs (AUTO-F35) — none of them panels
       beside or under the canvas.
-- [ ] `AUTO-F13` · **Canvas graph** — On the workbench, inspect the canvas →
-      Region labelled **Automation canvas** (`automations.canvas.ariaLabel`); each
-      node is a box naming its type and the nodes it reads (`flow.list.reads`,
-      else `automations.canvas.readsNothing`); the legend says what each line
-      means (`automations.canvas.legend.data` /
-      `automations.canvas.legend.control`); a
-      versionless/empty document shows `automations.canvas.empty.title`
+- [ ] `AUTO-F13` · **Canvas graph** — On the workbench of
+      `github-triage-issues`, inspect the canvas → a group labelled
+      **Automation canvas** (`automations.canvas.ariaLabel`), laid out by
+      itself: **Start** (`flow.node.entry`) on top, **End**
+      (`flow.node.exit`) at the bottom, every node below the nodes it reads.
+      Each node box shows its icon, a title from its ID, its catalog line,
+      what it returns once known and what it reads in its strip
+      (`flow.list.reads`, else `automations.canvas.readsNothing`); Score
+      sits in a frame headed by `automations.canvas.controlFlow.forEach`.
+      **Legend** (`flow.controls.legend`) opens `flow.legend.title` with
+      every line and box kind (`automations.canvas.legend.*`); a version with
+      no nodes shows `automations.canvas.empty.title` with **Edit with your
+      coding agent** as its action.
 - [ ] `AUTO-F14` · **Node inspector** — Click a node; **Close**
       (`common.aria.close`); Escape; click the box again; click empty canvas →
       First click opens the node's fields, rings the box, and moves focus into the
@@ -219,13 +257,17 @@ output:
       empty canvas all close the inspector and hand its width back to the
       canvas. A box near the canvas's right edge that the opening inspector
       would cover pans back into view. Canvas height stays
-      put; extra node fields scroll inside the inspector. Inspector heading is the
-      node id with a type badge (catalog copy is not dumped into the header).
-      Typed fields come first (e.g. **Prompt**), then **Input**
-      (`automations.editor.fields.input`); unused **Control flow**
-      (`automations.editor.controlFlowTitle`) is a closed disclosure that opens
-      when any of When / Else of / For each / Repeat until is set. Read-only
-      without the developer capability.
+      put; extra node fields scroll inside the inspector. The header reads the
+      node's title, its catalog line and its ID with **Copy node ID**
+      (`automations.editor.inspector.copyId`); **When it runs**
+      (`automations.editor.flow.title`) follows, then the tabs **Fields**,
+      **Shape** and, while a run is shown, **Last run**
+      (`automations.editor.inspector.tabs.*`). Typed fields come first (e.g.
+      **Prompt**), then **Input** (`automations.editor.fields.input`); unused
+      **Control flow** (`automations.editor.controlFlowTitle`) is a closed
+      disclosure that opens when any of When / Else of / For each / Repeat
+      until / Maximum repeats / On error is set. The URL carries
+      `?node=<id>`. Read-only without the developer capability.
 - [ ] `AUTO-F15` · **Edit → Save version** — Change a node field → **Save
       version** (`automations.detail.saveVersion`) → dialog
       (`automations.detail.saveDialog.title`) → enter a **Version message**
@@ -254,12 +296,12 @@ output:
       **Deploy** control.
 - [ ] `AUTO-F18` · **Test run (mock)** — On `qa/manual-probe` (undeployed is
   fine) → **Test run** (`automations.detail.runMock`); when the saved version declares inputs, fill **Run input (JSON)** (`automations.detail.runInput.label`) using **Input schema** (`automations.detail.runInput.schema`) — missing required fields and invalid JSON keep confirmation disabled → A run starts on the
-  version on screen; the canvas icon **Show last run** / **Hide last run**
-  (`automations.detail.showLastRun` / `automations.detail.hideLastRun`)
-  toggles per-node status overlays on the canvas
-  (`automations.runs.nodeStatus.*`), and the inspector gains an **In this
-  run** section (`automations.editor.runTitle`) with **Resolved input** /
-  **Output** (`automations.editor.resolvedInput` /
+  version on screen; the canvas shows it at once, each node's strip saying
+  how it ended (`flow.state.*`), and the eye at the canvas's top right,
+  **Hide last run** / **Show last run** (`automations.detail.hideLastRun` /
+  `automations.detail.showLastRun`), takes it off and back; the inspector
+  gains the **Last run** tab (`automations.editor.inspector.tabs.run`) with
+  **Resolved input** / **Output** (`automations.editor.resolvedInput` /
   `automations.editor.output`)
 - [ ] `AUTO-F19` · **Runs tab** — **Runs** tab (`automations.navigation.runs`)
       after AUTO-F18 → `…/{slug}/runs` lists the runs newest first under the
@@ -749,6 +791,143 @@ output:
       the node's sheet closes, the Problems sheet opens on All
       (`automations.problems.filter.all`) with focus on the first error, and
       Enter on it opens the node that holds the error with its field focused.
+- [ ] `AUTO-F70` · **Open Triage GitHub issues on the Editor tab** → **Start**
+      (`flow.node.entry`) sits above every node: under **Starts**
+      (`flow.node.triggers`) the schedule in words with its time zone and
+      next run, the state badge while it is not live
+      (`automations.canvas.start.notLive`), then **By hand, the API or MCP**
+      (`automations.canvas.start.manual`); under **Input** (`flow.node.inputs`)
+      owner and repo as required, trigger and firedAt as from the trigger
+      (`automations.canvas.start.fromTrigger`); a notice says the schedule
+      starts runs without owner and repo
+      (`automationIssues.codes.TRIGGER_INPUT_MISMATCH.cause`). **End** (`flow.node.exit`) at the
+      bottom says **The output of Report** (`automations.canvas.end.returnsNode`),
+      its shape once the check has answered, and the three ways a run ends
+      under **Ends** (`flow.node.outcomes`).
+- [ ] `AUTO-F71` · **Follow the line from Open issues to Report** → it runs
+      beside Score's frame, never through it; no line on the canvas crosses a
+      box, a condition pill, a frame header or a Yes / No label.
+- [ ] `AUTO-F72` · **Read the node boxes of Triage GitHub issues** → each shows
+      an icon, a title from its ID (**Open issues**), its catalog line
+      (**GitHub · List issues**, `automations.canvas.node.catalog.connector`;
+      **Transform**, **Language model · …**), what it returns once the check
+      has answered, and what it reads in its bottom strip
+      (`flow.list.reads`); no raw `{{ }}` and no raw type name such as
+      github.list_issues on any box. In Deutsch and Français the action titles are translated
+      (**GitHub · Issues auflisten**, **GitHub · Lister les issues**).
+- [ ] `AUTO-F73` · **Upload the branch probe (Preconditions) and open it** → a
+      condition pill above Escalate says
+      `automations.condition.gt` in words ("total of Score is greater than
+      1,000"); **Yes** (`flow.branch.yes`) leads to Escalate on the left,
+      **No** (`flow.branch.no`) to File on the right; Escalate and File have
+      dashed borders; the gate's name reads `flow.gate.name` and its
+      description `flow.gate.branches`.
+- [ ] `AUTO-F74` · **Open Gmail triage inbox** → Propose carries the chip
+      **Continues on error** (`automations.canvas.controlFlow.onError`); the
+      paths list has a path whose clause reads
+      `automations.paths.clause.fails`; Propose's **When it runs** says
+      `automations.editor.flow.failContinues`.
+- [ ] `AUTO-F75` · **Open the paths list, point at each path, then press Enter
+      on one** → the button (`automations.paths.button`) opens **Possible
+      paths** (`automations.paths.title`) as a panel under the view switch;
+      pointing previews a path, Enter pins it: off-path nodes turn dashed
+      with their reason (`automations.paths.skip.*`), End marks outputs
+      empty on that path (`automations.canvas.end.emptyOnPath`), and a screen
+      reader hears `automations.paths.showing` once; **Show all**
+      (`flow.paths.showAll`) or Escape restores every node. The panel stays
+      open while you click nodes.
+- [ ] `AUTO-F76` · **In the paths list, point at a node under Ends the run
+      when it fails** → the section (`automations.paths.halts.title`) rings
+      every halting node in red at once; Enter on a row opens that node in
+      the inspector.
+- [ ] `AUTO-F77` · **In a second window, save a new version through MCP while
+      the first shows the latest with no draft** → the first canvas glides
+      to the new layout in about a third of a second, a new node fades in,
+      changed nodes ring once, no node swaps sides with its row neighbour, a
+      screen reader hears `automations.canvas.updated`, and the open node
+      stays open (or the inspector closes with
+      `automations.canvas.selectionRemoved` when it is gone).
+- [ ] `AUTO-F78` · **With a draft open, save another version through MCP** →
+      an info notice above the canvas says
+      `automations.canvas.newerVersion.title` with
+      `automations.canvas.newerVersion.show`; nothing on the canvas moves
+      until you choose it, and choosing it shows the new version.
+- [ ] `AUTO-F79` · **In a Prompt, type `{{` then `nodes.`** → the field reads
+      `{{  }}` with the caret inside and suggestions open; after `nodes.` only
+      nodes that run earlier are offered, never the node itself or a later
+      one; after `.output.` the node's fields are listed with their kinds; the
+      finished expression shows as a tinted mono chip in the prose.
+- [ ] `AUTO-F80` · **Point at a reference in a code field, then press ⌘K ⌘I
+      (Ctrl+K Ctrl+I) on it** → the same type tooltip
+      (`codeEditor.typeInfo.label`) both ways; the keyboard one is read aloud
+      (`codeEditor.typeInfo.announce`).
+- [ ] `AUTO-F81` · **Misspell a node ID inside a transform's Code** → within
+      about a second a wavy underline sits under exactly that ID; F8 moves
+      to it and reads it (`codeEditor.diagnostics.atCursor`); ⌘. (Ctrl+.)
+      applies `automations.editor.fixSuggestion` with the closest ID; going
+      to the same problem from the Problems list selects the same span.
+- [ ] `AUTO-F82` · **Under Control flow, set On error to Continue without it,
+      Maximum repeats to 3 on a node with Repeat until, and an Else of
+      target** → **On error** (`automations.editor.fields.onError`) offers
+      `automations.editor.fields.onErrorStop` and
+      `automations.editor.fields.onErrorContinue`; **Else of** offers only
+      nodes with a condition, plus **None**
+      (`automations.editor.fields.elseOfNone`); 25 in **Maximum repeats** is
+      refused with `automations.editor.fields.maxRepeatsRange` and changes
+      nothing; each valid setting is in the saved version's Source.
+- [ ] `AUTO-F83` · **Open a node's Shape tab** → **Receives**, **Returns** with
+      where the shape comes from (`automations.editor.shape.origin.*`) and
+      **Read by** (`automations.editor.shape.readBy`), whose buttons open each
+      reader; **Show as TypeScript** (`schemaTree.asTypeScript`) shows the
+      same shape as a type.
+- [ ] `AUTO-F84` · **Select Start and edit its Input schema; select End and edit
+      its Output; save** → Start's inspector (`automations.editor.start.title`)
+      shows the trigger rows with **Change in General**
+      (`automations.editor.start.editTrigger`), the input fields as a tree and
+      **Input schema** (`automations.detail.runInput.schema`); End's
+      (`automations.editor.end.title`) shows **How a run ends** with each
+      halting node as a button, and **Output**
+      (`automations.editor.fields.output`); both edits are in the new version;
+      a problem in either opens there from the Problems list; `?node=__start`
+      and `?node=__end` open them from a link.
+- [ ] `AUTO-F85` · **Switch to Source** (`automations.canvas.view.source`) → the
+      whole document as highlighted YAML with line numbers, folding and
+      search (⌘F); **Copy YAML** (`automations.source.copy`) copies it and its
+      icon turns into a check for two seconds; **Download YAML**
+      (`automations.source.download`) saves `<name>-v<n>.yml`, with `-draft`
+      while a draft is open; `automations.source.readOnlyHint` stands under
+      the toolbar; a problem in `tests` goes to its line from the Problems
+      list.
+- [ ] `AUTO-F86` · **Switch to List** (`automations.canvas.view.list`) → the
+      nodes in run order, each with what it reads (`flow.list.reads`) and its
+      condition folded in as `flow.relation.onlyIf`; Enter opens a node; the
+      view stays in the URL as `?view=list` across a reload.
+- [ ] `AUTO-F87` · **Find Edit with your coding agent**
+      (`automations.codingAgent.button`) → it is the last button at the
+      canvas's top right in Canvas, List and Source, and the primary action of
+      a version with no nodes (`automations.canvas.empty.title`); its dialog
+      shows **Name of this automation** (`automations.codingAgent.nameLabel`)
+      to copy, **Set up MCP** (`automations.codingAgent.setUp`) opening
+      `/dashboard/{org}/settings/api/mcp`, and **How to connect a coding
+      agent** (`automations.codingAgent.learnMore`) opening the MCP endpoint
+      guide in a new tab.
+- [ ] `AUTO-F88` · **Upload a document whose `ui` block stacks every node at
+      0,0** → it is laid out automatically like any other; after a field edit
+      and **Save version**, Source shows the `ui` block unchanged.
+- [ ] `AUTO-F89` · **Open a failed run** → the failed node is in view, framed in
+      red with its error's first line in its strip; the way the run took to
+      it stands out while other nodes step back; End says
+      `automations.canvas.end.failedAt`; selecting a node opens its inspector
+      on **Last run** (`automations.editor.inspector.tabs.run`).
+- [ ] `AUTO-F90` · **Expand a node's Code field, edit, then go back** →
+      **Expand editor** (`codeEditor.expand`) opens the larger editor; **Back
+      to the field** (`codeEditor.collapse`) returns with the edit in place and
+      the caret where it was.
+- [ ] `AUTO-F91` · **Switch to Deutsch, Français and Deutsch (Schweiz)** →
+      every canvas, paths, Start/End, inspector and Source string is
+      translated; German conditions put the verb last ("… größer als 1.000
+      ist"); French shows « Canevas » with no-break spaces before `:`; Swiss
+      German shows «…» and "grösser".
 
 ## Boundary & error tests
 
@@ -772,9 +951,11 @@ output:
       disabled with reason `automations.detail.runLiveNeedsDeploy`; no dialog, no
       run row appears.
 - [ ] `AUTO-B6` · **Invalid JSON in a node** — In the inspector, type the
-      text `{ not json` into the **Input** field → Notice
-      `automations.editor.invalidJson`; the node is NOT changed (no dirty state
-      from the invalid text; Save version keeps the last valid document)
+      text `{ not json` into the **Input** code field → the field says
+      `automations.editor.invalidJson` and the editor marks where the JSON
+      breaks (`codeEditor.syntax.json`); the node is NOT changed (no dirty
+      state from the invalid text; Save version keeps the last valid
+      document), and the text stays as typed
 - [ ] `AUTO-B7` · **Two tabs editing the same automation** — Open the same
       automation's workbench in tabs A and B (both on the latest version). In
       B, edit a node and leave it unsaved. In A, edit another node → **Save**
@@ -866,6 +1047,20 @@ output:
       answers instead of the editor and the network log shows no validate
       request; posting a document to the validate route with that session
       answers 403 and saves nothing.
+- [ ] `AUTO-B17` · **In Input, type `{"a":1}` one character at a time, then
+      replace it with `1`** → the caret never jumps while typing; `1` shows
+      `automations.editor.jsonMustBeObject` under the field and the node keeps
+      `{"a":1}`.
+- [ ] `AUTO-B18` · **Take the network offline and change a reference** →
+      Start, End, conditions, frames and the paths list still update; the
+      Shape tab says `automations.editor.shape.unavailable`; **Save** works
+      again once the network is back.
+- [ ] `AUTO-B19` · **Edit a field of a connector node that has a `credential`,
+      then save** → Source shows the `credential` key unchanged in the new
+      version, and so does every key the inspector has no field for.
+- [ ] `AUTO-B20` · **Upload an automation with 40 nodes and 13 conditions** →
+      it lays out in about a second, typing in a prompt never stutters, and
+      the paths list says `automations.paths.truncated`.
 
 ## Run liveness — chaos recovery (backend, scripted)
 
@@ -899,11 +1094,12 @@ Those doors were Convex functions, gone with that backend: mark the five boxes
 
 ## Accessibility (WCAG 2.1 AA)
 
-- [ ] `AUTO-A1` · **Canvas semantics** → The canvas is a labelled region
-      (**Automation canvas**, `automations.canvas.ariaLabel`); every node box is a
-      real `<button>` that is keyboard reachable and expands/controls the
-      inspector (`aria-expanded` / `aria-controls`). Enter/Space toggles the
-      inspector; Escape closes it (not while typing); **Close**
+- [ ] `AUTO-A1` · **Canvas semantics** → The canvas is a labelled group
+      (**Automation canvas**, `automations.canvas.ariaLabel`) described by
+      `flow.canvas.keyboardHelp`; the chart is one Tab stop with roving focus
+      (`AUTO-A11`), and every box is a real `<button>` that expands/controls
+      the inspector (`aria-expanded` / `aria-controls`). Enter/Space toggles
+      the inspector; Escape closes it (not while typing); **Close**
       (`common.aria.close`) is in the panel. Selection never needs a mouse.
 - [ ] `AUTO-A2` · **Status not by colour** → Run and node status badges each
       carry an icon AND a word (`automations.runs.status.*`,
@@ -952,6 +1148,33 @@ Those doors were Convex functions, gone with that backend: mark the five boxes
       `AUTO-F62`, press ⌘S (Ctrl+S) in the Prompt field → the browser's
       "Save page as" dialog does not open, focus moves to **Save** and its
       tooltip says `automations.problems.saveBlocked`; nothing is saved.
+- [ ] `AUTO-A11` · **Keyboard only on the canvas** → one Tab enters the chart
+      at Start; the arrows follow the lines and move along a row; Home and End
+      jump to Start and End; Enter opens the box; Tab leaves to the toolbars;
+      a screen reader hears each box's title, catalog line and what it reads;
+      the paths list works with the arrows, Enter and Escape.
+- [ ] `AUTO-A12` · **Keyboard only in the code editor** → Tab indents; Escape
+      then Tab leaves (`codeEditor.leaveArmed`); the legend chip
+      (`codeEditor.legend.leave`) shows only after keyboard focus; a condition
+      field never traps Tab; Ctrl+Space opens suggestions; the field's problem
+      is read as its description.
+- [ ] `AUTO-A13` · **At 390 px, in a node's sheet** → Escape closes the
+      suggestion list, then arms leaving, then closes the sheet; selecting text
+      never drags the sheet; code text is 16 px, so the page never zooms;
+      suggestions stay inside the sheet.
+- [ ] `AUTO-A14` · **With reduced motion on** → relayouts, refits, the changed
+      ring and the paths panel appear without movement; the caret does not
+      blink.
+- [ ] `AUTO-A15` · **In dark mode, with forced colours, at 200 % zoom, at
+      375 px and on touch** → tokens, lines, labels and squiggles stay
+      readable; toolbars and sheets stay usable; on the run page one finger
+      scrolls the page and two move the chart, with
+      `flow.canvas.touchHint` shown once.
+- [ ] `AUTO-A16` · **With a screen reader on Start, a condition and End** →
+      Start reads its triggers and fields
+      (`automations.canvas.start.description`); the condition reads
+      `flow.gate.name` then `flow.gate.branches`; End reads what it returns
+      and how a run ends.
 
 ## Performance
 

From eb30ef5e6a72941491eb065021703cc91394f4a4 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 01:03:16 +0200
Subject: [PATCH 60/78] test(platform): hold the scanners apart on a regex now
 that comments agree

---
 .../automations/lib/template-scan.parity.test.ts | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/services/platform/app/features/automations/lib/template-scan.parity.test.ts b/services/platform/app/features/automations/lib/template-scan.parity.test.ts
index 5aa8d1ea23..d6ee1cbc32 100644
--- a/services/platform/app/features/automations/lib/template-scan.parity.test.ts
+++ b/services/platform/app/features/automations/lib/template-scan.parity.test.ts
@@ -19,8 +19,8 @@ import { engineTemplateScan } from './template-scanner';
  * runtime's for anything an author writes.
  *
  * They differ on purpose only where "balanced" and "parses" part ways: a
- * comment or a regular expression holding `}}`, and a span that is
- * balanced but not an expression. The generator writes neither.
+ * regular expression holding `}}`, a line comment, and a span that is
+ * balanced but not an expression. The generator writes none of them.
  */
 
 /** The spans as both scanners must agree on them. */
@@ -169,12 +169,16 @@ describe('engineTemplateScan', () => {
     ]);
   });
 
-  it('follows the run where the package rule cannot: a comment holding the closer', () => {
-    const text = '{{ a /* }} */ }}';
+  it('follows the run where the package rule cannot: a regular expression holding the closer', () => {
+    const text = '{{ /}}/.test(a) }}';
     expect(engineTemplateScan(text).spans.map((span) => span.end)).toEqual([
-      10,
+      18,
     ]);
-    expect(scanTemplates(text).spans.map((span) => span.end)).toEqual([16]);
+    expect(scanTemplates(text).spans.map((span) => span.end)).toEqual([6]);
+  });
+
+  it('agrees with the package on a block comment holding the closer', () => {
+    expectSame('{{ a /* }} */ }}');
   });
 });
 

From 7436ac9f058a2b0ed1e9d96a874e645f57ef41e9 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 01:05:15 +0200
Subject: [PATCH 61/78] style(ui): order the dialog imports after moving onto
 main

---
 packages/ui/src/components/dialog/dialog.tsx              | 2 +-
 packages/ui/src/components/overlays/responsive-dialog.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/dialog/dialog.tsx b/packages/ui/src/components/dialog/dialog.tsx
index 23437eb8da..6b5c7e19fa 100644
--- a/packages/ui/src/components/dialog/dialog.tsx
+++ b/packages/ui/src/components/dialog/dialog.tsx
@@ -9,8 +9,8 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { ChevronLeft, X } from 'lucide-react';
 import * as React from 'react';
 
-import { CLOSE_BUTTON_CLASS } from '../overlays/close-button-class';
 import { respectEscapeClaims } from '../overlays/claims-escape';
+import { CLOSE_BUTTON_CLASS } from '../overlays/close-button-class';
 import { PagePointerPin } from '../overlays/page-pointer-pin';
 
 // Tracks dialog nesting so a child Dialog opened from inside another
diff --git a/packages/ui/src/components/overlays/responsive-dialog.tsx b/packages/ui/src/components/overlays/responsive-dialog.tsx
index 3bb0afe0b7..943972f5f2 100644
--- a/packages/ui/src/components/overlays/responsive-dialog.tsx
+++ b/packages/ui/src/components/overlays/responsive-dialog.tsx
@@ -18,8 +18,8 @@ import { useIsMobile } from '../../hooks/use-is-mobile';
 import { useRestoreFocus } from '../../hooks/use-restore-focus';
 import { useT } from '../../i18n/client';
 import { cn } from '../../lib/cn';
-import { CLOSE_BUTTON_CLASS } from './close-button-class';
 import { respectEscapeClaims } from './claims-escape';
+import { CLOSE_BUTTON_CLASS } from './close-button-class';
 import { PagePointerPin } from './page-pointer-pin';
 
 /**

From 949470d9c257e345d3b851ed3c2661cd4909cfaf Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 03:53:53 +0200
Subject: [PATCH 62/78] test(manual): check the code editor and workflow
 examples by hand

DOCS-21 to DOCS-25 judge the code editor, schema tree, vendor icon, workflow canvas, paths and playback examples in both themes, at 375 px, with reduced motion and with VoiceOver. The automation reference names the specs that own each half, and the docs suite's cost grows to about 50 minutes.
---
 services/ui-docs/tests/manual/readme.md               | 2 +-
 services/ui-docs/tests/manual/reference/automation.md | 4 ++++
 services/ui-docs/tests/manual/suites/docs.md          | 7 ++++++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/services/ui-docs/tests/manual/readme.md b/services/ui-docs/tests/manual/readme.md
index ded843e10f..3ff4030b10 100644
--- a/services/ui-docs/tests/manual/readme.md
+++ b/services/ui-docs/tests/manual/readme.md
@@ -37,7 +37,7 @@ prefix may shadow another.
 |---|---|---|---|---|
 | [smoke](suites/smoke.md) | `SMOKE-` | is this build even drivable — run it before investing in anything bigger | once, at the start | 10 min |
 | [home](suites/home.md) | `HOME-` | the first guide at the root: shared frame, spacing and responsive reading | none | 5 min |
-| [docs](suites/docs.md) | `DOCS-` | the shared app-language documentation frame: rail, trail, page actions, live examples + Code, outline, neighbours, footer, drawer, print, both themes, 404 | none | 30 min |
+| [docs](suites/docs.md) | `DOCS-` | the shared app-language documentation frame: rail, trail, page actions, live examples + Code, outline, neighbours, footer, drawer, print, both themes, 404, and the code editor and workflow examples | none | 50 min |
 | [search](suites/search.md) | `SEARCH-` | the ⌘K palette: triggers, results, keyboard, recents, empty state | none | 10 min |
 | [seo](suites/seo.md) | `SEO-` | the crawler surface on the built server: prerendered head, JSON-LD, sitemap, robots, llms + `.md` twins, real 404, headers | none | 15 min |
 
diff --git a/services/ui-docs/tests/manual/reference/automation.md b/services/ui-docs/tests/manual/reference/automation.md
index e41a20ba7d..e66e5ab9f4 100644
--- a/services/ui-docs/tests/manual/reference/automation.md
+++ b/services/ui-docs/tests/manual/reference/automation.md
@@ -51,6 +51,10 @@ a spec failure and belongs in the gate, not in a round.
 | Print                                                                                                                                                                                                                                 | —                                                                                                                     | **manual-only** — the frame hides its chrome in print (`DOCS-16`)                                                     |
 | The root renders the first guide with one shared frame, selected rail row, canonical guide URL, search and the shared public-site footnote | `tests/e2e/specs/smoke.spec.ts` › documentation entry, `tests/e2e/specs/entry-a11y.spec.ts` (real contrast in both themes) | responsive visual treatment (`HOME-16`) |
 | `ResponsiveDialogContent` header actions sit in one cluster before Close on the dialog and the drawer, Close reads the translated label, a hidden Close leaves the actions; `PropertyList` rows align and wrap long labels; `PropertyChip` empty and set states | `packages/ui/src/components/overlays/responsive-dialog.test.tsx` + `.browser.test.tsx`, `packages/ui/src/components/data-display/property-list.test.tsx` + `.browser.test.tsx`, `packages/ui/src/components/forms/property-chip.test.tsx` + `.browser.test.tsx` | the `dialog/header-actions`, `property-list/basic` and `property-list/chips` demos in both themes and on a phone |
+| Code editor: a controlled value round-trips without moving the caret or echoing; Tab indents, Escape then Tab leaves, one line never takes Tab and submits on Enter; the legend shows after keyboard focus only; in a sheet the first Escape closes the list and the sheet waits for leave to be armed; `{{` opens a pair, Backspace removes it, each template is one chip; completion after a dot, on Ctrl+Space and after `{{`, with types in its panel; problems underlined by severity, walked with F8 and read aloud, fixed with ⌘.; hover and ⌘K ⌘I share one type text; Expand brings the caret back; it keeps its size while loading; the palette keeps 4.5:1 on its surfaces in both themes and colours each character as Shiki does; CodeMirror stays out of the light modules | `packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx`, `code-editor.loading.browser.test.tsx`, `providers.test.ts`, `template-scan.test.ts`, `locate.test.ts`, `member-path.test.ts`, `diagnostic-mapping.test.ts`, `phrases.test.ts`, `code-roles.parity.test.ts`, `light.test.ts`, `deps.test.ts`, `packages/ui/src/lib/code-palette.test.ts`, `packages/ui/src/markdown/shiki.test.ts`, `packages/ui/src/components/overlays/claims-escape.test.tsx` | judge the six `code-editor/*` examples by eye in both themes, with VoiceOver, and with touch selection and the on-screen keyboard at 375 px (`DOCS-21`, `DOCS-22`) |
+| Schema tree and vendor icon: kinds in words in three languages, required and optional said in words, compact and comfortable densities, the TypeScript shape from the keyboard; the plug glyph without an icon or when it fails to load | `packages/ui/src/components/data-display/schema-tree.test.tsx` + `schema-tree.browser.test.tsx`, `vendor-icon.test.tsx` | judge the `schema-tree/basic` and `foundations/vendor-icon` examples in both themes and at 375 px (`DOCS-23`) |
+| Workflow canvas: the layout in the worker with every line along its route and none through a box, a condition, a frame header or a label; the main-thread layout and its one warning when the worker cannot start; a busy skeleton until the first layout; 40 nodes inside the budget; one Tab stop whose arrows follow the lines; each node's name and description, a condition's branches; the List view and its stored choice; a live relayout that glides, grows in, fades lines in last, shrinks out what leaves and rings outside changes once; a new picture without a glide; reduced motion without animation or ring; the fit, zoom and reset; the legend | `packages/ui/src/components/flow/workflow-canvas.browser.test.tsx`, `workflow-canvas.motion.browser.test.tsx`, `flow-canvas.browser.test.tsx`, `flow-legend.browser.test.tsx`, `flow-step-list.browser.test.tsx`, `layout/layout-flow-graph.test.ts`, `layout/geometry.test.ts`, `layout/sizes.test.ts`, `interaction/navigation.test.ts`, `motion/flow-motion.test.ts`, `motion/use-layout-transition.test.ts`, `validate-graph.test.ts`, `describe.test.ts` | judge the seven `flow/*` examples of the Workflow canvas guide in both themes, at 375 px and with reduced motion: the glide's feel, the ring, the focus ring, the touch hint (`DOCS-24`) |
+| Workflow paths and playback: the path list is one Tab stop, pins with Enter, says so once and unpins with Escape or Show all, also from Show all and in a sheet; highlights through a branch label, a node's own lines, a host highlight with its reasons; a run's states at each moment, dots that follow the moment, none under reduced motion; a failed run's way forward and the line into it red; how each condition decided; the running bar and settling strips; following the run until the reader moves the view; the playback bar's keys, Space, speed, live follow and phone menu | `packages/ui/src/components/flow/flow-path-list.browser.test.tsx`, `paths/highlight.test.ts`, `workflow-canvas.run.browser.test.tsx`, `playback/build-timeline.test.ts`, `playback/derive-state.test.ts`, `playback/flow-playback-bar.browser.test.tsx`, `render/looks.test.ts`, `node-status.test.tsx` | judge the `flow/possible-paths`, `flow/static-overlay` and `flow/playback` examples in both themes, at 375 px and with reduced motion (`DOCS-25`) |
 
 Legend: a named spec owns the row end to end · a named spec **plus** a manual
 scope is partial · `—` is manual-only.
diff --git a/services/ui-docs/tests/manual/suites/docs.md b/services/ui-docs/tests/manual/suites/docs.md
index 28f826fa78..d8339ffe2c 100644
--- a/services/ui-docs/tests/manual/suites/docs.md
+++ b/services/ui-docs/tests/manual/suites/docs.md
@@ -1,6 +1,6 @@
 # Documentation pages
 
-> **Prefix** `DOCS-` · **Reset** none · **Cost** ~30 min
+> **Prefix** `DOCS-` · **Reset** none · **Cost** ~50 min
 
 Every page under `/docs` — the **app** design language, in the shared
 `@tale/ui/docs/*` frame the product docs render too: the navigation rail, the
@@ -114,3 +114,8 @@ judges **behaviour**, not link rot.
 - [ ] `DOCS-18` · **Open `/docs/patterns/list-page`, use Scroll to last item in the large-list example, then select Item 5000 with the keyboard** → the last item is reachable, **Selected Item 5000** appears, its focus remains visible, and the example and its Code panel fit desktop and phone widths in both themes.
 - [ ] `DOCS-19` · **Open `/docs/components/time-field`, tab into the first example and set 17:45 with the keyboard only, then paste `9:30 pm` into the second field; repeat with VoiceOver** → each part is one tab stop with a visible focus highlight, the arrows wrap without carrying into the next part, typing `1` `7` moves on to the minutes, the pasted time replaces the whole value, the stored line under the fields follows, and VoiceOver reads the field's name and whole time, then each part's name and spoken value ("9 PM", "45 minutes").
 - [ ] `DOCS-20` · **At 320 px wide, open `/docs/components/recurrence-picker#schedule-with-times-of-day`, open the first schedule example and go to Custom interval; check Only between and set Until to 11:00 AM with the keyboard; go back, open Custom times, add a time and remove it; repeat with VoiceOver** → the popover stays inside the window with no sideways scroll; the views swap with a soft fade (none with reduced motion); with Every 15 minutes the sentence under the hours names the first and last start; a step of 6 hours between 8:00 and 11:00 turns it red and Save reads as unavailable with the same reason; the new time drops in with focus on its hour, and after Remove focus lands on the remaining row; VoiceOver reads each time as **Time 1**, **Time 2** with its whole time, and each remove button with the time it removes.
+- [ ] `DOCS-21` · **Open `/docs/components/code-editor` in light and dark: in Write templates, type `{{` at the end of Prompt and then `}`; in Show problems, press F8 three times, then go back to the misspelled `triag` and press ⌘. (Ctrl+.); in Complete names and show types, type `nodes.` in Code, then put the cursor on `total` and press ⌘K ⌘I (Ctrl+K Ctrl+I); repeat with VoiceOver** → each example highlights in the same colours as the Read-only code example, readable in both themes; `{{` becomes `{{  }}` with the caret inside and the list open, `}` steps over the closing braces, and each template reads as one tinted chip; F8 selects each problem in turn, opens its tooltip and VoiceOver reads it; ⌘. replaces `triag` with the suggested name; after `nodes.` the list offers `issues` and `score` with their types; ⌘K ⌘I shows the same type tooltip a pointer gets and VoiceOver reads it.
+- [ ] `DOCS-22` · **On `/docs/components/code-editor`, Tab into the Code field of Edit code in a form, press Tab, then Escape, then Tab; open Expand editor, move the caret, and return; at 375 px wide, repeat the first example with the on-screen keyboard** → after keyboard focus, a legend on the field's bottom edge shows the way out, and a click never shows it; the first Tab indents, Escape then Tab leaves the field for the next control; the expanded editor opens with the caret where it was and brings it back on return; at 375 px no example scrolls sideways, the text does not zoom the page, and selecting text with touch handles works.
+- [ ] `DOCS-23` · **Open `/docs/components/schema-tree` and `/docs/foundations/icons#show-a-vendors-own-icon` in light and dark, then at 375 px** → the Compact tree lists one line per top-level field and the Comfortable one nests the fields of objects and list items with their descriptions; each kind reads in words and "required" is said in words, not only by colour; the vendor icon shows the vendor's own mark, a neutral plug for WebDAV, which ships none, and the same plug for the icon that failed to load, never a broken image; nothing overflows at 375 px.
+- [ ] `DOCS-24` · **Open `/docs/components/workflow-canvas` in light and dark: watch Draw a workflow appear, press Save the next version twice and Go back a version once in Watch it change, turn on the route switch in Follow the lines, Tab into a chart and walk it with the arrow keys, Home and End, then switch to the list with Show as list; repeat at 375 px and with reduced motion** → each chart appears laid out top to bottom from Start to End, with no line through a box, a condition, a frame header or a label; a saved version glides to its new layout in about a third of a second, a new box grows in, nothing swaps sides with its row neighbour, and the changed boxes ring once; the route's points sit on the line's corners; the chart is one Tab stop whose arrows follow the lines and whose Home and End jump to Start and End, with a visible focus ring; the list says the same in text; at 375 px the canvas opens as a list and still offers its controls; with reduced motion every change simply appears, with no glide and no ring.
+- [ ] `DOCS-25` · **Open `/docs/components/workflow-paths#explore-the-paths` and `/docs/components/workflow-playback` in light and dark: point at each path, press Enter on one and Escape; point at a row under Ends the run when it fails; in Replay a run, press Play, drag the scrubber back, and press `[` and `]` on the bar; repeat at 375 px and with reduced motion** → pointing previews a path and Enter pins it: the boxes off the path turn dashed on a muted surface with their reason and full-contrast words, and Escape or Show all shows every path again; a halting row rings its nodes in red; in Show where a run ended the failed node is framed red with its error line and the way to it stands out; Play moves dots along the lines that dissolve into the box they reach, the approval wait shows as a hatched band on the scrubber, scrubbing back swaps the strips at once, and `[` and `]` step between events; at 375 px the bar folds its speed into a menu and nothing overflows; with reduced motion there are no dots and Play steps from event to event.

From 43b38ad22baa3afa137abb414cb7716f538e25fc Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 04:20:39 +0200
Subject: [PATCH 63/78] test(platform): follow a condition's branch from upload
 to run page

The new end-to-end spec uploads a document whose condition has an alternative, finds the condition above Escalate with Yes to Escalate and No to File, changes Score's Input in the inspector's code editor, saves v2, starts a test run and reads on the run page that the condition said No: the line to File is taken, File succeeded and Escalate was skipped. Upload and delete move into a shared helper the automations spec uses too; the e2e helper tables and the manual reference name them.
---
 services/platform/tests/e2e/AGENTS.md         |   1 +
 services/platform/tests/e2e/README.md         |   1 +
 .../platform/tests/e2e/helpers/automations.ts |  77 +++++++
 .../tests/e2e/specs/automation-canvas.spec.ts | 196 ++++++++++++++++++
 .../tests/e2e/specs/automations.spec.ts       |  58 +-----
 .../tests/manual/reference/automation.md      |   1 +
 6 files changed, 282 insertions(+), 52 deletions(-)
 create mode 100644 services/platform/tests/e2e/helpers/automations.ts
 create mode 100644 services/platform/tests/e2e/specs/automation-canvas.spec.ts

diff --git a/services/platform/tests/e2e/AGENTS.md b/services/platform/tests/e2e/AGENTS.md
index 0ff7292c36..82b9c140ee 100644
--- a/services/platform/tests/e2e/AGENTS.md
+++ b/services/platform/tests/e2e/AGENTS.md
@@ -43,6 +43,7 @@ When a manual case earns automation, bring it here under these rules.
 | [`helpers/fixtures.ts`](helpers/fixtures.ts) | the `org` fixture + extended `test`/`expect`                                                            |
 | [`helpers/auth.ts`](helpers/auth.ts)         | `signUpViaApi`, `signInViaApi`, `uniqueCredentials`, `createOrgViaWizard`, `waitForSeededOrg`           |
 | [`helpers/chat.ts`](helpers/chat.ts)         | `sendNewThreadMessage`, `waitForReplyComplete`, `expectCannedReply`, `deleteThreadById`, `fillComposer` |
+| [`helpers/automations.ts`](helpers/automations.ts) | `uploadAutomationDraft`, `deleteAutomationRow`                                                         |
 | [`helpers/forms.ts`](helpers/forms.ts)       | `reloadAndSettle`                                                                                       |
 | [`helpers/totp.ts`](helpers/totp.ts)         | RFC-6238 codes for the 2FA flow                                                                         |
 | [`helpers/seed.ts`](helpers/seed.ts)         | backend-seeded starter-content names (the "Getting started" project)                                    |
diff --git a/services/platform/tests/e2e/README.md b/services/platform/tests/e2e/README.md
index 40a478614b..03d8504065 100644
--- a/services/platform/tests/e2e/README.md
+++ b/services/platform/tests/e2e/README.md
@@ -85,6 +85,7 @@ mock README for the boundary between fixture responses and real integration cove
 | Helper | Purpose |
 | --- | --- |
 | [`helpers/auth.ts`](helpers/auth.ts) | Sign up, sign in, drive the organization wizard, and wait for seeded state |
+| [`helpers/automations.ts`](helpers/automations.ts) | Upload a workflow document as a draft, and delete an automation from its list row |
 | [`helpers/env.ts`](helpers/env.ts) | Base URL, mock-mode detection, and named timeout budgets |
 | [`helpers/chat.ts`](helpers/chat.ts) | Fill the composer, create a thread, wait for reply completion, and clean up by ID |
 | [`helpers/forms.ts`](helpers/forms.ts) | Reload and wait for a stable form before checking persisted values |
diff --git a/services/platform/tests/e2e/helpers/automations.ts b/services/platform/tests/e2e/helpers/automations.ts
new file mode 100644
index 0000000000..2d780b46bf
--- /dev/null
+++ b/services/platform/tests/e2e/helpers/automations.ts
@@ -0,0 +1,77 @@
+import { expect, type Locator, type Page } from '@playwright/test';
+
+import { TIMEOUT } from './env';
+import { t } from './i18n';
+
+/**
+ * Upload one workflow document through the automation list's Create menu and
+ * keep it a draft: the upload dialog's deploy offer is declined, so nothing
+ * runs until a test says so. Ends on the list, with the success dialog gone.
+ */
+export async function uploadAutomationDraft(
+  page: Page,
+  organizationId: string,
+  workflowYml: string,
+): Promise<void> {
+  // The list toolbar's create menu — a dropdown of three lanes. Its trigger
+  // is the DataTable `addAction`, labelled with the Create verb every list
+  // page carries (`list.createButton`).
+  await page.goto(`/dashboard/${organizationId}/automations`);
+  const createButton = page
+    .getByRole('button', { name: t('automations.list.createButton') })
+    .first();
+  await expect(createButton).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
+  await createButton.click();
+  await page
+    .getByRole('menuitem', { name: t('automations.upload.trigger') })
+    .click();
+
+  // The drop zone's aria-label duplicates the field label, so target the
+  // file input directly rather than by accessible name.
+  const uploadDialog = page.getByRole('dialog', {
+    name: t('automations.upload.title'),
+  });
+  await expect(uploadDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await uploadDialog.locator('input[type="file"]').setInputFiles({
+    name: 'workflow.yml',
+    mimeType: 'application/yaml',
+    buffer: Buffer.from(workflowYml, 'utf8'),
+  });
+  await uploadDialog
+    .getByRole('button', { name: t('automations.upload.submit'), exact: true })
+    .click();
+
+  // Saved as a draft — the dialog re-titles itself and offers to deploy;
+  // decline so the upload stays a draft.
+  const successDialog = page.getByRole('dialog', {
+    name: t('automations.upload.successTitle'),
+  });
+  await expect(successDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await successDialog
+    .getByRole('button', { name: t('automations.upload.deployLater') })
+    .click();
+  await expect(successDialog).not.toBeVisible({ timeout: TIMEOUT.VISIBLE });
+}
+
+/**
+ * Delete the automation of a list row through its row menu and the named
+ * confirmation, and wait for the row to leave the list.
+ */
+export async function deleteAutomationRow(
+  page: Page,
+  row: Locator,
+): Promise<void> {
+  await expect(row).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await row.getByRole('button', { name: t('common.actions.openMenu') }).click();
+  await page
+    .getByRole('menuitem', { name: t('common.actions.delete') })
+    .click();
+  const deleteDialog = page.getByRole('dialog', {
+    name: t('automations.detail.delete.title'),
+  });
+  await expect(deleteDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await deleteDialog
+    .getByRole('button', { name: t('common.actions.delete'), exact: true })
+    .click();
+  await expect(row).not.toBeVisible({ timeout: TIMEOUT.VISIBLE });
+}
diff --git a/services/platform/tests/e2e/specs/automation-canvas.spec.ts b/services/platform/tests/e2e/specs/automation-canvas.spec.ts
new file mode 100644
index 0000000000..48e9528578
--- /dev/null
+++ b/services/platform/tests/e2e/specs/automation-canvas.spec.ts
@@ -0,0 +1,196 @@
+import type { Locator, Page } from '@playwright/test';
+
+import {
+  deleteAutomationRow,
+  uploadAutomationDraft,
+} from '../helpers/automations';
+import { TIMEOUT } from '../helpers/env';
+import { test, expect } from '../helpers/fixtures';
+import { labelStart } from '../helpers/forms';
+import { t } from '../helpers/i18n';
+
+/**
+ * The automation canvas end to end, over transforms only (no provider, no
+ * connector): upload a document whose condition has an alternative, read
+ * the condition and its Yes and No on the canvas, change a field in the
+ * inspector, save a version, test-run it, and find the branch the run took
+ * on the run page's canvas. The probe is deleted at the end, so the worker
+ * org leaves the spec as it entered.
+ */
+
+const PROBE_SLUG = 'canvas-branch-probe';
+
+// The manual plan's branch probe (`AUTO-F73`): Score's total decides between
+// Escalate (Yes) and its alternative File (No).
+const PROBE_WORKFLOW_YML = `name: ${PROBE_SLUG}
+description: E2E probe — a condition with an alternative, no connectors.
+nodes:
+  - id: score
+    type: transform
+    input: { total: 1200 }
+    code: 'return { total: input.total };'
+  - id: escalate
+    type: transform
+    when: '{{ nodes.score.output.total > 1000 }}'
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "escalate " + input.total };'
+  - id: file
+    type: transform
+    elseOf: escalate
+    input: { total: '{{ nodes.score.output.total }}' }
+    code: 'return { text: "file " + input.total };'
+output:
+  text: '{{ nodes.escalate.output?.text ?? nodes.file.output?.text }}'
+`;
+
+/** The input that turns the condition false, typed into Score's Input. */
+const SCORE_INPUT_BELOW = '{ "total": 50 }';
+
+/** The condition's id on the canvas: one per node with a `when`. */
+const GATE_ID = '__gate:escalate';
+
+function escapeRegExp(text: string): string {
+  return text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/** The automation's canvas once its layout has landed (busy until then). */
+function laidOutCanvas(page: Page): Locator {
+  return page
+    .getByRole('group', {
+      name: t('automations.canvas.ariaLabel'),
+      exact: true,
+    })
+    .and(page.locator('[aria-busy="false"]'));
+}
+
+/** A box on the canvas — a node, Start, End or a condition — by its id. */
+function flowNode(page: Page, id: string): Locator {
+  return page.locator(`[data-flow-node="${id}"]`);
+}
+
+/** The Yes or No label on the line from the condition to `target`. */
+function branchLabel(page: Page, target: string): Locator {
+  return page.locator(`[data-flow-edge-label="${GATE_ID}>${target}"]`);
+}
+
+test('draws a condition with Yes and No, saves a field edit and shows the branch a run took', async ({
+  page,
+  org,
+}) => {
+  const { organizationId } = org;
+  const automationRoute = `/dashboard/${organizationId}/automations/${PROBE_SLUG}`;
+
+  await uploadAutomationDraft(page, organizationId, PROBE_WORKFLOW_YML);
+  await page.goto(`${automationRoute}/editor`);
+  await expect(laidOutCanvas(page)).toBeVisible({
+    timeout: TIMEOUT.FIRST_PAINT,
+  });
+
+  // The condition stands above Escalate as a box of its own, named for the
+  // node it decides on; Yes leads to Escalate and No to its alternative.
+  const gateName = t('flow.gate.name')
+    .replace('{node}', 'Escalate')
+    .split('{condition}')[0];
+  await expect(flowNode(page, GATE_ID)).toHaveAccessibleName(
+    new RegExp(`^${escapeRegExp(gateName ?? '')}`),
+  );
+  await expect(branchLabel(page, 'escalate')).toHaveText(t('flow.branch.yes'));
+  await expect(branchLabel(page, 'file')).toHaveText(t('flow.branch.no'));
+
+  // Change Score's input in the inspector so the condition no longer holds.
+  // The field is a code editor: replace its whole text in one insert, the way
+  // a paste would, so no bracket is closed for us halfway.
+  await flowNode(page, 'score').click();
+  const input = page.getByRole('textbox', {
+    name: labelStart(t('automations.editor.fields.input')),
+  });
+  await expect(input).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await input.click();
+  await page.keyboard.press('ControlOrMeta+a');
+  await page.keyboard.insertText(SCORE_INPUT_BELOW);
+  await expect(input).toHaveText(SCORE_INPUT_BELOW);
+
+  // Save appends v2 and the editor shows it.
+  await page
+    .getByRole('button', { name: t('common.actions.save'), exact: true })
+    .filter({ visible: true })
+    .first()
+    .click();
+  const saveDialog = page.getByRole('dialog', {
+    name: t('automations.detail.saveDialog.title'),
+  });
+  await expect(saveDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await saveDialog
+    .getByRole('textbox', {
+      name: labelStart(t('automations.detail.saveMessageLabel')),
+    })
+    .fill('Score below the escalation threshold');
+  await saveDialog
+    .getByRole('button', {
+      name: t('automations.detail.saveVersion'),
+      exact: true,
+    })
+    .click();
+  await expect(saveDialog).not.toBeVisible({ timeout: TIMEOUT.PERSIST });
+  await expect(
+    page.getByRole('button', {
+      name: t('automations.detail.versionSelect'),
+      exact: true,
+    }),
+  ).toContainText(
+    t('automations.versions.versionLabel').replace('{version}', '2'),
+    {
+      timeout: TIMEOUT.PERSIST,
+    },
+  );
+
+  // The document declares no input, so Test run starts at once.
+  await page
+    .getByRole('button', { name: t('automations.detail.runMock'), exact: true })
+    .filter({ visible: true })
+    .first()
+    .click();
+
+  // The runs list does not refresh itself: reload until the run has settled.
+  const runsRoute = `${automationRoute}/runs`;
+  const succeeded = page.getByText(t('automations.runs.status.success'), {
+    exact: true,
+  });
+  await expect(async () => {
+    await page.goto(runsRoute);
+    await expect(succeeded.first()).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  }).toPass({ timeout: TIMEOUT.EXECUTION });
+  await page.locator('a[href*="/runs/"]').first().click();
+  await page.waitForURL(/\/runs\/[^/?#]+(?:[?#]|$)/, { timeout: TIMEOUT.NAV });
+
+  // The run page's canvas says how the condition decided: No, so the line
+  // to File is taken and the one to Escalate is not; File ran, Escalate was
+  // skipped.
+  await expect(laidOutCanvas(page)).toBeVisible({
+    timeout: TIMEOUT.FIRST_PAINT,
+  });
+  await expect(
+    flowNode(page, GATE_ID).locator('[data-slot="flow-gate-decision"]'),
+  ).toHaveText(t('flow.branch.no'), { timeout: TIMEOUT.VISIBLE });
+  await expect(branchLabel(page, 'file')).toHaveAttribute('data-taken', 'true');
+  await expect(branchLabel(page, 'escalate')).toHaveAttribute(
+    'data-taken',
+    'false',
+  );
+  await expect(flowNode(page, 'file')).toHaveAttribute(
+    'data-flow-state',
+    'succeeded',
+  );
+  await expect(flowNode(page, 'escalate')).toHaveAttribute(
+    'data-flow-state',
+    'skipped',
+  );
+
+  // Cleanup: the probe goes, with its versions; its finished run stays in
+  // the run history.
+  await page.goto(`/dashboard/${organizationId}/automations`);
+  await deleteAutomationRow(
+    page,
+    page.getByRole('row').filter({ hasText: PROBE_SLUG }).first(),
+  );
+});
diff --git a/services/platform/tests/e2e/specs/automations.spec.ts b/services/platform/tests/e2e/specs/automations.spec.ts
index e8951622e9..8439276e27 100644
--- a/services/platform/tests/e2e/specs/automations.spec.ts
+++ b/services/platform/tests/e2e/specs/automations.spec.ts
@@ -1,3 +1,7 @@
+import {
+  deleteAutomationRow,
+  uploadAutomationDraft,
+} from '../helpers/automations';
 import { TIMEOUT } from '../helpers/env';
 import { test, expect } from '../helpers/fixtures';
 import { t } from '../helpers/i18n';
@@ -32,43 +36,7 @@ test('uploads a package and switches automations from the breadcrumb leaf', asyn
 }) => {
   const { organizationId } = org;
 
-  // The list toolbar's create menu — a dropdown of three lanes. Its trigger
-  // is the DataTable `addAction`, labelled with the Create verb every list
-  // page carries (`list.createButton`).
-  await page.goto(`/dashboard/${organizationId}/automations`);
-  const createButton = page
-    .getByRole('button', { name: t('automations.list.createButton') })
-    .first();
-  await expect(createButton).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
-  await createButton.click();
-  await page
-    .getByRole('menuitem', { name: t('automations.upload.trigger') })
-    .click();
-
-  // Upload the probe. The drop zone's aria-label duplicates the field label,
-  // so target the file input directly rather than by accessible name.
-  const uploadDialog = page.getByRole('dialog', {
-    name: t('automations.upload.title'),
-  });
-  await expect(uploadDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
-  await uploadDialog.locator('input[type="file"]').setInputFiles({
-    name: 'workflow.yml',
-    mimeType: 'application/yaml',
-    buffer: Buffer.from(PROBE_WORKFLOW_YML, 'utf8'),
-  });
-  await uploadDialog
-    .getByRole('button', { name: t('automations.upload.submit'), exact: true })
-    .click();
-
-  // Saved as a draft — the dialog re-titles itself and offers to deploy;
-  // decline so the probe stays a draft.
-  const successDialog = page.getByRole('dialog', {
-    name: t('automations.upload.successTitle'),
-  });
-  await expect(successDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
-  await successDialog
-    .getByRole('button', { name: t('automations.upload.deployLater') })
-    .click();
+  await uploadAutomationDraft(page, organizationId, PROBE_WORKFLOW_YML);
 
   // The draft row appears (rows show the display name over the raw slug);
   // clicking it opens the org-level detail — the probe has no project bound.
@@ -160,19 +128,5 @@ test('uploads a package and switches automations from the breadcrumb leaf', asyn
     .first()
     .click();
   await page.waitForURL(/\/automations(?:[/?#]|$)/, { timeout: TIMEOUT.NAV });
-  await expect(probeRow).toBeVisible({ timeout: TIMEOUT.VISIBLE });
-  await probeRow
-    .getByRole('button', { name: t('common.actions.openMenu') })
-    .click();
-  await page
-    .getByRole('menuitem', { name: t('common.actions.delete') })
-    .click();
-  const deleteDialog = page.getByRole('dialog', {
-    name: t('automations.detail.delete.title'),
-  });
-  await expect(deleteDialog).toBeVisible({ timeout: TIMEOUT.VISIBLE });
-  await deleteDialog
-    .getByRole('button', { name: t('common.actions.delete'), exact: true })
-    .click();
-  await expect(probeRow).not.toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await deleteAutomationRow(page, probeRow);
 });
diff --git a/services/platform/tests/manual/reference/automation.md b/services/platform/tests/manual/reference/automation.md
index b478a4ae31..3105ad0674 100644
--- a/services/platform/tests/manual/reference/automation.md
+++ b/services/platform/tests/manual/reference/automation.md
@@ -572,6 +572,7 @@ Legend: ✅ fully automated · 🔶 partially automated · ⛔ manual-only (no s
 | [auth](../suites/auth.md) | `AUTH-F5`, `AUTH-F10`–`AUTH-F12`, `AUTH-F17`, `AUTH-B3`, `AUTH-B4` | ⛔ manual-only | — (fresh DB / WebAuthn / IdP / mid-session policy / TOTP / needs 2 orgs) |
 | [automations](../suites/automations.md) | `AUTO-F57` and the trail half of `AUTO-B12`: an automation opened inside a project starts its trail at the project — the project's name leads to the project, **Automations** to the project's Automations tab, the automation's name (on a run) to its editor; a project the read answers without (deleted, or out of reach) gives the organization's trail, whose **Automations** and back arrow lead to the organization's list, a read that failed leaves a **Projects** crumb, a loading one a skeleton; only the leaf is the current page, a long project or automation name truncates while the leaf keeps its room and shows whole in a tooltip on hover or focus (never over a name that fits), and the phone's back arrow returns to the project's Automations tab; the rail and the tab bar light **Automations** there, never **Home**, and no Home panel stands beside it | 🔶 Chromium + component | `app/features/automations/components/automation-breadcrumbs.browser.test.tsx`, `app/features/automations/components/automation-breadcrumbs.test.tsx`, `app/hooks/use-navigation-items.test.ts`, `app/features/home/lib/home-paths.test.ts`, `app/components/layout/mobile-bottom-nav.test.tsx`, `app/components/layout/app-sidebar/sidebar-nav.browser.test.tsx`; the pill's glide, the look of the truncation and the DE/FR read stay manual |
 | [automations](../suites/automations.md) | `AUTO-F1` (toolbar create), `AUTO-F1b`, `AUTO-F4` (org-level row), `AUTO-F8` (yml lane, Later), `AUTO-F12` (leaf switcher), `AUTO-F35` (tab strip walk) | 🔶 partial | `automations.spec.ts` (upload → detail tabs + switcher → delete) |
+| [automations](../suites/automations.md) | The end-to-end half of `AUTO-F73`, on the branch probe: after an upload, the condition stands above Escalate and is named for it, **Yes** leads to Escalate and **No** to File; an edit of Score's **Input** in the inspector saves v2; after a **Test run** of v2, the run page's condition says **No**, the line to File is taken and the one to Escalate is not, File succeeded and Escalate was skipped | 🔶 partial | `automation-canvas.spec.ts` (upload → condition and branches → field edit → save → test run → the branch on the run page → delete); the layout, the dashed borders and the condition's words stay manual |
 | [automations](../suites/automations.md) | The leaf switcher keeps all automations after project navigation, lists organization automations above a separator and project-specific ones below, searches across both groups, routes each selection to its bound project or the organization, and resets the editor's version and draft when the automation changes | ✅ automated | `app/features/automations/components/automation-breadcrumb-switcher.browser.test.tsx` (real Chromium navigation and grouping), `automation-breadcrumb-switcher.test.tsx` (project binding destinations), `automation-editor.test.tsx` (editor identity reset), `app/components/ui/forms/searchable-select.test.tsx` (group filtering and keyboard navigation) |
 | [automations](../suites/automations.md) | `AUTO-F12` workbench layout: at phone width the canvas fills the available height at every point — before selection and after — with editor actions inside it never overlapping zoom or navigation; picking a node opens its fields (and Save/Discard) in a sheet over the canvas instead of stacking below it, and the canvas never grows or scrolls under that sheet; at desktop width the canvas and inspector split into columns and fill the tab without scrolling the page | ✅ automated | `app/features/automations/components/automation-editor.browser.test.tsx` (real Chromium layout at 390×844 and 1280×800; tablet node dialogs keep one localized close control in EN/DE/FR; compact automation navigation is covered by `app/components/layout/mobile-bottom-nav.test.tsx`) |
 | [automations](../suites/automations.md) | `AUTO-F37` (the Editor runs edge to edge): at desktop width the canvas starts under the tab strip at the page's left edge with no border of its own, the inspector ends at the page's right and bottom edges, and the two meet at the inspector's border with no gutter | ✅ automated | `app/features/automations/components/automation-editor.browser.test.tsx` (real Chromium layout at 1280×800, measured against the page's content box) |

From 28b611456138ba48c99f074092eb4e8dd21d61c3 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 04:21:42 +0200
Subject: [PATCH 64/78] test(platform): photograph the canvas, paths, code
 fields and Source

The screenshot manifest gains the Editor's paths list with Path 2 pinned, completion open in a Prompt, a node's Shape tab, Start's inspector, the Source view, the Editor at phone width, and a failed test run's failure focus. The seeder uploads a small invoice digest, transforms only, and starts one test run that fails at Totals for that last shot.

The canvas, Problems and run-input shots wait for the laid-out canvas, the settled check and the loaded code editor, so their retakes show Start, End, the condition and the code palette. These three are also the only existing shots with highlighted code; the endpoint, device and MCP snippets use the plain code block, whose colours did not change. Capture is left to a docs-shot round, which embeds each new image in the editor and execution-log guides.
---
 .../tests/docs-screenshots/demo-content.ts    |  47 ++++
 .../tests/docs-screenshots/manifest.ts        | 262 ++++++++++++++++--
 .../tests/docs-screenshots/seed-demo-org.ts   |  45 +++
 3 files changed, 325 insertions(+), 29 deletions(-)

diff --git a/services/platform/tests/docs-screenshots/demo-content.ts b/services/platform/tests/docs-screenshots/demo-content.ts
index 471dd5effe..558305a1fe 100644
--- a/services/platform/tests/docs-screenshots/demo-content.ts
+++ b/services/platform/tests/docs-screenshots/demo-content.ts
@@ -520,6 +520,53 @@ export const DEMO_TEST_RUN = {
   input: { owner: 'tale-project', repo: 'tale' },
 } as const;
 
+/**
+ * The failed run the docs show (the run page's failure focus): a TEST run of
+ * a small demo automation, uploaded as a draft, that stops at Totals because
+ * one of the week's invoices carries no amount. Transforms only — no
+ * connector, model or secret — so it fails the same way on every stack.
+ * Its name stays clear of "triage", which the catalog shot searches for.
+ */
+export const DEMO_FAILED_RUN = {
+  automation: 'invoice-digest',
+  failsAt: 'totals',
+  workflow: `name: invoice-digest
+description: Sum the week's open invoices per customer and write the digest.
+nodes:
+  - id: invoices
+    type: transform
+    code: |
+      return {
+        invoices: [
+          { customer: 'Atelier Lumen', amount: 1200 },
+          { customer: 'Northwind', amount: 860 },
+          { customer: 'Globex', amount: null },
+        ],
+      };
+  - id: totals
+    type: transform
+    input:
+      invoices: '{{ nodes.invoices.output.invoices }}'
+    code: |
+      const totals = {};
+      for (const invoice of input.invoices) {
+        if (typeof invoice.amount !== 'number') {
+          throw new Error('The invoice for ' + invoice.customer + ' has no amount');
+        }
+        totals[invoice.customer] = (totals[invoice.customer] ?? 0) + invoice.amount;
+      }
+      return { totals };
+  - id: digest
+    type: transform
+    input:
+      totals: '{{ nodes.totals.output.totals }}'
+    code: |
+      const lines = Object.entries(input.totals).map(([customer, amount]) => customer + ': ' + amount);
+      return { text: lines.join('\\n') };
+output: '{{ nodes.digest.output }}'
+`,
+} as const;
+
 export const DEMO_PROVIDER_CREDENTIAL = 'Production key';
 export const MOCK_PROVIDER_DISPLAY_NAME = 'E2E Mock Gateway';
 /** The mock provider's slug — the `name` in `docs-demo/providers/e2e-mock.yml`. */
diff --git a/services/platform/tests/docs-screenshots/manifest.ts b/services/platform/tests/docs-screenshots/manifest.ts
index a016ebe651..d38e7e9959 100644
--- a/services/platform/tests/docs-screenshots/manifest.ts
+++ b/services/platform/tests/docs-screenshots/manifest.ts
@@ -30,6 +30,7 @@ import {
   DEMO_DATA_NOTICE,
   DEMO_DOCUMENTS,
   DEMO_EMPTY_DOCUMENT,
+  DEMO_FAILED_RUN,
   DEMO_INBOX,
   DEMO_KNOWLEDGE_ENTRIES,
   DEMO_ORG_NAME,
@@ -391,6 +392,65 @@ async function showTriageAutomationExamples(page: Page): Promise<void> {
   await expect(page.getByRole('row')).toHaveCount(5);
 }
 
+/** The Editor's canvas once its layout has landed: the chart is busy while
+ * the layout engine arranges the nodes. */
+const laidOutAutomationCanvas = (page: Page): Locator =>
+  page
+    .getByRole('group', {
+      name: t('automations.canvas.ariaLabel'),
+      exact: true,
+    })
+    .and(page.locator('[aria-busy="false"]'));
+
+/** The node box (or Start, End, or a condition) with this id on the canvas. */
+const flowNode = (page: Page, id: string): Locator =>
+  page.locator(`[data-flow-node="${id}"]`);
+
+/**
+ * Wait until an automation's Editor can be photographed: the saved version
+ * on screen, its canvas laid out, and the check of the draft settled — the
+ * Problems button no longer says it is checking.
+ */
+async function settleAutomationEditor(page: Page): Promise<void> {
+  await expect(
+    page.getByRole('button', {
+      name: t('automations.detail.versionSelect'),
+      exact: true,
+    }),
+  ).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
+  await expect(laidOutAutomationCanvas(page)).toBeVisible({
+    timeout: TIMEOUT.FIRST_PAINT,
+  });
+  const problems = page
+    .locator('[data-slot="issue-count-button"]')
+    .filter({ visible: true })
+    .first();
+  await expect(problems).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  await expect(problems).not.toHaveAccessibleName(
+    new RegExp(escapeRegExp(t('issues.checking'))),
+    { timeout: TIMEOUT.FIRST_PAINT },
+  );
+}
+
+/** Open a node's inspector from its box on the canvas. */
+async function openAutomationNode(page: Page, id: string): Promise<void> {
+  const box = flowNode(page, id);
+  await box.waitFor({ timeout: TIMEOUT.VISIBLE });
+  await box.click();
+}
+
+/**
+ * A plural message such as `{count, plural, one {# path} other {# paths}}`
+ * as a pattern for any count. The e2e `t()` returns the raw message, and a
+ * button that counts is found by its words, whatever the number.
+ */
+function pluralPattern(message: string): RegExp {
+  const forms = [...message.matchAll(/\{([^{}]*)\}/g)].map((match) =>
+    escapeRegExp(match[1] ?? '').replaceAll('#', String.raw`\d+`),
+  );
+  return new RegExp(`^(?:${forms.join('|')})$`);
+}
+
 export const SHOTS: readonly Shot[] = [
   {
     // The flagship hero: a finished, believable chat conversation.
@@ -1364,8 +1424,11 @@ export const SHOTS: readonly Shot[] = [
       page.getByRole('heading', { name: t('automations.upload.title') }),
   },
   {
-    // The Editor tab — the saved version's step graph on the canvas with the
-    // node inspector beside it and the version/run actions in the tab strip.
+    // The Editor tab — the saved version laid out between Start (the
+    // schedule in words, the run input's fields) and End: the condition in
+    // words above Triage, the Continues on error chip on Propose, the frames
+    // of the nodes that run once per item, and the node inspector beside the
+    // canvas with the version and run actions in the tab strip.
     name: 'automation-editor-canvas',
     section: 'platform',
     // A pack's automation is NAMED after its path with the separator
@@ -1384,23 +1447,18 @@ export const SHOTS: readonly Shot[] = [
           exact: true,
         }),
       ).toHaveAttribute('aria-current', 'page');
-      await expect(
-        page.getByRole('button', {
-          name: t('automations.detail.versionSelect'),
-          exact: true,
-        }),
-      ).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
-      const triageStep = page.locator('[data-flow-node="triage"]');
-      await triageStep.waitFor({ timeout: 30_000 });
-      await triageStep.click();
+      await settleAutomationEditor(page);
+      await openAutomationNode(page, 'triage');
     },
     // The inspector renders the selected node's Input field only once the
-    // node-type catalog has answered — gate on it so the panel is never
-    // captured mid-load.
+    // node-type catalog has answered, and the field is a code editor that
+    // loads on first use — gate on the loaded editor so the panel is never
+    // captured mid-load. (Start's face also reads "Input", as plain text.)
     readyWhen: (page) =>
-      page
-        .getByText(t('automations.editor.fields.input'), { exact: true })
-        .first(),
+      page.getByRole('textbox', {
+        name: t('automations.editor.fields.input'),
+        exact: true,
+      }),
   },
   {
     // The Editor's Problems list under the canvas: a draft whose triage
@@ -1411,21 +1469,17 @@ export const SHOTS: readonly Shot[] = [
     section: 'platform',
     route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
     prepare: async (page) => {
-      await expect(
-        page.getByRole('button', {
-          name: t('automations.detail.versionSelect'),
-          exact: true,
-        }),
-      ).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
-      const triageStep = page.locator('[data-flow-node="triage"]');
-      await triageStep.waitFor({ timeout: 30_000 });
-      await triageStep.click();
+      await settleAutomationEditor(page);
+      await openAutomationNode(page, 'triage');
       const prompt = page.getByRole('textbox', {
         name: t('automations.editor.fields.prompt'),
         exact: true,
       });
       await prompt.click();
       await prompt.press('ControlOrMeta+End');
+      // The Prompt is a code editor: `{{` closes itself with the caret
+      // inside, and the final `}}` steps over the closing braces, so the
+      // typed text ends as one template.
       await prompt.pressSequentially(' {{ nodes.nope.output }}');
       // The button's name opens with the panel's title ("Problems: 1 error")
       // once the check of the draft has settled.
@@ -1445,6 +1499,140 @@ export const SHOTS: readonly Shot[] = [
         .getByRole('listitem')
         .first(),
   },
+  {
+    // Possible paths open beside the canvas with Path 2 pinned: the nodes
+    // off that path dashed with the reason they don't run, End marking the
+    // outputs that stay empty on it, and the nodes whose failure ends the
+    // run listed under the paths.
+    name: 'automation-editor-paths',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: async (page) => {
+      await settleAutomationEditor(page);
+      // The button counts the paths ("3 paths"); find it by its words.
+      await page
+        .getByRole('button', {
+          name: pluralPattern(t('automations.paths.button')),
+        })
+        .click();
+      await page.locator('[data-flow-path-row="path:2"]').click();
+    },
+    readyWhen: (page) =>
+      page.locator('[data-flow-path-row="path:2"][aria-pressed="true"]'),
+  },
+  {
+    // A Prompt in the code editor: `{{` typed on its last line became a
+    // template with the caret inside, and after `nodes.` the completion
+    // list offers the nodes that run earlier, with their shapes.
+    name: 'automation-editor-code',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: async (page) => {
+      await settleAutomationEditor(page);
+      await openAutomationNode(page, 'triage');
+      const prompt = page.getByRole('textbox', {
+        name: t('automations.editor.fields.prompt'),
+        exact: true,
+      });
+      await prompt.click();
+      // The prompt ends with a line break, so its end is an empty line.
+      await prompt.press('ControlOrMeta+End');
+      await prompt.pressSequentially('{{nodes.');
+    },
+    // Inbox is the one node that runs before Triage.
+    readyWhen: (page) =>
+      page
+        .getByRole('listbox')
+        .getByRole('option')
+        .filter({ hasText: 'inbox' })
+        .first(),
+  },
+  {
+    // A node's Shape tab: what Triage receives and returns, where the
+    // returned shape comes from (its output schema), and the nodes that read
+    // it. The shapes come from the check of the draft.
+    name: 'automation-editor-node-shape',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: async (page) => {
+      await settleAutomationEditor(page);
+      await openAutomationNode(page, 'triage');
+      await page
+        .getByRole('tab', {
+          name: t('automations.editor.inspector.tabs.shape'),
+          exact: true,
+        })
+        .click();
+      await expect(
+        page.getByText(t('automations.editor.shape.checking'), {
+          exact: true,
+        }),
+      ).toHaveCount(0, { timeout: TIMEOUT.FIRST_PAINT });
+    },
+    readyWhen: (page) =>
+      page.getByRole('heading', {
+        name: t('automations.editor.shape.returns'),
+        exact: true,
+      }),
+  },
+  {
+    // Start's inspector: the trigger in words with Change in General, the
+    // run input's fields as a tree, and the JSON Schema behind them in the
+    // code editor.
+    name: 'automation-editor-start',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: async (page) => {
+      await settleAutomationEditor(page);
+      await openAutomationNode(page, '__start');
+      await expect(
+        page.getByRole('link', {
+          name: t('automations.editor.start.editTrigger'),
+          exact: true,
+        }),
+      ).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+    },
+    // Start's schema field carries the run dialog's "Input schema" label.
+    readyWhen: (page) =>
+      page.getByRole('textbox', {
+        name: t('automations.detail.runInput.schema'),
+        exact: true,
+      }),
+  },
+  {
+    // The Source view: the whole document as highlighted YAML with line
+    // numbers and fold markers, Copy YAML and Download YAML, and the line
+    // saying how to change it.
+    name: 'automation-editor-source',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: async (page) => {
+      await settleAutomationEditor(page);
+      await page
+        .getByRole('radio', {
+          name: t('automations.canvas.view.source'),
+          exact: true,
+        })
+        .click();
+    },
+    // The source is a read-only code editor that loads on first use.
+    readyWhen: (page) =>
+      page.getByRole('textbox', {
+        name: t('automations.source.ariaLabel'),
+        exact: true,
+      }),
+  },
+  {
+    // The Editor on a phone: compact navigation, the canvas filling the
+    // height between Start and End, and the run and save controls in the
+    // toolbar at its foot.
+    name: 'automation-editor-canvas-mobile',
+    section: 'platform',
+    route: '/dashboard/:orgId/automations/gmail-triage-inbox/editor',
+    prepare: settleAutomationEditor,
+    readyWhen: (page) => laidOutAutomationCanvas(page),
+    viewport: { width: 390, height: 844 },
+  },
   {
     // An automation's General tab — its trigger (the pack's schedule: cron,
     // timezone, enabled) above the projects it is bound to. The form paints
@@ -1469,6 +1657,8 @@ export const SHOTS: readonly Shot[] = [
     viewport: { width: 1440, height: 640 },
   },
   {
+    // The Test run dialog: the run input as JSON in the code editor, and the
+    // input schema expanded as a tree of fields with their kinds.
     name: 'automation-run-input',
     section: 'platform',
     route: `/dashboard/:orgId/automations/${DEMO_TEST_RUN.automation}/editor`,
@@ -1520,7 +1710,7 @@ export const SHOTS: readonly Shot[] = [
     // tab as a reader does: status, mode, version, starter and timing above
     // the workflow with every node's result; the effects list starts below
     // the fold (the canvas grows with the window). The canvas draws its
-    // boxes before the trace arrives — gate on the last node's result badge.
+    // boxes before the trace arrives — gate on the last node's run state.
     name: 'automation-run-detail',
     section: 'platform',
     route: `/dashboard/:orgId/automations/${DEMO_TEST_RUN.automation}/runs`,
@@ -1528,9 +1718,23 @@ export const SHOTS: readonly Shot[] = [
       await page.locator('a[href*="/runs/"]').first().click();
     },
     readyWhen: (page) =>
-      page
-        .locator('[data-flow-node="report"]')
-        .getByText(t('automations.runs.nodeStatus.ok'), { exact: true }),
+      page.locator('[data-flow-node="report"][data-flow-state="succeeded"]'),
+  },
+  {
+    // The seeded failed test run of the invoice digest: the node that failed
+    // in view, framed red with its error line, the way the run took to it
+    // brought forward while the rest steps back, and End saying where the
+    // run failed.
+    name: 'automation-run-failed',
+    section: 'platform',
+    route: `/dashboard/:orgId/automations/${DEMO_FAILED_RUN.automation}/runs`,
+    prepare: async (page) => {
+      await page.locator('a[href*="/runs/"]').first().click();
+    },
+    readyWhen: (page) =>
+      page.locator(
+        `[data-flow-node="${DEMO_FAILED_RUN.failsAt}"][data-flow-state="failed"]`,
+      ),
   },
   {
     // Settings > Connectors with Add credential open on its first step — the
diff --git a/services/platform/tests/docs-screenshots/seed-demo-org.ts b/services/platform/tests/docs-screenshots/seed-demo-org.ts
index 2f40f12b84..995f585b22 100644
--- a/services/platform/tests/docs-screenshots/seed-demo-org.ts
+++ b/services/platform/tests/docs-screenshots/seed-demo-org.ts
@@ -17,6 +17,7 @@ import { expect, type Locator, type Page } from '@playwright/test';
 
 import { matchDocsReply } from '../../lib/mocks/overrides/docs-replies';
 import { E2E_PASSWORD } from '../e2e/helpers/auth';
+import { uploadAutomationDraft } from '../e2e/helpers/automations';
 import {
   deleteThreadById,
   messageLog,
@@ -33,6 +34,7 @@ import {
   DEMO_DEPARTING_MEMBER,
   DEMO_DOCUMENTS,
   DEMO_EMPTY_DOCUMENT,
+  DEMO_FAILED_RUN,
   DEMO_INBOX,
   DEMO_INBOX_KEY_NAME,
   DEMO_INBOX_SOURCE,
@@ -1559,6 +1561,46 @@ async function ensureAutomationTestRun(
   }).toPass({ timeout: TIMEOUT.EXECUTION });
 }
 
+/**
+ * One failed test run of the demo invoice digest, so the failed-run shot
+ * shows the run page's failure focus. The digest is uploaded as a draft
+ * through the list's Create menu, then started with Test run like a reader
+ * would; it declares no input, so the run starts without a dialog.
+ * Idempotent — any run of it is enough, and an earlier upload is reused.
+ */
+async function ensureAutomationFailedRun(
+  page: Page,
+  orgId: string,
+): Promise<void> {
+  const automationRoute = `/dashboard/${orgId}/automations/${DEMO_FAILED_RUN.automation}`;
+  const runsRoute = `${automationRoute}/runs`;
+  const runRow = page.locator(`a[href*="/runs/"]`);
+  await page.goto(runsRoute);
+  if (await alreadySeeded(runRow)) return;
+
+  const versionSelect = page.getByRole('button', {
+    name: t('automations.detail.versionSelect'),
+    exact: true,
+  });
+  await page.goto(`${automationRoute}/editor`);
+  if (!(await alreadySeeded(versionSelect))) {
+    await uploadAutomationDraft(page, orgId, DEMO_FAILED_RUN.workflow);
+    await page.goto(`${automationRoute}/editor`);
+  }
+  await expect(versionSelect).toBeVisible({ timeout: TIMEOUT.FIRST_PAINT });
+  await page
+    .getByRole('button', { name: t('automations.detail.runMock'), exact: true })
+    .click();
+
+  const failed = page.getByText(t('automations.runs.status.failed'), {
+    exact: true,
+  });
+  await expect(async () => {
+    await page.goto(runsRoute);
+    await expect(failed.first()).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+  }).toPass({ timeout: TIMEOUT.EXECUTION });
+}
+
 export function webdavPasswordRow(page: Page, label: string): Locator {
   return page.getByRole('row').filter({
     has: page.getByText(label, { exact: true }),
@@ -1848,6 +1890,9 @@ export async function seedDemoOrg(
   await step('products', () => ensureProducts(page, orgId));
   await step('tavily connector', () => ensureTavilyConnector(page, orgId));
   await step('automation test run', () => ensureAutomationTestRun(page, orgId));
+  await step('automation failed run', () =>
+    ensureAutomationFailedRun(page, orgId),
+  );
 
   // The settings surfaces that otherwise screenshot as bare empty states.
   await step('API keys', () => ensureApiKeys(page, orgId));

From c54e06131b8762500601295d8a8c6f9446667b77 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 04:24:23 +0200
Subject: [PATCH 65/78] docs: keep a no-break space before a colon in the
 French concepts page

---
 docs/fr/platform/automations/concepts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/fr/platform/automations/concepts.md b/docs/fr/platform/automations/concepts.md
index 36514cede2..7135cec5ac 100644
--- a/docs/fr/platform/automations/concepts.md
+++ b/docs/fr/platform/automations/concepts.md
@@ -46,7 +46,7 @@ Tale dispose le canevas à partir des références entre les nœuds : personne
 
 ### Les liaisons se déduisent, elles ne se déclarent pas
 
-Il n’y a pas de liste de liaisons. Un nœud en lit un autre en le référençant — `{{ nodes.invoice.output.id }}` — et cette référence _est_ la liaison que trace le canevas. L’ordre d’exécution est un tri topologique sur ces liaisons déduites : supprimer une référence retire donc aussi un trait, et deux nœuds qui se lisent l’un l’autre sont refusés comme une boucle.
+Il n’y a pas de liste de liaisons. Un nœud en lit un autre en le référençant — `{{ nodes.invoice.output.id }}` — et cette référence _est_ la liaison que trace le canevas. L’ordre d’exécution est un tri topologique sur ces liaisons déduites : supprimer une référence retire donc aussi un trait, et deux nœuds qui se lisent l’un l’autre sont refusés comme une boucle.
 
 Les templates utilisent une seule grammaire `{{ }}` d’expressions JavaScript sur `input`, `nodes.<id>.output` et, à l’intérieur d’un nœud qui itère, `item` et `index`.
 

From 0c07f2bb0a612bd920bfa67279defed86f3875e3 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 07:28:28 +0200
Subject: [PATCH 66/78] fix(ui): give Start and End the accent and canvas
 targets 44 px

Start and End take the accent tile in both themes, dashed borders keep 3:1 against the card at half zoom, every corner control keeps a 44 px target under a coarse pointer, and pulses dissolve into the box they reach. The chart, its List view and its legend share one chrome module.
---
 .../ui/src/components/flow/flow-canvas.tsx    |  56 ++-
 .../ui/src/components/flow/flow-legend.tsx    |  12 +-
 .../ui/src/components/flow/flow-step-list.tsx |  14 +-
 .../flow/motion/flow-motion.test.ts           |  33 +-
 .../src/components/flow/motion/flow-motion.ts |  20 +-
 .../ui/src/components/flow/render/chrome.ts   |  30 ++
 .../src/components/flow/render/entry-node.tsx |   5 +-
 .../src/components/flow/render/exit-node.tsx  |   1 +
 .../flow/render/flow-render-context.tsx       |  14 +-
 .../components/flow/render/pulse-layer.tsx    |  30 +-
 .../src/components/flow/render/step-node.tsx  |  14 +-
 .../workflow-canvas.look.browser.test.tsx     | 363 ++++++++++++++++++
 .../workflow-canvas.motion.browser.test.tsx   |   6 +-
 .../flow/workflow-canvas.run.browser.test.tsx |  52 ++-
 .../src/components/flow/workflow-canvas.tsx   |   7 +-
 packages/ui/src/globals.css                   |  29 +-
 16 files changed, 627 insertions(+), 59 deletions(-)
 create mode 100644 packages/ui/src/components/flow/render/chrome.ts
 create mode 100644 packages/ui/src/components/flow/workflow-canvas.look.browser.test.tsx

diff --git a/packages/ui/src/components/flow/flow-canvas.tsx b/packages/ui/src/components/flow/flow-canvas.tsx
index 8e314eea63..034f72b480 100644
--- a/packages/ui/src/components/flow/flow-canvas.tsx
+++ b/packages/ui/src/components/flow/flow-canvas.tsx
@@ -29,6 +29,9 @@ import {
 } from 'react';
 
 import { usePrefersReducedMotion } from '../../hooks/use-prefers-reduced-motion';
+import { FLOW_TOUCH_TARGET } from './render/chrome';
+
+export { FLOW_TOUCH_TARGET };
 
 /** The `--ease-out-quint` curve, for viewport moves run from script. */
 export const easeOutQuint = (t: number) => 1 - (1 - t) ** 5;
@@ -48,6 +51,10 @@ export type FlowFitPolicy = 'all' | 'auto';
 const READABLE_ZOOM = 0.5;
 /** Room an `auto` fit leaves above the graph's top. */
 const TOP_MARGIN = 24;
+/** Room the top corners' controls take — the panels' 15 px inset, a 36 px
+ *  control and a 12 px gap, on the 4-px grid: a fit never puts the first
+ *  box under a view switch or a toolbar. */
+const TOP_CONTROLS_INSET = 64;
 
 /**
  * The ONE base React Flow canvas every graph editor in the app builds on
@@ -103,8 +110,14 @@ const sameView = (a: Viewport, b: Viewport) =>
   Math.abs(a.y - b.y) < 0.5 &&
   Math.abs(a.zoom - b.zoom) < 0.001;
 
-/** Fit by the policy, then remember where the fit left the view. */
-function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
+/** Fit by the policy, then remember where the fit left the view. With
+ *  `topInset`, the fit keeps the graph's top at least that far below the
+ *  canvas's top edge. */
+function useFitAndRemember(
+  memo: FitMemo,
+  policy: FlowFitPolicy,
+  topInset: number,
+) {
   const { fitView, getViewport, setViewport, getNodes, getNodesBounds } =
     useReactFlow();
   const store = useStoreApi();
@@ -116,17 +129,28 @@ function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
       const { width, height } = store.getState();
       const minZoom = options?.minZoom ?? store.getState().minZoom;
       const nodes = getNodes();
+      const padding =
+        typeof options?.padding === 'number' ? options.padding : 0.1;
+      // React Flow reads a bare number as a share of each side; the top
+      // takes whichever is more, that share or the controls' room.
+      const fitPadding =
+        topInset > 0 && height > 0
+          ? {
+              top: `${Math.max(topInset, Math.floor((height - height / (1 + padding)) * 0.5))}px` as const,
+              right: padding,
+              bottom: padding,
+              left: padding,
+            }
+          : padding;
       if (policy === 'auto' && nodes.length > 0 && width > 0 && height > 0) {
         const bounds = getNodesBounds(nodes);
-        const padding =
-          typeof options?.padding === 'number' ? options.padding : 0.1;
         const whole = getViewportForBounds(
           bounds,
           width,
           height,
           0,
           Number.POSITIVE_INFINITY,
-          padding,
+          fitPadding,
         );
         if (whole.zoom < READABLE_ZOOM) {
           // Too big to read whole: show its top at a readable zoom, centred
@@ -150,7 +174,7 @@ function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
           await setViewport(
             {
               x: width / 2 - centreX * zoom,
-              y: TOP_MARGIN - bounds.y * zoom,
+              y: Math.max(TOP_MARGIN, topInset) - bounds.y * zoom,
               zoom,
             },
             { duration, ease: easeOutQuint, interpolate: 'linear' },
@@ -161,6 +185,7 @@ function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
       }
       await fitView({
         ...options,
+        padding: fitPadding,
         duration,
         ease: easeOutQuint,
         interpolate: 'linear',
@@ -170,6 +195,7 @@ function useFitAndRemember(memo: FitMemo, policy: FlowFitPolicy) {
     [
       memo,
       policy,
+      topInset,
       reduced,
       store,
       fitView,
@@ -197,17 +223,19 @@ function FlowAutoFit({
   memo,
   fitViewOptions,
   policy,
+  topInset,
   fitKey,
   refitDuration = 0,
 }: {
   memo: FitMemo;
   fitViewOptions?: FitViewOptions;
   policy: FlowFitPolicy;
+  topInset: number;
   fitKey: unknown;
   refitDuration?: number;
 }) {
   const { getViewport, getNodes, getNodesBounds } = useReactFlow();
-  const fitAndRemember = useFitAndRemember(memo, policy);
+  const fitAndRemember = useFitAndRemember(memo, policy, topInset);
   const minZoom = useStore((state) => state.minZoom);
   const width = useStore((state) => state.width);
   const height = useStore((state) => state.height);
@@ -269,18 +297,20 @@ function FlowAutoFit({
 function FlowCornerControls({
   memo,
   policy,
+  topInset,
   fitViewOptions,
   children,
 }: {
   memo: FitMemo;
   policy: FlowFitPolicy;
+  topInset: number;
   fitViewOptions?: FitViewOptions;
   children?: ReactNode;
 }) {
   const { t } = useT('common');
   const { zoomIn, zoomOut } = useReactFlow();
   const reduced = usePrefersReducedMotion();
-  const fitAndRemember = useFitAndRemember(memo, policy);
+  const fitAndRemember = useFitAndRemember(memo, policy, topInset);
   const zoom = {
     duration: reduced ? 0 : FLOW_VIEWPORT_DURATION.zoom,
     ease: easeOutQuint,
@@ -288,11 +318,12 @@ function FlowCornerControls({
   return (
     <Panel
       position="bottom-left"
-      className="mb-[max(1rem,var(--mobile-nav-clearance-live,0px))]! flex flex-col gap-1"
+      className="mb-[max(1rem,var(--mobile-nav-clearance-live,0px))]! flex flex-col gap-1 pointer-coarse:gap-2"
     >
       <Button
         size="icon"
         variant="secondary"
+        className={FLOW_TOUCH_TARGET}
         title={t('flow.zoomIn')}
         tooltipSide="right"
         onClick={() => void zoomIn(zoom)}
@@ -302,6 +333,7 @@ function FlowCornerControls({
       <Button
         size="icon"
         variant="secondary"
+        className={FLOW_TOUCH_TARGET}
         title={t('flow.zoomOut')}
         tooltipSide="right"
         onClick={() => void zoomOut(zoom)}
@@ -311,6 +343,7 @@ function FlowCornerControls({
       <Button
         size="icon"
         variant="secondary"
+        className={FLOW_TOUCH_TARGET}
         title={t('flow.resetView')}
         tooltipSide="right"
         onClick={() =>
@@ -364,6 +397,7 @@ export function FlowCanvas({
   // The `auto` fit is the canvas's own: React Flow's built-in fit would show
   // a tall graph whole at an unreadable zoom first.
   const builtInFit = fitPolicy === 'all' && flowProps.fitView !== false;
+  const topInset = topStartActions || topEndActions ? TOP_CONTROLS_INSET : 0;
   return (
     <ReactFlow
       colorMode={resolvedTheme}
@@ -377,12 +411,13 @@ export function FlowCanvas({
           memo={fitMemo}
           fitViewOptions={flowProps.fitViewOptions}
           policy={fitPolicy}
+          topInset={topInset}
           fitKey={fitKey}
           refitDuration={refitDuration}
         />
       )}
       {topStartActions && (
-        <Panel position="top-left" className="flex items-center gap-1">
+        <Panel position="top-left" className="flex items-start gap-1">
           {topStartActions}
         </Panel>
       )}
@@ -394,6 +429,7 @@ export function FlowCanvas({
       <FlowCornerControls
         memo={fitMemo}
         policy={fitPolicy}
+        topInset={topInset}
         fitViewOptions={flowProps.fitViewOptions}
       >
         {cornerActions}
diff --git a/packages/ui/src/components/flow/flow-legend.tsx b/packages/ui/src/components/flow/flow-legend.tsx
index 939424ee80..7b617fe363 100644
--- a/packages/ui/src/components/flow/flow-legend.tsx
+++ b/packages/ui/src/components/flow/flow-legend.tsx
@@ -13,6 +13,7 @@ import {
   flowEdgeDash,
   flowEdgeTone,
 } from './edge-palette';
+import { FLOW_NODE_DASHED, FLOW_TOUCH_TARGET } from './render/chrome';
 import type { FlowEdgeKind } from './types';
 
 /** One line of the legend: what a mark looks like and what it means. */
@@ -52,10 +53,11 @@ function Swatch({ swatch }: { swatch: FlowLegendEntry['swatch'] }) {
     <span
       aria-hidden="true"
       className={cn(
-        'border-muted-foreground bg-card inline-block h-3 w-8 shrink-0 border',
-        swatch.node === 'dashed' && 'rounded-sm border-dashed',
-        swatch.node === 'gate' && 'rounded-full',
-        swatch.node === 'frame' && 'bg-muted/30 rounded-sm border-dashed',
+        'bg-card inline-block h-3 w-8 shrink-0 border',
+        swatch.node === 'dashed' && cn('rounded-sm', FLOW_NODE_DASHED),
+        swatch.node === 'gate' && 'border-muted-foreground rounded-full',
+        swatch.node === 'frame' &&
+          'border-muted-foreground bg-muted/30 rounded-sm border-dashed',
       )}
     />
   );
@@ -89,7 +91,7 @@ export function FlowLegend({
           variant="secondary"
           title={t('controls.legend')}
           tooltipSide="right"
-          className={className}
+          className={cn(FLOW_TOUCH_TARGET, className)}
         >
           <CircleHelp className="size-4" />
         </Button>
diff --git a/packages/ui/src/components/flow/flow-step-list.tsx b/packages/ui/src/components/flow/flow-step-list.tsx
index 3a4804fcd5..9e7f960535 100644
--- a/packages/ui/src/components/flow/flow-step-list.tsx
+++ b/packages/ui/src/components/flow/flow-step-list.tsx
@@ -22,6 +22,7 @@ import {
 import { FlowNodeStatusIcon, type FlowNodeState } from './node-status';
 import type { FlowHighlight } from './paths/highlight';
 import type { FlowFrameState } from './playback/types';
+import { FLOW_ICON_TILE, FLOW_NODE_DASHED } from './render/chrome';
 import type { FlowGraph, FlowGroup, FlowNode } from './types';
 
 export interface FlowStepListProps {
@@ -265,13 +266,22 @@ function FlowListRow({
         data-flow-quiet={quiet || undefined}
         className={cn(
           'hover:bg-muted/60 flex min-h-9 w-full cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-1.5 text-left',
-          quiet && 'border-border border-dashed',
+          quiet && FLOW_NODE_DASHED,
           'ring-offset-background focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:outline-none',
           flowNodeIssueFrameClass(counts),
           selected && 'bg-muted ring-ring ring-2',
         )}
       >
-        <span className="bg-muted text-muted-foreground flex size-5 shrink-0 items-center justify-center rounded-md">
+        <span
+          className={cn(
+            'flex size-5 shrink-0 items-center justify-center rounded-md',
+            FLOW_ICON_TILE[
+              node.kind === 'entry' || node.kind === 'exit'
+                ? 'terminal'
+                : 'plain'
+            ],
+          )}
+        >
           <Icon aria-hidden="true" className="size-3.5" />
         </span>
         <span className="min-w-0 flex-1">
diff --git a/packages/ui/src/components/flow/motion/flow-motion.test.ts b/packages/ui/src/components/flow/motion/flow-motion.test.ts
index 3bd0a2a7fd..bd7115b25a 100644
--- a/packages/ui/src/components/flow/motion/flow-motion.test.ts
+++ b/packages/ui/src/components/flow/motion/flow-motion.test.ts
@@ -10,7 +10,6 @@ import {
   FLOW_EDGE_ENTER_DELAY,
   FLOW_MOTION_CLASS,
   FLOW_RELAYOUT_SETTLE,
-  FLOW_RING_DELAY,
   FLOW_RING_TOTAL,
 } from './flow-motion';
 
@@ -44,18 +43,38 @@ describe('flow motion', () => {
     // New lines fade in last; the relayout has settled once they are in.
     expect(FLOW_MOTION_CLASS.fadeIn).toContain(`_${FLOW_EDGE_ENTER_DELAY}ms_`);
     expect(FLOW_RELAYOUT_SETTLE).toBe(450);
-    // The ring shows through the glide, then fades: gone at 700 ms.
-    expect(FLOW_RING_DELAY).toBe(FLOW_DURATION.medium);
-    expect(FLOW_MOTION_CLASS.ring).toContain(
-      '_var(--duration-long)_var(--ease-default)_var(--duration-medium)_',
-    );
-    expect(FLOW_RING_TOTAL).toBe(700);
+    // The ring fades in, holds and fades out; script drops it when the
+    // animation ends, and it outlasts the relayout it marks.
+    expect(FLOW_MOTION_CLASS.ring).toContain(`_${FLOW_RING_TOTAL}ms_`);
+    expect(FLOW_RING_TOTAL).toBeGreaterThan(FLOW_RELAYOUT_SETTLE);
     // A node joins once the glide is under way.
     expect(FLOW_MOTION_CLASS.enter).toContain(
       '_var(--duration-standard)_var(--ease-out-quint)_var(--duration-short)_',
     );
   });
 
+  it('fades the ring in over short and out over long, never at once', () => {
+    const block = /@keyframes flow-ring \{([\s\S]*?)\n\}/.exec(css)?.[1];
+    if (block === undefined) throw new Error('no @keyframes flow-ring');
+    const stops = [
+      ...block.matchAll(/([\d.]+)%\s*\{\s*opacity:\s*([\d.]+);/g),
+    ].map((match) => ({
+      at: (Number(match[1]) / 100) * FLOW_RING_TOTAL,
+      opacity: Number(match[2]),
+    }));
+    // It starts and ends unseen: no frame where it switches on or off.
+    expect(stops[0]).toEqual({ at: 0, opacity: 0 });
+    expect(stops.at(-1)).toEqual({ at: FLOW_RING_TOTAL, opacity: 0 });
+    const shown = stops.filter((stop) => stop.opacity === 1);
+    expect(shown[0]?.at).toBeCloseTo(FLOW_DURATION.short, 0);
+    expect(FLOW_RING_TOTAL - (shown.at(-1)?.at ?? 0)).toBeCloseTo(
+      FLOW_DURATION.long,
+      0,
+    );
+    // Fully there until the relayout has settled, so the eye finds it.
+    expect(shown.at(-1)?.at).toBeGreaterThan(FLOW_RELAYOUT_SETTLE);
+  });
+
   it('names only keyframes the stylesheet defines', () => {
     for (const [name, className] of Object.entries(FLOW_MOTION_CLASS)) {
       const keyframes = /animate-\[([a-z-]+)_/.exec(className)?.[1];
diff --git a/packages/ui/src/components/flow/motion/flow-motion.ts b/packages/ui/src/components/flow/motion/flow-motion.ts
index d8f86668fa..e02ab250d0 100644
--- a/packages/ui/src/components/flow/motion/flow-motion.ts
+++ b/packages/ui/src/components/flow/motion/flow-motion.ts
@@ -30,10 +30,13 @@ export const FLOW_EDGE_ENTER_DELAY = 250;
 export const FLOW_RELAYOUT_SETTLE =
   FLOW_EDGE_ENTER_DELAY + FLOW_DURATION.standard;
 
-/** How long a changed node's ring shows: visible through the glide, then
- *  fading over `long`. */
-export const FLOW_RING_DELAY = FLOW_DURATION.medium;
-export const FLOW_RING_TOTAL = FLOW_RING_DELAY + FLOW_DURATION.long;
+/**
+ * A changed node's ring: it fades in over `short` while the box glides —
+ * never switched on at full strength, which reads as a flash — holds while
+ * the relayout settles and a moment after, so the eye finds it, then fades
+ * out over `long`. Gone at 1.2 s.
+ */
+export const FLOW_RING_TOTAL = 1_200;
 
 /** The move of a relayout, on React Flow's node wrapper (which positions
  *  each node with a `transform`). */
@@ -53,10 +56,11 @@ export const FLOW_MOTION_CLASS = {
   /** A line that is gone or re-routed, a frame that changed size. */
   fadeOut:
     'animate-[flow-fade-out_var(--duration-short)_var(--ease-out-quint)_forwards]',
-  /** A changed node's ring: shows through the glide, then fades. */
-  ring: 'animate-[flow-ring-out_var(--duration-long)_var(--ease-default)_var(--duration-medium)_backwards]',
-  /** A running node's top bar. */
-  sweep: 'animate-[flow-running-sweep_1.2s_linear_infinite]',
+  /** A changed node's ring: fades in, holds, fades out (`flow-ring`). */
+  ring: 'animate-[flow-ring_1200ms_var(--ease-default)_both]',
+  /** A running node's top bar: a soft light gliding across its track,
+   *  slow and eased, so a chart with several nodes running stays calm. */
+  sweep: 'animate-[flow-running-sweep_1.6s_var(--ease-in-out)_infinite]',
 } as const;
 
 /** A strip whose words change while a run plays: a soft settle. */
diff --git a/packages/ui/src/components/flow/render/chrome.ts b/packages/ui/src/components/flow/render/chrome.ts
new file mode 100644
index 0000000000..b3028cd8a1
--- /dev/null
+++ b/packages/ui/src/components/flow/render/chrome.ts
@@ -0,0 +1,30 @@
+/**
+ * Box chrome the chart, its List view and its legend share, so the three
+ * always draw a mark the same way.
+ */
+
+/**
+ * The border of a box that may not run, or did not: dashed, in a colour
+ * that keeps 3:1 against the card (`--flow-node-dashed`), so the dashes
+ * still read at half zoom.
+ */
+export const FLOW_NODE_DASHED =
+  'border-dashed border-[color:var(--flow-node-dashed)]';
+
+/** The icon tile at the head of a box. Start and End take the accent pair
+ *  (`accent-base` / `accent-fg`): the chart's two anchors, the same token in
+ *  both themes. */
+export const FLOW_ICON_TILE = {
+  plain: 'bg-muted text-muted-foreground',
+  terminal: 'bg-accent-base text-accent-fg',
+} as const;
+
+/**
+ * A control on a canvas keeps a 44 px target under a coarse pointer: an
+ * invisible layer grows it to 44 px each way it falls short, never shrinking
+ * it. Every button in the canvas's corners wears it — a host's too, through
+ * `@tale/ui/flow/flow-canvas` — and the corner cluster spaces its buttons so
+ * no two targets overlap.
+ */
+export const FLOW_TOUCH_TARGET =
+  "relative pointer-coarse:after:absolute pointer-coarse:after:inset-[min(0px,calc((100%-44px)/2))] pointer-coarse:after:content-['']";
diff --git a/packages/ui/src/components/flow/render/entry-node.tsx b/packages/ui/src/components/flow/render/entry-node.tsx
index 0e49cd0e9d..7afe712188 100644
--- a/packages/ui/src/components/flow/render/entry-node.tsx
+++ b/packages/ui/src/components/flow/render/entry-node.tsx
@@ -85,7 +85,9 @@ export function FlowNodeSection({
         {heading}
       </span>
       {rows.length === 0 ? (
-        <span className="text-muted-foreground flex h-5 items-center text-xs">
+        // One line, like every row: words too long for it end in an
+        // ellipsis rather than wrapping over the next section.
+        <span className="text-muted-foreground h-5 truncate text-xs leading-5">
           {empty}
         </span>
       ) : (
@@ -142,6 +144,7 @@ export const FlowEntryNodeView = memo(function FlowEntryNodeView({
           id={node.id}
           icon={Play}
           title={flowNodeTitle(node, t)}
+          terminal
         />
         {node.triggers.length > 0 && (
           <FlowNodeSection
diff --git a/packages/ui/src/components/flow/render/exit-node.tsx b/packages/ui/src/components/flow/render/exit-node.tsx
index 879ed53672..6343f9e362 100644
--- a/packages/ui/src/components/flow/render/exit-node.tsx
+++ b/packages/ui/src/components/flow/render/exit-node.tsx
@@ -34,6 +34,7 @@ export const FlowExitNodeView = memo(function FlowExitNodeView({
           id={node.id}
           icon={Flag}
           title={flowNodeTitle(node, t)}
+          terminal
         />
         <FlowNodeSection
           heading={t('node.outputs')}
diff --git a/packages/ui/src/components/flow/render/flow-render-context.tsx b/packages/ui/src/components/flow/render/flow-render-context.tsx
index 44cdd67633..a60abc3444 100644
--- a/packages/ui/src/components/flow/render/flow-render-context.tsx
+++ b/packages/ui/src/components/flow/render/flow-render-context.tsx
@@ -18,6 +18,7 @@ import { Tooltip } from '../../overlays/tooltip';
 import { FLOW_MOTION_CLASS, FLOW_STRIP_SETTLE } from '../motion/flow-motion';
 import { flowNodeIssueFrameClass } from '../node-issue-marker';
 import type { FlowNodeState } from '../node-status';
+import { FLOW_NODE_DASHED } from './chrome';
 
 /** How a box looks right now: its run state, and where it stands in a
  *  highlight. */
@@ -140,11 +141,14 @@ function RunChrome({ state }: { state: FlowNodeState }) {
       <span
         aria-hidden="true"
         data-slot="flow-node-running"
-        className="pointer-events-none absolute inset-x-0 top-0 h-0.5 overflow-hidden rounded-t-[inherit]"
+        className="pointer-events-none absolute inset-x-0 top-0 h-0.5 overflow-hidden rounded-t-[inherit] bg-[hsl(var(--info-foreground)/0.3)]"
       >
+        {/* A third of the track, fading out at both ends; under reduced
+            motion it stands still and fills the track. */}
         <span
           className={cn(
-            'block h-full w-full bg-[hsl(var(--info-foreground))] motion-reduce:animate-none',
+            'block h-full w-1/3 bg-linear-to-r from-transparent via-[hsl(var(--info-foreground))] to-transparent',
+            'motion-reduce:w-full motion-reduce:animate-none motion-reduce:bg-[hsl(var(--info-foreground))] motion-reduce:bg-none',
             FLOW_MOTION_CLASS.sweep,
           )}
         />
@@ -228,9 +232,12 @@ export function FlowNodeButton({
       onPointerLeave={() => context.onHoverNode(null)}
       className={cn(
         'relative block size-full cursor-pointer text-left',
+        // The kind's own look (card, border, shape) comes first: every state
+        // below overrides its border colour or surface, never the reverse.
+        className,
         FLOW_NODE_LIFT,
         FLOW_NODE_RING,
-        (dashed || look.quiet || PASSED_BY.has(look.state)) && 'border-dashed',
+        (dashed || look.quiet || PASSED_BY.has(look.state)) && FLOW_NODE_DASHED,
         // The frame takes the worst problem's colour; the selection ring
         // stays its own, so a picked node with a problem shows both. A run
         // state's frame wins over a problem's.
@@ -241,7 +248,6 @@ export function FlowNodeButton({
         selected && 'ring-ring ring-2 ring-offset-1',
         phase === 'enter' && FLOW_MOTION_CLASS.enter,
         leaving && FLOW_MOTION_CLASS.exit,
-        className,
         look.quiet && 'bg-muted/40',
       )}
     >
diff --git a/packages/ui/src/components/flow/render/pulse-layer.tsx b/packages/ui/src/components/flow/render/pulse-layer.tsx
index e16d55e609..4f8026cdda 100644
--- a/packages/ui/src/components/flow/render/pulse-layer.tsx
+++ b/packages/ui/src/components/flow/render/pulse-layer.tsx
@@ -15,6 +15,23 @@ export const FLOW_PULSE_DURATION = 1_000;
 const SAMPLE_STEP = 8;
 /** Half the dot, so its centre rides the line. */
 const DOT_HALF = 4;
+/** Over how much of its route a dot fades in, and dissolves into the box
+ *  it reaches: a fixed distance, so a dot on a short line does not blink
+ *  out and one on a long line does not fade from far away. */
+const FADE_PX = 16;
+/** The most of a route the two fades may take, together under half. */
+const FADE_MAX = 0.2;
+
+/** The share of a route each fade takes. */
+function fadeShare(points: readonly FlowPoint[]): number {
+  let length = 0;
+  for (let index = 1; index < points.length; index++) {
+    const a = points[index - 1];
+    const b = points[index];
+    if (a && b) length += Math.hypot(b.x - a.x, b.y - a.y);
+  }
+  return length > 0 ? Math.min(FADE_MAX, FADE_PX / length) : FADE_MAX;
+}
 
 /**
  * Keyframe points every 8 px along the route the canvas draws (rounded
@@ -59,8 +76,8 @@ function pulsePoints(
  * A value on its way: an 8 px dot riding its line. The motion is a Web
  * Animation created paused — the host's time sets its `currentTime`, so
  * playing, scrubbing and stepping are the same thing, and a dot is exactly
- * where the travel's progress says. It fades in over the first 8 % and
- * dissolves into the box it reaches over the last 8 %.
+ * where the travel's progress says. It fades in over its first 16 px and,
+ * over its last 16 px, shrinks to half and fades into the box it reaches.
  */
 const FlowPulse = memo(function FlowPulse({
   edgeId,
@@ -90,12 +107,13 @@ const FlowPulse = memo(function FlowPulse({
       })),
       { duration: FLOW_PULSE_DURATION, fill: 'both', easing: 'linear' },
     );
+    const share = fadeShare(points);
     const fade = dot.animate(
       [
-        { opacity: 0, offset: 0 },
-        { opacity: 1, offset: 0.08 },
-        { opacity: 1, offset: 0.92 },
-        { opacity: 0, offset: 1 },
+        { opacity: 0, transform: 'scale(1)', offset: 0 },
+        { opacity: 1, transform: 'scale(1)', offset: share },
+        { opacity: 1, transform: 'scale(1)', offset: 1 - share },
+        { opacity: 0, transform: 'scale(0.5)', offset: 1 },
       ],
       { duration: FLOW_PULSE_DURATION, fill: 'both' },
     );
diff --git a/packages/ui/src/components/flow/render/step-node.tsx b/packages/ui/src/components/flow/render/step-node.tsx
index d22504fb6a..7924b7030a 100644
--- a/packages/ui/src/components/flow/render/step-node.tsx
+++ b/packages/ui/src/components/flow/render/step-node.tsx
@@ -11,6 +11,7 @@ import { SKELETON_PULSE } from '../../feedback/skeleton';
 import { FlowNodeIssueMarker } from '../node-issue-marker';
 import { FlowNodeStatusIcon } from '../node-status';
 import type { FlowChip, FlowIcon, FlowStepNode } from '../types';
+import { FLOW_ICON_TILE } from './chrome';
 import {
   FlowNodeButton,
   FlowNodeStrip,
@@ -49,24 +50,33 @@ function FlowChipPill({ chip }: { chip: FlowChip }) {
 }
 
 /** The title row every box shares: icon tile, title, glyphs, problems and,
- *  in a run, the state's glyph. */
+ *  in a run, the state's glyph. Start and End (`terminal`) wear the accent
+ *  tile. */
 export function FlowNodeTitleRow({
   id,
   icon: Icon,
   title,
   trailing,
+  terminal = false,
 }: {
   id: string;
   icon: FlowIcon;
   title: string;
   trailing?: ReactNode;
+  terminal?: boolean;
 }) {
   const { issues, looks } = useFlowRender();
   const counts = issues.get(id);
   const state = looks.get(id)?.state ?? 'idle';
   return (
     <span className="flex h-5 items-center gap-2">
-      <span className="bg-muted text-muted-foreground flex size-5 shrink-0 items-center justify-center rounded-md">
+      <span
+        data-slot="flow-node-tile"
+        className={cn(
+          'flex size-5 shrink-0 items-center justify-center rounded-md',
+          FLOW_ICON_TILE[terminal ? 'terminal' : 'plain'],
+        )}
+      >
         <Icon className="size-3.5" />
       </span>
       <span className="min-w-0 flex-1 truncate text-sm leading-5 font-medium">
diff --git a/packages/ui/src/components/flow/workflow-canvas.look.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.look.browser.test.tsx
new file mode 100644
index 0000000000..c839685ddf
--- /dev/null
+++ b/packages/ui/src/components/flow/workflow-canvas.look.browser.test.tsx
@@ -0,0 +1,363 @@
+import { viewportAtRest } from '@tale/ui/testing/flow';
+import { cleanup } from '@testing-library/react';
+import type { i18n as I18n } from 'i18next';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cdp, page } from 'vitest/browser';
+
+import { ratioAgainst } from '@/tests/utils/contrast';
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { Button } from '../primitives/button';
+import type { FlowRunOverlay } from './playback/types';
+import { branchFlowGraph, triageFlowGraph } from './testing/flow-fixtures';
+import { assertLabelsClear } from './testing/flow-geometry';
+import type { FlowGraph, FlowLayout } from './types';
+import { WorkflowCanvas, type WorkflowCanvasProps } from './workflow-canvas';
+
+import '../../globals.css';
+
+/**
+ * How the chart looks, measured as Chromium paints it: the accent on Start
+ * and End, dashes that still read at half zoom, a problem's frame, a run's
+ * frame and the selection telling themselves apart, Yes and No clear of
+ * every box in each language, touch targets, and a fit that keeps the
+ * first box out from under the top corners' controls.
+ */
+
+// The tree holds the language it detected while mounted; each test that
+// switches it hands the shared instance back in English.
+const shared: { i18n?: I18n } = {};
+function CaptureI18n() {
+  const { i18n } = useTranslation();
+  useEffect(() => {
+    shared.i18n = i18n;
+  }, [i18n]);
+  return null;
+}
+
+afterEach(async () => {
+  cleanup();
+  document.documentElement.classList.remove('dark');
+  window.localStorage.removeItem('tale:flow-view');
+  window.localStorage.removeItem('user-locale');
+  await shared.i18n?.changeLanguage('en-US');
+  await cdp().send('Emulation.setEmulatedMedia', { features: [] });
+  await cdp().send('Emulation.setTouchEmulationEnabled', { enabled: false });
+});
+
+function Canvas({
+  width = 1100,
+  height = 1500,
+  ...props
+}: Partial<WorkflowCanvasProps> & {
+  graph: FlowGraph;
+  width?: number;
+  height?: number;
+}) {
+  const [selected, setSelected] = useState<string | null>(
+    props.selectedId ?? null,
+  );
+  return (
+    <div data-testid="frame" style={{ width, height }}>
+      <CaptureI18n />
+      <WorkflowCanvas
+        aria-label="Workflow"
+        layoutKey={`look-${props.graph.nodes.length}`}
+        fitPolicy="all"
+        selectedId={selected}
+        onSelect={setSelected}
+        {...props}
+      />
+    </div>
+  );
+}
+
+/** Renders a chart and resolves once its layout is drawn and at rest. */
+async function renderChart(
+  props: Partial<WorkflowCanvasProps> & {
+    graph: FlowGraph;
+    width?: number;
+    height?: number;
+  },
+) {
+  await page.viewport(1280, 1600);
+  let layout: FlowLayout | null = null;
+  const view = render(
+    <Canvas
+      {...props}
+      onLayout={(next) => {
+        layout = next;
+      }}
+    />,
+  );
+  await waitFor(
+    () => {
+      if (layout === null) throw new Error('not laid out yet');
+    },
+    { timeout: 20_000 },
+  );
+  await waitFor(
+    () =>
+      expect(
+        view.container.querySelectorAll('path[data-flow-edge]'),
+      ).toHaveLength(
+        props.graph.edges.filter((edge) => !edge.layoutOnly).length,
+      ),
+    { timeout: 10_000 },
+  );
+  await viewportAtRest();
+  // The chart fades in; colours are read once it is fully there.
+  await Promise.all(
+    document
+      .getAnimations()
+      .filter(
+        (animation) =>
+          animation.effect?.getComputedTiming().endTime !== Infinity,
+      )
+      .map((animation) => animation.finished),
+  );
+  return { ...view, layout: layout as unknown as FlowLayout };
+}
+
+const box = (id: string) =>
+  document.querySelector<HTMLElement>(`[data-flow-node="${CSS.escape(id)}"]`);
+
+/** What a CSS colour expression resolves to on the page right now. */
+function resolved(property: 'color' | 'backgroundColor', value: string) {
+  const probe = document.createElement('span');
+  probe.style.setProperty(
+    property === 'color' ? 'color' : 'background-color',
+    value,
+  );
+  document.body.append(probe);
+  const colour = getComputedStyle(probe)[property];
+  probe.remove();
+  return colour;
+}
+
+const overlaps = (a: DOMRect, b: DOMRect) =>
+  a.left < b.right - 1 &&
+  a.right > b.left + 1 &&
+  a.top < b.bottom - 1 &&
+  a.bottom > b.top + 1;
+
+describe('WorkflowCanvas look', () => {
+  it.each(['light', 'dark'] as const)(
+    'draws Start and End on the accent tile, and dashes that keep 3:1 (%s)',
+    async (theme) => {
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+      await renderChart({ graph: branchFlowGraph() });
+      const accent = resolved('backgroundColor', 'var(--color-accent-base)');
+      for (const id of ['__start', '__end']) {
+        const tile = box(id)?.querySelector<HTMLElement>(
+          '[data-slot="flow-node-tile"]',
+        );
+        expect(tile, id).not.toBeNull();
+        // The same token in both themes: ink on light, white on dark.
+        expect(getComputedStyle(tile as Element).backgroundColor, id).toBe(
+          accent,
+        );
+        const glyph = tile?.querySelector('svg') as Element;
+        expect(
+          ratioAgainst(tile as Element, getComputedStyle(glyph).color),
+          `${id} glyph`,
+        ).toBeGreaterThanOrEqual(4.5);
+      }
+      // A step keeps the plain tile.
+      expect(
+        getComputedStyle(
+          box('fetch')?.querySelector(
+            '[data-slot="flow-node-tile"]',
+          ) as Element,
+        ).backgroundColor,
+      ).not.toBe(accent);
+
+      const dashed = [
+        ...document.querySelectorAll<HTMLElement>('[data-flow-node]'),
+      ].filter((node) => getComputedStyle(node).borderTopStyle === 'dashed');
+      expect(dashed.length).toBeGreaterThan(0);
+      for (const node of dashed)
+        expect(
+          ratioAgainst(node, getComputedStyle(node).borderTopColor),
+          `${theme} ${node.dataset.flowNode} dashes`,
+        ).toBeGreaterThanOrEqual(3);
+    },
+  );
+
+  it('keeps a problem’s frame, a run’s frame and the selection apart', async () => {
+    const issues = new Map([
+      ['open_issues', { errors: 1, warnings: 0 }],
+      ['score', { errors: 0, warnings: 2 }],
+    ]);
+    const view = await renderChart({
+      graph: triageFlowGraph(),
+      issues,
+      selectedId: 'score',
+    });
+    const destructive = resolved('color', 'hsl(var(--destructive))');
+    const plain = getComputedStyle(box('issues') as Element).borderTopColor;
+    const error = getComputedStyle(box('open_issues') as Element);
+    const warning = getComputedStyle(box('score') as Element);
+    expect(error.borderTopColor).toBe(destructive);
+    // Amber, not the plain border and not the error red.
+    expect(warning.borderTopColor).not.toBe(plain);
+    expect(warning.borderTopColor).not.toBe(destructive);
+    // The selected node keeps its problem's frame and adds the ring.
+    expect(warning.boxShadow).not.toBe('none');
+    expect(error.boxShadow).not.toContain(
+      resolved('color', 'hsl(var(--ring))'),
+    );
+    view.unmount();
+
+    const overlay: FlowRunOverlay = {
+      finished: false,
+      nodes: {
+        issues: { state: 'succeeded' },
+        open_issues: { state: 'failed' },
+        score: { state: 'running' },
+      },
+    };
+    await renderChart({ graph: triageFlowGraph(), overlay });
+    expect(getComputedStyle(box('open_issues') as Element).borderTopColor).toBe(
+      destructive,
+    );
+    expect(
+      box('open_issues')?.querySelector('[data-slot="flow-node-failed"]'),
+    ).not.toBeNull();
+    expect(getComputedStyle(box('score') as Element).borderTopColor).toBe(
+      resolved('color', 'hsl(var(--info-foreground))'),
+    );
+    expect(getComputedStyle(box('issues') as Element).borderTopColor).toBe(
+      plain,
+    );
+  });
+
+  it.each([
+    ['de', 'Ja', 'Nein'],
+    ['fr', 'Oui', 'Non'],
+    ['en', 'Yes', 'No'],
+  ])(
+    'keeps Yes and No clear of every box in %s, and conditions inside their width',
+    async (locale, yes, no) => {
+      window.localStorage.setItem('user-locale', locale);
+      const { container, layout } = await renderChart({
+        graph: branchFlowGraph(),
+      });
+      const labels = [
+        ...container.querySelectorAll<HTMLElement>('[data-flow-edge-label]'),
+      ];
+      expect(labels.map((label) => label.textContent).sort()).toEqual(
+        [yes, yes, no, no].sort(),
+      );
+      assertLabelsClear(layout);
+      const boxes = [
+        ...container.querySelectorAll<HTMLElement>('[data-flow-node]'),
+      ];
+      for (const label of labels) {
+        const rect = label.getBoundingClientRect();
+        // The pill holds its word on one line.
+        expect(label.scrollWidth, label.textContent ?? '').toBeLessThanOrEqual(
+          label.clientWidth + 1,
+        );
+        for (const node of boxes)
+          expect(
+            overlaps(rect, node.getBoundingClientRect()),
+            `${label.textContent} over ${node.dataset.flowNode}`,
+          ).toBe(false);
+      }
+      // Each condition is as wide as its words need, inside 160 to 288 px.
+      for (const [id, rect] of Object.entries(layout.nodes))
+        if (id.startsWith('__gate:')) {
+          expect(rect.width, id).toBeGreaterThanOrEqual(160);
+          expect(rect.width, id).toBeLessThanOrEqual(288);
+        }
+    },
+  );
+
+  it('keeps the first box clear of the top corners’ controls when it fits', async () => {
+    await renderChart({
+      graph: triageFlowGraph(),
+      width: 640,
+      height: 420,
+      fitPolicy: 'auto',
+      topStart: <Button size="sm">Canvas</Button>,
+      topEnd: (
+        <Button size="sm" variant="secondary">
+          Paths
+        </Button>
+      ),
+    });
+    const corner = screen
+      .getByRole('button', { name: 'Paths' })
+      .closest('.react-flow__panel')
+      ?.getBoundingClientRect();
+    const start = box('__start')?.getBoundingClientRect();
+    expect(corner).toBeDefined();
+    expect(start?.top ?? 0).toBeGreaterThanOrEqual((corner?.bottom ?? 0) + 8);
+  });
+
+  it('gives every corner control a 44 px target under a coarse pointer, none overlapping', async () => {
+    await cdp().send('Emulation.setTouchEmulationEnabled', {
+      enabled: true,
+      maxTouchPoints: 1,
+    });
+    expect(window.matchMedia('(pointer: coarse)').matches).toBe(true);
+    await renderChart({
+      graph: triageFlowGraph(),
+      legend: [{ id: 'data', swatch: { edge: 'data' }, label: 'Data' }],
+    });
+    const names = ['Zoom in', 'Zoom out', 'Reset view', 'Legend'];
+    const targets = names.map((name) => {
+      const button = screen.getByRole('button', { name });
+      const after = getComputedStyle(button, '::after');
+      const rect = button.getBoundingClientRect();
+      const top = Number.parseFloat(after.top);
+      const left = Number.parseFloat(after.left);
+      return {
+        name,
+        top: rect.top + top,
+        bottom: rect.bottom - Number.parseFloat(after.bottom),
+        width: rect.width - left - Number.parseFloat(after.right),
+        height: rect.height - top - Number.parseFloat(after.bottom),
+      };
+    });
+    for (const target of targets) {
+      expect(target.width, target.name).toBeGreaterThanOrEqual(44);
+      expect(target.height, target.name).toBeGreaterThanOrEqual(44);
+    }
+    for (let index = 1; index < targets.length; index++)
+      expect(
+        targets[index]?.top ?? 0,
+        `${names[index]} under ${names[index - 1]}`,
+      ).toBeGreaterThanOrEqual((targets[index - 1]?.bottom ?? 0) - 0.5);
+  });
+
+  it('lines the List view’s corners up along their tops', async () => {
+    await page.viewport(1280, 1600);
+    render(
+      <Canvas
+        graph={triageFlowGraph()}
+        view="list"
+        topStart={
+          <div className="flex flex-col items-start gap-2">
+            <Button size="sm">Canvas</Button>
+            <div className="h-8 w-40">Path 2</div>
+          </div>
+        }
+        topEnd={
+          <Button size="sm" variant="secondary">
+            Paths
+          </Button>
+        }
+      />,
+    );
+    const start = await screen.findByRole('button', { name: 'Canvas' });
+    const end = screen.getByRole('button', { name: 'Paths' });
+    expect(end.getBoundingClientRect().top).toBeCloseTo(
+      start.getBoundingClientRect().top,
+      0,
+    );
+  });
+});
diff --git a/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
index 2597aa42df..0755ead522 100644
--- a/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.motion.browser.test.tsx
@@ -190,9 +190,9 @@ describe('WorkflowCanvas live relayout', () => {
       return element;
     });
     const style = getComputedStyle(ring);
-    expect(style.animationName).toBe('flow-ring-out');
-    expect(style.animationDelay).toBe('0.3s');
-    expect(style.animationDuration).toBe('0.4s');
+    expect(style.animationName).toBe('flow-ring');
+    expect(style.animationDelay).toBe('0s');
+    expect(style.animationDuration).toBe('1.2s');
     await waitFor(
       () =>
         expect(
diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
index c4c7f00058..1548167f05 100644
--- a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -143,7 +143,7 @@ describe('WorkflowCanvas with a run', () => {
     );
     if (travel === undefined) throw new Error('no travel');
     const t = travel.start + (travel.end - travel.start) * 0.25;
-    await renderRun({ graph, playback: { timeline, t } });
+    const { layout } = await renderRun({ graph, playback: { timeline, t } });
     const frame = flowStateAt(graph, timeline, t);
     for (const each of graph.nodes)
       expect(node(each.id)?.getAttribute('data-flow-state'), each.id).toBe(
@@ -164,6 +164,27 @@ describe('WorkflowCanvas with a run', () => {
       0.25 * FLOW_PULSE_DURATION,
       0,
     );
+    // It fades in over its first 16 px (a fifth of a line too short for
+    // that), and over its last 16 px shrinks to half and fades into the box
+    // it reaches.
+    const dot = pulses[0]?.firstElementChild;
+    const fade = dot?.getAnimations()[0]?.effect as KeyframeEffect | undefined;
+    const keyframes = fade?.getKeyframes() ?? [];
+    const points = layout.edges['issues>open_issues']?.points ?? [];
+    let length = 0;
+    for (let index = 1; index < points.length; index++)
+      length += Math.hypot(
+        (points[index]?.x ?? 0) - (points[index - 1]?.x ?? 0),
+        (points[index]?.y ?? 0) - (points[index - 1]?.y ?? 0),
+      );
+    expect(length).toBeGreaterThan(0);
+    const share = keyframes[1]?.computedOffset ?? 0;
+    expect(share).toBeCloseTo(Math.min(0.2, 16 / length), 5);
+    expect(keyframes.at(-1)).toMatchObject({
+      opacity: '0',
+      transform: 'scale(0.5)',
+    });
+    expect(keyframes.at(-2)?.computedOffset).toBeCloseTo(1 - share, 5);
   });
 
   it('moves the dot with the moment, and scrubbing back resets the states', async () => {
@@ -310,9 +331,23 @@ describe('WorkflowCanvas run motion', () => {
       node('issues')?.querySelector('[data-slot="flow-node-running"] > span');
     let style = getComputedStyle(bar() as Element);
     expect(style.animationName).toBe('flow-running-sweep');
-    expect(style.animationDuration).toBe('1.2s');
-    expect(style.animationTimingFunction).toBe('linear');
+    expect(style.animationDuration).toBe('1.6s');
+    expect(style.animationTimingFunction).toBe(
+      'cubic-bezier(0.42, 0, 0.58, 1)',
+    );
     expect(style.animationIterationCount).toBe('infinite');
+    // A soft light, a third of a faint track: calm beside other runners.
+    const track = node('issues')?.querySelector<HTMLElement>(
+      '[data-slot="flow-node-running"]',
+    );
+    expect(getComputedStyle(track as Element).backgroundColor).not.toBe(
+      'rgba(0, 0, 0, 0)',
+    );
+    expect(style.backgroundImage).toContain('linear-gradient');
+    expect(
+      (bar() as HTMLElement).getBoundingClientRect().width /
+        (track as HTMLElement).getBoundingClientRect().width,
+    ).toBeCloseTo(1 / 3, 1);
     unmount();
 
     await cdp().send('Emulation.setEmulatedMedia', {
@@ -320,9 +355,18 @@ describe('WorkflowCanvas run motion', () => {
     });
     await renderRun({ graph: triageFlowGraph(), overlay });
     style = getComputedStyle(bar() as Element);
-    // Still there, still blue — it only stops moving.
+    // Still there, still blue, the whole track — it only stops moving.
     expect(style.animationName).toBe('none');
+    expect(style.backgroundImage).toBe('none');
     expect(bar()).toBeVisible();
+    expect((bar() as HTMLElement).getBoundingClientRect().width).toBeCloseTo(
+      (
+        node('issues')?.querySelector(
+          '[data-slot="flow-node-running"]',
+        ) as Element
+      ).getBoundingClientRect().width,
+      0,
+    );
   });
 
   it('settles a strip softly as the run plays on, and swaps it when scrubbing back', async () => {
diff --git a/packages/ui/src/components/flow/workflow-canvas.tsx b/packages/ui/src/components/flow/workflow-canvas.tsx
index 70f685b678..afa2d2445c 100644
--- a/packages/ui/src/components/flow/workflow-canvas.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.tsx
@@ -34,6 +34,7 @@ import { Button } from '../primitives/button';
 import { describeFlowGraph, flowListFormat } from './describe';
 import {
   easeOutQuint,
+  FLOW_TOUCH_TARGET,
   FLOW_VIEWPORT_DURATION,
   FlowCanvas,
   type FlowFitPolicy,
@@ -905,6 +906,7 @@ function WorkflowCanvasInner({
       <Button
         size="icon"
         variant="secondary"
+        className={FLOW_TOUCH_TARGET}
         title={t(view === 'chart' ? 'controls.showList' : 'controls.showChart')}
         tooltipSide="right"
         onClick={() => changeView(view === 'chart' ? 'list' : 'chart')}
@@ -946,7 +948,10 @@ function WorkflowCanvasInner({
       {announcer}
       {view === 'list' ? (
         <div ref={swapRef} className={cn(frameClass, 'overflow-y-auto')}>
-          <div className="flex items-center gap-1 px-3 pt-3">
+          {/* The corners line up along their tops: a pill or a panel the
+              host stacks under its view switch never pulls the other
+              corner's buttons down to its middle. */}
+          <div className="flex items-start gap-1 px-3 pt-3">
             {topStart}
             <span className="ml-auto flex items-center gap-1">
               {topEnd}
diff --git a/packages/ui/src/globals.css b/packages/ui/src/globals.css
index 753806f840..3864072d12 100644
--- a/packages/ui/src/globals.css
+++ b/packages/ui/src/globals.css
@@ -297,6 +297,11 @@
      a line, so light mode takes amber-700 (5:1); the edge palette reads it
      through FLOW_EDGE_COLORS.negative. */
   --flow-edge-negative: #b45309;
+  /* A flow box's dashed border ("may not run", "did not run"): the dash is
+     the meaning, so it keeps 3:1 against the card and the muted surface of
+     a box stepping back from a highlight — the plain border (1.3:1) left the
+     dashes unreadable at half zoom. */
+  --flow-node-dashed: hsl(var(--muted-foreground) / 0.8);
 }
 
 .dark {
@@ -402,6 +407,7 @@
   --code-match: hsl(var(--info-foreground) / 0.25);
   --code-squiggle-warning: #f59e0b;
   --flow-edge-negative: #f59e0b;
+  --flow-node-dashed: hsl(var(--muted-foreground) / 0.6);
 }
 
 /* Windows contrast themes repaint text in their own colours; the selection
@@ -816,8 +822,9 @@
 /* Workflow canvas motion (components/flow/motion/flow-motion.ts names the
    timings; every one is skipped under reduced motion). A node that joins a
    relaid chart grows in from the exit scale, one that leaves shrinks back
-   to it, a re-routed line fades out, a changed node's ring fades away, and
-   a running node's top bar sweeps across. Opacity and transform only. */
+   to it, a re-routed line fades out, a changed node's ring fades in and
+   away, and a light glides along a running node's top bar. Opacity and
+   transform only. */
 @keyframes flow-enter {
   from {
     opacity: 0;
@@ -838,21 +845,31 @@
   }
 }
 
-@keyframes flow-ring-out {
-  from {
+/* In over 150 ms (`--duration-short` of 1.2 s), out over the last 400 ms
+   (`--duration-long`). */
+@keyframes flow-ring {
+  0% {
+    opacity: 0;
+  }
+  12.5% {
     opacity: 1;
   }
-  to {
+  66.667% {
+    opacity: 1;
+  }
+  100% {
     opacity: 0;
   }
 }
 
+/* The light is a third of the track: from just off its left end to just
+   off its right. */
 @keyframes flow-running-sweep {
   from {
     transform: translateX(-100%);
   }
   to {
-    transform: translateX(100%);
+    transform: translateX(300%);
   }
 }
 

From ebe95b0c5ed2741cc8f37c9ab319db1be6e7a9eb Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 07:28:32 +0200
Subject: [PATCH 67/78] fix(ui): hold code chips to the prose x-height and
 popover look

A template chip in prose keeps the prose size and holds its monospace font to Inter's x-height through font-size-adjust; tooltips and the completion list draw the app's popover ring and shadow.
---
 .../code-editor/code-editor.browser.test.tsx  | 30 +++++++++++++++++++
 .../forms/code-editor/extensions/theme.ts     | 22 ++++++++++----
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
index dc18a32698..30b8d12a08 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -28,6 +28,7 @@ import {
   type CodeEditorHandle,
   type CodeEditorProps,
 } from './code-editor';
+import { PROSE_X_HEIGHT } from './extensions/theme';
 import type { CodeEditorProviders } from './providers';
 
 import '../../../globals.css';
@@ -563,6 +564,35 @@ describe('CodeEditor templates', () => {
       '{{ input.email }}',
     ]);
   });
+
+  it('stands a chip’s code as tall as the prose round it', async () => {
+    render(
+      <CodeEditor
+        aria-label="Code"
+        language="markdown"
+        font="prose"
+        templates
+        value="Summarize {{ nodes.issues.output.title }} for the team."
+      />,
+    );
+    const box = await content('Code');
+    const chip = box.querySelector<HTMLElement>('.cm-template');
+    if (chip === null) throw new Error('no chip');
+    const prose = getComputedStyle(box);
+    const code = getComputedStyle(chip);
+    await document.fonts.load(`400 ${prose.fontSize} Inter`);
+    // Inter's own x-height, as the page draws it.
+    const canvas = document.createElement('canvas').getContext('2d');
+    if (canvas === null) throw new Error('no 2D canvas');
+    canvas.font = `400 100px Inter`;
+    const inter = canvas.measureText('x').actualBoundingBoxAscent / 100;
+    expect(inter).toBeCloseTo(PROSE_X_HEIGHT, 2);
+    // The chip keeps the prose's size and holds whatever monospace font
+    // the system supplies to that x-height.
+    expect(code.fontFamily).toContain('monospace');
+    expect(code.fontSize).toBe(prose.fontSize);
+    expect(Number(code.fontSizeAdjust)).toBeCloseTo(PROSE_X_HEIGHT, 3);
+  });
 });
 
 describe('CodeEditor colours', () => {
diff --git a/packages/ui/src/components/forms/code-editor/extensions/theme.ts b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
index cefe263f3f..b4ac9ba98e 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/theme.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/theme.ts
@@ -1,5 +1,13 @@
 import { EditorView } from '@codemirror/view';
 
+/** Inter's x-height as a share of its size (1118 of 2048 units). */
+export const PROSE_X_HEIGHT = 0.546;
+
+/** `shadow-md` under a `ring-1 ring-border`: the app's popover, as one
+ *  `box-shadow` (CodeMirror's tooltips take no utility classes). */
+const POPOVER_SHADOW =
+  '0 0 0 1px hsl(var(--border)), 0 4px 6px -1px var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 2px 4px -2px var(--tw-shadow-color, rgb(0 0 0 / 0.1))';
+
 /**
  * The editor's chrome, all through CSS variables (`--code-*` and the app's
  * tokens), so one theme serves light and dark. Sizes come from the frame:
@@ -94,7 +102,9 @@ export const codeEditorTheme = EditorView.theme({
   },
   '.cm-selectionMatch': { backgroundColor: 'var(--code-match)' },
   // A `{{ … }}` template reads as one chip; in prose it keeps the code font,
-  // a little smaller so it sits on the text's x-height.
+  // scaled so its lowercase letters stand exactly as tall as the prose's:
+  // `font-size-adjust` holds any monospace font to Inter's x-height (0.546
+  // of its size), whichever one the reader's system supplies.
   '.cm-template': {
     backgroundColor: 'var(--code-template-tint)',
     borderRadius: '3px',
@@ -103,7 +113,7 @@ export const codeEditorTheme = EditorView.theme({
   },
   '&.cm-prose .cm-template': {
     fontFamily: 'var(--font-mono)',
-    fontSize: '0.92em',
+    fontSizeAdjust: String(PROSE_X_HEIGHT),
   },
   '.cm-tale-object': { color: 'var(--code-token-constant)' },
   // Problems: the underline's style says the severity (wavy for an error or
@@ -141,13 +151,15 @@ export const codeEditorTheme = EditorView.theme({
     width: '1.25rem',
     paddingLeft: '0.25rem',
   },
-  // Tooltips and the completion list look like the app's popovers.
+  // Tooltips and the completion list look like the app's popovers: a 1 px
+  // ring in the border colour over `shadow-md`, whose layers the dark theme
+  // recolours through `--tw-shadow-color` (globals.css).
   '.cm-tooltip': {
     backgroundColor: 'hsl(var(--popover))',
     color: 'hsl(var(--popover-foreground))',
-    border: '1px solid hsl(var(--border))',
+    border: 'none',
     borderRadius: '0.5rem',
-    boxShadow: 'var(--shadow-overlay)',
+    boxShadow: POPOVER_SHADOW,
     fontFamily: 'var(--font-sans)',
     fontSize: '0.75rem',
     lineHeight: '1.4',

From 140109d1d27946d5caa8586ddd1565aea969f823 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 12:00:35 +0200
Subject: [PATCH 68/78] test(ui): read the running bar without an unsafe
 optional chain

---
 .../flow/workflow-canvas.run.browser.test.tsx          | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
index 1548167f05..2eebbabb46 100644
--- a/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
+++ b/packages/ui/src/components/flow/workflow-canvas.run.browser.test.tsx
@@ -359,12 +359,12 @@ describe('WorkflowCanvas run motion', () => {
     expect(style.animationName).toBe('none');
     expect(style.backgroundImage).toBe('none');
     expect(bar()).toBeVisible();
+    const running = node('issues')?.querySelector(
+      '[data-slot="flow-node-running"]',
+    );
+    if (!running) throw new Error('the running step lost its bar');
     expect((bar() as HTMLElement).getBoundingClientRect().width).toBeCloseTo(
-      (
-        node('issues')?.querySelector(
-          '[data-slot="flow-node-running"]',
-        ) as Element
-      ).getBoundingClientRect().width,
+      running.getBoundingClientRect().width,
       0,
     );
   });

From 1c83a55664247fe97034c00cddafa64b6af46156 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 19:39:13 +0200
Subject: [PATCH 69/78] fix(ui): keep a code field editable when its editor
 does not load

The CodeEditor's implementation is a lazy chunk with no boundary of its own, so a failed load (a flaky connection, a deploy that replaced the chunk) reached the page's error route and took an unsaved draft with it. The field now holds the failure itself: the value goes on in a labelled plain text area that still edits through onChange, with a way to try the editor again on a fresh lazy component, since React keeps a rejected one rejected.
---
 .../code-editor.load-failure.browser.test.tsx |  93 ++++++++++++
 .../forms/code-editor/code-editor.tsx         | 141 ++++++++++++++++--
 packages/ui/src/i18n/messages/de.yml          |   2 +
 packages/ui/src/i18n/messages/en.yml          |   2 +
 packages/ui/src/i18n/messages/fr.yml          |   2 +
 5 files changed, 225 insertions(+), 15 deletions(-)
 create mode 100644 packages/ui/src/components/forms/code-editor/code-editor.load-failure.browser.test.tsx

diff --git a/packages/ui/src/components/forms/code-editor/code-editor.load-failure.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.load-failure.browser.test.tsx
new file mode 100644
index 0000000000..bad0083902
--- /dev/null
+++ b/packages/ui/src/components/forms/code-editor/code-editor.load-failure.browser.test.tsx
@@ -0,0 +1,93 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { useState } from 'react';
+import { afterEach, expect, it, vi } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+import { render, screen, waitFor } from '@/tests/utils/render';
+
+import { CodeEditor } from './code-editor';
+
+import '../../../globals.css';
+
+/**
+ * When the editor's implementation cannot load — a flaky connection, a
+ * deploy that replaced its chunk — the failure stays in the field: the value
+ * goes on in plain text, edits still reach the form, and the editor can be
+ * tried again. Each browser test file runs in a fresh page, so the chunk is
+ * cold here.
+ */
+
+const chunk = vi.hoisted(() => ({ fail: true, renders: 0 }));
+
+// The implementation fails the way a chunk that did not load does: the
+// lazy component rejects when it renders, until the "network" is back.
+vi.mock('./code-editor-view', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./code-editor-view')>();
+  const View = actual.default;
+  return {
+    ...actual,
+    default: function FlakyView(props: Parameters<typeof View>[0]) {
+      chunk.renders += 1;
+      if (chunk.fail) {
+        throw new TypeError('Failed to fetch dynamically imported module');
+      }
+      return <View {...props} />;
+    },
+  };
+});
+
+afterEach(cleanup);
+
+function Draft() {
+  const [value, setValue] = useState('return 1;');
+  return (
+    <>
+      <CodeEditor
+        aria-label="Code"
+        language="javascript"
+        value={value}
+        onChange={setValue}
+      />
+      <output data-testid="draft">{value}</output>
+    </>
+  );
+}
+
+it('keeps the field editable in plain text when the editor does not load, and loads it on retry', async () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+  const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  render(<Draft />);
+
+  const plain = await screen.findByRole('textbox', { name: 'Code' });
+  expect(plain.tagName).toBe('TEXTAREA');
+  expect(plain).toHaveValue('return 1;');
+  expect(
+    screen.getByText(
+      "The editor didn't load. You can keep editing here as plain text.",
+    ),
+  ).toBeVisible();
+
+  // The draft keeps working: an edit in the plain field reaches the form.
+  await userEvent.click(plain);
+  await userEvent.keyboard('{End} // kept');
+  expect(screen.getByTestId('draft')).toHaveTextContent('return 1; // kept');
+
+  chunk.fail = false;
+  await userEvent.click(
+    screen.getByRole('button', { name: 'Try the editor again' }),
+  );
+  await waitFor(() =>
+    expect(
+      document.querySelector('[data-code-editor] .cm-content'),
+    ).not.toBeNull(),
+  );
+  expect(chunk.renders).toBeGreaterThanOrEqual(2);
+  expect(document.querySelector('textarea')).toBeNull();
+  // The editor took over with the text the plain field left.
+  expect(
+    document.querySelector('[data-code-editor] .cm-content'),
+  ).toHaveTextContent('return 1; // kept');
+  warn.mockRestore();
+  error.mockRestore();
+});
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.tsx b/packages/ui/src/components/forms/code-editor/code-editor.tsx
index 745cfeaa91..1e57fc2d8d 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.tsx
@@ -33,6 +33,7 @@ import { useIsMac } from '../../../hooks/use-is-mac';
 import { usePrefersReducedMotion } from '../../../hooks/use-prefers-reduced-motion';
 import { useT } from '../../../i18n/client';
 import { cn } from '../../../lib/cn';
+import { ErrorBoundaryBase } from '../../error-boundaries/core/error-boundary-base';
 import {
   DisabledReasonTooltip,
   hasDisabledReason,
@@ -66,7 +67,16 @@ export type {
 export type { CodeLanguage } from '../../../lib/code-roles';
 
 const loadView = () => import('./code-editor-view');
-const CodeEditorView = lazy(loadView);
+/** The editor's implementation, shared by every field. React keeps a lazy
+ * component whose load failed failed for good, so a retry swaps in a fresh
+ * one (`retryView`). */
+let CodeEditorView = lazy(loadView);
+let viewFailed = false;
+function retryView(): void {
+  if (!viewFailed) return;
+  viewFailed = false;
+  CodeEditorView = lazy(loadView);
+}
 
 /**
  * Starts loading the editor's implementation, so the first code field a
@@ -346,28 +356,56 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
           className,
         )}
       >
-        <Suspense
-          fallback={
-            <LoadingText
+        {/* A failed load stays in the field: the value goes on in plain
+            text, and the page around it — a draft — keeps working. */}
+        <ErrorBoundaryBase
+          onError={(error) => {
+            viewFailed = true;
+            console.warn('[code-editor] the editor did not load', error);
+          }}
+          onReset={retryView}
+          fallback={({ reset }) => (
+            <PlainTextFallback
               value={value}
+              onChange={props.onChange}
+              editable={editable}
               placeholder={placeholder}
-              wraps={wraps}
               font={font}
-              lineNumbers={lineNumbers}
               minRows={minRows}
               maxRows={maxRows}
               fillHeight={fillHeight}
-              loadingLabel={t('loading')}
+              id={props.id}
+              label={props['aria-label']}
+              labelledBy={props['aria-labelledby']}
+              describedBy={props['aria-describedby']}
+              invalid={invalid}
+              onRetry={reset}
             />
-          }
+          )}
         >
-          <CodeEditorView
-            {...props}
-            describedBy={describedBy}
-            reducedMotion={reducedMotion}
-            onView={onView}
-          />
-        </Suspense>
+          <Suspense
+            fallback={
+              <LoadingText
+                value={value}
+                placeholder={placeholder}
+                wraps={wraps}
+                font={font}
+                lineNumbers={lineNumbers}
+                minRows={minRows}
+                maxRows={maxRows}
+                fillHeight={fillHeight}
+                loadingLabel={t('loading')}
+              />
+            }
+          >
+            <CodeEditorView
+              {...props}
+              describedBy={describedBy}
+              reducedMotion={reducedMotion}
+              onView={onView}
+            />
+          </Suspense>
+        </ErrorBoundaryBase>
         {expandable !== false ? (
           <IconButton
             icon={Maximize2}
@@ -465,6 +503,79 @@ const CodeEditorBase = forwardRef<CodeEditorHandle, CodeEditorProps>(
   },
 );
 
+/**
+ * What a field shows when the editor's implementation could not load: the
+ * same value in a plain text area, still edited through `onChange`, and a
+ * way to try the editor again.
+ */
+function PlainTextFallback({
+  value,
+  onChange,
+  editable,
+  placeholder,
+  font,
+  minRows,
+  maxRows,
+  fillHeight,
+  id,
+  label,
+  labelledBy,
+  describedBy,
+  invalid,
+  onRetry,
+}: {
+  value: string;
+  onChange: ((value: string) => void) | undefined;
+  editable: boolean;
+  placeholder: string | undefined;
+  font: 'mono' | 'prose';
+  minRows: number;
+  maxRows: number;
+  fillHeight: boolean;
+  id: string | undefined;
+  label: string | undefined;
+  labelledBy: string | undefined;
+  describedBy: string | undefined;
+  invalid: boolean;
+  onRetry: () => void;
+}) {
+  const { t } = useT('codeEditor');
+  const noticeId = useId();
+  return (
+    <div className={cn('flex flex-col', fillHeight && 'h-full min-h-0')}>
+      <textarea
+        id={id}
+        value={value}
+        onChange={(event) => onChange?.(event.target.value)}
+        readOnly={!editable}
+        placeholder={placeholder}
+        spellCheck={false}
+        aria-label={label}
+        aria-labelledby={labelledBy}
+        aria-describedby={[describedBy, noticeId].filter(Boolean).join(' ')}
+        aria-invalid={invalid || undefined}
+        rows={minRows}
+        className={cn(
+          'block w-full resize-y bg-transparent px-3 py-2 leading-[1.6] outline-none',
+          font === 'prose' ? 'font-sans' : 'font-mono',
+          fillHeight && 'min-h-0 flex-1',
+        )}
+        style={
+          fillHeight
+            ? undefined
+            : { maxHeight: `calc(${maxRows} * 1.6em + 1rem)` }
+        }
+      />
+      <div className="border-border text-muted-foreground flex items-center justify-between gap-2 border-t px-3 py-1.5 text-xs">
+        <span id={noticeId}>{t('loadFailed')}</span>
+        <Button type="button" variant="secondary" size="sm" onClick={onRetry}>
+          {t('retry')}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
 /**
  * What shows while the editor's implementation loads: the value in the
  * editor's own metrics, so nothing moves when the editor replaces it.
diff --git a/packages/ui/src/i18n/messages/de.yml b/packages/ui/src/i18n/messages/de.yml
index ec7e86873e..a607c1f277 100644
--- a/packages/ui/src/i18n/messages/de.yml
+++ b/packages/ui/src/i18n/messages/de.yml
@@ -449,6 +449,8 @@ codeEditor:
   tabFocusOff: Tab rückt jetzt ein.
   expand: Editor vergrößern
   collapse: Zurück zum Feld
+  loadFailed: 'Der Editor wurde nicht geladen. Du kannst hier als reiner Text weiterbearbeiten.'
+  retry: 'Editor erneut laden'
   diagnostics:
     atCursor: '{severity} in Zeile {line}: {message}'
     severity:
diff --git a/packages/ui/src/i18n/messages/en.yml b/packages/ui/src/i18n/messages/en.yml
index e5206d7af9..ccbf06c78c 100644
--- a/packages/ui/src/i18n/messages/en.yml
+++ b/packages/ui/src/i18n/messages/en.yml
@@ -449,6 +449,8 @@ codeEditor:
   tabFocusOff: Tab now indents.
   expand: Expand editor
   collapse: Back to the field
+  loadFailed: 'The editor didn''t load. You can keep editing here as plain text.'
+  retry: 'Try the editor again'
   diagnostics:
     atCursor: '{severity} on line {line}: {message}'
     severity:
diff --git a/packages/ui/src/i18n/messages/fr.yml b/packages/ui/src/i18n/messages/fr.yml
index e2b2a35f0c..41325ae999 100644
--- a/packages/ui/src/i18n/messages/fr.yml
+++ b/packages/ui/src/i18n/messages/fr.yml
@@ -449,6 +449,8 @@ codeEditor:
   tabFocusOff: Tab indente maintenant.
   expand: Agrandir l'éditeur
   collapse: Revenir au champ
+  loadFailed: 'L’éditeur ne s’est pas chargé. Tu peux continuer à modifier ici en texte brut.'
+  retry: 'Recharger l’éditeur'
   diagnostics:
     atCursor: '{severity} à la ligne {line} : {message}'
     severity:

From c7f62f5c9d46e7b1ef36dd971ba3b7c338be99a2 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 19:39:19 +0200
Subject: [PATCH 70/78] fix(ui): start undo afresh when a code field's text is
 replaced

A value set from outside while the reader was elsewhere (a discard, another version, an agent's edit) was applied outside the undo history, which then mapped its old edits into the new text: undo after a discard put the discarded edit back and duplicated it. Such a replacement is now a hard edge for undo; a host answering the reader's own typing keeps their history.
---
 .../forms/code-editor/code-editor-view.tsx    | 29 ++++++++++++--
 .../code-editor/code-editor.browser.test.tsx  | 39 +++++++++++++++++++
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
index 8df876cdff..67ef2969ef 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
@@ -219,6 +219,9 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
     hover: new Compartment(),
   };
   const applied = useRef<Partial<Record<SlotName, string>>>({});
+  // Undo history in a slot of its own, so a value replaced from outside
+  // starts it afresh (`applyValue`).
+  const [historySlot] = useState(() => new Compartment());
 
   useLayoutEffect(() => {
     latest.current = props;
@@ -494,7 +497,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
           slotExtensions,
           indentUnit.of('  '),
           EditorState.tabSize.of(2),
-          history(),
+          historySlot.of(history()),
           highlightSpecialChars(),
           highlightActiveLine(),
           bracketMatching(),
@@ -535,7 +538,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
                   return;
                 }
                 pendingValue.current = null;
-                applyValue(current, waiting);
+                applyValue(current, waiting, historySlot);
               }, 0);
             },
           }),
@@ -616,7 +619,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       pendingValue.current = props.value;
       return;
     }
-    applyValue(view, props.value);
+    applyValue(view, props.value, historySlot);
   }, [props.value]);
 
   return (
@@ -681,11 +684,29 @@ function hasReason(reason: unknown): boolean {
   return typeof reason !== 'string' || reason.trim() !== '';
 }
 
-function applyValue(view: EditorView, value: string): void {
+/**
+ * A value set from outside, applied as the smallest change. While the reader
+ * is in the field it is the host answering their typing (a host may tidy
+ * what they type), and their undo history carries on. Otherwise it replaced
+ * the text — a discard, another version, an agent's edit — and it is a hard
+ * edge for undo: the history of the text it replaced is dropped (the slot is
+ * emptied, then filled with a fresh history), since undoing an old edit into
+ * the new text would put back text the reader never saw there.
+ */
+function applyValue(
+  view: EditorView,
+  value: string,
+  historySlot: Compartment,
+): void {
   const current = view.state.doc.toString();
   if (current === value) return;
+  const replaced = !view.hasFocus;
   view.dispatch({
     changes: minimalChange(current, value),
     annotations: [external.of(true), Transaction.addToHistory.of(false)],
+    ...(replaced && { effects: historySlot.reconfigure([]) }),
   });
+  if (replaced) {
+    view.dispatch({ effects: historySlot.reconfigure(history()) });
+  }
 }
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
index 30b8d12a08..3a1d72f170 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -86,7 +86,46 @@ function selection(element: HTMLElement): [number, number] {
   return [from, to];
 }
 
+/** A host whose Discard puts the saved text back, as an editor's does. */
+function WithDiscard({ saved }: { saved: string }) {
+  const [value, setValue] = useState(saved);
+  return (
+    <>
+      <CodeEditor
+        aria-label="Code"
+        language="javascript"
+        value={value}
+        onChange={setValue}
+      />
+      <button type="button" onClick={() => setValue(saved)}>
+        Discard
+      </button>
+      <output data-testid="value">{value}</output>
+    </>
+  );
+}
+
 describe('CodeEditor typing', () => {
+  // REGRESSION: undo after a discard replayed the discarded edit into the
+  // text the discard put back, duplicating it.
+  it('starts undo afresh when the text is replaced from outside', async () => {
+    render(<WithDiscard saved="return total + tax;" />);
+    const box = await content('Code');
+    await userEvent.click(box);
+    await userEvent.keyboard(
+      '{End}{Backspace}{Backspace}{Backspace}{Backspace}{Backspace}',
+    );
+    expect(screen.getByTestId('value')).toHaveTextContent('return total +');
+    await userEvent.click(screen.getByRole('button', { name: 'Discard' }));
+    expect(box).toHaveTextContent('return total + tax;');
+    await userEvent.click(box);
+    await userEvent.keyboard('{ControlOrMeta>}z{/ControlOrMeta}');
+    expect(box).toHaveTextContent('return total + tax;');
+    expect(screen.getByTestId('value')).toHaveTextContent(
+      /^return total \+ tax;$/,
+    );
+  });
+
   it('round-trips a controlled value', async () => {
     render(<Controlled initial="return 1;" />);
     const box = await content('Code');

From 7af3ab5478afb33353f3d17b83bbcfc9475e5fc5 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 19:39:23 +0200
Subject: [PATCH 71/78] fix(platform): load the code editor with the automation
 editor

Start loading the code editor when the automation editor opens, as the canvas design meant, so the first node opened finds its fields ready; and give the phone inspector's node fields the node's key, as the desktop panel has, so no half-typed text follows the reader to the next node.
---
 .../components/automation-editor.tsx           | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 6e15d1b314..10fc1df274 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -5,7 +5,10 @@ import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
 import { CatalogLoadError } from '@tale/ui/catalog/catalog-view';
 import { cn } from '@tale/ui/cn';
-import type { CodeEditorDiagnosticsStatus } from '@tale/ui/code-editor';
+import {
+  preloadCodeEditor,
+  type CodeEditorDiagnosticsStatus,
+} from '@tale/ui/code-editor';
 import { locateYamlPointer } from '@tale/ui/code-editor/locate';
 import { ContentArea } from '@tale/ui/content-area';
 import { ConfirmDialog } from '@tale/ui/dialog/confirm-dialog';
@@ -216,6 +219,11 @@ function usePausedDraft(draft: Automation | null): Automation | null {
  * canvas is the route's search, so it already belongs to the new URL — while
  * the shared dirty guard still confirms navigation before these props change. */
 export function AutomationEditor(props: AutomationEditorProps) {
+  // The inspector's fields are code: start loading the editor with the page,
+  // so the first node opened finds it ready.
+  useEffect(() => {
+    preloadCodeEditor();
+  }, []);
   return (
     // "Go to" a problem: the Problems list asks, the inspector's controls
     // answer — one registry for the page, the node sheet included.
@@ -1573,7 +1581,13 @@ function AutomationEditorScope({
     return place === 'panel' ? (
       <NodeInspector id={inspectorId} variant="panel" {...props} />
     ) : (
-      <NodeFields headingId={inspectorId} {...props} />
+      <NodeFields
+        // As in the panel: each node opens on its own fields, so no
+        // half-typed text follows the reader to the next node.
+        key={selectedNode.id}
+        headingId={inspectorId}
+        {...props}
+      />
     );
   };
 

From 01f868b0d531886ea04a6129279cf547648cb6ab Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 19:39:27 +0200
Subject: [PATCH 72/78] fix(platform): show how a mixed condition groups

a && (b || c) and (a && b) || c both read "A and B or C" on the canvas, in every language. A group of the other kind inside a condition now reads in brackets, so the two read apart.
---
 .../automations/lib/condition-text.test.ts    | 21 +++++++++++++++++++
 .../automations/lib/condition-text.ts         |  8 ++++++-
 services/platform/messages/de/automations.yml |  1 +
 services/platform/messages/en/automations.yml |  1 +
 services/platform/messages/fr/automations.yml |  1 +
 5 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/services/platform/app/features/automations/lib/condition-text.test.ts b/services/platform/app/features/automations/lib/condition-text.test.ts
index 9ecaeb6272..cd777acb9a 100644
--- a/services/platform/app/features/automations/lib/condition-text.test.ts
+++ b/services/platform/app/features/automations/lib/condition-text.test.ts
@@ -90,10 +90,31 @@ describe('conditionText', () => {
       'a of the run input is set, b of the run input is set, or c of the run input is set',
     ],
     ['nodes.check.output.ok', 'ok of Check is set'],
+    [
+      '{{ input.a && (input.b || input.c) }}',
+      'a of the run input is set and (b of the run input is set or c of the run input is set)',
+    ],
+    [
+      '{{ (input.a && input.b) || input.c }}',
+      '(a of the run input is set and b of the run input is set) or c of the run input is set',
+    ],
   ])('says %s', (text, words) => {
     expect(say(text)).toBe(words);
   });
 
+  it.each(['en', 'de', 'fr', 'de-CH'])(
+    'tells %s readers which way a mixed condition groups',
+    (locale) => {
+      const inner = say('{{ input.a && (input.b || input.c) }}', locale);
+      const outer = say('{{ (input.a && input.b) || input.c }}', locale);
+      expect(inner).not.toBeNull();
+      expect(outer).not.toBeNull();
+      expect(inner).not.toBe(outer);
+      expect(inner).toContain('(');
+      expect(outer?.startsWith('(')).toBe(true);
+    },
+  );
+
   it.each([
     ['{{ input.a && input.b && input.c && input.d }}'],
     ['{{ input.a && (input.b || (input.c && input.d)) }}'],
diff --git a/services/platform/app/features/automations/lib/condition-text.ts b/services/platform/app/features/automations/lib/condition-text.ts
index 72533fc204..ff23d1778f 100644
--- a/services/platform/app/features/automations/lib/condition-text.ts
+++ b/services/platform/app/features/automations/lib/condition-text.ts
@@ -523,7 +523,13 @@ export function renderCondition(
       for (const part of phrase.parts) {
         const text = renderCondition(part, ctx);
         if (text === null) return null;
-        parts.push(text);
+        // A group of the other kind inside reads in brackets, so
+        // `a && (b || c)` and `(a && b) || c` never read alike.
+        parts.push(
+          part.kind === 'and' || part.kind === 'or'
+            ? t('condition.group', { parts: text })
+            : text,
+        );
       }
       return new Intl.ListFormat(ctx.locale, {
         type: phrase.kind === 'and' ? 'conjunction' : 'disjunction',
diff --git a/services/platform/messages/de/automations.yml b/services/platform/messages/de/automations.yml
index 676b2fed75..eedc7bcc54 100644
--- a/services/platform/messages/de/automations.yml
+++ b/services/platform/messages/de/automations.yml
@@ -676,6 +676,7 @@ problems:
   emptyFiltered: '{filter, select, errors {Keine Fehler} warnings {Keine Warnungen} other {Keine Probleme}}'
   fieldPart: '{part}: {message}'
 condition:
+  group: '({parts})'
   gt: '{a} größer als {b} ist'
   gte: '{a} mindestens {b} ist'
   lt: '{a} kleiner als {b} ist'
diff --git a/services/platform/messages/en/automations.yml b/services/platform/messages/en/automations.yml
index 84325e27f9..0a909df0aa 100644
--- a/services/platform/messages/en/automations.yml
+++ b/services/platform/messages/en/automations.yml
@@ -666,6 +666,7 @@ problems:
   emptyFiltered: '{filter, select, errors {No errors} warnings {No warnings} other {No problems}}'
   fieldPart: '{part}: {message}'
 condition:
+  group: '({parts})'
   gt: '{a} is greater than {b}'
   gte: '{a} is at least {b}'
   lt: '{a} is less than {b}'
diff --git a/services/platform/messages/fr/automations.yml b/services/platform/messages/fr/automations.yml
index a4671078a0..1f4b5cfec2 100644
--- a/services/platform/messages/fr/automations.yml
+++ b/services/platform/messages/fr/automations.yml
@@ -678,6 +678,7 @@ problems:
   emptyFiltered: '{filter, select, errors {Aucune erreur} warnings {Aucun avertissement} other {Aucun problème}}'
   fieldPart: '{part} : {message}'
 condition:
+  group: '({parts})'
   gt: '{a} est supérieur à {b}'
   gte: '{a} vaut au moins {b}'
   lt: '{a} est inférieur à {b}'

From 08cfbbeefebe92f03a3fdb8c139085fbcbf0af6f Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 20:02:13 +0200
Subject: [PATCH 73/78] fix(ui): show a condition's problems on the step it
 guards in the List view

A condition's problems were counted on its own box, which the List view has no row for: no row showed them and no screen reader heard them, though the List view is the chart's text alternative and the default on narrow phones. The step a condition guards now carries its marker and says its problems in its description.
---
 packages/ui/src/components/flow/describe.ts   | 53 +++++++++++++++++++
 .../flow/flow-step-list.browser.test.tsx      | 20 +++++++
 .../ui/src/components/flow/flow-step-list.tsx | 13 ++++-
 3 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/flow/describe.ts b/packages/ui/src/components/flow/describe.ts
index 970a849698..1bfe95844a 100644
--- a/packages/ui/src/components/flow/describe.ts
+++ b/packages/ui/src/components/flow/describe.ts
@@ -101,6 +101,44 @@ function rowText(row: FlowRow, t: FlowTranslate): string {
     : t('node.rowWithDetail', { label: row.label, detail });
 }
 
+/** The gates in front of each step: an only-if gate, or the if/else gate
+ *  whose Yes it is — the condition the step's `when` writes. */
+function gatesOf(graph: FlowGraph): Map<string, string[]> {
+  const kinds = new Map(graph.nodes.map((node) => [node.id, node.kind]));
+  const gates = new Map<string, string[]>();
+  for (const edge of graph.edges) {
+    if (kinds.get(edge.source) !== 'gate') continue;
+    if (edge.kind !== 'gate' && edge.kind !== 'branch-yes') continue;
+    gates.set(edge.target, [...(gates.get(edge.target) ?? []), edge.source]);
+  }
+  return gates;
+}
+
+/**
+ * Problems per row of the List view, which has no row for a condition: a
+ * step's own, with those of the condition in front of it.
+ */
+export function flowStepIssues(
+  graph: FlowGraph,
+  issues: ReadonlyMap<string, IssueCounts> | undefined,
+): ReadonlyMap<string, IssueCounts> {
+  const out = new Map(issues ?? []);
+  if (issues === undefined) return out;
+  for (const [step, gates] of gatesOf(graph)) {
+    let counts = out.get(step) ?? NO_ISSUES;
+    for (const gate of gates) {
+      const own = issues.get(gate);
+      if (own === undefined) continue;
+      counts = {
+        errors: counts.errors + own.errors,
+        warnings: counts.warnings + own.warnings,
+      };
+    }
+    out.set(step, counts);
+  }
+  return out;
+}
+
 /**
  * Every node's name, description, strip and List view lines — one place,
  * so the chart and the List view say the same.
@@ -135,6 +173,7 @@ export function describeFlowGraph(
     graph.nodes.map((node) => [node.id, flowNodeTitle(node, t)]),
   );
   const drawn = graph.edges.filter((edge) => !edge.layoutOnly);
+  const guards = gatesOf(graph);
   const incoming = new Map<string, FlowEdge[]>();
   const outgoing = new Map<string, FlowEdge[]>();
   for (const edge of drawn) {
@@ -243,6 +282,20 @@ export function describeFlowGraph(
         reason,
         reads,
         ...conditions(node.id),
+        // The List view has no row for a condition: its problems are said
+        // on the step it guards.
+        ...(guards.get(node.id) ?? []).map((gate) => {
+          const gateIssues = flowNodeIssueText(
+            tIssues,
+            issues?.get(gate) ?? NO_ISSUES,
+          );
+          return gateIssues === ''
+            ? null
+            : t('node.rowWithDetail', {
+                label: titleOf(gate),
+                detail: gateIssues,
+              });
+        }),
         leadsTo(node.id),
         node.unreachable ? t('node.unreachable') : null,
       ];
diff --git a/packages/ui/src/components/flow/flow-step-list.browser.test.tsx b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
index 623f9986b6..c7416470d1 100644
--- a/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
+++ b/packages/ui/src/components/flow/flow-step-list.browser.test.tsx
@@ -13,6 +13,7 @@ import {
   branchFlowGraph,
   branchRunOverlay,
   triageFlowGraph,
+  triageInboxFlowGraph,
 } from './testing/flow-fixtures';
 import type { FlowGraph } from './types';
 
@@ -82,6 +83,25 @@ describe('FlowStepList', () => {
     ).toHaveAccessibleDescription(/Runs when the condition of Normal is false/);
   });
 
+  // REGRESSION: a condition's problems were counted on its own box, which
+  // the List view has no row for, so no row showed them and no reader
+  // heard them.
+  it('shows and says a condition’s problems on the step it guards', () => {
+    render(
+      <FlowStepList
+        graph={triageInboxFlowGraph()}
+        issues={new Map([['__gate:triage', { errors: 1, warnings: 0 }]])}
+      />,
+    );
+    const triage = screen.getByRole('button', { name: /^Triage/ });
+    expect(triage).toHaveAccessibleDescription(/1 error/);
+    expect(
+      triage.querySelector(
+        '[data-slot="flow-node-issue-marker"] [data-severity="error"]',
+      ),
+    ).not.toBeNull();
+  });
+
   it('is one Tab stop: arrows move, Home and End jump, Enter opens', async () => {
     const onSelect = vi.fn();
     render(<Harness graph={triageFlowGraph()} onSelect={onSelect} />);
diff --git a/packages/ui/src/components/flow/flow-step-list.tsx b/packages/ui/src/components/flow/flow-step-list.tsx
index 9e7f960535..e7ca841a82 100644
--- a/packages/ui/src/components/flow/flow-step-list.tsx
+++ b/packages/ui/src/components/flow/flow-step-list.tsx
@@ -14,7 +14,12 @@ import { useTranslation } from 'react-i18next';
 import { useT } from '../../i18n/client';
 import { cn } from '../../lib/cn';
 import type { IssueCounts } from '../feedback/issue-summary';
-import { describeFlowGraph, flowListFormat, type FlowWords } from './describe';
+import {
+  describeFlowGraph,
+  flowListFormat,
+  flowStepIssues,
+  type FlowWords,
+} from './describe';
 import {
   FlowNodeIssueMarker,
   flowNodeIssueFrameClass,
@@ -126,6 +131,10 @@ export function FlowStepList({
     [graph, t, tIssues, locale, issues, run, stoppedAt, reasons],
   );
   const items = useMemo(() => itemsOf(graph), [graph]);
+  const stepIssues = useMemo(
+    () => flowStepIssues(graph, issues),
+    [graph, issues],
+  );
   const order = useMemo(
     () =>
       items.flatMap((item) =>
@@ -179,7 +188,7 @@ export function FlowStepList({
       baseId={baseId}
       selected={selectedId === node.id}
       tabbable={tabStop === node.id}
-      counts={issues?.get(node.id) ?? NO_ISSUES}
+      counts={stepIssues.get(node.id) ?? NO_ISSUES}
       state={run?.nodes[node.id]?.state ?? 'idle'}
       quiet={quietRest && !highlight?.nodes.has(node.id)}
       controlsId={controlsId}

From ef45e1effc894ff0aebbd01d6e82f2ae48811c74 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 20:05:10 +0200
Subject: [PATCH 74/78] perf(platform): keep the canvas still while a field is
 typed in

The canvas's problem counts and its select handler took a new identity on every keystroke in an inspector field, which rebuilt the graph's words and re-rendered every node view, though the layout itself waits for a pause. The counts are now read against the document the canvas draws, which settles at that pause, and the handler reads the typed document through a ref.
---
 .../components/automation-editor.tsx          | 22 ++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/services/platform/app/features/automations/components/automation-editor.tsx b/services/platform/app/features/automations/components/automation-editor.tsx
index 10fc1df274..afa0393fdc 100644
--- a/services/platform/app/features/automations/components/automation-editor.tsx
+++ b/services/platform/app/features/automations/components/automation-editor.tsx
@@ -57,6 +57,7 @@ import {
   useCallback,
   useEffect,
   useId,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -551,12 +552,15 @@ function AutomationEditorScope({
     () => issueViews.map((view) => view.item),
     [issueViews],
   );
+  // Read against the document the canvas draws, which settles at a pause
+  // like the check does: a keystroke gives the canvas no new counts, so it
+  // never redraws every node per keystroke.
   const countsByNode = useMemo(
     () =>
-      automation === null
+      canvasDocument === null
         ? new Map<string, IssueCounts>()
-        : issueCountsByNode([...shownErrors, ...shownWarnings], automation),
-    [automation, shownErrors, shownWarnings],
+        : issueCountsByNode([...shownErrors, ...shownWarnings], canvasDocument),
+    [canvasDocument, shownErrors, shownWarnings],
   );
 
   // ── The canvas ────────────────────────────────────────────────────────
@@ -628,6 +632,12 @@ function AutomationEditorScope({
 
   /** A box picked on the canvas: a node, Start or End opens its inspector,
    * a condition opens its node at the condition's field. */
+  // The document as typed, read when a box is picked rather than closed
+  // over: the canvas keeps one handler however many keystrokes land.
+  const automationRef = useRef(automation);
+  useLayoutEffect(() => {
+    automationRef.current = automation;
+  });
   const selectOnCanvas = useCallback(
     (id: string | null) => {
       if (id === null) {
@@ -641,10 +651,12 @@ function AutomationEditorScope({
       }
       setSelectedId(target.nodeId);
       const index =
-        automation?.nodes.findIndex((node) => node.id === target.nodeId) ?? -1;
+        automationRef.current?.nodes.findIndex(
+          (node) => node.id === target.nodeId,
+        ) ?? -1;
       if (index >= 0) requestIssueFocus(ptr('nodes', index, 'when'));
     },
-    [automation, requestIssueFocus],
+    [requestIssueFocus],
   );
 
   // ── The inspector ────────────────────────────────────────────────────

From dd240d7f11a967b9d5ea62be20aafcd24e890eb6 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 21:02:51 +0200
Subject: [PATCH 75/78] fix(ui): map a go-to range through the edits made since
 the check

"Go to" a problem selected the check's raw offsets though the reader had typed since the check settled, so the next keystroke replaced the wrong characters. The range is now mapped from the checked text to the text shown, as the underlines are; a range inside what changed selects nothing.
---
 .../forms/code-editor/code-editor-view.tsx    | 13 +++++-
 .../code-editor/code-editor.browser.test.tsx  | 42 +++++++++++++++++++
 .../code-editor/extensions/diagnostics.ts     |  2 +-
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
index 67ef2969ef..e2abfeb76f 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
@@ -61,6 +61,7 @@ import {
   applyFix,
   diagnosticsExtension,
   goToDiagnostic,
+  mapperFrom,
   placeDiagnostics,
   setDiagnostics,
   type DiagnosticWords,
@@ -550,7 +551,17 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       view,
       focus(range, part) {
         view.focus();
-        const target = range ?? locatePart(view, latest.current.language, part);
+        // A range from the check indexes into the text it checked: mapped
+        // through the edits made since, as the underlines are; one inside
+        // what changed selects nothing rather than the wrong characters.
+        const checked = latest.current.diagnosticsFor;
+        const mapped =
+          range === undefined || checked === undefined
+            ? range
+            : (mapperFrom(checked, view.state.doc)(range[0], range[1]) ?? null);
+        if (mapped === null) return;
+        const target =
+          mapped ?? locatePart(view, latest.current.language, part);
         if (target === undefined) return;
         const [from, to] = clampRange(view.state, target);
         view.dispatch({
diff --git a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
index 3a1d72f170..1a3babf7cc 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor.browser.test.tsx
@@ -768,6 +768,48 @@ it('exposes a handle that focuses, selects and reports the selection', async ()
   expect(selection(box)).toEqual([2, 4]);
 });
 
+// REGRESSION: "go to" a problem selected the check's raw offsets, though
+// the reader had typed since the check settled; the next keystroke then
+// replaced the wrong characters.
+it('maps a go-to range through the edits made since the check', async () => {
+  function Checked() {
+    const ref = useRef<CodeEditorHandle>(null);
+    const [value, setValue] = useState('total + tax');
+    return (
+      <>
+        <CodeEditor
+          ref={ref}
+          aria-label="Code"
+          language="text"
+          value={value}
+          onChange={setValue}
+          diagnosticsFor="total + tax"
+          diagnostics={[]}
+        />
+        <button type="button" onClick={() => ref.current?.focus([8, 11])}>
+          Go to tax
+        </button>
+        <button type="button" onClick={() => ref.current?.focus([0, 5])}>
+          Go to total
+        </button>
+      </>
+    );
+  }
+  render(<Checked />);
+  const box = await content('Code');
+  await userEvent.click(box);
+  await userEvent.keyboard('{Home}net ');
+  // "tax" sat at 8–11 in the checked text; four characters were typed
+  // before it since.
+  await userEvent.click(screen.getByRole('button', { name: 'Go to tax' }));
+  expect(selection(box)).toEqual([12, 15]);
+  // "total" is next to the edit: the range is stale, so nothing is selected
+  // rather than the wrong characters.
+  const [before] = selection(box);
+  await userEvent.click(screen.getByRole('button', { name: 'Go to total' }));
+  expect(selection(box)).toEqual([before, before + 3]);
+});
+
 it('preloads without rendering', async () => {
   expect(() => preloadCodeEditor()).not.toThrow();
 });
diff --git a/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts b/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
index 970ca4986f..8d295d5c09 100644
--- a/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
+++ b/packages/ui/src/components/forms/code-editor/extensions/diagnostics.ts
@@ -120,7 +120,7 @@ function widen(doc: Text, from: number, to: number): [number, number] {
  * How text the host checked maps onto the text now shown: the common
  * prefix and suffix stay; a range inside what changed is gone.
  */
-function mapperFrom(
+export function mapperFrom(
   checked: string | undefined,
   doc: Text,
 ): (from: number, to: number) => [number, number] | null {

From ae1afc406f5551ba1e39ef0ab90280e6a02e8b71 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 21:02:56 +0200
Subject: [PATCH 76/78] fix(platform): mark a JSON field's problems in the
 author's own text

A JSON field's problems were placed against the two-space JSON the check read; in a value the author had formatted another way, a problem inside the reformatted part lost its underline and its one-click fix. The field now places them in its own text whenever that text holds the value the check read, through a diagnosticsAt function the inspectors pass.
---
 .../components/document-inspector-parts.tsx   | 25 ++++-----
 .../components/json-code-field.test.tsx       | 39 +++++++++++++
 .../components/json-code-field.tsx            | 55 ++++++++++++++++++-
 .../automations/components/node-inspector.tsx | 27 ++++-----
 4 files changed, 117 insertions(+), 29 deletions(-)

diff --git a/services/platform/app/features/automations/components/document-inspector-parts.tsx b/services/platform/app/features/automations/components/document-inspector-parts.tsx
index 27f5a06c59..5d60d0a7cc 100644
--- a/services/platform/app/features/automations/components/document-inspector-parts.tsx
+++ b/services/platform/app/features/automations/components/document-inspector-parts.tsx
@@ -182,19 +182,17 @@ export function DocumentJsonField({
   );
   const marks = useMemo(() => {
     const text = jsonFieldText(settledValue(context.settled, field, value));
-    return {
-      diagnosticsFor: text,
-      diagnostics:
-        issues.length === 0
-          ? []
-          : fieldDiagnostics({
-              views: issues,
-              fieldPointer: pointer,
-              text,
-              kind: 'json',
-              t,
-            }),
-    };
+    const at = (shown: string) =>
+      issues.length === 0
+        ? []
+        : fieldDiagnostics({
+            views: issues,
+            fieldPointer: pointer,
+            text: shown,
+            kind: 'json',
+            t,
+          });
+    return { diagnosticsFor: text, diagnostics: at(text), diagnosticsAt: at };
   }, [context.settled, field, value, issues, pointer, t]);
   return (
     <JsonCodeField
@@ -213,6 +211,7 @@ export function DocumentJsonField({
       issues={lines}
       diagnostics={marks.diagnostics}
       diagnosticsFor={marks.diagnosticsFor}
+      diagnosticsAt={marks.diagnosticsAt}
       diagnosticsStatus={context.diagnosticsStatus}
       readOnly={readOnly}
     />
diff --git a/services/platform/app/features/automations/components/json-code-field.test.tsx b/services/platform/app/features/automations/components/json-code-field.test.tsx
index 9169015f0c..1605725d1f 100644
--- a/services/platform/app/features/automations/components/json-code-field.test.tsx
+++ b/services/platform/app/features/automations/components/json-code-field.test.tsx
@@ -58,6 +58,45 @@ describe('JsonCodeField', () => {
     expect(onValue).toHaveBeenLastCalledWith({ a: 1 });
   });
 
+  // REGRESSION: a problem was placed against the two-space JSON the check
+  // read; in a value the author had formatted another way it lost its mark
+  // and its fix.
+  it('places the check’s problems in the author’s own text of the value', async () => {
+    const checked = { channel: '#ops' };
+    const placedIn = vi.fn((text: string) => {
+      const at = text.indexOf('#ops');
+      return [
+        {
+          id: 'issue-1',
+          severity: 'error' as const,
+          message: 'Unknown channel',
+          range: [at, at + 4] as const,
+        },
+      ];
+    });
+    function Checked() {
+      const [value, setValue] = useState<unknown>(checked);
+      return (
+        <JsonCodeField
+          label="Input"
+          value={value}
+          expect="object"
+          anchor={null}
+          readOnly={false}
+          onCommit={setValue}
+          diagnosticsFor={jsonFieldText(checked)}
+          diagnostics={placedIn(jsonFieldText(checked))}
+          diagnosticsAt={placedIn}
+        />
+      );
+    }
+    const { user } = render(<Checked />);
+    const box = screen.getByRole('textbox', { name: 'Input' });
+    await user.clear(box);
+    await user.type(box, '{{"channel":"#ops"}');
+    expect(placedIn).toHaveBeenLastCalledWith('{"channel":"#ops"}');
+  });
+
   it('takes a value that changed for another reason', async () => {
     const { user } = render(<Owner initial={{ a: 1 }} />);
     await user.click(screen.getByRole('button', { name: 'replace' }));
diff --git a/services/platform/app/features/automations/components/json-code-field.tsx b/services/platform/app/features/automations/components/json-code-field.tsx
index 2726f5f8ae..27b9aa40e1 100644
--- a/services/platform/app/features/automations/components/json-code-field.tsx
+++ b/services/platform/app/features/automations/components/json-code-field.tsx
@@ -9,7 +9,7 @@ import type { CodeEditorProviders } from '@tale/ui/code-editor/providers';
 import type { TemplateScan } from '@tale/ui/code-editor/template-scan';
 import { Field } from '@tale/ui/field';
 import type { FieldIssue } from '@tale/ui/field-issue-messages';
-import { useEffect, useId, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useT } from '@/lib/i18n/client';
 import { stableStringify } from '@/lib/shared/utils/stable-stringify';
@@ -26,6 +26,28 @@ export function jsonFieldText(value: unknown): string {
   }
 }
 
+const NOT_JSON = Symbol('not JSON');
+
+function parsedJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Text that is not JSON (yet) holds no value to compare.
+    return NOT_JSON;
+  }
+}
+
+/** Whether two texts hold the same JSON value, however each is formatted. */
+function sameJsonValue(a: string, b: string): boolean {
+  const left = parsedJson(a);
+  const right = parsedJson(b);
+  return (
+    left !== NOT_JSON &&
+    right !== NOT_JSON &&
+    stableStringify(left) === stableStringify(right)
+  );
+}
+
 /** What a JSON field accepts: an object, a list, or any JSON value. */
 export type JsonExpect = 'object' | 'array' | 'any';
 
@@ -55,6 +77,13 @@ export interface JsonCodeFieldProps {
   issues?: readonly FieldIssue[];
   diagnostics?: readonly CodeEditorDiagnostic[];
   diagnosticsFor?: string;
+  /**
+   * The check's problems placed in a given text of the value. With it, a
+   * field whose text holds the value the check read (`diagnosticsFor`),
+   * however the author formatted it, marks its problems in that text — not
+   * only where it matches the two-space JSON the check read.
+   */
+  diagnosticsAt?: (text: string) => readonly CodeEditorDiagnostic[];
   diagnosticsStatus?: CodeEditorDiagnosticsStatus;
   providers?: CodeEditorProviders;
   readOnly: boolean;
@@ -85,6 +114,7 @@ export function JsonCodeField({
   issues,
   diagnostics,
   diagnosticsFor,
+  diagnosticsAt,
   diagnosticsStatus,
   providers,
   readOnly,
@@ -108,6 +138,21 @@ export function JsonCodeField({
     setError(null);
   }, [value]);
 
+  // The check read the value as two-space JSON; the author may have written
+  // it another way. While the author's text holds the same value, its
+  // problems are placed in that text, so none loses its mark or its fix.
+  const placed = useMemo(() => {
+    if (
+      diagnosticsAt === undefined ||
+      diagnosticsFor === undefined ||
+      text === diagnosticsFor ||
+      !sameJsonValue(text, diagnosticsFor)
+    ) {
+      return { diagnostics, diagnosticsFor };
+    }
+    return { diagnostics: diagnosticsAt(text), diagnosticsFor: text };
+  }, [diagnosticsAt, diagnostics, diagnosticsFor, text]);
+
   const change = (next: string): void => {
     setText(next);
     if (next.trim() === '') {
@@ -160,8 +205,12 @@ export function JsonCodeField({
         expandable={expandable && !readOnly ? { title: label } : false}
         issueAnchor={anchor}
         {...(issueReveal !== undefined && { issueReveal })}
-        {...(diagnostics !== undefined && { diagnostics })}
-        {...(diagnosticsFor !== undefined && { diagnosticsFor })}
+        {...(placed.diagnostics !== undefined && {
+          diagnostics: placed.diagnostics,
+        })}
+        {...(placed.diagnosticsFor !== undefined && {
+          diagnosticsFor: placed.diagnosticsFor,
+        })}
         {...(diagnosticsStatus !== undefined && { diagnosticsStatus })}
         {...(providers !== undefined && { providers })}
         describeDiagnostics={false}
diff --git a/services/platform/app/features/automations/components/node-inspector.tsx b/services/platform/app/features/automations/components/node-inspector.tsx
index bdacaf7e17..9074bab8e3 100644
--- a/services/platform/app/features/automations/components/node-inspector.tsx
+++ b/services/platform/app/features/automations/components/node-inspector.tsx
@@ -726,6 +726,8 @@ export function InspectorTabs({
 type FieldMarks = {
   diagnostics: readonly CodeEditorDiagnostic[];
   diagnosticsFor: string;
+  /** The same problems placed in another text of the value (JSON). */
+  diagnosticsAt: (text: string) => readonly CodeEditorDiagnostic[];
 };
 
 /**
@@ -875,19 +877,17 @@ export function NodeFields({
           : ''
         : jsonFieldText(value);
     const views = fieldViews.get(field) ?? [];
-    return {
-      diagnostics:
-        nodeIndex === undefined || views.length === 0
-          ? []
-          : fieldDiagnostics({
-              views,
-              fieldPointer: ptr('nodes', nodeIndex, field),
-              text,
-              kind,
-              t,
-            }),
-      diagnosticsFor: text,
-    };
+    const at = (shown: string): readonly CodeEditorDiagnostic[] =>
+      nodeIndex === undefined || views.length === 0
+        ? []
+        : fieldDiagnostics({
+            views,
+            fieldPointer: ptr('nodes', nodeIndex, field),
+            text: shown,
+            kind,
+            t,
+          });
+    return { diagnostics: at(text), diagnosticsFor: text, diagnosticsAt: at };
   };
   const providersOf = (
     source: Parameters<typeof automationProviders>[0]['field'],
@@ -1000,6 +1000,7 @@ export function NodeFields({
             issues={issueLines}
             diagnostics={marks.diagnostics}
             diagnosticsFor={marks.diagnosticsFor}
+            diagnosticsAt={marks.diagnosticsAt}
             diagnosticsStatus={context.diagnosticsStatus}
             readOnly={readOnly}
             minRows={editor.minRows}

From fd48c82148e58eb791f3ff664e5b5196d3a869fc Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 21:03:44 +0200
Subject: [PATCH 77/78] fix(ui): name the history slot among the editor's hook
 dependencies

The undo history slot is read in the view's creation effect and in the value effect; it never changes, but the hook rules want every value an effect reads in its dependency list.
---
 .../ui/src/components/forms/code-editor/code-editor-view.tsx  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
index e2abfeb76f..50e1351730 100644
--- a/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
+++ b/packages/ui/src/components/forms/code-editor/code-editor-view.tsx
@@ -588,7 +588,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       view.destroy();
       viewRef.current = null;
     };
-  }, [portals]);
+  }, [portals, historySlot]);
 
   // Reconfigure the parts whose props changed.
   useEffect(() => {
@@ -631,7 +631,7 @@ export default function CodeEditorView(props: CodeEditorViewProps) {
       return;
     }
     applyValue(view, props.value, historySlot);
-  }, [props.value]);
+  }, [props.value, historySlot]);
 
   return (
     <>

From 7a0754a93acc90ec41a60663dfd67c0770f5b610 Mon Sep 17 00:00:00 2001
From: yannickmonney <ym@tale.dev>
Date: Fri, 9 Oct 2026 21:29:26 +0200
Subject: [PATCH 78/78] fix: carry main's guard fixes (as #4666) for this
 branch's checks

Main's AUDIT-R7 heading is longer than the spec guard allows, its CLI lint inputs miss audit_logs/request-actor.ts, and the CLI phase list misses observation.test.ts; every pull request's checks inherit the three. The same lines as #4666, so whichever lands first leaves the other a no-op.
---
 services/platform/backend/domains/audit_logs/spec.md | 2 +-
 tools/cli/scripts/cli-workflow.test.ts               | 1 +
 tools/cli/turbo.json                                 | 1 +
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/services/platform/backend/domains/audit_logs/spec.md b/services/platform/backend/domains/audit_logs/spec.md
index 4530862310..2968d95b34 100644
--- a/services/platform/backend/domains/audit_logs/spec.md
+++ b/services/platform/backend/domains/audit_logs/spec.md
@@ -66,7 +66,7 @@ spreadsheet shows it as text. Other text is exported as it is.
 
 ## Attribution
 
-### AUDIT-R7 · A key-made entry names the key’s maker and keeps the member it acts for as its subject
+### AUDIT-R7 · A key-made entry names the key’s maker, its subject the member it acts for
 
 An entry written during an authenticated API-key request names the maker as its acting
 principal and records the verified key ID, the member the key acts for and the event's
diff --git a/tools/cli/scripts/cli-workflow.test.ts b/tools/cli/scripts/cli-workflow.test.ts
index 1c7b3c0148..a1b386b169 100644
--- a/tools/cli/scripts/cli-workflow.test.ts
+++ b/tools/cli/scripts/cli-workflow.test.ts
@@ -492,6 +492,7 @@ describe('CLI command test targets', () => {
       'deployment.test.ts',
       'doctor.test.ts',
       'hash-password.test.ts',
+      'observation.test.ts',
       'platform-configuration.test.ts',
       'provision.test.ts',
     ]);
diff --git a/tools/cli/turbo.json b/tools/cli/turbo.json
index 98d55ef4fe..f7479f236c 100644
--- a/tools/cli/turbo.json
+++ b/tools/cli/turbo.json
@@ -20,6 +20,7 @@
         "$TURBO_ROOT$/services/platform/backend/domains/api_keys/owners.ts",
         "$TURBO_ROOT$/services/platform/backend/domains/api_keys/retire.ts",
         "$TURBO_ROOT$/services/platform/backend/domains/audit_logs/hash-input.ts",
+        "$TURBO_ROOT$/services/platform/backend/domains/audit_logs/request-actor.ts",
         "$TURBO_ROOT$/services/platform/backend/domains/audit_logs/service.ts",
         "$TURBO_ROOT$/services/platform/backend/domains/audit_logs/types.ts",
         "$TURBO_ROOT$/services/platform/backend/domains/audit_logs/user-scoped.ts",