loom-spec 0.3.0 → 0.4.0

package/dist/cli/exportHtml.d.ts

@@ -0,0 +1,25 @@
+export interface ExportHtmlArgs {
+    /** Output file path. Default: "loom.html" in cwd. */
+    out: string;
+    /** Working directory root (walked up to find .loom/). */
+    root: string;
+    /** If set, only this diagram (plus any timelines that reference it). */
+    diagram?: string;
+    /** Skip all timelines. Useful for manuals where the static topology is
+     *  the whole story. */
+    noTimelines: boolean;
+    /** Only export nodes carrying at least one of these tags. */
+    includeTags?: string[];
+    /** Drop nodes carrying any of these tags. */
+    excludeTags?: string[];
+    /** Named bundle from .loom/exports.json. Settings from the bundle become
+     *  defaults; explicit CLI flags override. */
+    bundle?: string;
+}
+/**
+ * Used by the bundle-merge logic to tell "user passed --out" from "we are
+ * using the default". Exported so the CLI dispatcher can default-init the
+ * field once and stay consistent with this module's notion of "default".
+ */
+export declare const DEFAULT_OUT = "loom.html";
+export declare function runExportHtml(args: ExportHtmlArgs): Promise<void>;

package/dist/cli/exportHtml.js

@@ -0,0 +1,201 @@
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { listDiagrams, readDiagram, listTimelines, readTimeline, readNodeTypes, } from "../server/fileOps.js";
+import { applyFilter } from "../server/exportFilter.js";
+import { loadExportsConfig } from "../server/exportConfig.js";
+const here = dirname(fileURLToPath(import.meta.url));
+async function fileExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate the export-mode view bundle. Tries both layouts:
+ *   - Production: alongside cli/ in dist/ → ../view-export/
+ *   - Dev (tsx running from src/cli/): ../../dist/view-export/
+ */
+async function findExportBundle() {
+    const candidates = [
+        resolve(here, "../view-export"),
+        resolve(here, "../../dist/view-export"),
+    ];
+    for (const c of candidates) {
+        if (await fileExists(resolve(c, "index.html")))
+            return c;
+    }
+    throw new Error(`Could not find the export view bundle. Looked in:\n  - ${candidates.join("\n  - ")}\n` +
+        `Did you run 'pnpm build' (or 'pnpm build:export') to produce dist/view-export?`);
+}
+/**
+ * Used by the bundle-merge logic to tell "user passed --out" from "we are
+ * using the default". Exported so the CLI dispatcher can default-init the
+ * field once and stay consistent with this module's notion of "default".
+ */
+export const DEFAULT_OUT = "loom.html";
+async function loadAllData(args) {
+    const loomRoot = await findLoomRoot(args.root);
+    const nodeTypes = await readNodeTypes(loomRoot.loomPath);
+    // Diagrams — either one specific or all
+    const diagrams = {};
+    if (args.diagram) {
+        diagrams[args.diagram] = await readDiagram(loomRoot.loomPath, args.diagram);
+    }
+    else {
+        const summaries = await listDiagrams(loomRoot.loomPath);
+        for (const s of summaries) {
+            diagrams[s.id] = await readDiagram(loomRoot.loomPath, s.id);
+        }
+    }
+    // Timelines — include those that reference at least one diagram we exported
+    const timelines = {};
+    if (!args.noTimelines) {
+        const summaries = await listTimelines(loomRoot.loomPath);
+        for (const s of summaries) {
+            if (!(s.diagram in diagrams))
+                continue;
+            timelines[s.id] = await readTimeline(loomRoot.loomPath, s.id);
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        diagrams,
+        timelines,
+        nodeTypes,
+    };
+}
+/**
+ * Inline the view bundle (HTML + CSS + JS) and the exported data into a
+ * single self-contained HTML string.
+ *
+ * The export bundle's index.html looks roughly like:
+ *   <html><head><link rel="stylesheet" href="/assets/bundle.css">
+ *     <script type="module" crossorigin src="/assets/bundle.js"></script>
+ *   </head><body><div id="root"></div></body></html>
+ *
+ * We rewrite the link/script tags to inline contents and inject a
+ * <script>window.__LOOM_DATA__ = {...}</script> before the bundle.
+ */
+function buildHtml(bundleHtml, bundleCss, bundleJs, data, meta) {
+    // Sanitize the JSON for inlining inside a <script> tag.
+    // Replace </script> sequences and <!-- inside string values so they can't
+    // close the surrounding script element or confuse parsers.
+    const safeJson = JSON.stringify(data)
+        .replace(/<\/script/gi, "<\\/script")
+        .replace(/<!--/g, "<\\!--");
+    const inlineDataTag = `<script>window.__LOOM_DATA__ = ${safeJson};</script>`;
+    const inlineCssTag = `<style>${bundleCss}</style>`;
+    const inlineJsTag = `<script type="module">${bundleJs}</script>`;
+    let out = bundleHtml;
+    // CRITICAL: pass replacement as a function rather than a string. With a
+    // string second arg, JS treats `$$` as a literal `$`, which mangles any
+    // `$$typeof` / `$&` / `$'` in the JS bundle (React's reconciler uses
+    // `$$typeof` heavily). Function form bypasses the pattern processing.
+    out = out.replace(/<link\s+rel=["']stylesheet["'][^>]*>/i, () => inlineCssTag);
+    out = out.replace(/<script\s+type=["']module["'][^>]*><\/script>/i, () => inlineDataTag + inlineJsTag);
+    out = out.replace(/<title>[^<]*<\/title>/i, () => `<title>loom-spec export · ${escapeHtml(meta.sourceRoot)}</title>`);
+    return out;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export async function runExportHtml(args) {
+    // If a bundle name was given, resolve its settings from .loom/exports.json
+    // first. Explicit CLI args take precedence (for ad-hoc overrides).
+    let effective = args;
+    if (args.bundle) {
+        const loomRoot = await findLoomRoot(args.root);
+        const config = await loadExportsConfig(loomRoot.loomPath);
+        if (!config) {
+            console.error(`export-html: no .loom/exports.json found, but '${args.bundle}' looks like a named bundle.\n` +
+                `  Create .loom/exports.json with an 'exports.${args.bundle}' entry, or pass ad-hoc flags instead.`);
+            process.exit(1);
+        }
+        const bundle = config.exports[args.bundle];
+        if (!bundle) {
+            const available = Object.keys(config.exports).sort().join(", ") || "(none)";
+            console.error(`export-html: bundle '${args.bundle}' not found in .loom/exports.json. ` +
+                `Available: ${available}.`);
+            process.exit(1);
+        }
+        // Merge: explicit CLI args (in `args`) override config-supplied values.
+        effective = {
+            ...args,
+            out: args.out !== DEFAULT_OUT ? args.out : bundle.out ?? args.out,
+            diagram: args.diagram ?? bundle.diagram,
+            noTimelines: args.noTimelines || (bundle.noTimelines ?? false),
+            includeTags: args.includeTags ?? bundle.includeTags,
+            excludeTags: args.excludeTags ?? bundle.excludeTags,
+        };
+    }
+    const bundleDir = await findExportBundle();
+    const [bundleHtml, bundleCss, bundleJs] = await Promise.all([
+        readFile(resolve(bundleDir, "index.html"), "utf8"),
+        readFile(resolve(bundleDir, "assets/bundle.css"), "utf8"),
+        readFile(resolve(bundleDir, "assets/bundle.js"), "utf8"),
+    ]);
+    const data = await loadAllData(effective);
+    if (Object.keys(data.diagrams).length === 0) {
+        console.error("export-html: no diagrams found — refusing to write an empty export.");
+        process.exit(1);
+    }
+    const filterSpec = {
+        includeTags: effective.includeTags,
+        excludeTags: effective.excludeTags,
+    };
+    const { payload: filtered, summary } = applyFilter(data, filterSpec);
+    // After filtering, if everything's gone, bail. Better to fail loud than
+    // silently emit a blank HTML the user will wonder about.
+    const survivingNodes = Object.values(filtered.diagrams).reduce((n, d) => n + d.nodes.length, 0);
+    if (survivingNodes === 0) {
+        console.error("export-html: filter matched 0 nodes — refusing to write an empty export.");
+        if (filterSpec.includeTags?.length || filterSpec.excludeTags?.length) {
+            console.error(`  filter was: include=[${(filterSpec.includeTags ?? []).join(", ")}], ` +
+                `exclude=[${(filterSpec.excludeTags ?? []).join(", ")}]`);
+        }
+        process.exit(1);
+    }
+    const finalData = {
+        ...data,
+        diagrams: filtered.diagrams,
+        timelines: filtered.timelines,
+    };
+    const html = buildHtml(bundleHtml, bundleCss, bundleJs, finalData, {
+        sourceRoot: effective.root,
+    });
+    const outPath = resolve(effective.out);
+    await writeFile(outPath, html, "utf8");
+    const sizeKb = Math.round(Buffer.byteLength(html, "utf8") / 1024);
+    const diagramCount = Object.keys(finalData.diagrams).length;
+    const timelineCount = Object.keys(finalData.timelines).length;
+    console.log(`Wrote ${outPath} (${sizeKb} kB): ` +
+        `${diagramCount} diagram${diagramCount === 1 ? "" : "s"}, ` +
+        `${timelineCount} timeline${timelineCount === 1 ? "" : "s"}.`);
+    const droppedParts = [];
+    if (summary.nodesDropped > 0)
+        droppedParts.push(`${summary.nodesDropped} nodes`);
+    if (summary.edgesDropped > 0)
+        droppedParts.push(`${summary.edgesDropped} edges`);
+    if (summary.groupsDropped > 0)
+        droppedParts.push(`${summary.groupsDropped} groups`);
+    if (summary.eventsDropped > 0)
+        droppedParts.push(`${summary.eventsDropped} events`);
+    if (summary.timelinesDropped > 0)
+        droppedParts.push(`${summary.timelinesDropped} timelines`);
+    if (summary.drillDownsCleared > 0)
+        droppedParts.push(`${summary.drillDownsCleared} drill-down refs`);
+    if (droppedParts.length > 0) {
+        console.log(`Filter dropped: ${droppedParts.join(", ")}.`);
+    }
+    console.log(`Open it directly in a browser, or drop it into any docs / wiki / GitHub-Pages site.`);
+}
+//# sourceMappingURL=exportHtml.js.map

package/dist/cli/exportHtml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportHtml.js","sourceRoot":"","sources":["../../src/cli/exportHtml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAmB,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AA+B9D,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAErD,KAAK,UAAU,UAAU,CAAC,CAAS;IACjC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,gBAAgB;IAC7B,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,wBAAwB,CAAC;KACxC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,KAAK,CACb,0DAA0D,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI;QACrF,gFAAgF,CACnF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AAEvC,KAAK,UAAU,WAAW,CAAC,IAAoB;IAC7C,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEzD,wCAAwC;IACxC,MAAM,QAAQ,GAAgC,EAAE,CAAC;IACjD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9E,CAAC;SAAM,CAAC;QACN,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,MAAM,SAAS,GAAiC,EAAE,CAAC;IACnD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,QAAQ,CAAC;gBAAE,SAAS;YACvC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,OAAO;QACL,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,QAAQ;QACR,SAAS;QACT,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,SAAS,CAChB,UAAkB,EAClB,SAAiB,EACjB,QAAgB,EAChB,IAAgB,EAChB,IAA4B;IAE5B,wDAAwD;IACxD,0EAA0E;IAC1E,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAClC,OAAO,CAAC,aAAa,EAAE,YAAY,CAAC;SACpC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE9B,MAAM,aAAa,GAAG,kCAAkC,QAAQ,YAAY,CAAC;IAC7E,MAAM,YAAY,GAAG,UAAU,SAAS,UAAU,CAAC;IACnD,MAAM,WAAW,GAAG,yBAAyB,QAAQ,WAAW,CAAC;IAEjE,IAAI,GAAG,GAAG,UAAU,CAAC;IAErB,wEAAwE;IACxE,wEAAwE;IACxE,qEAAqE;IACrE,sEAAsE;IACtE,GAAG,GAAG,GAAG,CAAC,OAAO,CACf,uCAAuC,EACvC,GAAG,EAAE,CAAC,YAAY,CACnB,CAAC;IACF,GAAG,GAAG,GAAG,CAAC,OAAO,CACf,gDAAgD,EAChD,GAAG,EAAE,CAAC,aAAa,GAAG,WAAW,CAClC,CAAC;IACF,GAAG,GAAG,GAAG,CAAC,OAAO,CACf,wBAAwB,EACxB,GAAG,EAAE,CAAC,6BAA6B,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CACzE,CAAC;IAEF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC;SACL,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAoB;IACtD,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CACX,kDAAkD,IAAI,CAAC,MAAM,gCAAgC;gBAC3F,gDAAgD,IAAI,CAAC,MAAM,wCAAwC,CACtG,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;YAC5E,OAAO,CAAC,KAAK,CACX,wBAAwB,IAAI,CAAC,MAAM,qCAAqC;gBACtE,cAAc,SAAS,GAAG,CAC7B,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,wEAAwE;QACxE,SAAS,GAAG;YACV,GAAG,IAAI;YACP,GAAG,EAAE,IAAI,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG;YACjE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;YACvC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,KAAK,CAAC;YAC9D,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW;YACnD,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW;SACpD,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,gBAAgB,EAAE,CAAC;IAC3C,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1D,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAClD,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACzD,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACzD,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,CAAC;IAE1C,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,UAAU,GAAe;QAC7B,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,WAAW,EAAE,SAAS,CAAC,WAAW;KACnC,CAAC;IACF,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAErE,wEAAwE;IACxE,yDAAyD;IACzD,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,CAC5D,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAC5B,CAAC,CACF,CAAC;IACF,IAAI,cAAc,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CACX,0EAA0E,CAC3E,CAAC;QACF,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;YACrE,OAAO,CAAC,KAAK,CACX,0BAA0B,CAAC,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;gBACtE,YAAY,CAAC,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3D,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAe;QAC5B,GAAG,IAAI;QACP,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC;IAEF,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE;QACjE,UAAU,EAAE,SAAS,CAAC,IAAI;KAC3B,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IAC5D,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;IAC9D,OAAO,CAAC,GAAG,CACT,SAAS,OAAO,KAAK,MAAM,QAAQ;QACjC,GAAG,YAAY,WAAW,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI;QAC3D,GAAG,aAAa,YAAY,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAChE,CAAC;IACF,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,IAAI,OAAO,CAAC,YAAY,GAAG,CAAC;QAAE,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,YAAY,QAAQ,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,YAAY,GAAG,CAAC;QAAE,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,YAAY,QAAQ,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,aAAa,GAAG,CAAC;QAAE,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,SAAS,CAAC,CAAC;IACpF,IAAI,OAAO,CAAC,aAAa,GAAG,CAAC;QAC3B,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,SAAS,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,gBAAgB,GAAG,CAAC;QAC9B,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,gBAAgB,YAAY,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,iBAAiB,GAAG,CAAC;QAC/B,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,iBAAiB,kBAAkB,CAAC,CAAC;IACpE,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,mBAAmB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,CAAC,GAAG,CACT,qFAAqF,CACtF,CAAC;AACJ,CAAC"}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { runValidate } from "./validate.js";
 import { runMcp } from "./mcp.js";
 import { runInstallMcp } from "./installMcp.js";
 import { runImportTrace } from "./importTrace.js";
+import { runExportHtml, DEFAULT_OUT as EXPORT_DEFAULT_OUT } from "./exportHtml.js";
 const HELP = `loom-spec — node-based architecture spec for your repo
 
 Usage:
@@ -33,6 +34,23 @@ Usage:
       and timelines (loom_list_timelines, loom_add_event, …) — wire it
       into Claude Code's mcp.json (or any MCP-capable client).
 
+  loom-spec export-html [<bundle-name>] [--out <path>] [--diagram <id>]
+                        [--no-timelines]
+                        [--include-tag <comma-list>] [--exclude-tag <comma-list>]
+                        [--root <dir>]
+      Build a standalone interactive HTML file from the spec — pan/zoom,
+      drill-down, switch diagrams, play timelines. Single self-contained
+      file, no server needed. Drop it into a manual, wiki, GitHub Pages
+      site, anywhere. Output defaults to ./loom.html. With --diagram, only
+      that diagram (and timelines referencing it) ship. With
+      --include-tag / --exclude-tag, only nodes whose 'tags' match
+      survive — edges, groups, drill-down chevrons, timeline events that
+      point at dropped nodes are cleaned up automatically.
+
+      Pass a <bundle-name> as the first positional arg to read settings
+      from a named bundle in .loom/exports.json. Explicit flags override
+      the bundle's values.
+
   loom-spec import-trace <trace.json> --as <timeline-id> --diagram <diagram-id>
                         [--map <mapping.json>] [--append] [--root <dir>]
       Read an OpenTelemetry OTLP-JSON trace and generate a timeline that
@@ -46,6 +64,7 @@ Usage:
 `;
 function parseFlags(argv) {
     const flags = {};
+    const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (!a)
@@ -61,12 +80,15 @@ function parseFlags(argv) {
                 flags[key] = true;
             }
         }
+        else {
+            positional.push(a);
+        }
     }
-    return flags;
+    return { flags, positional };
 }
 async function main() {
     const [, , subcommand, ...rest] = process.argv;
-    const flags = parseFlags(rest);
+    const { flags, positional } = parseFlags(rest);
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
         console.log(HELP);
         return;
@@ -106,9 +128,29 @@ async function main() {
         });
         return;
     }
+    if (subcommand === "export-html") {
+        const splitTags = (v) => {
+            if (typeof v !== "string" || !v.trim())
+                return undefined;
+            return v.split(",").map((s) => s.trim()).filter(Boolean);
+        };
+        // First positional arg, if any, is a named-bundle key from
+        // .loom/exports.json (e.g. `loom-spec export-html user-manual`).
+        const bundle = positional[0];
+        await runExportHtml({
+            out: flags.out ?? EXPORT_DEFAULT_OUT,
+            root: flags.root ?? process.cwd(),
+            diagram: typeof flags.diagram === "string" ? flags.diagram : undefined,
+            noTimelines: Boolean(flags["no-timelines"]),
+            includeTags: splitTags(flags["include-tag"]),
+            excludeTags: splitTags(flags["exclude-tag"]),
+            bundle,
+        });
+        return;
+    }
     if (subcommand === "import-trace") {
-        // Positional arg: the trace file path (first non-flag in rest).
-        const trace = rest.find((a) => a && !a.startsWith("--"));
+        // Positional arg: the trace file path.
+        const trace = positional[0];
         if (!trace) {
             console.error("import-trace: missing trace file path");
             console.log(HELP);

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCZ,CAAC;AAEF,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACzB,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,AAAD,EAAG,UAAU,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAE/B,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC;YACZ,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;YAC3B,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;SACxB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QACjC,MAAM,aAAa,CAAC;YAClB,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC;YACZ,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;YAC5C,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;SACxB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9B,MAAM,WAAW,CAAC;YAChB,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,CAAC;YACX,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QAClC,gEAAgE;QAChE,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAwB,CAAC;QAC5C,MAAM,SAAS,GAAG,KAAK,CAAC,OAA6B,CAAC;QACtD,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,0EAA0E,CAAC,CAAC;YAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,cAAc,CAAC;YACnB,KAAK;YACL,IAAI;YACJ,SAAS;YACT,GAAG,EAAE,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;YAC1D,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;YAC7B,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,uBAAuB,UAAU,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/server/exportConfig.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Optional `.loom/exports.json` config — defines named export bundles so
+ * teams can keep export settings versioned in the repo instead of in shell
+ * commands. A new contributor runs `loom-spec export-html user-manual`
+ * and gets the same output as everyone else without having to remember
+ * which flags to pass.
+ *
+ * Shape:
+ *
+ *   {
+ *     "exports": {
+ *       "user-manual": {
+ *         "include-tags": ["public"],
+ *         "exclude-tags": ["wip"],
+ *         "diagram": "overview",       // optional, single-diagram mode
+ *         "no-timelines": true,        // default false
+ *         "out": "docs/architecture.html"  // optional, default loom.html
+ *       },
+ *       "ops-runbook": {
+ *         "include-tags": ["ops"]
+ *       }
+ *     }
+ *   }
+ *
+ * All fields are optional. Unknown keys are tolerated (forward-compat).
+ * CLI flags override config values when both are present.
+ */
+export interface NamedExport {
+    includeTags?: string[];
+    excludeTags?: string[];
+    diagram?: string;
+    noTimelines?: boolean;
+    out?: string;
+}
+export interface ExportsFile {
+    exports: Record<string, NamedExport>;
+}
+/**
+ * Try to read `.loom/exports.json`. Returns null when the file is missing
+ * (that's a normal, non-error state — exports config is opt-in).
+ */
+export declare function loadExportsConfig(loomPath: string): Promise<ExportsFile | null>;

package/dist/server/exportConfig.js

@@ -0,0 +1,88 @@
+/**
+ * Optional `.loom/exports.json` config — defines named export bundles so
+ * teams can keep export settings versioned in the repo instead of in shell
+ * commands. A new contributor runs `loom-spec export-html user-manual`
+ * and gets the same output as everyone else without having to remember
+ * which flags to pass.
+ *
+ * Shape:
+ *
+ *   {
+ *     "exports": {
+ *       "user-manual": {
+ *         "include-tags": ["public"],
+ *         "exclude-tags": ["wip"],
+ *         "diagram": "overview",       // optional, single-diagram mode
+ *         "no-timelines": true,        // default false
+ *         "out": "docs/architecture.html"  // optional, default loom.html
+ *       },
+ *       "ops-runbook": {
+ *         "include-tags": ["ops"]
+ *       }
+ *     }
+ *   }
+ *
+ * All fields are optional. Unknown keys are tolerated (forward-compat).
+ * CLI flags override config values when both are present.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+function asStringArray(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (!Array.isArray(v) || !v.every((s) => typeof s === "string")) {
+        throw new Error(`exports.json: ${where} must be an array of strings`);
+    }
+    return v;
+}
+function asString(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new Error(`exports.json: ${where} must be a string`);
+    }
+    return v;
+}
+function asBool(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "boolean") {
+        throw new Error(`exports.json: ${where} must be a boolean`);
+    }
+    return v;
+}
+function normalize(raw) {
+    const out = { exports: {} };
+    const entries = Object.entries(raw.exports ?? {});
+    for (const [name, e] of entries) {
+        if (!/^[a-z0-9-]+$/.test(name)) {
+            throw new Error(`exports.json: bundle name '${name}' must match ^[a-z0-9-]+$`);
+        }
+        out.exports[name] = {
+            includeTags: asStringArray(e["include-tags"], `${name}.include-tags`),
+            excludeTags: asStringArray(e["exclude-tags"], `${name}.exclude-tags`),
+            diagram: asString(e.diagram, `${name}.diagram`),
+            noTimelines: asBool(e["no-timelines"], `${name}.no-timelines`),
+            out: asString(e.out, `${name}.out`),
+        };
+    }
+    return out;
+}
+/**
+ * Try to read `.loom/exports.json`. Returns null when the file is missing
+ * (that's a normal, non-error state — exports config is opt-in).
+ */
+export async function loadExportsConfig(loomPath) {
+    try {
+        const raw = await readFile(resolve(loomPath, "exports.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return normalize(parsed);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return null;
+        throw e;
+    }
+}
+//# sourceMappingURL=exportConfig.js.map

package/dist/server/exportConfig.js.map

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

package/dist/server/exportFilter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tag-based filter for HTML exports. Used by `loom-spec export-html` to
+ * produce scoped bundles (public manual, ops runbook, etc.) from the same
+ * `.loom/` source.
+ *
+ * Semantics:
+ *
+ *  - A node "matches" iff
+ *      (includeTags is empty OR node has at least one matching include tag)
+ *      AND
+ *      (excludeTags is empty OR node has none of the exclude tags)
+ *
+ *    If both lists are empty the filter is a no-op (all nodes match).
+ *
+ *  - Cascade rules (applied in order, so later rules see post-filter state):
+ *      1. Drop nodes that don't match.
+ *      2. Drop edges whose source or target node was dropped.
+ *      3. Drop or shrink groups: if any group's `children` are all dropped,
+ *         drop the group; otherwise keep with surviving children.
+ *      4. Null out `drill_down` chevrons that target diagrams with zero
+ *         surviving nodes after filtering.
+ *      5. Drop timeline events whose referenced node was dropped.
+ *      6. Drop timelines that end up with zero events.
+ *      7. Null out `triggered_by` refs pointing at dropped events.
+ *
+ *  - Diagrams that end up empty are NOT dropped automatically — the caller
+ *    decides (often via --diagram for explicit single-diagram exports).
+ *    Empty diagrams still render an empty canvas, which is visible to the
+ *    reader and gives them a clue something was filtered out.
+ */
+import type { LoomDiagram } from "../types/diagram.js";
+import type { LoomTimeline } from "../types/timeline.js";
+import type { LoomNodeTypes } from "../types/node-types.js";
+export interface FilterSpec {
+    includeTags?: string[];
+    excludeTags?: string[];
+}
+export interface LoomExportPayload {
+    diagrams: Record<string, LoomDiagram>;
+    timelines: Record<string, LoomTimeline>;
+    nodeTypes: LoomNodeTypes;
+}
+export interface FilterResult {
+    payload: LoomExportPayload;
+    /** Summary, used by the CLI to print "Dropped N nodes, M edges, …". */
+    summary: {
+        nodesDropped: number;
+        edgesDropped: number;
+        groupsDropped: number;
+        eventsDropped: number;
+        timelinesDropped: number;
+        drillDownsCleared: number;
+    };
+}
+/**
+ * Apply the filter cascade. Returns a deep-enough copy that mutating the
+ * result doesn't mutate the input.
+ */
+export declare function applyFilter(payload: LoomExportPayload, spec: FilterSpec): FilterResult;