@diagc/cli 0.1.0

package/dist/publish/assets.d.ts

@@ -0,0 +1,20 @@
+import type { DiagramModel } from '@diagc/core';
+export declare function dataUri(bytes: Buffer, ext: string): string;
+/**
+ * Classify an asset ref so publish-time code knows whether/where to read it from disk.
+ * - `library`: bundled shape, lives under the library dir (`/library/<rest>`).
+ * - `api-assets`: uploaded asset served via the studio API (`/api/assets/<rest>`).
+ * - `bare`: uploaded asset stored as a bare content-hash filename (no leading slash,
+ *   not a URL, not already a data: URI) — the studio's on-disk model shape.
+ * - `skip`: anything else (external http(s) URL, data: URI, or an unrecognized
+ *   absolute path) — left untouched.
+ */
+export type AssetRefKind = 'library' | 'api-assets' | 'bare' | 'skip';
+export declare function classifyAssetRef(ref: string): AssetRefKind;
+/**
+ * Resolve `rel` under `base`, or `undefined` if it would escape `base` via `..`
+ * (path traversal). Guards the publish step so a crafted asset ref such as
+ * `/library/../../etc/passwd` can never read a file outside the intended root.
+ */
+export declare function safeAssetPath(base: string, rel: string): string | undefined;
+export declare function rewriteAssetRefs(model: DiagramModel, resolve: (ref: string) => Buffer | undefined): DiagramModel;

package/dist/publish/assets.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+const MIME = {
+    svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif',
+};
+export function dataUri(bytes, ext) {
+    const mime = MIME[ext.toLowerCase()] ?? 'application/octet-stream';
+    return `data:${mime};base64,${bytes.toString('base64')}`;
+}
+export function classifyAssetRef(ref) {
+    if (ref.startsWith('/library/'))
+        return 'library';
+    if (ref.startsWith('/api/assets/'))
+        return 'api-assets';
+    if (!ref.startsWith('/') && !/^https?:/.test(ref) && !ref.startsWith('data:'))
+        return 'bare';
+    return 'skip';
+}
+/**
+ * Resolve `rel` under `base`, or `undefined` if it would escape `base` via `..`
+ * (path traversal). Guards the publish step so a crafted asset ref such as
+ * `/library/../../etc/passwd` can never read a file outside the intended root.
+ */
+export function safeAssetPath(base, rel) {
+    const root = path.resolve(base);
+    const resolved = path.resolve(root, rel);
+    return resolved.startsWith(root + path.sep) ? resolved : undefined;
+}
+function inlineRef(ref, resolve) {
+    if (ref === undefined || classifyAssetRef(ref) === 'skip')
+        return ref;
+    const bytes = resolve(ref);
+    if (bytes === undefined)
+        return ref;
+    const ext = ref.split('.').pop()?.split(/[?#]/)[0] ?? '';
+    return dataUri(bytes, ext);
+}
+export function rewriteAssetRefs(model, resolve) {
+    const nodes = model.nodes.map((n) => {
+        const image = inlineRef(n.image, resolve);
+        const shape = inlineRef(n.shape, resolve);
+        if (image === n.image && shape === n.shape)
+            return n;
+        return { ...n, ...(image !== undefined ? { image } : {}), ...(shape !== undefined ? { shape } : {}) };
+    });
+    return { ...model, nodes };
+}

package/dist/publish/discover.d.ts

@@ -0,0 +1,10 @@
+export interface DiscoveredDiagram {
+    name: string;
+    modelPath: string;
+    layoutPath?: string;
+    drawingsPath?: string;
+}
+/** Discover render-ready diagrams from the compiled artifacts dir; pair each
+ * with its layout and drawings sidecars from the source tree (artifacts carry
+ * neither — compile never touches a sidecar). */
+export declare function discoverDiagrams(artifactsDir: string, srcDir: string): Promise<DiscoveredDiagram[]>;

package/dist/publish/discover.js

@@ -0,0 +1,31 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+/** Discover render-ready diagrams from the compiled artifacts dir; pair each
+ * with its layout and drawings sidecars from the source tree (artifacts carry
+ * neither — compile never touches a sidecar). */
+export async function discoverDiagrams(artifactsDir, srcDir) {
+    const files = await fg('**/*.diagram.json', { cwd: artifactsDir, absolute: true });
+    const out = [];
+    const exists = async (p) => {
+        try {
+            await access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const modelPath of files) {
+        const name = path.relative(artifactsDir, modelPath).replace(/\.diagram\.json$/, '').split(path.sep).join('/');
+        const layoutPath = path.join(srcDir, `${name}.layout.json`);
+        const drawingsPath = path.join(srcDir, `${name}.drawings.json`);
+        out.push({
+            name,
+            modelPath,
+            ...((await exists(layoutPath)) ? { layoutPath } : {}),
+            ...((await exists(drawingsPath)) ? { drawingsPath } : {}),
+        });
+    }
+    return out;
+}

package/dist/publish/gallery.d.ts

@@ -0,0 +1,4 @@
+export declare function buildGallery(entries: {
+    name: string;
+    hasImage: boolean;
+}[]): string;

package/dist/publish/gallery.js

@@ -0,0 +1,27 @@
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+}
+export function buildGallery(entries) {
+    const cards = entries
+        .map((e) => {
+        const thumb = e.hasImage
+            ? `<img src="../static/${esc(e.name)}.png" alt="${esc(e.name)}" loading="lazy" />`
+            : '';
+        return `<a class="card" href="${esc(e.name)}.html">${thumb}<span>${esc(e.name)}</span></a>`;
+    })
+        .join('\n');
+    return `<!doctype html>
+<html lang="en"><head><meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Diagrams</title>
+<style>
+body{font-family:system-ui,sans-serif;margin:24px;background:#fafafa}
+h1{font-size:18px}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:16px}
+.card{display:flex;flex-direction:column;gap:8px;padding:12px;border:1px solid #ddd;border-radius:8px;text-decoration:none;color:#222;background:#fff}
+.card img{width:100%;height:140px;object-fit:contain;background:#f4f4f4;border-radius:4px}
+</style></head>
+<body><h1>Diagrams</h1><div class="grid">
+${cards}
+</div></body></html>`;
+}

package/dist/publish/html.d.ts

@@ -0,0 +1,23 @@
+import { SOURCE_URL } from '@diagc/core';
+export declare const DG_DATA_SENTINEL = "\"__DG_DIAGRAM_DATA__\"";
+export { SOURCE_URL };
+/**
+ * AGPL section 13 offer, carried by every published page.
+ *
+ * A published page inlines the whole viewer bundle, so publishing one distributes
+ * AGPL-licensed code and owes its recipients an offer of the corresponding source. The
+ * bundle `publish` stamps is unmodified, so pointing upstream discharges that — the
+ * author of the diagram has nothing to do, which is the point: compliance should not be
+ * something they can forget.
+ *
+ * A comment rather than visible chrome, deliberately. The page belongs to whoever drew
+ * the diagram; a banner on their work would be a tax, and nothing in the licence asks
+ * for one.
+ *
+ * Must contain no `--` (ends an HTML comment early) and no `</script>` (the data
+ * sentinel's own test asserts the page holds exactly one).
+ */
+export declare const SOURCE_NOTICE = "<!--\n  Rendered by diagc \u2014 https://github.com/Ferroman/diagc\n\n  This page embeds the diagc viewer, free software under the GNU Affero General\n  Public License, version 3 (AGPL-3.0-only). The complete corresponding source of\n  the viewer is available at the address above.\n\n  The diagram on this page is not covered by that licence. See the additional\n  permissions under section 7 in the project's LICENSE file.\n-->";
+/** Insert the source offer without disturbing the doctype. */
+export declare function withSourceNotice(shell: string): string;
+export declare function stampHtml(shell: string, data: unknown): string;

package/dist/publish/html.js

@@ -0,0 +1,45 @@
+import { SOURCE_URL } from '@diagc/core';
+export const DG_DATA_SENTINEL = '"__DG_DIAGRAM_DATA__"';
+export { SOURCE_URL };
+/**
+ * AGPL section 13 offer, carried by every published page.
+ *
+ * A published page inlines the whole viewer bundle, so publishing one distributes
+ * AGPL-licensed code and owes its recipients an offer of the corresponding source. The
+ * bundle `publish` stamps is unmodified, so pointing upstream discharges that — the
+ * author of the diagram has nothing to do, which is the point: compliance should not be
+ * something they can forget.
+ *
+ * A comment rather than visible chrome, deliberately. The page belongs to whoever drew
+ * the diagram; a banner on their work would be a tax, and nothing in the licence asks
+ * for one.
+ *
+ * Must contain no `--` (ends an HTML comment early) and no `</script>` (the data
+ * sentinel's own test asserts the page holds exactly one).
+ */
+export const SOURCE_NOTICE = `<!--
+  Rendered by diagc — ${SOURCE_URL}
+
+  This page embeds the diagc viewer, free software under the GNU Affero General
+  Public License, version 3 (AGPL-3.0-only). The complete corresponding source of
+  the viewer is available at the address above.
+
+  The diagram on this page is not covered by that licence. See the additional
+  permissions under section 7 in the project's LICENSE file.
+-->`;
+/**
+ * Anchored at the start: only a leading doctype counts. The notice has to land *after*
+ * it — an HTML comment ahead of the doctype puts the document into quirks mode in every
+ * browser, which would silently change how the viewer lays out.
+ */
+const LEADING_DOCTYPE = /^\s*<!doctype html>/i;
+/** Insert the source offer without disturbing the doctype. */
+export function withSourceNotice(shell) {
+    return LEADING_DOCTYPE.test(shell)
+        ? shell.replace(LEADING_DOCTYPE, (m) => `${m}\n${SOURCE_NOTICE}`)
+        : `${SOURCE_NOTICE}\n${shell}`;
+}
+export function stampHtml(shell, data) {
+    const json = JSON.stringify(data).replace(/</g, '\\u003c');
+    return withSourceNotice(shell).replace(DG_DATA_SENTINEL, () => json);
+}

package/dist/publish/pageSize.d.ts

@@ -0,0 +1,21 @@
+export interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * The capture frame for a diagram: the content at the largest scale that fits
+ * the caps, plus padding, plus an unscaled `reserve` for the legend.
+ *
+ * `reserve` is in SCREEN px and is deliberately NOT part of `bounds`. The
+ * content is scaled to fit the frame; the legend is a fixed-size overlay and is
+ * not. Adding the legend's height to `bounds.height` shrinks it by the same
+ * factor as the graph, so the frame comes out short by `reserve * (1 - scale)`
+ * — and the fit, which still pays the legend in full, draws the graph at a
+ * fraction of the intended size with the rest of the frame left blank.
+ */
+export declare function pageSize(bounds: Size, opts: {
+    maxWidth: number;
+    padding: number;
+    maxHeight?: number;
+    reserve?: number;
+}): Size;

package/dist/publish/pageSize.js

@@ -0,0 +1,26 @@
+/**
+ * The capture frame for a diagram: the content at the largest scale that fits
+ * the caps, plus padding, plus an unscaled `reserve` for the legend.
+ *
+ * `reserve` is in SCREEN px and is deliberately NOT part of `bounds`. The
+ * content is scaled to fit the frame; the legend is a fixed-size overlay and is
+ * not. Adding the legend's height to `bounds.height` shrinks it by the same
+ * factor as the graph, so the frame comes out short by `reserve * (1 - scale)`
+ * — and the fit, which still pays the legend in full, draws the graph at a
+ * fraction of the intended size with the rest of the frame left blank.
+ */
+export function pageSize(bounds, opts) {
+    const pad = opts.padding * 2;
+    // Cap the reserve at half the frame, mirroring the viewer's legendPadding: a
+    // legend taller than the frame must not leave the graph nothing to sit in.
+    const reserve = opts.maxHeight === undefined
+        ? Math.max(0, opts.reserve ?? 0)
+        : Math.min(Math.max(0, opts.reserve ?? 0), Math.floor(opts.maxHeight / 2));
+    const fit = (avail, extent) => (extent <= 0 ? 1 : avail / extent);
+    const scale = Math.min(1, // never upscale: a small diagram is captured at 1:1, as it always was
+    fit(opts.maxWidth - pad, bounds.width), opts.maxHeight === undefined ? 1 : fit(opts.maxHeight - pad - reserve, bounds.height));
+    return {
+        width: Math.max(1, Math.round(bounds.width * scale) + pad),
+        height: Math.max(1, Math.round(bounds.height * scale) + pad + reserve),
+    };
+}

package/dist/publish/publish.d.ts

@@ -0,0 +1,18 @@
+export interface PublishOptions {
+    srcDir: string;
+    artifactsDir: string;
+    htmlDir: string;
+    staticDir: string;
+    shellPath: string;
+    libraryDir: string;
+    assetsDir: string;
+    images: boolean;
+    names?: string[];
+    renderPng?: (htmlPath: string, pngPath: string) => Promise<void>;
+}
+export interface PublishResult {
+    pages: string[];
+    images: string[];
+    gallery: string;
+}
+export declare function publishDiagrams(opts: PublishOptions): Promise<PublishResult>;

package/dist/publish/publish.js

@@ -0,0 +1,100 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { errMessage, isDrawings } from '@diagc/core';
+import { classifyAssetRef, rewriteAssetRefs, safeAssetPath } from './assets.js';
+import { buildGallery } from './gallery.js';
+import { discoverDiagrams } from './discover.js';
+import { stampHtml } from './html.js';
+async function readMaybe(p) {
+    try {
+        return await readFile(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function publishDiagrams(opts) {
+    const shell = await readFile(opts.shellPath, 'utf8');
+    await mkdir(opts.htmlDir, { recursive: true });
+    if (opts.images)
+        await mkdir(opts.staticDir, { recursive: true });
+    const cache = new Map();
+    const resolveAsset = (ref) => cache.get(ref);
+    let all = await discoverDiagrams(opts.artifactsDir, opts.srcDir);
+    if (opts.names !== undefined && opts.names.length > 0) {
+        const want = new Set(opts.names);
+        all = all.filter((d) => want.has(d.name));
+    }
+    const pages = [];
+    const images = [];
+    for (const d of all) {
+        try {
+            const modelRaw = JSON.parse(await readFile(d.modelPath, 'utf8'));
+            const layout = d.layoutPath !== undefined
+                ? JSON.parse(await readFile(d.layoutPath, 'utf8'))
+                : undefined;
+            // A hand-edited sidecar can be valid JSON and still not be a drawings
+            // overlay. Publishing it would stamp shapeless data into a page that has
+            // no validator of its own, so it is warned about and dropped — the page
+            // still ships, just without ink. (Unparseable JSON keeps its old
+            // behaviour: it throws, and the diagram is skipped below.)
+            let drawings;
+            if (d.drawingsPath !== undefined) {
+                const parsed = JSON.parse(await readFile(d.drawingsPath, 'utf8'));
+                if (isDrawings(parsed))
+                    drawings = parsed;
+                else
+                    console.warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
+            }
+            // Pre-read every inlinable ref so the rewrite can stay a pure sync function.
+            for (const n of modelRaw.nodes) {
+                for (const ref of [n.image, n.shape]) {
+                    if (ref === undefined || cache.has(ref))
+                        continue;
+                    const kind = classifyAssetRef(ref);
+                    if (kind === 'skip')
+                        continue;
+                    const base = kind === 'library' ? opts.libraryDir : opts.assetsDir;
+                    const rel = kind === 'library' ? ref.slice('/library/'.length)
+                        : kind === 'api-assets' ? ref.slice('/api/assets/'.length)
+                            : ref;
+                    const filePath = safeAssetPath(base, rel);
+                    if (filePath === undefined) {
+                        console.warn(`publish: refusing out-of-root asset "${ref}" for diagram "${d.name}"; leaving ref as-is.`);
+                        continue;
+                    }
+                    const bytes = await readMaybe(filePath);
+                    if (bytes !== undefined)
+                        cache.set(ref, bytes);
+                    else
+                        console.warn(`publish: could not read asset "${ref}" for diagram "${d.name}" (looked in ${filePath}); leaving ref as-is.`);
+                }
+            }
+            const inlined = rewriteAssetRefs(modelRaw, resolveAsset);
+            const pagePath = path.join(opts.htmlDir, `${d.name}.html`);
+            await mkdir(path.dirname(pagePath), { recursive: true });
+            await writeFile(pagePath, stampHtml(shell, { model: inlined, layout, drawings }));
+            pages.push(pagePath);
+            if (opts.images && opts.renderPng !== undefined) {
+                const pngPath = path.join(opts.staticDir, `${d.name}.png`);
+                await mkdir(path.dirname(pngPath), { recursive: true });
+                await opts.renderPng(pagePath, pngPath);
+                images.push(pngPath);
+            }
+        }
+        catch (e) {
+            console.warn(`publish: skipping diagram "${d.name}": ${errMessage(e)}`);
+            continue;
+        }
+    }
+    // Only diagrams whose page was actually written belong in the gallery — a
+    // source that failed before its HTML wrote would otherwise get a dead link.
+    const written = new Set(pages);
+    const galleryPath = path.join(opts.htmlDir, 'index.html');
+    await writeFile(galleryPath, buildGallery(all
+        .filter((d) => written.has(path.join(opts.htmlDir, `${d.name}.html`)))
+        .map((d) => ({
+        name: d.name, hasImage: images.includes(path.join(opts.staticDir, `${d.name}.png`)),
+    }))));
+    return { pages, images, gallery: galleryPath };
+}

package/dist/publish/snapshot.d.ts

@@ -0,0 +1,3 @@
+/** Locate an installed Chrome/Chromium; undefined means "no browser available". */
+export declare function findChrome(): string | undefined;
+export declare function renderPng(htmlPath: string, pngPath: string): Promise<void>;

package/dist/publish/snapshot.js

@@ -0,0 +1,53 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright-core';
+import { pageSize } from './pageSize.js';
+/** Locate an installed Chrome/Chromium; undefined means "no browser available". */
+export function findChrome() {
+    const env = process.env['CHROME_PATH'];
+    if (env !== undefined && existsSync(env))
+        return env;
+    const candidates = [
+        '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium',
+        '/usr/bin/chromium-browser', '/snap/bin/chromium',
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    ];
+    return candidates.find((p) => existsSync(p));
+}
+/** Frame padding around the graph, in screen px. */
+const FRAME_PADDING = 32;
+export async function renderPng(htmlPath, pngPath) {
+    const executablePath = findChrome();
+    if (executablePath === undefined) {
+        throw new Error('No Chrome found for image export. Install Google Chrome/Chromium, set CHROME_PATH, or run with --no-images.');
+    }
+    const browser = await chromium.launch({ executablePath, headless: true });
+    try {
+        const page = await browser.newPage({ viewport: { width: 1600, height: 1000 }, deviceScaleFactor: 2 });
+        // `?export=1` tells the viewer to unfold every group for a full overview.
+        await page.goto(`${pathToFileURL(path.resolve(htmlPath)).href}?export=1`);
+        await page.waitForFunction(() => window.__DG_READY__ === true, null, { timeout: 15_000 });
+        // __DG_BOUNDS__ is the TRUE node bounding box in flow coordinates, so the
+        // frame gets the real content aspect; then re-fit into it (React Flow's
+        // `fitView` prop only fits on init, not after this resize) so nothing clips.
+        // __DG_RESERVE__ is the legend's extent in SCREEN px and is added to the
+        // frame unscaled — see pageSize for why the two must not be mixed.
+        const bounds = await page.evaluate(() => window.__DG_BOUNDS__ ?? { width: 1200, height: 800 });
+        const reserve = await page.evaluate(() => window.__DG_RESERVE__ ?? null);
+        const size = pageSize(bounds, {
+            maxWidth: 2000, maxHeight: 1400, padding: FRAME_PADDING,
+            // Only a top/bottom legend costs height, which is all `legendReserve`
+            // ever reports today; a side legend would need pageSize to widen instead.
+            reserve: reserve === null || reserve.side === 'left' || reserve.side === 'right' ? 0 : reserve.px,
+        });
+        await page.setViewportSize(size);
+        await page.evaluate((pad) => window.__DG_FIT__?.(pad), FRAME_PADDING);
+        await page.waitForTimeout(350); // let the re-fit settle into the resized frame
+        const el = await page.$('.react-flow');
+        await (el ?? page).screenshot({ path: pngPath });
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/serve.d.ts

@@ -0,0 +1,32 @@
+export declare const contentTypeFor: (file: string) => string;
+export interface ServeOptions {
+    /** prebuilt studio bundle (index.html + assets + library) */
+    studioDir: string;
+    diagramsDir: string;
+    artifactsDir: string;
+    /** first port to try; the server walks upward when one is taken */
+    port?: number;
+    host?: string;
+}
+export interface StudioServer {
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+}
+/** Resolve a request path to a file inside `root`, or undefined if it escapes.
+ *
+ * Traversal is *clamped*, not rejected: `posix.normalize` collapses `..` against
+ * the leading `/`, so `/a/../../etc/passwd` becomes `/etc/passwd` and then
+ * resolves under `root`. A request can therefore only ever name something inside
+ * the bundle. The explicit boundary check below is not redundant — on Windows a
+ * backslash segment survives posix normalization and would escape at
+ * `path.resolve` — and it is the assertion that keeps this function honest if
+ * the normalization above is ever changed. */
+export declare function resolveStatic(root: string, urlPath: string): string | undefined;
+/** Serve the prebuilt studio and its read/write API over plain http.
+ *
+ * This is the installed-from-npm counterpart to the Vite dev server: same API
+ * routes (they come from the same table), no bundler, no workspace. The studio
+ * itself is an ordinary SPA that only ever talks to `/api/*`, which is what
+ * makes a static bundle behave identically here. */
+export declare function startStudioServer(opts: ServeOptions): Promise<StudioServer>;

package/dist/serve.js

@@ -0,0 +1,154 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { errMessage } from '@diagc/core';
+import { handleApiRequest } from './api/dispatch.js';
+import * as handlers from './api/handlers.js';
+/** Content types for what a Vite build actually emits, plus the image formats a
+ * diagram can reference. Anything else is streamed as octet-stream. */
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.map': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.wasm': 'application/wasm',
+};
+export const contentTypeFor = (file) => CONTENT_TYPES[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+/** Resolve a request path to a file inside `root`, or undefined if it escapes.
+ *
+ * Traversal is *clamped*, not rejected: `posix.normalize` collapses `..` against
+ * the leading `/`, so `/a/../../etc/passwd` becomes `/etc/passwd` and then
+ * resolves under `root`. A request can therefore only ever name something inside
+ * the bundle. The explicit boundary check below is not redundant — on Windows a
+ * backslash segment survives posix normalization and would escape at
+ * `path.resolve` — and it is the assertion that keeps this function honest if
+ * the normalization above is ever changed. */
+export function resolveStatic(root, urlPath) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(urlPath.split('?')[0] ?? '');
+    }
+    catch {
+        return undefined; // malformed percent-encoding
+    }
+    // Normalizing against '/' first collapses '..' segments before they are ever
+    // joined to a real directory, so the resolve below cannot climb out.
+    const rel = path.posix.normalize(decoded).replace(/^(\.\.(\/|$))+/, '').replace(/^\/+/, '');
+    const full = path.resolve(root, rel);
+    const rootResolved = path.resolve(root);
+    if (full !== rootResolved && !full.startsWith(rootResolved + path.sep))
+        return undefined;
+    return full;
+}
+async function sendFile(res, file) {
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            return false;
+        res.statusCode = 200;
+        res.setHeader('content-type', contentTypeFor(file));
+        res.setHeader('content-length', String(info.size));
+        // The studio is a localhost tool reading files the user is actively
+        // editing; caching a bundle across a reinstall would serve a stale studio.
+        res.setHeader('cache-control', 'no-store');
+        await new Promise((resolve, reject) => {
+            createReadStream(file).on('error', reject).on('end', resolve).pipe(res);
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Listen on the first free port at or above `port`. */
+function listen(server, port, host, attempts = 20) {
+    return new Promise((resolve, reject) => {
+        const tryPort = (p, left) => {
+            const onError = (e) => {
+                server.removeListener('listening', onListening);
+                if (e.code === 'EADDRINUSE' && left > 0) {
+                    tryPort(p + 1, left - 1);
+                    return;
+                }
+                reject(e);
+            };
+            const onListening = () => {
+                server.removeListener('error', onError);
+                // Read the bound port back rather than echoing the requested one: port
+                // 0 means "any free port", and the caller needs the real one to print.
+                const addr = server.address();
+                resolve(typeof addr === 'object' && addr !== null ? addr.port : p);
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(p, host);
+        };
+        tryPort(port, attempts);
+    });
+}
+/** Serve the prebuilt studio and its read/write API over plain http.
+ *
+ * This is the installed-from-npm counterpart to the Vite dev server: same API
+ * routes (they come from the same table), no bundler, no workspace. The studio
+ * itself is an ordinary SPA that only ever talks to `/api/*`, which is what
+ * makes a static bundle behave identically here. */
+export async function startStudioServer(opts) {
+    const { studioDir, diagramsDir, artifactsDir } = opts;
+    const host = opts.host ?? '127.0.0.1';
+    const index = path.join(studioDir, 'index.html');
+    const server = createServer((req, res) => {
+        void (async () => {
+            try {
+                if (await handleApiRequest(req, res, { diagramsDir, artifactsDir }, handlers))
+                    return;
+                const file = resolveStatic(studioDir, req.url ?? '/');
+                if (file === undefined) {
+                    res.statusCode = 400;
+                    res.end('Bad request');
+                    return;
+                }
+                if (await sendFile(res, file))
+                    return;
+                // Unmatched API paths must 404 as API, not fall back to the SPA shell —
+                // a JSON caller should never have to parse HTML to learn it missed.
+                if ((req.url ?? '').startsWith('/api/')) {
+                    res.statusCode = 404;
+                    res.setHeader('content-type', 'application/json');
+                    res.end(JSON.stringify({ issues: [{ message: `No such API route: ${req.url ?? ''}` }] }));
+                    return;
+                }
+                if (await sendFile(res, index))
+                    return;
+                res.statusCode = 404;
+                res.end('Not found');
+            }
+            catch (e) {
+                res.statusCode = 500;
+                res.end(errMessage(e));
+            }
+        })();
+    });
+    const port = await listen(server, opts.port ?? 5173, host);
+    return {
+        url: `http://${host}:${port}`,
+        port,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/snapshots.d.ts

@@ -0,0 +1,13 @@
+import { type IncludeResolver } from '@diagc/core';
+export type SnapshotMode = 'locked' | 'update';
+export interface SnapshotSession {
+    resolver: IncludeResolver;
+    prune(): Promise<void>;
+}
+/**
+ * Wrap an include resolver with lockfile-pinned vendoring for remote specs.
+ * Local specs pass straight through — they are already in-repo and reviewable.
+ * The wrapper always returns the ORIGINAL absolute URL as the ref, so cycle
+ * detection and nested relative resolution behave exactly as unlocked fetches.
+ */
+export declare function snapshotSession(base: IncludeResolver, rootDir: string, mode: SnapshotMode): SnapshotSession;