@elaraai/e3-ui-cli 1.0.28

package/dist/capture.js

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Headless capture: serve the prebuilt browser app, inject the component
+ * payload, wait for fonts + render to settle, and screenshot to PNG.
+ *
+ * The app is served over a throwaway `node:http` server (NOT `file://` —
+ * Chromium blocks ES-module scripts loaded from `file://` on CORS grounds).
+ * The wait/settle/screenshot loop mirrors the in-repo snapshot pipeline
+ * (`libs/east-ui/scripts/snapshot-capture.mts`).
+ *
+ * @packageDocumentation
+ */
+import { createServer } from 'node:http';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { once } from 'node:events';
+import * as path from 'node:path';
+import { launchBrowser } from './browser.js';
+/** Default capture parameters — single source of truth (CLI help text in
+ *  `cli.ts` documents these values; keep them in sync). */
+export const CAPTURE_DEFAULTS = {
+    viewport: { width: 1280, height: 900 },
+    deviceScaleFactor: 2,
+    settleMs: 300,
+    timeoutMs: 30_000,
+    storageKey: 'shot',
+    statusPollMs: 100,
+    skeletonPollMs: 200,
+    errorTextLimit: 600,
+};
+const MIME = {
+    '.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',
+    '.map': 'application/json; charset=utf-8',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+};
+/** Serve the prebuilt app directory over a random localhost port. */
+/**
+ * Resolve a URL pathname to a file within `root`, or `null` if it would escape
+ * (path traversal). Uses a separator-boundary check so a sibling dir sharing the
+ * root's prefix cannot pass. Exported for unit tests.
+ */
+export function resolveWithinRoot(root, urlPathname) {
+    const resolvedRoot = path.resolve(root);
+    const rel = urlPathname === '/' ? 'index.html' : urlPathname.replace(/^\/+/, '');
+    const filePath = path.join(resolvedRoot, rel);
+    if (filePath !== resolvedRoot && !filePath.startsWith(resolvedRoot + path.sep))
+        return null;
+    return filePath;
+}
+function serveApp(appDir) {
+    const root = path.resolve(appDir);
+    const server = createServer((req, res) => {
+        void (async () => {
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const filePath = resolveWithinRoot(root, url.pathname);
+                if (!filePath) {
+                    res.statusCode = 403;
+                    res.end('forbidden');
+                    return;
+                }
+                const body = await readFile(filePath);
+                res.statusCode = 200;
+                res.setHeader('content-type', MIME[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream');
+                res.end(body);
+            }
+            catch {
+                res.statusCode = 404;
+                res.end('not found');
+            }
+        })();
+    });
+    return once(server.listen(0, '127.0.0.1'), 'listening').then(() => {
+        const port = server.address().port;
+        return { server, baseUrl: `http://127.0.0.1:${port}` };
+    });
+}
+/** Escape text for safe inclusion in HTML. Exported for unit tests. */
+export function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, c => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+}
+/**
+ * Inline `url(...woff2)` font references in CSS as base64 data URIs (read from
+ * the app's built `assets/`), so the standalone HTML renders with the brand
+ * fonts over `file://` with no server. A font that cannot be read is left as its
+ * original (server-relative) URL and a warning is emitted — a silently broken
+ * `--html` is worse than a visible warning. Exported for unit tests.
+ */
+export async function inlineFonts(css, appDir) {
+    const assetsDir = path.join(appDir, 'assets');
+    const re = /url\((['"]?)[^)'"]*?([^/)'"]+\.woff2)\1\)/g;
+    const cache = new Map();
+    for (const m of css.matchAll(re)) {
+        const name = m[2];
+        if (cache.has(name))
+            continue;
+        try {
+            const buf = await readFile(path.join(assetsDir, name));
+            cache.set(name, `data:font/woff2;base64,${buf.toString('base64')}`);
+        }
+        catch {
+            cache.set(name, '');
+            console.warn(`[e3-ui shot] could not inline font "${name}" into --html — it will be a relative URL that won't resolve standalone.`);
+        }
+    }
+    return css.replace(re, (full, _q, name) => {
+        const uri = cache.get(name);
+        return uri ? `url(${uri})` : full;
+    });
+}
+/**
+ * Build a self-contained HTML snapshot: the rendered body + every stylesheet
+ * rule serialized into one `<style>` block (Emotion injects rules via
+ * `insertRule`, so they are NOT in the serialized DOM and must be read from
+ * `document.styleSheets`), with fonts inlined and no scripts.
+ */
+async function selfContainedHtml(page, appDir) {
+    const { bodyHtml, cssText, title } = await page.evaluate(() => {
+        // `document.styleSheets` (Emotion's injected <style>s) PLUS
+        // `adoptedStyleSheets` (constructable sheets — where Vite injects the
+        // @fontsource @font-face rules, which the styleSheets list misses).
+        const sheets = [
+            ...Array.from(document.styleSheets),
+            ...(document.adoptedStyleSheets ?? []),
+        ];
+        const css = sheets
+            .map(sheet => {
+            try {
+                return Array.from(sheet.cssRules).map(r => r.cssText).join('\n');
+            }
+            catch {
+                return '';
+            }
+        })
+            .filter(Boolean)
+            .join('\n\n');
+        return { bodyHtml: document.body.innerHTML, cssText: css, title: document.title || 'e3-ui shot' };
+    });
+    const inlined = await inlineFonts(cssText, appDir);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>${escapeHtml(title)}</title>
+<style>
+${inlined}
+</style>
+</head>
+<body>
+${bodyHtml}
+</body>
+</html>
+`;
+}
+/**
+ * Render a component payload to a PNG (and optionally a standalone HTML).
+ *
+ * @param opts - Capture options
+ * @throws If the app reports a compile/render error, or capture times out
+ */
+export async function capture(opts) {
+    const viewport = opts.viewport ?? CAPTURE_DEFAULTS.viewport;
+    const deviceScaleFactor = opts.deviceScaleFactor ?? CAPTURE_DEFAULTS.deviceScaleFactor;
+    const mode = opts.mode ?? { kind: 'frame' };
+    const settleMs = opts.settleMs ?? CAPTURE_DEFAULTS.settleMs;
+    const timeout = opts.timeoutMs ?? CAPTURE_DEFAULTS.timeoutMs;
+    const storageKey = opts.storageKey ?? CAPTURE_DEFAULTS.storageKey;
+    // Pre-flight: fail clearly if the prebuilt app is missing, instead of
+    // letting a 404 page turn into an opaque navigation timeout.
+    if (!existsSync(path.join(opts.appDir, 'index.html'))) {
+        throw new Error(`Prebuilt app not found at ${opts.appDir} — run \`make build\` (or \`npm run build\`) first.`);
+    }
+    const { server, baseUrl } = await serveApp(opts.appDir);
+    let browser;
+    try {
+        ({ browser } = await launchBrowser());
+        const context = await browser.newContext({ viewport, deviceScaleFactor });
+        const page = await context.newPage();
+        const consoleErrors = [];
+        page.on('pageerror', err => consoleErrors.push(err.message));
+        page.on('console', msg => { if (msg.type() === 'error')
+            consoleErrors.push(msg.text()); });
+        // Inject the payload BEFORE any page script runs. The task-mode hard-stop
+        // deadline is derived from the capture timeout (minus a buffer) so the app
+        // always reports before the driver's navigation timeout fires.
+        const taskDeadlineMs = Math.max(5_000, timeout - 5_000);
+        await page.addInitScript(([p, key, deadline]) => {
+            window.__E3_UI_SHOT__ = p;
+            window.__E3_UI_SHOT_KEY__ = key;
+            window.__E3_UI_SHOT_DEADLINE__ = deadline;
+        }, [opts.payload, storageKey, taskDeadlineMs]);
+        // Component mode has no e3 polling, so wait for `networkidle` (catches
+        // lazy chunks / Map tiles / chart sizing). Task mode polls the e3 server
+        // so the network never idles — use `load` and rely on the readiness marker.
+        await page.goto(`${baseUrl}/`, {
+            waitUntil: opts.payload.kind === 'task' ? 'load' : 'networkidle',
+            timeout,
+        });
+        await page.evaluate(() => document.fonts.ready);
+        // Both modes signal terminal state on #shot-root[data-shot-status]:
+        // 'ready' once content has rendered (component: next frame; task: once
+        // e3 fetches settle), or 'error' on an East compile/render failure.
+        try {
+            await page.waitForFunction(() => {
+                const s = document.querySelector('#shot-root')?.getAttribute('data-shot-status');
+                return s === 'ready' || s === 'error';
+            }, { timeout, polling: CAPTURE_DEFAULTS.statusPollMs });
+        }
+        catch {
+            const detail = consoleErrors.length ? `\nBrowser errors:\n  ${consoleErrors.join('\n  ')}` : '';
+            throw new Error(`Timed out after ${timeout}ms waiting for the render to complete.${detail}\n` +
+                `(For a slow live task raise --timeout; otherwise the component may have failed to load.)`);
+        }
+        // Surface render/compile failures via stable hooks (NOT title-text
+        // scraping): data-shot-status='error', [data-east-error] from
+        // EastErrorDisplay (component mode), and [data-status="error"] from
+        // e3-ui's StatusDisplay / ErrorBoundary (task fetch/decode/render errors).
+        const renderError = await page.evaluate((limit) => {
+            const root = document.querySelector('#shot-root');
+            if (root?.getAttribute('data-shot-status') === 'error') {
+                return root.getAttribute('data-shot-error') ?? 'unknown render error';
+            }
+            const card = document.querySelector('[data-east-error], [data-status="error"]');
+            return card ? card.innerText.slice(0, limit) : null;
+        }, CAPTURE_DEFAULTS.errorTextLimit);
+        if (renderError) {
+            throw new Error(`Render failed:\n${renderError}`);
+        }
+        // A live task that hit its hard-stop without settling marks itself partial.
+        const partial = await page.evaluate(() => document.querySelector('#shot-root')?.getAttribute('data-shot-partial') === 'true');
+        if (partial) {
+            console.warn('[e3-ui shot] the live task did not finish loading before capture — the image may be incomplete (raise --timeout).');
+        }
+        // Let in-component skeletons clear, then settle. A component may keep a
+        // skeleton legitimately (slow async chart/map) — warn rather than fail,
+        // mirroring the in-repo snapshot pipeline.
+        await page
+            .waitForFunction(() => document.querySelectorAll('.elara-skeleton').length === 0, { timeout, polling: CAPTURE_DEFAULTS.skeletonPollMs })
+            .catch(() => console.warn('[e3-ui shot] skeletons still present at capture — the image may be premature (raise --wait).'));
+        await page.waitForTimeout(settleMs);
+        if (mode.kind === 'full-page') {
+            await page.screenshot({ path: opts.outPng, fullPage: true });
+        }
+        else {
+            const selector = mode.kind === 'element' ? mode.selector : '#shot-frame';
+            const locator = page.locator(selector);
+            if (await locator.count() === 0) {
+                throw new Error(`No element matches selector "${selector}" to screenshot.`);
+            }
+            await locator.first().screenshot({ path: opts.outPng });
+        }
+        if (opts.outHtml) {
+            await writeFile(opts.outHtml, await selfContainedHtml(page, opts.appDir), 'utf8');
+        }
+    }
+    finally {
+        await browser?.close();
+        server.close();
+    }
+}
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C;2DAC2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACtC,iBAAiB,EAAE,CAAC;IACpB,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,MAAM;IAClB,YAAY,EAAE,GAAG;IACjB,cAAc,EAAE,GAAG;IACnB,cAAc,EAAE,GAAG;CACb,CAAC;AAgCX,MAAM,IAAI,GAA2B;IACjC,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,gCAAgC;IACxC,MAAM,EAAE,yBAAyB;IACjC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,iCAAiC;IACzC,QAAQ,EAAE,YAAY;IACtB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,cAAc;CACzB,CAAC;AAEF,qEAAqE;AACrE;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,WAAmB;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,WAAW,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,QAAQ,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5F,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACrC,KAAK,CAAC,KAAK,IAAI,EAAE;YACb,IAAI,CAAC;gBACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;gBACxD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACvD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACZ,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;oBACrB,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;oBACrB,OAAO;gBACX,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACtC,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;gBACrB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,0BAA0B,CAAC,CAAC;gBACxG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACL,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;gBACrB,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACzB,CAAC;QACL,CAAC,CAAC,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QAC9D,MAAM,IAAI,GAAI,MAAM,CAAC,OAAO,EAAkB,CAAC,IAAI,CAAC;QACpD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,IAAI,EAAE,EAAE,CAAC;IAC3D,CAAC,CAAC,CAAC;AACP,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/B,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO;KACtE,CAAC,CAAC,CAAY,CAAA,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,MAAc;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,EAAE,GAAG,4CAA4C,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;YACvD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,0BAA0B,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,MAAM,CAAC;YACL,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,uCAAuC,IAAI,0EAA0E,CAAC,CAAC;QACxI,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,EAAU,EAAE,IAAY,EAAE,EAAE;QACtD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,iBAAiB,CAAC,IAAU,EAAE,MAAc;IACvD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QAC1D,4DAA4D;QAC5D,sEAAsE;QACtE,oEAAoE;QACpE,MAAM,MAAM,GAAoB;YAC5B,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YACnC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,IAAI,EAAE,CAAC;SACzC,CAAC;QACF,MAAM,GAAG,GAAG,MAAM;aACb,GAAG,CAAC,KAAK,CAAC,EAAE;YACT,IAAI,CAAC;gBAAC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAAC,CAAC;YACzE,MAAM,CAAC;gBAAC,OAAO,EAAE,CAAC;YAAC,CAAC;QACxB,CAAC,CAAC;aACD,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,MAAM,CAAC,CAAC;QAClB,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,YAAY,EAAE,CAAC;IACtG,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,OAAO;;;;;SAKF,UAAU,CAAC,KAAK,CAAC;;EAExB,OAAO;;;;EAIP,QAAQ;;;CAGT,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAoB;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,CAAC;IAC5D,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;IACvF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,CAAC,SAAS,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,gBAAgB,CAAC,UAAU,CAAC;IAElE,sEAAsE;IACtE,6DAA6D;IAC7D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,MAAM,qDAAqD,CAAC,CAAC;IACnH,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,OAA4B,CAAC;IACjC,IAAI,CAAC;QACD,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,aAAa,EAAE,CAAC,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAErC,MAAM,aAAa,GAAa,EAAE,CAAC;QACnC,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,OAAO;YAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE3F,0EAA0E;QAC1E,2EAA2E;QAC3E,+DAA+D;QAC/D,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,aAAa,CACpB,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE;YAClB,MAAiD,CAAC,cAAc,GAAG,CAAC,CAAC;YACrE,MAAqD,CAAC,kBAAkB,GAAG,GAAG,CAAC;YAC/E,MAA0D,CAAC,uBAAuB,GAAG,QAAQ,CAAC;QACnG,CAAC,EACD,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAU,CACtD,CAAC;QAEF,uEAAuE;QACvE,yEAAyE;QACzE,4EAA4E;QAC5E,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,GAAG,EAAE;YAC3B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;YAChE,OAAO;SACV,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAEhD,oEAAoE;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,eAAe,CACtB,GAAG,EAAE;gBACD,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,kBAAkB,CAAC,CAAC;gBACjF,OAAO,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,OAAO,CAAC;YAC1C,CAAC,EACD,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,CAAC,YAAY,EAAE,CACtD,CAAC;QACN,CAAC;QAAC,MAAM,CAAC;YACL,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,wBAAwB,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChG,MAAM,IAAI,KAAK,CACX,mBAAmB,OAAO,yCAAyC,MAAM,IAAI;gBAC7E,0FAA0F,CAC7F,CAAC;QACN,CAAC;QAED,mEAAmE;QACnE,8DAA8D;QAC9D,oEAAoE;QACpE,2EAA2E;QAC3E,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE;YAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;YAClD,IAAI,IAAI,EAAE,YAAY,CAAC,kBAAkB,CAAC,KAAK,OAAO,EAAE,CAAC;gBACrD,OAAO,IAAI,CAAC,YAAY,CAAC,iBAAiB,CAAC,IAAI,sBAAsB,CAAC;YAC1E,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,0CAA0C,CAAC,CAAC;YAChF,OAAO,IAAI,CAAC,CAAC,CAAE,IAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QACpC,IAAI,WAAW,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,mBAAmB,WAAW,EAAE,CAAC,CAAC;QACtD,CAAC;QAED,4EAA4E;QAC5E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAC/B,GAAG,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,mBAAmB,CAAC,KAAK,MAAM,CAC3F,CAAC;QACF,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,mHAAmH,CAAC,CAAC;QACtI,CAAC;QAED,wEAAwE;QACxE,wEAAwE;QACxE,2CAA2C;QAC3C,MAAM,IAAI;aACL,eAAe,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,MAAM,KAAK,CAAC,EAC5E,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,CAAC,cAAc,EAAE,CAAC;aACzD,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,8FAA8F,CAAC,CAAC,CAAC;QAC/H,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAEpC,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;aAAM,CAAC;YACJ,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC;YACzE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACvC,IAAI,MAAM,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,kBAAkB,CAAC,CAAC;YAChF,CAAC;YACD,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACtF,CAAC;IACL,CAAC;YAAS,CAAC;QACP,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/cli.js

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * e3-ui CLI — render east-ui / e3-ui components to PNG.
+ *
+ * One screenshot verb, three `--from-*` sources (mirroring e3-cli's
+ * `--from-zip` / `--from-source`):
+ *   e3-ui shot --from-source <file.tsx>           a TS/TSX component
+ *   e3-ui shot --from-ir <file.beast2|.json>      serialized component IR
+ *   e3-ui shot --from-task <ws.task> --repo <r>   a live e3 task's output (dataflow must have run)
+ *
+ * Plus the browser lifecycle for headless servers:
+ *   e3-ui install-browser [--with-deps]           download the managed headless Chromium
+ *   e3-ui doctor                                  diagnose the browser setup
+ *
+ * @packageDocumentation
+ */
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { shotCommand } from './commands/shot.js';
+import { installBrowser, doctor } from './browser.js';
+import { CAPTURE_DEFAULTS as D } from './capture.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+const program = new Command();
+program
+    .name('e3-ui')
+    .description('Render east-ui / e3-ui components to PNG')
+    .version(packageJson.version);
+program
+    .command('shot')
+    .description('Render an east-ui / e3-ui component to a PNG — from a source file, serialized IR, or a live e3 task')
+    // Exactly one source (mutually exclusive).
+    .option('--from-source <file>', 'Render a TS/TSX component source file (.ts/.tsx)')
+    .option('--from-ir <file>', 'Render serialized component IR (.beast2/.json); "-" reads from stdin')
+    .option('--from-task <ws.task>', 'Render a live e3 task\'s output (requires --repo; the workspace dataflow must have already run)')
+    .option('--repo <path>', 'Local e3 repository path for --from-task')
+    // --from-source only.
+    .option('-e, --export <name>', 'Which exported component to render (default: the default / sole export)')
+    // Shared.
+    .option('-o, --output <path>', 'Output PNG path (default: derived from the source / task name)')
+    .option('--html', 'Also write a self-contained HTML next to the PNG')
+    .option('--viewport <WxH>', `Chromium viewport (default ${D.viewport.width}x${D.viewport.height})`)
+    .option('--dpr <n>', `Device scale factor / pixel ratio (default ${D.deviceScaleFactor})`)
+    .option('--full-page', 'Capture the full page instead of the component frame')
+    .option('--element <selector>', 'Capture a specific CSS selector instead of the component frame')
+    .option('--wait <ms>', `Extra settle time after fonts/skeletons clear (default ${D.settleMs})`)
+    .option('--timeout <ms>', `Max time to wait for the render to complete (default ${D.timeoutMs}); raise for slow live tasks`)
+    .option('--storage-key <key>', 'Storage key prefix for persisted component state')
+    .action(shotCommand);
+program
+    .command('install-browser')
+    .description('Download the version-matched headless Chromium into the playwright-managed cache (honors PLAYWRIGHT_BROWSERS_PATH)')
+    .option('--with-deps', 'Also install required system libraries (Linux only)')
+    .action(async (options) => {
+    process.exit(await installBrowser(options));
+});
+program
+    .command('doctor')
+    .description('Diagnose the browser setup: env overrides, launch cascade, and remediation')
+    .action(async () => {
+    process.exit(await doctor());
+});
+program.parseAsync().catch((err) => {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,IAAI,CAAC,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,0CAA0C,CAAC;KACvD,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;AAElC,OAAO;KACF,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,qGAAqG,CAAC;IACnH,2CAA2C;KAC1C,MAAM,CAAC,sBAAsB,EAAE,kDAAkD,CAAC;KAClF,MAAM,CAAC,kBAAkB,EAAE,sEAAsE,CAAC;KAClG,MAAM,CAAC,uBAAuB,EAAE,iGAAiG,CAAC;KAClI,MAAM,CAAC,eAAe,EAAE,0CAA0C,CAAC;IACpE,sBAAsB;KACrB,MAAM,CAAC,qBAAqB,EAAE,yEAAyE,CAAC;IACzG,UAAU;KACT,MAAM,CAAC,qBAAqB,EAAE,gEAAgE,CAAC;KAC/F,MAAM,CAAC,QAAQ,EAAE,kDAAkD,CAAC;KACpE,MAAM,CAAC,kBAAkB,EAAE,8BAA8B,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;KAClG,MAAM,CAAC,WAAW,EAAE,8CAA8C,CAAC,CAAC,iBAAiB,GAAG,CAAC;KACzF,MAAM,CAAC,aAAa,EAAE,sDAAsD,CAAC;KAC7E,MAAM,CAAC,sBAAsB,EAAE,gEAAgE,CAAC;KAChG,MAAM,CAAC,aAAa,EAAE,0DAA0D,CAAC,CAAC,QAAQ,GAAG,CAAC;KAC9F,MAAM,CAAC,gBAAgB,EAAE,wDAAwD,CAAC,CAAC,SAAS,8BAA8B,CAAC;KAC3H,MAAM,CAAC,qBAAqB,EAAE,kDAAkD,CAAC;KACjF,MAAM,CAAC,WAAW,CAAC,CAAC;AAEzB,OAAO;KACF,OAAO,CAAC,iBAAiB,CAAC;KAC1B,WAAW,CAAC,oHAAoH,CAAC;KACjI,MAAM,CAAC,aAAa,EAAE,qDAAqD,CAAC;KAC5E,MAAM,CAAC,KAAK,EAAE,OAA+B,EAAE,EAAE;IAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;AAChD,CAAC,CAAC,CAAC;AAEP,OAAO;KACF,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,4EAA4E,CAAC;KACzF,MAAM,CAAC,KAAK,IAAI,EAAE;IACf,OAAO,CAAC,IAAI,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;AACjC,CAAC,CAAC,CAAC;AAEP,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IACxC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/commands/shot.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { type InputFormat } from '../payload.js';
+/** Options accepted by the `shot` command (commander camel-cases flags). */
+export interface ShotCommandOptions {
+    fromSource?: string;
+    fromIr?: string;
+    fromTask?: string;
+    repo?: string;
+    export?: string;
+    output?: string;
+    html?: boolean;
+    viewport?: string;
+    dpr?: string;
+    fullPage?: boolean;
+    element?: string;
+    wait?: string;
+    timeout?: string;
+    storageKey?: string;
+}
+/** Parse `--dpr`, bounded to a sane range (mirrors the viewport bound). */
+export declare function parseDpr(value: string): number;
+/** Parse `WIDTHxHEIGHT`, bounded to a sane positive range. */
+export declare function parseViewport(spec: string): {
+    width: number;
+    height: number;
+};
+export declare function parsePositive(value: string, flag: string): number;
+/** Split a `<workspace>.<task>` specifier on its first dot. */
+export declare function parseTaskPath(spec: string): {
+    workspace: string;
+    task: string;
+};
+/** Detect the IR format of a `--from-ir` file (rejecting `.ts`/`.tsx`). */
+export declare function detectIrFormat(filePath: string): InputFormat;
+/** Default PNG base name: `<file-without-ext>` / `<ws>.<task>` / `shot`. */
+export declare function stripExt(filePath: string): string;
+/** Commander action for `e3-ui shot`. */
+export declare function shotCommand(options: ShotCommandOptions): Promise<void>;
+//# sourceMappingURL=shot.d.ts.map

package/dist/commands/shot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shot.d.ts","sourceRoot":"","sources":["../../src/commands/shot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAG/D,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS7E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAM/E;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAM5D;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjD;AAsBD,yCAAyC;AACzC,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqD5E"}

package/dist/commands/shot.js

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `e3-ui shot` — render an east-ui / e3-ui component to a PNG. Exactly one
+ * source: `--from-source` (a TS/TSX file), `--from-ir` (serialized IR), or
+ * `--from-task` (a live e3 task). Static and `State`-only components render with
+ * no backend; `--from-task` fetches a task's already-computed output.
+ *
+ * @packageDocumentation
+ */
+import { basename } from 'node:path';
+import { renderToPng, renderTaskToPng } from '../render.js';
+import { detectFormat } from '../payload.js';
+/** Max Chromium viewport dimension (px). */
+const MAX_VIEWPORT = 16384;
+/** Max device scale factor — `viewport × dpr` is the raster size, so an
+ *  unbounded dpr can OOM Chromium. */
+const MAX_DPR = 8;
+/** Parse `--dpr`, bounded to a sane range (mirrors the viewport bound). */
+export function parseDpr(value) {
+    const n = parsePositive(value, '--dpr');
+    if (n > MAX_DPR)
+        throw new Error(`Invalid --dpr "${value}" (must be 1..${MAX_DPR})`);
+    return n;
+}
+/** Parse `WIDTHxHEIGHT`, bounded to a sane positive range. */
+export function parseViewport(spec) {
+    const m = /^(\d+)x(\d+)$/i.exec(spec.trim());
+    if (!m)
+        throw new Error(`Invalid --viewport "${spec}" (expected WIDTHxHEIGHT, e.g. 1280x900)`);
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    if (width < 1 || height < 1 || width > MAX_VIEWPORT || height > MAX_VIEWPORT) {
+        throw new Error(`Invalid --viewport "${spec}" (each dimension must be 1..${MAX_VIEWPORT})`);
+    }
+    return { width, height };
+}
+export function parsePositive(value, flag) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`Invalid ${flag} "${value}" (expected a positive number)`);
+    return n;
+}
+/** Split a `<workspace>.<task>` specifier on its first dot. */
+export function parseTaskPath(spec) {
+    const dot = spec.indexOf('.');
+    if (dot <= 0 || dot === spec.length - 1) {
+        throw new Error(`Invalid --from-task "${spec}" (expected <workspace>.<task>)`);
+    }
+    return { workspace: spec.slice(0, dot), task: spec.slice(dot + 1) };
+}
+/** Detect the IR format of a `--from-ir` file (rejecting `.ts`/`.tsx`). */
+export function detectIrFormat(filePath) {
+    const format = detectFormat(filePath);
+    if (format === 'ts') {
+        throw new Error(`"${filePath}" is a TypeScript source — use --from-source, not --from-ir.`);
+    }
+    return format;
+}
+/** Default PNG base name: `<file-without-ext>` / `<ws>.<task>` / `shot`. */
+export function stripExt(filePath) {
+    return basename(filePath).replace(/\.(tsx?|beast2|json)$/i, '');
+}
+/** Shared capture options parsed from the CLI flags. */
+function captureOptionsFrom(options) {
+    let mode = { kind: 'frame' };
+    if (options.element)
+        mode = { kind: 'element', selector: options.element };
+    else if (options.fullPage)
+        mode = { kind: 'full-page' };
+    return {
+        mode,
+        ...(options.viewport ? { viewport: parseViewport(options.viewport) } : {}),
+        ...(options.dpr ? { deviceScaleFactor: parseDpr(options.dpr) } : {}),
+        ...(options.wait ? { settleMs: parsePositive(options.wait, '--wait') } : {}),
+        ...(options.timeout ? { timeoutMs: parsePositive(options.timeout, '--timeout') } : {}),
+    };
+}
+/** Commander action for `e3-ui shot`. */
+export async function shotCommand(options) {
+    try {
+        const sources = [
+            options.fromSource !== undefined ? 'source' : null,
+            options.fromIr !== undefined ? 'ir' : null,
+            options.fromTask !== undefined ? 'task' : null,
+        ].filter((s) => s !== null);
+        if (sources.length !== 1) {
+            throw new Error('Provide exactly one of --from-source, --from-ir, or --from-task.');
+        }
+        // --from-task: a live e3 task.
+        if (options.fromTask !== undefined) {
+            if (!options.repo)
+                throw new Error('--from-task requires --repo (a local e3 repository path).');
+            const { workspace, task } = parseTaskPath(options.fromTask);
+            const output = options.output ?? `${workspace}.${task}.png`.replace(/[^\w.-]+/g, '_');
+            const html = options.html ? output.replace(/\.png$/i, '') + '.html' : undefined;
+            await renderTaskToPng({ repo: options.repo, workspace, task, output, html, ...captureOptionsFrom(options) });
+            console.log(`Wrote ${output}${html ? ` and ${html}` : ''}`);
+            return;
+        }
+        // --from-source (.ts/.tsx) or --from-ir (.beast2/.json | stdin).
+        let inputPath;
+        let from;
+        let outBase;
+        if (options.fromSource !== undefined) {
+            inputPath = options.fromSource;
+            from = 'ts';
+            outBase = stripExt(options.fromSource);
+        }
+        else {
+            const ir = options.fromIr;
+            inputPath = ir === '-' ? null : ir;
+            from = inputPath ? detectIrFormat(inputPath) : 'beast2';
+            outBase = inputPath ? stripExt(inputPath) : 'shot';
+        }
+        const output = options.output ?? `${outBase}.png`;
+        const html = options.html ? output.replace(/\.png$/i, '') + '.html' : undefined;
+        await renderToPng({
+            input: { path: inputPath, from, exportName: options.export },
+            output,
+            html,
+            ...captureOptionsFrom(options),
+            ...(options.storageKey ? { storageKey: options.storageKey } : {}),
+        });
+        console.log(`Wrote ${output}${html ? ` and ${html}` : ''}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=shot.js.map

package/dist/commands/shot.js.map

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

package/dist/e3-server.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** A running single-repo e3 server. */
+export interface RepoServerHandle {
+    /** Base API URL (`http://127.0.0.1:<port>`). */
+    apiUrl: string;
+    /** Repo id — always `default` in single-repo mode. */
+    repo: string;
+    /** Stop the server. */
+    stop(): Promise<void>;
+}
+/**
+ * Start a single-repo e3 API server (CORS enabled) over a local repo path.
+ *
+ * @param repoPath - Local e3 repository directory
+ * @returns A handle with the API URL, repo id, and a `stop()`
+ */
+export declare function startRepoServer(repoPath: string): Promise<RepoServerHandle>;
+//# sourceMappingURL=e3-server.d.ts.map

package/dist/e3-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"e3-server.d.ts","sourceRoot":"","sources":["../src/e3-server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC7B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAajF"}

package/dist/e3-server.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Start a local e3 API server over a repository so the browser app can fetch a
+ * live task's output + bound datasets — the same `@elaraai/e3-api-server`
+ * single-repo bootstrap the VS Code extension uses (`startE3Server`).
+ *
+ * @packageDocumentation
+ */
+import * as path from 'node:path';
+import { createServer } from '@elaraai/e3-api-server';
+/**
+ * Start a single-repo e3 API server (CORS enabled) over a local repo path.
+ *
+ * @param repoPath - Local e3 repository directory
+ * @returns A handle with the API URL, repo id, and a `stop()`
+ */
+export async function startRepoServer(repoPath) {
+    const server = await createServer({
+        singleRepoPath: path.resolve(repoPath),
+        port: 0,
+        host: '127.0.0.1',
+        cors: true,
+    });
+    await server.start();
+    return {
+        apiUrl: `http://127.0.0.1:${server.port}`,
+        repo: 'default',
+        async stop() { await server.stop(); },
+    };
+}
+//# sourceMappingURL=e3-server.js.map

package/dist/e3-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"e3-server.js","sourceRoot":"","sources":["../src/e3-server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,YAAY,EAAe,MAAM,wBAAwB,CAAC;AAYnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IAClD,MAAM,MAAM,GAAW,MAAM,YAAY,CAAC;QACtC,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QACtC,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,IAAI;KACb,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,OAAO;QACH,MAAM,EAAE,oBAAoB,MAAM,CAAC,IAAI,EAAE;QACzC,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,IAAI,KAAK,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;KACxC,CAAC;AACN,CAAC"}