@sapiom/harness 0.0.0 → 0.1.0

package/dist/core/canvas-render.js

@@ -0,0 +1,145 @@
+/**
+ * The deterministic render pipeline: given a session bound to a workflow,
+ * extracts that workflow's graph (core/canvas-cache.ts — cached, so an
+ * unchanged workflow never pays for a second child process), builds the SVG +
+ * panel markup (core/canvas-svg.ts, core/canvas-body.ts), wraps it through
+ * the shared document shell (core/canvas-template.ts's
+ * `renderCanvasDocument`), and writes it to the workflow's own render file,
+ * `<cwd>/.sapiom/canvas/renders/<slug>.html`. Zero LLM involvement —
+ * extraction failure degrades to an honest error panel, never a crash.
+ *
+ * Renders are per-WORKFLOW files (not a shared index.html) so switching the
+ * binding never rewrites anything another binding depends on — the server
+ * (src/server/canvas.ts) resolves the session's current binding at request
+ * time and serves the matching render. `index.html` remains the
+ * agent-authored/custom canvas and is never touched here. An unbound session
+ * renders nothing at all (no extraction, no write): the server serves the
+ * existing empty-state/custom canvas for it.
+ *
+ * The write alone is enough to hot-reload an open canvas pane —
+ * CanvasWatcherManager already watches the whole session cwd and treats any
+ * change under `.sapiom/canvas/` as a reload signal, regardless of who wrote
+ * it.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { CANVAS_CACHE_DIR, CANVAS_RENDERS_DIR } from "../shared/types.js";
+import { renderCanvasDocument } from "./canvas-template.js";
+import { extractWorkflowGraphCached } from "./canvas-cache.js";
+import { readEnrichmentCacheFile } from "./canvas-enrichment.js";
+import { usedKinds } from "./canvas-svg.js";
+import { assembleCanvasBody, buildErrorPanelHtml, buildLegendHtml, buildWorkflowPanelHtml, } from "./canvas-body.js";
+/**
+ * Stable, filesystem-safe render-file name for a workflow: its directory
+ * basename (readable in `ls`) plus a short path hash (two same-named
+ * workflows at different paths can never collide). Shared by the writer here
+ * and the server's request-time resolution — must stay deterministic.
+ */
+export function slugForWorkflowPath(workflowPath) {
+    const base = path
+        .basename(workflowPath)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "workflow";
+    const hash = createHash("sha256").update(path.resolve(workflowPath)).digest("hex").slice(0, 8);
+    return `${base}-${hash}`;
+}
+/** Absolute path of `workflowPath`'s render file under `cwd`'s canvas dir. */
+export function renderFileFor(cwd, workflowPath) {
+    return path.join(cwd, CANVAS_RENDERS_DIR, `${slugForWorkflowPath(workflowPath)}.html`);
+}
+/** Absolute path of `workflowPath`'s enrichment cache file under `cwd`'s
+ *  canvas dir — same slug scheme as the render file. */
+export function enrichmentCacheFileFor(cwd, workflowPath) {
+    return path.join(cwd, CANVAS_CACHE_DIR, `${slugForWorkflowPath(workflowPath)}.json`);
+}
+function badgesFor(workflow) {
+    return [workflow.definitionId != null ? "deployed" : "local only"];
+}
+function buildSingleBody(workflow, graph, reason, panelEnrichment) {
+    if (!graph) {
+        return assembleCanvasBody({
+            panels: [buildErrorPanelHtml(workflow.name, reason ?? "unknown extraction failure")],
+            legend: "",
+            note: "Static preview — this workflow has a build error; regenerate once it's fixed.",
+        });
+    }
+    const used = usedKinds(graph);
+    return assembleCanvasBody({
+        panels: [buildWorkflowPanelHtml(graph, { title: workflow.name, badges: badgesFor(workflow) }, panelEnrichment)],
+        legend: buildLegendHtml(used.nodeKinds, used.edgeKinds),
+        note: "Static preview — re-renders automatically when the workflow changes.",
+        ...(panelEnrichment?.enrichment.notes ? { notes: panelEnrichment.enrichment.notes } : {}),
+        ...(panelEnrichment?.enrichment.crossWorkflow
+            ? { crossWorkflow: panelEnrichment.enrichment.crossWorkflow }
+            : {}),
+    });
+}
+/**
+ * Renders `session`'s bound workflow to its per-workflow render file. Never
+ * throws — every failure mode (extraction, filesystem) is captured in the
+ * returned outcome instead. Unbound sessions are a cheap no-op: no
+ * extraction, no write (`mode: "empty"`).
+ */
+export async function renderCanvasForSession(session, workflows, options = {}) {
+    const bound = session.boundWorkflowPath ? workflows.find((w) => w.path === session.boundWorkflowPath) : undefined;
+    if (!bound) {
+        return { mode: "empty", extractionFailed: [] };
+    }
+    return renderWorkflowRenderFile(session.cwd, bound, options);
+}
+/**
+ * Renders ONE workflow to its render file under `cwd`, merging in any cached
+ * enrichment (fresh or stale — stale gets the chip; the base structure is
+ * always freshly extracted either way). This is the write path shared by
+ * bind/create/macro renders (via `renderCanvasForSession`) and by the
+ * enrichment task's own completion re-render (core/canvas-enrich.ts), which
+ * targets a workflow directly — the session may have switched bindings while
+ * the task ran, and the render file is per-workflow anyway.
+ */
+export async function renderWorkflowRenderFile(cwd, bound, options = {}) {
+    const { result, cached, fingerprint } = await extractWorkflowGraphCached(bound.path);
+    const failed = !result.ok;
+    // The enrichment cache only ever decorates a successful extraction — an
+    // error panel with AI annotations for steps it can't show would be noise.
+    let panelEnrichment = null;
+    if (result.ok) {
+        const entry = await readEnrichmentCacheFile(enrichmentCacheFileFor(cwd, bound.path));
+        if (entry) {
+            panelEnrichment = { enrichment: entry.enrichment, stale: entry.sourceFingerprint !== fingerprint };
+        }
+    }
+    const body = buildSingleBody(bound, result.ok ? result.graph : null, result.ok ? null : result.reason, panelEnrichment);
+    const renderPath = renderFileFor(cwd, bound.path);
+    const outcome = {
+        mode: "single",
+        workflowPath: bound.path,
+        renderPath,
+        extractionFailed: failed ? [bound.name] : [],
+        cachedExtraction: cached,
+        ...(panelEnrichment ? { enrichmentApplied: true, enrichmentStale: panelEnrichment.stale } : {}),
+    };
+    // An unprompted render that failed to extract must not destroy an existing
+    // (possibly good) diagram for this workflow — e.g. a project that merely
+    // hasn't run `npm install` yet after a fresh clone.
+    if (options.preserveExistingOnFailure && failed) {
+        const exists = await fs
+            .access(renderPath)
+            .then(() => true)
+            .catch(() => false);
+        if (exists) {
+            outcome.preservedExisting = true;
+            return outcome;
+        }
+    }
+    try {
+        await fs.mkdir(path.dirname(renderPath), { recursive: true });
+        await fs.writeFile(renderPath, renderCanvasDocument(body), "utf8");
+    }
+    catch (err) {
+        outcome.writeError = err instanceof Error ? err.message : String(err);
+    }
+    return outcome;
+}
+//# sourceMappingURL=canvas-render.js.map

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

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

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

@@ -0,0 +1,50 @@
+/**
+ * Server-side SVG layout for a `CanvasGraph` (see core/canvas-graph.ts),
+ * emitting markup against the classes `core/canvas-template.ts`'s CSS shell
+ * already defines (node--entry/step/pause/terminal-success/terminal-warn/
+ * launched-workflow, canvas-edge/--success/--warn/--cross/--launch). No DOM,
+ * no client-side script — the
+ * whole diagram is a static string built once, at render time.
+ *
+ * Layout: longest-path-from-roots layering (a Kahn's-algorithm variant),
+ * robust to reconverging branches (diamonds) and defensively bounded against
+ * a cycle (a malformed/adversarial manifest should degrade, not hang). Ported
+ * from the layout math in an earlier client-side renderer (see git history of
+ * canvas-template.ts, commit "canvas kit — LLM writes data, not HTML") — the
+ * geometry is unchanged, only where it runs (server, not browser).
+ */
+import type { CanvasEdge, CanvasEdgeKind, CanvasGraph, CanvasNode, CanvasNodeKind } from "./canvas-graph.js";
+import type { CanvasEnrichment, CanvasLayoutHints } from "./canvas-enrichment.js";
+export declare const NODE_W = 176;
+export declare const NODE_H = 64;
+export interface GraphLayout {
+    pos: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    width: number;
+    height: number;
+}
+/** Assigns each node the longest-path layer reachable from a root (an
+ *  in-degree-0 node). Nodes never reached by a root (only possible on a
+ *  disconnected/cyclic fragment) fall to the layer just past the deepest
+ *  known one, so they still render instead of vanishing. */
+export declare function computeLayers(nodes: readonly CanvasNode[], edges: readonly CanvasEdge[]): Map<string, number>;
+/** Computes (x, y) for every node and the overall canvas size. Nodes in the
+ *  same layer are centered as a row; layers stack top to bottom. An
+ *  enrichment's `laneOrder` hint reorders nodes WITHIN their computed layer
+ *  only — layer assignment itself stays purely structural. */
+export declare function layoutGraph(graph: CanvasGraph, laneOrder?: CanvasLayoutHints["laneOrder"]): GraphLayout;
+/** Renders one graph's `<svg>` diagram, merging in any enrichment content
+ *  (node sublabels/descriptions, edge labels, group bands, lane order) — all
+ *  of it pre-bounded plain strings (core/canvas-enrichment.ts), escaped here
+ *  like every other text. Assumes the shared `<defs>` (glow filter + arrow
+ *  markers) are already present once at the document level — see
+ *  `renderCanvasDocument`'s `SVG_DEFS` — so this never emits its own. */
+export declare function renderGraphSvg(graph: CanvasGraph, enrichment?: CanvasEnrichment | null): string;
+/** Every node/edge kind actually used, for the shared legend footer. */
+export declare function usedKinds(graph: CanvasGraph): {
+    nodeKinds: Set<CanvasNodeKind>;
+    edgeKinds: Set<CanvasEdgeKind>;
+};
+//# sourceMappingURL=canvas-svg.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-svg.d.ts","sourceRoot":"","sources":["../../src/core/canvas-svg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC7G,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElF,eAAO,MAAM,MAAM,MAAM,CAAC;AAC1B,eAAO,MAAM,MAAM,KAAK,CAAC;AAOzB,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;4DAG4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqC7G;AAED;;;8DAG8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,GAAG,WAAW,CAyBvG;AAkFD;;;;;yEAKyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CA4E/F;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAAC,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,CAAA;CAAE,CAKhH"}

package/dist/core/canvas-svg.js

@@ -0,0 +1,240 @@
+export const NODE_W = 176;
+export const NODE_H = 64;
+const LAYER_GAP = 72;
+const COL_GAP = 32;
+const MARGIN = 40;
+/** How far a group band extends past its member nodes' boxes. */
+const GROUP_PAD = 10;
+/** Assigns each node the longest-path layer reachable from a root (an
+ *  in-degree-0 node). Nodes never reached by a root (only possible on a
+ *  disconnected/cyclic fragment) fall to the layer just past the deepest
+ *  known one, so they still render instead of vanishing. */
+export function computeLayers(nodes, edges) {
+    const ids = nodes.map((n) => n.id);
+    const idSet = new Set(ids);
+    const indeg = new Map(ids.map((id) => [id, 0]));
+    const adj = new Map(ids.map((id) => [id, []]));
+    for (const e of edges) {
+        if (!idSet.has(e.from) || !idSet.has(e.to))
+            continue;
+        adj.get(e.from).push(e.to);
+        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+    }
+    const layer = new Map();
+    let queue = ids.filter((id) => indeg.get(id) === 0);
+    const seen = new Set(queue);
+    for (const id of queue)
+        layer.set(id, 0);
+    const maxIterations = ids.length * 2 + 2;
+    let iterations = 0;
+    while (queue.length > 0 && iterations++ < maxIterations) {
+        const next = [];
+        for (const id of queue) {
+            for (const child of adj.get(id) ?? []) {
+                const candidate = (layer.get(id) ?? 0) + 1;
+                if (!layer.has(child) || candidate > layer.get(child))
+                    layer.set(child, candidate);
+                if (!seen.has(child)) {
+                    seen.add(child);
+                    next.push(child);
+                }
+            }
+        }
+        queue = next;
+    }
+    let maxLayer = 0;
+    for (const l of layer.values())
+        if (l > maxLayer)
+            maxLayer = l;
+    for (const id of ids)
+        if (!layer.has(id))
+            layer.set(id, maxLayer + 1);
+    return layer;
+}
+/** Computes (x, y) for every node and the overall canvas size. Nodes in the
+ *  same layer are centered as a row; layers stack top to bottom. An
+ *  enrichment's `laneOrder` hint reorders nodes WITHIN their computed layer
+ *  only — layer assignment itself stays purely structural. */
+export function layoutGraph(graph, laneOrder) {
+    const layer = computeLayers(graph.nodes, graph.edges);
+    const byLayer = new Map();
+    for (const n of graph.nodes) {
+        const l = layer.get(n.id) ?? 0;
+        const arr = byLayer.get(l) ?? [];
+        arr.push(n.id);
+        byLayer.set(l, arr);
+    }
+    applyLaneOrder(byLayer, graph, laneOrder);
+    const layers = [...byLayer.keys()].sort((a, b) => a - b);
+    const maxCols = layers.reduce((m, l) => Math.max(m, byLayer.get(l).length), 1);
+    const width = MARGIN * 2 + maxCols * NODE_W + (maxCols - 1) * COL_GAP;
+    const pos = {};
+    for (const l of layers) {
+        const idsInLayer = byLayer.get(l);
+        const rowWidth = idsInLayer.length * NODE_W + (idsInLayer.length - 1) * COL_GAP;
+        const startX = (width - rowWidth) / 2;
+        idsInLayer.forEach((id, i) => {
+            pos[id] = { x: startX + i * (NODE_W + COL_GAP), y: MARGIN + l * (NODE_H + LAYER_GAP) };
+        });
+    }
+    const height = MARGIN * 2 + (layers.length - 1) * (NODE_H + LAYER_GAP) + NODE_H;
+    return { pos, width, height: Math.max(height, MARGIN * 2 + NODE_H) };
+}
+/**
+ * Reorders each hinted layer's nodes in place. A hint entry is applied only
+ * when every node id it lists exists in the graph (the schema's contract —
+ * a stale enrichment must degrade to "no hint", never to a broken layout);
+ * listed ids that live in a DIFFERENT layer are simply not in this layer's
+ * row and are ignored, since laneOrder can never move a node between layers.
+ */
+function applyLaneOrder(byLayer, graph, laneOrder) {
+    if (!laneOrder)
+        return;
+    const nodeIds = new Set(graph.nodes.map((n) => n.id));
+    for (const [layerKey, order] of Object.entries(laneOrder)) {
+        const layerIndex = Number(layerKey);
+        const row = byLayer.get(layerIndex);
+        if (!row || !order.every((id) => nodeIds.has(id)))
+            continue;
+        const inRow = new Set(row);
+        const ordered = order.filter((id) => inRow.has(id));
+        const rest = row.filter((id) => !ordered.includes(id));
+        byLayer.set(layerIndex, [...ordered, ...rest]);
+    }
+}
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function edgeColorClass(nodesById, edge) {
+    const target = nodesById.get(edge.to);
+    if (target?.kind === "terminal-success")
+        return "--success";
+    if (target?.kind === "terminal-warn")
+        return "--warn";
+    return "";
+}
+function arrowMarker(colorSuffix) {
+    if (colorSuffix === "--success")
+        return "url(#canvas-arrow-success)";
+    if (colorSuffix === "--warn")
+        return "url(#canvas-arrow-warn)";
+    return "url(#canvas-arrow)";
+}
+function edgePath(kind, x1, y1, x2, y2) {
+    if (kind === "branching") {
+        const midY = (y1 + y2) / 2;
+        return `M${x1},${y1} C${x1},${midY} ${x2},${midY} ${x2},${y2}`;
+    }
+    return `M${x1},${y1} L${x2},${y2}`;
+}
+/**
+ * Group-hint background bands: one subtle rect per group whose member nodes
+ * ALL exist, sized to their bounding box, labeled at its top-left. Rendered
+ * before edges/nodes so it sits behind everything.
+ */
+function groupBandMarkup(groups, graph, layout) {
+    if (!groups || groups.length === 0)
+        return "";
+    const nodeIds = new Set(graph.nodes.map((n) => n.id));
+    return groups
+        .map((group) => {
+        if (!group.nodeIds.every((id) => nodeIds.has(id)))
+            return "";
+        const positions = group.nodeIds.map((id) => layout.pos[id]).filter(Boolean);
+        if (positions.length === 0)
+            return "";
+        const minX = Math.min(...positions.map((p) => p.x)) - GROUP_PAD;
+        const minY = Math.min(...positions.map((p) => p.y)) - GROUP_PAD;
+        const maxX = Math.max(...positions.map((p) => p.x + NODE_W)) + GROUP_PAD;
+        const maxY = Math.max(...positions.map((p) => p.y + NODE_H)) + GROUP_PAD;
+        return (`<rect class="canvas-group-band" x="${minX}" y="${minY}" width="${maxX - minX}" height="${maxY - minY}" rx="18" />` +
+            `<text class="canvas-group-label" x="${minX + 8}" y="${minY - 4}">${esc(group.label)}</text>`);
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+/** Renders one graph's `<svg>` diagram, merging in any enrichment content
+ *  (node sublabels/descriptions, edge labels, group bands, lane order) — all
+ *  of it pre-bounded plain strings (core/canvas-enrichment.ts), escaped here
+ *  like every other text. Assumes the shared `<defs>` (glow filter + arrow
+ *  markers) are already present once at the document level — see
+ *  `renderCanvasDocument`'s `SVG_DEFS` — so this never emits its own. */
+export function renderGraphSvg(graph, enrichment) {
+    const layout = layoutGraph(graph, enrichment?.layoutHints?.laneOrder);
+    const nodesById = new Map(graph.nodes.map((n) => [n.id, n]));
+    const bandMarkup = groupBandMarkup(enrichment?.layoutHints?.groups, graph, layout);
+    const edgeMarkup = graph.edges
+        .map((edge) => {
+        const from = layout.pos[edge.from];
+        const to = layout.pos[edge.to];
+        if (!from || !to)
+            return "";
+        const x1 = from.x + NODE_W / 2;
+        const y1 = from.y + NODE_H;
+        const x2 = to.x + NODE_W / 2;
+        const y2 = to.y;
+        // Cross (signal/handoff) and launch edges are always dashed-neutral,
+        // never colored by their destination.
+        const dashedClass = edge.kind === "cross" ? "canvas-edge--cross" : edge.kind === "launch" ? "canvas-edge--launch" : null;
+        const colorSuffix = dashedClass ? "" : edgeColorClass(nodesById, edge);
+        const classes = ["canvas-edge", dashedClass ?? (colorSuffix && `canvas-edge${colorSuffix}`)]
+            .filter(Boolean)
+            .join(" ");
+        const d = edgePath(edge.kind, x1, y1, x2, y2);
+        const marker = dashedClass ? "url(#canvas-arrow)" : arrowMarker(colorSuffix);
+        const path = `<path class="${classes}" d="${d}" marker-end="${marker}" />`;
+        // An enriched label (an intent/condition name the AI read out of the
+        // step body) wins over the structural default (e.g. "launch()").
+        const labelText = enrichment?.edgeLabels?.[`${edge.from}->${edge.to}`] ?? edge.label;
+        if (!labelText)
+            return path;
+        const dx = x2 - x1;
+        const anchor = dx > 4 ? "start" : dx < -4 ? "end" : "middle";
+        const labelX = x1 + (dx > 0 ? 10 : dx < 0 ? -10 : 0);
+        const label = `<text class="canvas-edge-label" x="${labelX}" y="${y1 + 20}" text-anchor="${anchor}">${esc(labelText)}</text>`;
+        return path + label;
+    })
+        .join("\n");
+    const nodeMarkup = graph.nodes
+        .map((node) => {
+        const p = layout.pos[node.id];
+        if (!p)
+            return "";
+        const details = enrichment?.nodeDetails?.[node.id];
+        const sublabel = details?.sublabel ?? node.sublabel;
+        const titleY = sublabel ? 26 : NODE_H / 2;
+        const sub = sublabel
+            ? `<text class="canvas-node-sub" x="${NODE_W / 2}" y="44">${esc(sublabel)}</text>`
+            : "";
+        // SVG <title> = native hover tooltip; the only enrichment slot with
+        // room for a full sentence.
+        const description = details?.description ? `<title>${esc(details.description)}</title>` : "";
+        return (`<g class="canvas-node node--${node.kind}" filter="url(#canvas-glow)" transform="translate(${p.x},${p.y})">` +
+            description +
+            `<rect class="canvas-node-rect" width="${NODE_W}" height="${NODE_H}" rx="14" />` +
+            `<text class="canvas-node-title" x="${NODE_W / 2}" y="${titleY}">${esc(node.label)}</text>` +
+            sub +
+            `</g>`);
+    })
+        .join("\n");
+    // Explicit width/height pin the diagram to its NATURAL (1×) size. Without
+    // them, the CSS `width:100%` used to stretch a single-column workflow's
+    // tiny viewBox to fill the pane, ballooning every node and its font (~4×).
+    // The CSS now only centers the svg (`margin: 0 auto`); a graph wider than
+    // the pane keeps full size and scrolls (`.canvas-diagram-panel`'s
+    // overflow-x) rather than shrinking to an illegible size.
+    return (`<svg viewBox="0 0 ${layout.width} ${layout.height}" width="${layout.width}" height="${layout.height}" class="canvas-graph-svg">\n` +
+        (bandMarkup ? bandMarkup + "\n" : "") +
+        edgeMarkup +
+        "\n" +
+        nodeMarkup +
+        `\n</svg>`);
+}
+/** Every node/edge kind actually used, for the shared legend footer. */
+export function usedKinds(graph) {
+    return {
+        nodeKinds: new Set(graph.nodes.map((n) => n.kind)),
+        edgeKinds: new Set(graph.edges.map((e) => e.kind)),
+    };
+}
+//# sourceMappingURL=canvas-svg.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * Canvas kit: a prewritten template — CSS (light + dark, following the
+ * app's own theme) and a documented set of markup building blocks — that an
+ * agent clones and fills in with real content, instead of hand-writing a
+ * canvas from scratch every time. This is deliberately NOT a JSON-data +
+ * JS-renderer scheme: the agent authors real HTML/SVG using the template's
+ * classes, so it keeps full expressive freedom over the graph itself while
+ * the CSS (and therefore the visual language: colors, glow, edge styling,
+ * legend markers) is locked and can't drift.
+ *
+ * `renderCanvasDocument(bodyHtml)` is the single shared shell (CSS + theme
+ * switch) — `TEMPLATE_HTML` (the pristine, empty-state document) and
+ * `scripts/seed-example.mjs` (prefilled with real content) both wrap their
+ * body through it, so the kit and the seed can't drift from each other.
+ */
+/** Lives alongside index.html, in the same CANVAS_DIR — a pristine copy of
+ *  the template, written once and never touched again, so "clone the
+ *  template" always has a clean, un-filled-in source to clone from. */
+export declare const CANVAS_TEMPLATE_FILE = ".sapiom/canvas/_template.html";
+/**
+ * Wraps `bodyHtml` in the shared canvas document shell: doctype, the theme
+ * switch script, and every CSS class an agent's markup can use. This is the
+ * single source both the pristine template and `scripts/seed-example.mjs`'s
+ * prefilled instance render through, so they can't drift from each other.
+ */
+export declare function renderCanvasDocument(bodyHtml: string): string;
+/** The exact document written to both `_template.html` and the initial
+ *  `index.html` — a friendly empty state plus the patterns reference. */
+export declare const TEMPLATE_HTML: string;
+/**
+ * Backfill-only: ensures both `<cwd>/.sapiom/canvas/_template.html` (a
+ * pristine copy, so "clone the template" always has a clean source — see
+ * the visualize macro's prompt) and `<cwd>/.sapiom/canvas/index.html` (the
+ * live canvas, seeded with the same empty-state content) exist. Never
+ * clobbers either file if something's already there — an earlier session,
+ * or the agent's own edits. Called from SessionManager's create()/resume()
+ * (see its `ensureCanvasTemplate` option) so the canvas pane never opens to
+ * a completely empty iframe. Best-effort, like the sibling
+ * `workspace-context.ts` writer: a session's cwd could be unwritable, and
+ * that must never fail session creation itself.
+ */
+export declare function ensureCanvasTemplate(cwd: string): Promise<void>;
+//# sourceMappingURL=canvas-template.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-template.d.ts","sourceRoot":"","sources":["../../src/core/canvas-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH;;uEAEuE;AACvE,eAAO,MAAM,oBAAoB,kCAAiC,CAAC;AAiOnE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAsB7D;AAgCD;yEACyE;AACzE,eAAO,MAAM,aAAa,QAAsC,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrE"}