@sapiom/harness 0.1.5 → 0.2.0

package/dist/core/api-key-provider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * api-key-provider — the single source of truth for the Sapiom API key that
+ * Studio actions authenticate with server-side.
+ *
+ * WHY this exists: the key is resolved ONCE at CLI boot (from the cached
+ * credential or a fresh browser login) and then handed to the server as a plain
+ * string. Two problems fell out of that snapshot:
+ *
+ *  1. It never refreshes. If the key is rotated/revoked — or the user runs the
+ *     shared login again in another process, rewriting the credential store —
+ *     the running Studio server keeps sending the stale key and every upstream
+ *     call 401s until the whole server is restarted. There was no re-auth path.
+ *  2. It conflated two different secrets. The per-boot *boot token*
+ *     (`X-Harness-Token`) only gates the LOCAL `/api` surface; the *API key*
+ *     (`sk_…`) is what authenticates upstream Sapiom calls. Studio actions must
+ *     authenticate with the held API key, never the boot token.
+ *
+ * This provider holds the current key behind a getter (so consumers read the
+ * live value, not a boot-time copy) and can `refresh()` it by re-reading the
+ * shared credential store the CLI/MCP login writes to
+ * (`~/.sapiom/credentials.json`, via `@sapiom/mcp/auth`). A 401 from an
+ * upstream call can therefore recover in place — refresh, then retry — instead
+ * of locking the Studio.
+ *
+ * NOT in scope (deliberately, per the ticket): triggering an interactive
+ * browser re-login from the server, or a broader session-auth redesign. Refresh
+ * here is a silent re-read of already-cached credentials; if the store has no
+ * newer key, the call surfaces the auth error honestly.
+ */
+/**
+ * Reads the currently-held API key and can refresh it from the shared
+ * credential store. Consumers should call {@link getKey} per request (never
+ * cache the returned string across requests) and {@link refresh} exactly once
+ * when an upstream call returns 401/403, retrying only if refresh yields a
+ * different, non-null key.
+ */
+export interface ApiKeyProvider {
+    /** The current API key, or null when the harness is not signed in. */
+    getKey(): string | null;
+    /**
+     * Re-read the shared credential store and adopt any newer key found there.
+     * Returns the (possibly updated) current key, or null if none is available.
+     * Never throws — a read failure leaves the current key untouched and is
+     * reported by returning the existing value.
+     */
+    refresh(): Promise<string | null>;
+    /**
+     * Unconditionally zero the in-memory key (sets it to null). Called on
+     * disconnect so that {@link getKey} returns null immediately — distinct from
+     * {@link refresh}, whose `if (latest)` guard deliberately preserves the
+     * cached key when the credential store has nothing to offer.
+     */
+    clear(): void;
+}
+/** Overridable reads for the credential store — a test seam. Defaults hit the
+ *  real `@sapiom/mcp/auth` store the CLI login writes to. */
+export interface ApiKeyProviderDeps {
+    /** Resolve the active environment name (governs which cached entry to read). */
+    resolveEnvironmentName?: () => Promise<string>;
+    /** Read the cached API key for a given environment, or null if absent. */
+    readApiKeyForEnv?: (envName: string) => Promise<string | null>;
+    /** Overrides SAPIOM_ENVIRONMENT for environment resolution. */
+    environment?: string;
+}
+/**
+ * Build an {@link ApiKeyProvider} seeded with the boot-time key. `refresh()`
+ * re-reads the shared credential store for the active environment and adopts a
+ * newer key when one is present — the reconciliation point between the key the
+ * CLI captured at boot and any key rotated/re-logged-in afterward.
+ */
+export declare function createApiKeyProvider(initialKey: string | null, deps?: ApiKeyProviderDeps): ApiKeyProvider;
+/**
+ * Adapt a plain `string | null` API key into an {@link ApiKeyProvider} whose
+ * `refresh()` is a no-op and `clear()` is a no-op. Lets call sites that only
+ * ever have a static key (tests, callers with no credential store) share the
+ * one provider-shaped contract without special-casing.
+ */
+export declare function staticApiKeyProvider(key: string | null): ApiKeyProvider;
+//# sourceMappingURL=api-key-provider.d.ts.map

package/dist/core/api-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-provider.d.ts","sourceRoot":"","sources":["../../src/core/api-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,MAAM,IAAI,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClC;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;6DAC6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/D,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAkBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,IAAI,GAAE,kBAAuB,GAC5B,cAAc,CA8BhB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAQvE"}

package/dist/core/api-key-provider.js

@@ -0,0 +1,91 @@
+/**
+ * api-key-provider — the single source of truth for the Sapiom API key that
+ * Studio actions authenticate with server-side.
+ *
+ * WHY this exists: the key is resolved ONCE at CLI boot (from the cached
+ * credential or a fresh browser login) and then handed to the server as a plain
+ * string. Two problems fell out of that snapshot:
+ *
+ *  1. It never refreshes. If the key is rotated/revoked — or the user runs the
+ *     shared login again in another process, rewriting the credential store —
+ *     the running Studio server keeps sending the stale key and every upstream
+ *     call 401s until the whole server is restarted. There was no re-auth path.
+ *  2. It conflated two different secrets. The per-boot *boot token*
+ *     (`X-Harness-Token`) only gates the LOCAL `/api` surface; the *API key*
+ *     (`sk_…`) is what authenticates upstream Sapiom calls. Studio actions must
+ *     authenticate with the held API key, never the boot token.
+ *
+ * This provider holds the current key behind a getter (so consumers read the
+ * live value, not a boot-time copy) and can `refresh()` it by re-reading the
+ * shared credential store the CLI/MCP login writes to
+ * (`~/.sapiom/credentials.json`, via `@sapiom/mcp/auth`). A 401 from an
+ * upstream call can therefore recover in place — refresh, then retry — instead
+ * of locking the Studio.
+ *
+ * NOT in scope (deliberately, per the ticket): triggering an interactive
+ * browser re-login from the server, or a broader session-auth redesign. Refresh
+ * here is a silent re-read of already-cached credentials; if the store has no
+ * newer key, the call surfaces the auth error honestly.
+ */
+import { readCredentials, resolveEnvironment } from "@sapiom/mcp/auth";
+async function defaultResolveEnvironmentName(environment) {
+    const env = await resolveEnvironment(environment ?? process.env.SAPIOM_ENVIRONMENT);
+    return env.name;
+}
+async function defaultReadApiKeyForEnv(envName) {
+    const entry = await readCredentials(envName);
+    return entry?.apiKey ?? null;
+}
+/**
+ * Build an {@link ApiKeyProvider} seeded with the boot-time key. `refresh()`
+ * re-reads the shared credential store for the active environment and adopts a
+ * newer key when one is present — the reconciliation point between the key the
+ * CLI captured at boot and any key rotated/re-logged-in afterward.
+ */
+export function createApiKeyProvider(initialKey, deps = {}) {
+    let current = initialKey;
+    const resolveEnvName = deps.resolveEnvironmentName ??
+        (() => defaultResolveEnvironmentName(deps.environment));
+    const readApiKey = deps.readApiKeyForEnv ?? defaultReadApiKeyForEnv;
+    return {
+        getKey() {
+            return current;
+        },
+        async refresh() {
+            try {
+                const envName = await resolveEnvName();
+                const latest = await readApiKey(envName);
+                // Only adopt a real, non-empty key. A missing/emptied credential must
+                // not clobber a key that's simply been rotated out from under us but is
+                // still the best value we have to report an honest auth error with.
+                if (latest)
+                    current = latest;
+            }
+            catch {
+                // Store unreadable (HOME missing, malformed file, …) — keep the current
+                // key. The caller's retry will simply hit the same auth error, which is
+                // the correct, honest outcome.
+            }
+            return current;
+        },
+        clear() {
+            current = null;
+        },
+    };
+}
+/**
+ * Adapt a plain `string | null` API key into an {@link ApiKeyProvider} whose
+ * `refresh()` is a no-op and `clear()` is a no-op. Lets call sites that only
+ * ever have a static key (tests, callers with no credential store) share the
+ * one provider-shaped contract without special-casing.
+ */
+export function staticApiKeyProvider(key) {
+    return {
+        getKey: () => key,
+        refresh: () => Promise.resolve(key),
+        clear: () => {
+            /* static key — clear is a no-op */
+        },
+    };
+}
+//# sourceMappingURL=api-key-provider.js.map

package/dist/core/api-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-provider.js","sourceRoot":"","sources":["../../src/core/api-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAuCvE,KAAK,UAAU,6BAA6B,CAC1C,WAAoB;IAEpB,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAClC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAC9C,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,uBAAuB,CACpC,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAyB,EACzB,OAA2B,EAAE;IAE7B,IAAI,OAAO,GAAG,UAAU,CAAC;IACzB,MAAM,cAAc,GAClB,IAAI,CAAC,sBAAsB;QAC3B,CAAC,GAAG,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,IAAI,uBAAuB,CAAC;IAEpE,OAAO;QACL,MAAM;YACJ,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,cAAc,EAAE,CAAC;gBACvC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;gBACzC,sEAAsE;gBACtE,wEAAwE;gBACxE,oEAAoE;gBACpE,IAAI,MAAM;oBAAE,OAAO,GAAG,MAAM,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;gBACxE,wEAAwE;gBACxE,+BAA+B;YACjC,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK;YACH,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAkB;IACrD,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG;QACjB,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;QACnC,KAAK,EAAE,GAAG,EAAE;YACV,mCAAmC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/canvas-body.d.ts

@@ -1,10 +1,19 @@
 /**
  * Assembles the `<div id="canvas-root">` body — the bound workflow's
- * `<section class="canvas-panel">` (header + stats + SVG diagram) and a
- * legend footer — entirely from the classes `core/canvas-template.ts`'s shell
- * already defines. This is the HTML half of the deterministic render;
- * `core/canvas-render.ts` wraps the result through `renderCanvasDocument()`
- * and writes it to the workflow's render file.
+ * `<section class="canvas-panel">` (title/summary header + SVG diagram),
+ * entirely from the classes `core/canvas-template.ts`'s shell already defines.
+ * This is the HTML half of the deterministic render; `core/canvas-render.ts`
+ * wraps the result through `renderCanvasDocument()` and writes it to the
+ * workflow's render file.
+ *
+ * The panel ends with the color/shape legend (only the node kinds actually
+ * used, plus a cross-workflow row when relevant) so the diagram reads on its
+ * own. It sits at the bottom of `#canvas-root` INSIDE the iframe — safe from
+ * the SPA's floating zoom/fit controls because the pane reserves a strip below
+ * the iframe for them (see `.canvas-visual { padding-bottom }` in
+ * web/src/styles.css), so the two never sit "l'un sur l'autre". The only thing
+ * deliberately dropped is the old prose footer note ("Static preview —
+ * regenerate…"), which was pure noise.
  */
 import type { CanvasEdgeKind, CanvasGraph, CanvasNodeKind } from "./canvas-graph.js";
 import type { CanvasEnrichment } from "./canvas-enrichment.js";
@@ -12,34 +21,25 @@ export interface WorkflowPanelMeta {
     title: string;
     badges?: string[];
 }
-/** How enrichment content reaches the panel/footer builders: the validated
- *  content itself plus whether its source fingerprint no longer matches the
- *  workflow's current sources (kept displayed, marked stale). */
-export interface PanelEnrichment {
-    enrichment: CanvasEnrichment;
-    stale: boolean;
-}
-/** One workflow's full panel: title/badges header, step/entry stats, SVG
- *  diagram — with any enrichment merged in (summary line, node/edge
- *  annotations, a "stale" chip when its fingerprint no longer matches). */
-export declare function buildWorkflowPanelHtml(graph: CanvasGraph, meta: WorkflowPanelMeta, panelEnrichment?: PanelEnrichment | null): string;
+/**
+ * The color/shape key for one diagram: only the node kinds that actually appear
+ * (in stable order), plus a cross-workflow row when the graph has cross edges.
+ * Returns "" when nothing is worth keying, so the panel omits the footer.
+ */
+export declare function buildLegendHtml(nodeKinds: Set<CanvasNodeKind>, edgeKinds: Set<CanvasEdgeKind>): string;
+/** One workflow's full panel: title/badges + summary header and the SVG
+ *  diagram, with the deterministic enrichment merged in (summary line and
+ *  node/edge annotations), plus the embedded step-graph payload the Steps tab
+ *  reads. */
+export declare function buildWorkflowPanelHtml(graph: CanvasGraph, meta: WorkflowPanelMeta, enrichment?: CanvasEnrichment | null): string;
 /** A degraded panel for a workflow whose graph couldn't be extracted — never
  *  a crash, never a silent fallback to the LLM path, just an honest reason
  *  styled through the same shell. */
 export declare function buildErrorPanelHtml(title: string, reason: string): string;
-/** Legend footer covering every node/edge kind actually used across every
- *  rendered panel (aggregate, not per-panel — matches the template's shape). */
-export declare function buildLegendHtml(nodeKinds: Set<CanvasNodeKind>, edgeKinds: Set<CanvasEdgeKind>): string;
-/** Joins panels + a footer (enrichment notes/cross-workflow tie, legend,
- *  note) into the final `#canvas-root` body — the string
- *  `renderCanvasDocument()` wraps. */
+/** Joins the workflow panel(s) into the final `#canvas-root` body — the string
+ *  `renderCanvasDocument()` wraps. Each panel already carries its own legend
+ *  footer (see `buildWorkflowPanelHtml`); there is no document-level footer. */
 export declare function assembleCanvasBody(input: {
     panels: string[];
-    legend: string;
-    note: string;
-    /** Enrichment footer facts (already schema-bounded), rendered as a list. */
-    notes?: string[];
-    /** Enrichment's "how this ties into the other workflows" line. */
-    crossWorkflow?: string;
 }): string;
 //# sourceMappingURL=canvas-body.d.ts.map

package/dist/core/canvas-body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-body.d.ts","sourceRoot":"","sources":["../../src/core/canvas-body.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;iEAEiE;AACjE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;2EAE2E;AAC3E,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,iBAAiB,EACvB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,GACvC,MAAM,CA4BR;AAED;;qCAEqC;AACrC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYzE;AAmBD;gFACgF;AAChF,wBAAgB,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,MAAM,CAWtG;AAED;;sCAEsC;AACtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAcT"}
+{"version":3,"file":"canvas-body.d.ts","sourceRoot":"","sources":["../../src/core/canvas-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,MAAM,CAYtG;AAwED;;;aAGa;AACb,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,iBAAiB,EACvB,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,GACnC,MAAM,CA2BR;AAED;;qCAEqC;AACrC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYzE;AAED;;gFAEgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,CAEtE"}

package/dist/core/canvas-body.js

@@ -1,36 +1,134 @@
-import { renderGraphSvg } from "./canvas-svg.js";
+import { renderGraphSvg, usedKinds } from "./canvas-svg.js";
 function esc(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-/** One workflow's full panel: title/badges header, step/entry stats, SVG
- *  diagram — with any enrichment merged in (summary line, node/edge
- *  annotations, a "stale" chip when its fingerprint no longer matches). */
-export function buildWorkflowPanelHtml(graph, meta, panelEnrichment) {
+const NODE_KIND_LABEL = {
+    entry: "entry / active step",
+    step: "step",
+    pause: "pause / waits for input",
+    "terminal-success": "terminal · success",
+    "terminal-warn": "terminal · escalation",
+    "launched-workflow": "launches another workflow",
+};
+const NODE_KIND_ORDER = [
+    "entry",
+    "step",
+    "pause",
+    "terminal-success",
+    "terminal-warn",
+    "launched-workflow",
+];
+/**
+ * The color/shape key for one diagram: only the node kinds that actually appear
+ * (in stable order), plus a cross-workflow row when the graph has cross edges.
+ * Returns "" when nothing is worth keying, so the panel omits the footer.
+ */
+export function buildLegendHtml(nodeKinds, edgeKinds) {
+    const items = NODE_KIND_ORDER.filter((k) => nodeKinds.has(k)).map((k) => `<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--${k}"></span>${NODE_KIND_LABEL[k]}</span>`);
+    if (edgeKinds.has("cross")) {
+        items.push(`<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--cross"></span>cross-workflow signal/handoff</span>`);
+    }
+    if (items.length === 0)
+        return "";
+    return `<footer class="canvas-legend">${items.join("")}</footer>`;
+}
+/**
+ * Serializes the graph (enrichment merged) into the JSON payload the app's
+ * Steps tab / inspector consumes, embedded as a `<script id="sapiom-graph">`
+ * data block that `bootCanvasGraph` (canvas-run-state.ts) posts to the parent.
+ *
+ * The projection mirrors `renderGraphSvg`'s merge EXACTLY so the Steps tab and
+ * the drawn board never disagree: `role` = the node's sublabel (enrichment
+ * override first), `description` = the enrichment hover text, and each edge's
+ * `label` is keyed `from->to`. Web-only fields the server graph doesn't carry
+ * (timeout / input schema / capabilities) are omitted — `parseCanvasGraph`
+ * defaults them, so the drill-down degrades to names + roles + branch facts.
+ *
+ * `<` is escaped to `<` so a label containing `</script>` can't break out
+ * of the JSON block; the result is still valid JSON.
+ */
+function buildGraphPayload(graph, enrichment) {
+    const payload = {
+        name: graph.manifestName,
+        entry: graph.entry,
+        nodes: graph.nodes.map((n) => {
+            const details = enrichment?.nodeDetails?.[n.id];
+            return {
+                id: n.id,
+                kind: n.kind,
+                label: n.label,
+                role: details?.sublabel ?? n.sublabel ?? "",
+                // Manifest-authored description (Option A) wins; enrichment is the
+                // legacy fallback (currently always undefined).
+                description: details?.description ?? n.description ?? "",
+                inputSchema: n.inputSchema ?? null,
+                capabilities: n.capabilities ?? [],
+                timeoutMs: n.timeoutMs ?? null,
+            };
+        }),
+        edges: graph.edges.map((e) => ({
+            from: e.from,
+            to: e.to,
+            kind: e.kind,
+            label: enrichment?.edgeLabels?.[`${e.from}->${e.to}`] ?? e.label ?? "",
+        })),
+        warnings: graph.warnings,
+    };
+    return JSON.stringify(payload).replace(/</g, "\\u003c");
+}
+/** The workflow-level overview the Canvas tab's bottom panel shows: a
+ *  deterministic stats line ("N steps · M exits · <entry> entry"), the shape
+ *  summary as the description, and the graph's validation notes. Embedded as a
+ *  JSON data block (read by bootCanvasOverview), the same pattern as the step
+ *  graph — everything here is derived from the graph, no LLM. */
+function buildOverviewPayload(graph, enrichment) {
+    const exits = graph.nodes.filter((n) => n.kind === "terminal-success" || n.kind === "terminal-warn").length;
+    const steps = graph.nodes.length - exits;
+    const entryLabel = graph.nodes.find((n) => n.id === graph.entry)?.label ?? graph.entry;
+    const parts = [`${steps} ${steps === 1 ? "step" : "steps"}`];
+    if (exits > 0)
+        parts.push(`${exits} ${exits === 1 ? "exit" : "exits"}`);
+    if (entryLabel)
+        parts.push(`${entryLabel} entry`);
+    const overview = {
+        // Human-authored workflow description from the manifest (Option A); "" when
+        // the workflow declares none (the shape summary still renders on the board).
+        description: graph.description ?? "",
+        stats: parts.join(" · "),
+        notes: enrichment?.notes ?? [],
+    };
+    // JSON in a <script> block: neutralize any "</script>"/"<" in derived text.
+    return JSON.stringify(overview).replace(/</g, "\\u003c");
+}
+/** One workflow's full panel: title/badges + summary header and the SVG
+ *  diagram, with the deterministic enrichment merged in (summary line and
+ *  node/edge annotations), plus the embedded step-graph payload the Steps tab
+ *  reads. */
+export function buildWorkflowPanelHtml(graph, meta, enrichment) {
     const badges = (meta.badges ?? [])
         .map((b) => `<span class="canvas-badge">${esc(b)}</span>`)
         .join("");
     const warningBadge = graph.warnings.length > 0
         ? `<span class="canvas-badge">${graph.warnings.length} warning${graph.warnings.length === 1 ? "" : "s"}</span>`
         : "";
-    const enrichment = panelEnrichment?.enrichment ?? null;
-    const staleBadge = panelEnrichment?.stale
-        ? `<span class="canvas-badge canvas-badge--stale">stale — Refresh</span>`
-        : "";
     const summary = enrichment?.summary ? `\n    <p class="canvas-subtitle">${esc(enrichment.summary)}</p>` : "";
+    const used = usedKinds(graph);
+    const legend = buildLegendHtml(used.nodeKinds, used.edgeKinds);
+    const legendHtml = legend ? `\n  ${legend}` : "";
+    const graphData = buildGraphPayload(graph, enrichment);
+    const overviewData = buildOverviewPayload(graph, enrichment);
     return `<section class="canvas-panel">
   <header class="canvas-header">
     <div class="canvas-title-row">
       <h1 class="canvas-title">${esc(meta.title)}</h1>
-      ${badges}${warningBadge}${staleBadge}
+      ${badges}${warningBadge}
     </div>${summary}
-    <div class="canvas-stats">
-      <div class="canvas-stat"><span class="canvas-stat-value">${graph.nodes.length}</span><span class="canvas-stat-label">steps</span></div>
-      <div class="canvas-stat"><span class="canvas-stat-value">${esc(graph.entry)}</span><span class="canvas-stat-label">entry</span></div>
-    </div>
   </header>
   <div class="canvas-diagram-panel">
 ${renderGraphSvg(graph, enrichment)}
-  </div>
+  </div>${legendHtml}
+  <script type="application/json" id="sapiom-graph">${graphData}</script>
+  <script type="application/json" id="sapiom-overview">${overviewData}</script>
 </section>`;
 }
 /** A degraded panel for a workflow whose graph couldn't be extracted — never
@@ -49,46 +147,10 @@ export function buildErrorPanelHtml(title, reason) {
   </div>
 </section>`;
 }
-const NODE_KIND_LABEL = {
-    entry: "entry / active step",
-    step: "step",
-    pause: "pause / waits for input",
-    "terminal-success": "terminal · success",
-    "terminal-warn": "terminal · escalation",
-    "launched-workflow": "launches another workflow",
-};
-const NODE_KIND_ORDER = [
-    "entry",
-    "step",
-    "pause",
-    "terminal-success",
-    "terminal-warn",
-    "launched-workflow",
-];
-/** Legend footer covering every node/edge kind actually used across every
- *  rendered panel (aggregate, not per-panel — matches the template's shape). */
-export function buildLegendHtml(nodeKinds, edgeKinds) {
-    const items = NODE_KIND_ORDER.filter((k) => nodeKinds.has(k)).map((k) => `<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--${k}"></span>${NODE_KIND_LABEL[k]}</span>`);
-    if (edgeKinds.has("cross")) {
-        items.push(`<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--cross"></span>cross-workflow signal/handoff</span>`);
-    }
-    return `<div class="canvas-legend">${items.join("")}</div>`;
-}
-/** Joins panels + a footer (enrichment notes/cross-workflow tie, legend,
- *  note) into the final `#canvas-root` body — the string
- *  `renderCanvasDocument()` wraps. */
+/** Joins the workflow panel(s) into the final `#canvas-root` body — the string
+ *  `renderCanvasDocument()` wraps. Each panel already carries its own legend
+ *  footer (see `buildWorkflowPanelHtml`); there is no document-level footer. */
 export function assembleCanvasBody(input) {
-    const parts = [...input.panels];
-    const notesHtml = input.notes && input.notes.length > 0
-        ? `\n  <ul class="canvas-notes">${input.notes.map((n) => `<li>${esc(n)}</li>`).join("")}</ul>`
-        : "";
-    const crossHtml = input.crossWorkflow
-        ? `\n  <p class="canvas-cross-workflow">${esc(input.crossWorkflow)}</p>`
-        : "";
-    parts.push(`<footer class="canvas-footer">${notesHtml}${crossHtml}
-${input.legend}
-  <p class="canvas-note">${esc(input.note)}</p>
-</footer>`);
-    return parts.join("\n\n");
+    return input.panels.join("\n\n");
 }
 //# sourceMappingURL=canvas-body.js.map

package/dist/core/canvas-body.js.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-body.js","sourceRoot":"","sources":["../../src/core/canvas-body.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canvas-body.js","sourceRoot":"","sources":["../../src/core/canvas-body.ts"],"names":[],"mappings":"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"}

package/dist/core/canvas-derive.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Deterministic canvas enrichment (no LLM, no user token, no file reads, no
+ * cache). Given the already-extracted CanvasGraph (core/canvas-graph.ts), it
+ * computes the same CanvasEnrichment shape the old AI task returned
+ * (core/canvas-enrichment.ts) — a summary line, footer notes, and a
+ * cross-workflow tie — entirely from the graph's own structure. Pure and
+ * total: the same graph in always yields the same enrichment out, and every
+ * string is kept within ENRICHMENT_LIMITS so the layout can't break.
+ *
+ * What it deliberately does NOT reproduce from the retired AI pass: free-prose
+ * per-step descriptions and condition-named edge labels, which needed a reading
+ * of the step bodies. The base render already conveys role (node border +
+ * classify-derived sublabel) and outcome (edge color), so their absence
+ * degrades to "less prose", never "less structure".
+ */
+import { type CanvasEnrichment } from "./canvas-enrichment.js";
+import type { CanvasGraph } from "./canvas-graph.js";
+/**
+ * A one-line description of the workflow's shape — step count, branch points,
+ * and terminal outcomes — the deterministic stand-in for the AI summary. Reads
+ * the same graph the diagram is drawn from, so it can never disagree with it.
+ */
+export declare function deriveSummary(graph: CanvasGraph): string;
+/**
+ * Footer notes: the graph's own validation warnings (unreachable steps, no path
+ * to a terminal) — facts worth surfacing that the diagram can't show on its own.
+ * Undefined when the graph is clean, capped to the contract's count/length.
+ */
+export declare function deriveNotes(graph: CanvasGraph): string[] | undefined;
+/**
+ * The cross-workflow tie, derived from the dashed launched-workflow nodes the
+ * extraction already merged in (core/canvas-graph.ts's mergeLaunchesIntoGraph,
+ * fed by the grep in core/canvas-interconnections.ts). Undefined when this
+ * workflow launches none.
+ */
+export declare function deriveCrossWorkflow(graph: CanvasGraph): string | undefined;
+/**
+ * Builds the deterministic enrichment for a graph. Only sets a field when it
+ * has real content, so an annotation-light but valid workflow renders its clean
+ * base — matching the "every field optional" contract the AI enrichment had.
+ */
+export declare function deriveEnrichment(graph: CanvasGraph): CanvasEnrichment;
+//# sourceMappingURL=canvas-derive.d.ts.map

package/dist/core/canvas-derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-derive.d.ts","sourceRoot":"","sources":["../../src/core/canvas-derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,mBAAmB,CAAC;AAgBjF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAuBxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,GAAG,SAAS,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB,CAOrE"}

package/dist/core/canvas-derive.js

@@ -0,0 +1,95 @@
+/**
+ * Deterministic canvas enrichment (no LLM, no user token, no file reads, no
+ * cache). Given the already-extracted CanvasGraph (core/canvas-graph.ts), it
+ * computes the same CanvasEnrichment shape the old AI task returned
+ * (core/canvas-enrichment.ts) — a summary line, footer notes, and a
+ * cross-workflow tie — entirely from the graph's own structure. Pure and
+ * total: the same graph in always yields the same enrichment out, and every
+ * string is kept within ENRICHMENT_LIMITS so the layout can't break.
+ *
+ * What it deliberately does NOT reproduce from the retired AI pass: free-prose
+ * per-step descriptions and condition-named edge labels, which needed a reading
+ * of the step bodies. The base render already conveys role (node border +
+ * classify-derived sublabel) and outcome (edge color), so their absence
+ * degrades to "less prose", never "less structure".
+ */
+import { ENRICHMENT_LIMITS } from "./canvas-enrichment.js";
+/** Truncates to a hard cap with an ellipsis. The derivations below stay well
+ *  under their caps; this just makes the same guarantee the contract does. */
+function clamp(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+function countKind(nodes, kind) {
+    return nodes.filter((n) => n.kind === kind).length;
+}
+function plural(n, one, many = `${one}s`) {
+    return n === 1 ? one : many;
+}
+/**
+ * A one-line description of the workflow's shape — step count, branch points,
+ * and terminal outcomes — the deterministic stand-in for the AI summary. Reads
+ * the same graph the diagram is drawn from, so it can never disagree with it.
+ */
+export function deriveSummary(graph) {
+    // Real steps only — exclude the dashed launched-workflow placeholders.
+    const stepCount = graph.nodes.filter((n) => n.kind !== "launched-workflow").length;
+    // A branch point is a step that fans out to multiple successors; the graph
+    // marks exactly those edges "branching" (core/canvas-graph.ts's edgesForStep).
+    const branchPoints = new Set(graph.edges.filter((e) => e.kind === "branching").map((e) => e.from)).size;
+    const success = countKind(graph.nodes, "terminal-success");
+    const warn = countKind(graph.nodes, "terminal-warn");
+    const parts = [`${stepCount} ${plural(stepCount, "step")}`];
+    if (branchPoints > 0)
+        parts.push(`${branchPoints} ${plural(branchPoints, "branch point")}`);
+    const outcomes = [];
+    if (success > 0)
+        outcomes.push(`${success} success`);
+    if (warn > 0)
+        outcomes.push(`${warn} escalation`);
+    if (outcomes.length > 0) {
+        parts.push(`${outcomes.join(" / ")} ${plural(success + warn, "outcome")}`);
+    }
+    return clamp(parts.join(" · "), ENRICHMENT_LIMITS.summary);
+}
+/**
+ * Footer notes: the graph's own validation warnings (unreachable steps, no path
+ * to a terminal) — facts worth surfacing that the diagram can't show on its own.
+ * Undefined when the graph is clean, capped to the contract's count/length.
+ */
+export function deriveNotes(graph) {
+    if (graph.warnings.length === 0)
+        return undefined;
+    const notes = graph.warnings
+        .slice(0, ENRICHMENT_LIMITS.noteCount)
+        .map((w) => clamp(w, ENRICHMENT_LIMITS.note));
+    return notes.length > 0 ? notes : undefined;
+}
+/**
+ * The cross-workflow tie, derived from the dashed launched-workflow nodes the
+ * extraction already merged in (core/canvas-graph.ts's mergeLaunchesIntoGraph,
+ * fed by the grep in core/canvas-interconnections.ts). Undefined when this
+ * workflow launches none.
+ */
+export function deriveCrossWorkflow(graph) {
+    const launched = graph.nodes.filter((n) => n.kind === "launched-workflow").map((n) => n.label);
+    if (launched.length === 0)
+        return undefined;
+    const unique = [...new Set(launched)].sort();
+    return clamp(`Launches ${unique.join(", ")}.`, ENRICHMENT_LIMITS.crossWorkflow);
+}
+/**
+ * Builds the deterministic enrichment for a graph. Only sets a field when it
+ * has real content, so an annotation-light but valid workflow renders its clean
+ * base — matching the "every field optional" contract the AI enrichment had.
+ */
+export function deriveEnrichment(graph) {
+    const enrichment = { summary: deriveSummary(graph) };
+    const notes = deriveNotes(graph);
+    if (notes)
+        enrichment.notes = notes;
+    const crossWorkflow = deriveCrossWorkflow(graph);
+    if (crossWorkflow)
+        enrichment.crossWorkflow = crossWorkflow;
+    return enrichment;
+}
+//# sourceMappingURL=canvas-derive.js.map