@jenga-ai/agent 3.2.0 → 3.4.0

package/project/app/ui/dist/assets/index-CdK3Qrep.css

@@ -0,0 +1 @@
+.loading-spinner{padding:2rem;text-align:center;color:#888;font-size:1rem}.error-message{padding:1rem;background:#fef2f2;border:1px solid #fca5a5;border-radius:4px;color:#b91c1c}.history-tab h2{margin-bottom:1rem}.history-empty{color:#888;padding:2rem;text-align:center}.history-list{list-style:none;padding:0;margin:0;border:1px solid #e5e7eb;border-radius:6px;overflow:hidden}.history-entry{display:flex;align-items:center;gap:.75rem;padding:.65rem 1rem;cursor:pointer;border-bottom:1px solid #f3f4f6;transition:background .12s}.history-entry:last-child{border-bottom:none}.history-entry:hover,.history-entry:focus{background:#f0f7ff;outline:none}.history-entry.selected{background:#dbeafe}.history-badge{flex-shrink:0;font-size:.75rem;font-weight:600;padding:.2rem .55rem;border-radius:999px;white-space:nowrap}.badge-commit{background:#dbeafe;color:#1d4ed8}.badge-rapport{background:#dcfce7;color:#15803d}.history-subject{flex:1;font-size:.9rem;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:#1f2937}.history-date{flex-shrink:0;font-size:.78rem;color:#9ca3af}.panel-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;background:#00000040;z-index:100}.detail-panel{position:fixed;top:0;right:0;bottom:0;width:min(480px,100vw);background:#fff;box-shadow:-4px 0 24px #00000026;z-index:101;overflow-y:auto;padding:1.5rem;animation:slideIn .2s ease-out}@keyframes slideIn{0%{transform:translate(100%)}to{transform:translate(0)}}.panel-close{float:right;background:none;border:none;font-size:1.25rem;cursor:pointer;color:#6b7280;padding:.25rem;line-height:1}.panel-close:hover{color:#111827}.panel-title{margin:0 0 1rem;font-size:1.1rem;color:#1f2937}.panel-meta{display:grid;grid-template-columns:auto 1fr;gap:.3rem 1rem;font-size:.85rem;margin-bottom:1rem}.panel-meta dt{font-weight:600;color:#6b7280;white-space:nowrap}.panel-meta dd{margin:0;color:#1f2937;word-break:break-all}.panel-subject{font-size:.95rem;color:#1f2937}.panel-body{font-size:.82rem;white-space:pre-wrap;background:#f9fafb;border:1px solid #e5e7eb;border-radius:4px;padding:.75rem;max-height:40vh;overflow-y:auto}.panel-empty{color:#9ca3af;font-style:italic}.markdown-body{font-size:.9rem;line-height:1.6;color:#1f2937}.markdown-body h1,.markdown-body h2,.markdown-body h3,.markdown-body h4{margin:1em 0 .4em;line-height:1.3}.markdown-body p{margin:.5em 0}.markdown-body code{background:#f3f4f6;padding:.1em .35em;border-radius:3px;font-size:.85em}.markdown-body pre{background:#f3f4f6;padding:.75rem;border-radius:4px;overflow-x:auto;font-size:.82em}.markdown-body pre code{background:none;padding:0}.markdown-body blockquote{border-left:3px solid #d1d5db;margin:.75em 0;padding:.25em 1em;color:#6b7280}.markdown-body ul,.markdown-body ol{padding-left:1.5em;margin:.5em 0}@media (max-width: 480px){.history-entry{flex-wrap:wrap;row-gap:var(--space-xs)}.history-subject{flex-basis:100%;order:3;white-space:normal}.detail-panel{box-sizing:border-box;padding:var(--space-md)}.panel-close{padding:var(--space-sm);font-size:1.5rem;display:inline-flex;align-items:center;justify-content:center;min-width:44px;min-height:44px}.panel-meta{grid-template-columns:1fr;gap:.15rem 0}.panel-meta dt{margin-top:var(--space-xs)}.markdown-body code{overflow-wrap:break-word;word-break:break-word}.markdown-body table{display:block;max-width:100%;overflow-x:auto}}.board-view{display:flex;flex-direction:column;gap:1.5rem}.epic-card{background:#fff;border:1px solid #e5e7eb;border-radius:6px;padding:1rem}.epic-header{display:flex;align-items:center;gap:.75rem;margin-bottom:.75rem}.epic-title{font-size:1.1rem;font-weight:600;margin:0;cursor:pointer}.epic-id{color:#6b7280;font-size:.85rem}.stories-list{display:flex;flex-direction:column;gap:.75rem;padding-left:1rem}.story-card{background:#f9fafb;border:1px solid #e5e7eb;border-radius:4px;padding:.75rem}.story-header{display:flex;align-items:center;gap:.5rem;margin-bottom:.5rem}.story-title{font-size:1rem;font-weight:500;margin:0;cursor:pointer}.story-id{color:#6b7280;font-size:.8rem}.tasks-list{display:flex;flex-direction:column;gap:.4rem;padding-left:1rem}.task-card{background:#fff;border:1px solid #e5e7eb;border-radius:3px;padding:.5rem .75rem;display:flex;align-items:center;gap:.5rem}.task-title{font-size:.9rem;flex:1;cursor:pointer}.task-id{color:#9ca3af;font-size:.75rem}.task-assigned{color:#6b7280;font-size:.8rem}.status-badge{padding:.2rem .5rem;border-radius:9999px;font-size:.75rem;font-weight:500}.badge-pending{background:#f3f4f6;color:#374151}.badge-running{background:#dbeafe;color:#1d4ed8}.badge-in-progress{background:#ffedd5;color:#c2410c}.badge-passed{background:#dcfce7;color:#15803d}.badge-passed-remarks{background:#fff;color:#15803d;border:1px solid #dcfce7}.badge-done{background:#dbeafe;color:#1d4ed8}.badge-failed{background:#fee2e2;color:#b91c1c}.empty-state{padding:2rem;text-align:center;color:#6b7280}.status-filter{display:flex;flex-wrap:wrap;gap:.75rem;padding:.75rem 1rem;background:#f9fafb;border:1px solid #e5e7eb;border-radius:6px}.status-filter-option{display:flex;align-items:center;gap:.35rem;font-size:.85rem;color:#374151;cursor:pointer}@media (max-width: 480px){.epic-header,.story-header{flex-wrap:wrap;row-gap:var(--space-xs)}.epic-title,.story-title{flex-basis:100%}.task-card{flex-wrap:wrap;row-gap:var(--space-xs)}.task-card .task-title{flex-basis:100%}.stories-list,.tasks-list{padding-left:var(--space-sm)}}.kanban-board{display:flex;align-items:flex-start;gap:.75rem;overflow-x:auto;padding-bottom:.5rem}.kanban-column{flex:0 0 220px;width:220px;background:#f9fafb;border:1px solid #e5e7eb;border-radius:6px;padding:.6rem;display:flex;flex-direction:column;gap:.5rem}.kanban-column-empty{flex:0 0 140px;width:140px;opacity:.6}.kanban-column-header{display:flex;align-items:center;justify-content:space-between;gap:.4rem}.kanban-column-title{font-size:.8rem;font-weight:600;color:#374151;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.kanban-column-count{font-size:.7rem;color:#6b7280;background:#e5e7eb;border-radius:9999px;padding:.05rem .4rem}.kanban-column-empty-state{font-size:.75rem;color:#9ca3af;text-align:center;padding:.5rem 0}.kanban-column-items{display:flex;flex-direction:column;gap:.5rem}.kanban-card{background:#fff;border:1px solid #e5e7eb;border-radius:4px;padding:.5rem .6rem;display:flex;flex-direction:column;gap:.3rem}.kanban-card-header{display:flex;align-items:center;justify-content:space-between;gap:.4rem}.kanban-card-type{font-size:.65rem;text-transform:uppercase;letter-spacing:.03em;color:#9ca3af}.kanban-card-id{font-size:.7rem;color:#9ca3af}.kanban-card-title{font-size:.85rem;color:#111827;cursor:pointer}.kanban-card-queued{border-style:dashed;border-color:#c4b5fd;background:#fdfcff}.kanban-card-footer{display:flex;align-items:center;justify-content:space-between;gap:.4rem}.kanban-card-queued-marker{font-size:.65rem;text-transform:uppercase;letter-spacing:.03em;color:#6d28d9;background:#ede9fe;border:1px solid #ddd6fe;border-radius:9999px;padding:.05rem .4rem;white-space:nowrap;cursor:help}@media (max-width: 480px){.kanban-board{position:relative;gap:var(--space-sm);scroll-snap-type:x mandatory;-webkit-overflow-scrolling:touch}.kanban-column{flex:0 0 85%;width:85%;scroll-snap-align:start;scroll-snap-stop:always}.kanban-column-empty{flex:0 0 140px;width:140px}.kanban-board:after{content:"";position:sticky;top:0;right:0;flex:0 0 var(--space-xl);align-self:stretch;background:linear-gradient(to right,transparent,rgba(249,250,251,.95));pointer-events:none}}.architecture-tab{overflow-x:hidden}.architecture-tab h2{margin-bottom:1rem}.arch-empty{color:#9ca3af;font-style:italic}.arch-section{margin-bottom:2rem}.arch-section h3{font-size:1rem;font-weight:600;color:#374151;margin-bottom:.75rem;border-bottom:1px solid #e5e7eb;padding-bottom:.35rem}.tech-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:.75rem}.tech-card{background:#fff;border:1px solid #e5e7eb;border-radius:8px;padding:.85rem 1rem;display:flex;flex-direction:column;gap:.3rem;box-shadow:0 1px 3px #0000000d}.tech-name{font-weight:600;font-size:.9rem;color:#1f2937}.tech-description{font-size:.78rem;color:#6b7280}.dep-table{width:100%;border-collapse:collapse;font-size:.875rem}.dep-table th{text-align:left;padding:.5rem .75rem;background:#f9fafb;border:1px solid #e5e7eb;font-weight:600;color:#374151}.dep-table td{padding:.45rem .75rem;border:1px solid #f3f4f6;color:#1f2937}.dep-table tr:hover td{background:#f9fafb}.dep-name{font-family:monospace}.dep-version{color:#6b7280;font-family:monospace}.dep-badge{display:inline-block;font-size:.7rem;font-weight:600;padding:.18rem .55rem;border-radius:999px;white-space:nowrap}.dep-runtime{background:#dbeafe;color:#1d4ed8}.dep-dev{background:#f3f4f6;color:#4b5563}.dep-table-wrap{overflow-x:auto}.sad-map-scroll{width:100%;min-height:320px;overflow:auto;-webkit-overflow-scrolling:touch;border:1px solid var(--border, #e2e8f0);border-radius:8px;background:var(--bg-secondary, #f8fafc)}.sad-map-svg{display:block;min-width:800px;min-height:500px;padding:8px}.sad-empty{color:var(--text-muted, #94a3b8);font-style:italic}@media (max-width: 480px){.architecture-tab{padding-bottom:var(--space-sm)}.arch-section{margin-bottom:var(--space-lg)}.arch-section h3{padding-bottom:var(--space-xs)}.tech-grid{gap:var(--space-sm)}.tech-card{padding:var(--space-sm) var(--space-md)}.sad-map-scroll{min-height:180px}}.entry-list-empty{color:#888;padding:2rem;text-align:center}.entry-list{list-style:none;padding:0;margin:0;border:1px solid #e5e7eb;border-radius:6px;overflow:hidden}.entry-list-item{display:flex;align-items:center;gap:.75rem;padding:.65rem 1rem;cursor:pointer;border-bottom:1px solid #f3f4f6;transition:background .12s}.entry-list-item:last-child{border-bottom:none}.entry-list-item:hover,.entry-list-item:focus{background:#f0f7ff;outline:none}.entry-list-item.selected{background:#dbeafe}.entry-badge{flex-shrink:0;font-size:.75rem;font-weight:600;padding:.2rem .55rem;border-radius:999px;white-space:nowrap;text-transform:capitalize;background:#ede9fe;color:#6d28d9}.entry-title{flex:1;font-size:.9rem;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:#1f2937}.entry-date{flex-shrink:0;font-size:.78rem;color:#9ca3af}@media (max-width: 480px){.entry-list-item{flex-wrap:wrap;row-gap:var(--space-xs)}.entry-title{flex-basis:100%;order:3;white-space:normal}}.pagination-controls{display:flex;align-items:center;justify-content:center;gap:var(--space-md);margin-top:var(--space-md)}.pagination-btn{padding:.4rem .9rem;font-size:.85rem;border:1px solid #e5e7eb;border-radius:6px;background:#fff;color:#1f2937;cursor:pointer}.pagination-btn:hover:not(:disabled){background:#f0f7ff;border-color:#93c5fd}.pagination-btn:disabled{opacity:.45;cursor:not-allowed}.pagination-status{font-size:.82rem;color:#6b7280;white-space:nowrap}@media (max-width: 480px){.pagination-controls{gap:var(--space-sm)}.pagination-btn{padding:.5rem .85rem;font-size:.9rem}.pagination-status{font-size:.78rem}}.rapports-search-input{display:block;width:100%;box-sizing:border-box;padding:.55rem .75rem;margin-bottom:var(--space-md);font-size:.9rem;border:1px solid #e5e7eb;border-radius:6px;color:#1f2937}.rapports-search-input:focus{outline:none;border-color:#93c5fd;box-shadow:0 0 0 2px #3b82f640}@media (max-width: 480px){.rapports-search-input{font-size:1rem;padding:.65rem .75rem}}:root{--space-xs: .25rem;--space-sm: .5rem;--space-md: 1rem;--space-lg: 1.5rem;--space-xl: 2rem;--breakpoint-mobile: 480px;--breakpoint-tablet: 768px}body{font-family:sans-serif;margin:0;background:#f5f5f5}.app{max-width:1200px;margin:0 auto;padding:1rem}.tabs{display:flex;gap:0;border-bottom:1px solid #ddd}.tab-btn{padding:.6rem 1.2rem;border:none;background:transparent;cursor:pointer;font-size:1rem;color:#555;border-bottom:2px solid transparent}.tab-btn.active{color:#2563eb;border-bottom-color:#2563eb;font-weight:600}.tab-content{padding:1rem 0}@media (max-width: 480px){.app{width:100%;box-sizing:border-box;padding:var(--space-sm)}.tabs{flex-wrap:nowrap;overflow-x:auto;-webkit-overflow-scrolling:touch}.tab-btn{flex:0 0 auto;padding:var(--space-sm) var(--space-md)}}

package/project/app/ui/dist/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Jenga AI Dashboard</title>
+    <script type="module" crossorigin src="/assets/index-7fj-vllY.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CdK3Qrep.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/project/app/ui/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "jenga-dashboard",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "dashboard:start": "node scripts/dashboard-start.cjs",
+    "dashboard:open": "node scripts/dashboard-open.cjs"
+  },
+  "dependencies": {
+    "dompurify": "^3.4.2",
+    "marked": "^18.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.1",
+    "vite": "^5.0.8"
+  }
+}

package/project/app/ui/scripts/build-snapshot-html.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * build-snapshot-html.cjs
+ *
+ * Turns an already-built dashboard `dist/` into ONE self-contained HTML file
+ * with a captured data snapshot embedded inline — with zero dependencies, so it
+ * runs identically in this monorepo and in a consumer's node_modules.
+ *
+ * Why this replaced the vite path
+ * -------------------------------
+ * `--snapshot` used to shell out to `npm run build:snapshot` (vite build --mode
+ * snapshot) inside project/app/ui. That can only ever work in this monorepo:
+ * the published tarball ships `project/app/ui/dist/**` and `scripts/**` and
+ * nothing else — no package.json, no vite.config.js, no src/ — so there is no
+ * vite to run and no sources to build. `--snapshot` was therefore dead on every
+ * consumer install, and the bats suite could not see it because it faked `npm`
+ * on PATH.
+ *
+ * Inlining a prebuilt dist needs no build tooling at all, so the SAME code path
+ * now runs in both places. That is the point: the consumer path is no longer a
+ * separate, never-exercised branch — every local `--snapshot` run exercises it.
+ *
+ * What it does, given <dist>/index.html:
+ *   1. Inlines every <script src> into <script> with the file's contents.
+ *   2. Inlines every <link rel=stylesheet href> into <style>.
+ *   3. Drops <link rel=modulepreload> — the module it preloads is now inline.
+ *   4. Injects the captured JSON as
+ *      <script id="jenga-dashboard-data" type="application/json"> before </head>,
+ *      which src/api/client.js's get() already reads instead of calling fetch()
+ *      whenever it is present. That runtime branch is NOT build-mode-gated, so
+ *      the ordinary `vite build` output is already snapshot-capable.
+ *   5. Fails loudly if any local asset reference survives, so a future UI change
+ *      that adds an image/font/chunk can never silently ship a broken snapshot.
+ *
+ * Usage:
+ *   node build-snapshot-html.cjs --dist <dir> --data <json> --out <html>
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function die(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+// ── Parse args ───────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const opts = { dist: '', data: '', out: '' };
+
+for (let i = 0; i < args.length; i++) {
+  const flag = args[i];
+  if (flag === '--dist' || flag === '--data' || flag === '--out') {
+    const value = args[++i];
+    if (value === undefined) die(`${flag} requires a value`);
+    opts[flag.slice(2)] = value;
+  } else if (flag === '-h' || flag === '--help') {
+    console.log('Usage: build-snapshot-html.cjs --dist <dir> --data <json> --out <html>');
+    process.exit(0);
+  } else {
+    die(`unknown argument: ${flag}`);
+  }
+}
+
+for (const required of ['dist', 'data', 'out']) {
+  if (!opts[required]) die(`--${required} is required`);
+}
+
+const DIST_DIR = path.resolve(opts.dist);
+const INDEX_HTML = path.join(DIST_DIR, 'index.html');
+
+if (!fs.existsSync(INDEX_HTML)) {
+  die(
+    `no built dashboard found at ${INDEX_HTML}. ` +
+      'In this monorepo run `npm run ui:build --prefix project/app`; in a consumer install ' +
+      'this means the package shipped without project/app/ui/dist (a packaging regression).'
+  );
+}
+
+// ── Read the captured data ───────────────────────────────────────────────────
+// Parse rather than pass through, so a malformed capture artifact fails here,
+// loudly, instead of producing a snapshot that only breaks once opened.
+let snapshotData;
+try {
+  snapshotData = JSON.parse(fs.readFileSync(opts.data, 'utf8'));
+} catch (err) {
+  die(`could not read/parse snapshot data at ${opts.data}: ${err.message}`);
+}
+
+let html = fs.readFileSync(INDEX_HTML, 'utf8');
+
+/**
+ * Resolves an asset reference from index.html to a path on disk. Vite emits
+ * root-absolute refs ("/assets/index-abc.js") by default, but a custom `base`
+ * can make them relative ("./assets/...") — both resolve against dist.
+ * Returns null for anything we must not try to inline (protocol-absolute URLs,
+ * data: URIs), which the caller leaves untouched.
+ */
+function resolveAsset(ref) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(ref) || ref.startsWith('//')) return null;
+  const relative = ref.replace(/^\//, '').replace(/^\.\//, '').split('?')[0].split('#')[0];
+  return path.join(DIST_DIR, relative);
+}
+
+function readAsset(ref, kind) {
+  const assetPath = resolveAsset(ref);
+  if (assetPath === null) return null;
+  if (!fs.existsSync(assetPath)) {
+    die(`${kind} referenced by index.html not found on disk: ${ref} (resolved to ${assetPath})`);
+  }
+  return fs.readFileSync(assetPath, 'utf8');
+}
+
+// Escapes a closing tag inside inlined content so it cannot terminate the
+// wrapper element early. `<\/script` is valid inside a JS string literal and
+// parses identically; the same trick applies to `</style` in CSS.
+function escapeClosingTag(content, tagName) {
+  return content.replace(new RegExp(`</${tagName}`, 'gi'), `<\\/${tagName}`);
+}
+
+function attr(tag, name) {
+  const match = tag.match(new RegExp(`\\b${name}=["']([^"']*)["']`, 'i'));
+  return match ? match[1] : null;
+}
+
+// ── 0. Reserve the real </head> injection point ──────────────────────────────
+// This MUST run before step 1. Step 4 injects the payload before `</head>` with
+// a first-match regex, and step 1 inlines the ESM bundle INTO the head. The
+// bundle carries its own literal '</head>' -- DOMPurify builds an XHTML wrapper
+// string, `'<html xmlns="..."><head></head><body>' + dirty + '</body></html>'`
+// -- so after inlining, the first '</head>' in the document is that JS string
+// literal, not the document's own. Injecting there splices the payload into the
+// middle of the bundle's source, and the payload's trailing '</script>'
+// terminates the module element early, dumping the rest of the bundle onto the
+// page as visible text. Step 1 already escapes '</script' in inlined code for
+// the same class of reason; it cannot escape '</head>', because that sequence
+// is only dangerous to the anchor below, not to the script element itself.
+// Claiming the anchor up front makes the injection point order-independent.
+if (!/<\/head>/i.test(html)) {
+  die(`${INDEX_HTML} has no </head> to inject the snapshot data before`);
+}
+const DATA_PLACEHOLDER = '<!--__JENGA_SNAPSHOT_DATA__-->';
+html = html.replace(/<\/head>/i, () => `${DATA_PLACEHOLDER}\n  </head>`);
+
+// ── 1. Inline <script src="..."> ─────────────────────────────────────────────
+html = html.replace(/<script\b([^>]*)\bsrc=["']([^"']+)["']([^>]*)><\/script>/gi, (tag, pre, src, post) => {
+  const code = readAsset(src, 'script');
+  if (code === null) return tag; // external URL — leave as-is
+  // Preserve type="module": the dist bundle is ESM and breaks when run as a
+  // classic script. crossorigin is dropped; it is meaningless once inline.
+  const isModule = /type=["']module["']/i.test(pre + post);
+  const typeAttr = isModule ? ' type="module"' : '';
+  return `<script${typeAttr}>\n${escapeClosingTag(code, 'script')}\n</script>`;
+});
+
+// ── 2 & 3. Inline stylesheets, drop modulepreload ────────────────────────────
+html = html.replace(/<link\b[^>]*>/gi, (tag) => {
+  const rel = (attr(tag, 'rel') || '').toLowerCase();
+  if (rel === 'modulepreload' || rel === 'preload') return '';
+  if (rel !== 'stylesheet') return tag; // icons, manifests, etc. stay untouched
+  const href = attr(tag, 'href');
+  if (!href) return tag;
+  const css = readAsset(href, 'stylesheet');
+  if (css === null) return tag;
+  return `<style>\n${escapeClosingTag(css, 'style')}\n</style>`;
+});
+
+// ── 4. Inject the captured snapshot data ─────────────────────────────────────
+// Escaping every '<' as its JSON unicode escape keeps the payload from
+// prematurely closing its own <script> tag, whatever the board/history
+// content happens to contain.
+const serialized = JSON.stringify(snapshotData).replace(/</g, '\\u003c');
+const dataTag = `<script id="jenga-dashboard-data" type="application/json">${serialized}</script>`;
+
+// A replacer FUNCTION, not a string: board content legitimately contains '$&',
+// '$`' and similar sequences (markdown code spans like `^[1-5]$`), which a
+// string replacement would interpret as backreferences and splice the document
+// into itself. A function's return value is used verbatim.
+// The placeholder was claimed in step 0, before any inlining could contribute a
+// competing '</head>'; see there for why the anchor cannot be taken here.
+html = html.replace(DATA_PLACEHOLDER, () => `  ${dataTag}`);
+
+// ── 5. Refuse to emit a snapshot that still points at files it does not carry ─
+// Without this, adding (say) a background image to the UI would produce a
+// snapshot that looks fine here and renders broken on the recipient's machine.
+const leftovers = [...html.matchAll(/\b(?:src|href)=["'](?!data:|https?:|#|\/\/)([^"']+)["']/gi)]
+  .map((m) => m[1])
+  .filter((ref) => {
+    const resolved = resolveAsset(ref);
+    return resolved !== null && fs.existsSync(resolved);
+  });
+
+// Same check for url() references inside the CSS we just inlined — a font or
+// background image reached that way is just as missing on the recipient's
+// machine, and never appears as an src=/href= attribute.
+for (const match of html.matchAll(/url\(\s*["']?(?!data:|https?:|#|\/\/)([^"')]+)["']?\s*\)/gi)) {
+  const resolved = resolveAsset(match[1]);
+  if (resolved !== null && fs.existsSync(resolved)) leftovers.push(match[1]);
+}
+
+if (leftovers.length > 0) {
+  die(
+    'snapshot would not be self-contained — these local asset references survived inlining: ' +
+      `${[...new Set(leftovers)].join(', ')}. ` +
+      'Teach build-snapshot-html.cjs to inline them before shipping this UI change.'
+  );
+}
+
+// ── Write ────────────────────────────────────────────────────────────────────
+fs.mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
+fs.writeFileSync(opts.out, html);
+console.log(`Inlined single-file dashboard: ${opts.out}`);

package/project/app/ui/scripts/dashboard-open.cjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * jenga dashboard open
+ *
+ * Usage:
+ *   node scripts/dashboard-open.js [--port <number>]
+ *
+ * Performs a health check against the API server, then opens the dashboard
+ * URL in the system's default browser. Always exits with code 0.
+ *
+ *   --port <number>   Port to check / open (default: 3001).
+ *                     Also respects JENGA_API_PORT env var.
+ */
+
+'use strict';
+
+const http     = require('http');
+const { execFile } = require('child_process');
+
+// ── Parse CLI flags ───────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+
+let port = parseInt(process.env.JENGA_API_PORT || '3001', 10);
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && args[i + 1]) {
+    const p = parseInt(args[++i], 10);
+    if (!isNaN(p) && p >= 1 && p <= 65535) {
+      port = p;
+    } else {
+      console.error(`Error: --port must be a valid port number (1-65535), got: ${args[i]}`);
+      process.exit(0); // still exit 0 per spec
+    }
+  }
+}
+
+const url = `http://localhost:${port}`;
+
+// ── Health check ─────────────────────────────────────────────────────────────
+function healthCheck(timeoutMs = 2000) {
+  return new Promise(resolve => {
+    const req = http.get(`${url}/v1/health`, res => {
+      resolve(res.statusCode >= 200 && res.statusCode < 300);
+      res.resume();
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on('error', () => resolve(false));
+  });
+}
+
+// ── Open browser ──────────────────────────────────────────────────────────────
+function openBrowser(targetUrl) {
+  return new Promise(resolve => {
+    let cmd, args;
+    switch (process.platform) {
+      case 'darwin':  cmd = 'open';      args = [targetUrl]; break;
+      case 'win32':   cmd = 'cmd';       args = ['/c', 'start', '', targetUrl]; break;
+      default:        cmd = 'xdg-open';  args = [targetUrl]; break;
+    }
+
+    execFile(cmd, args, err => {
+      if (err && err.code === 'ENOENT') {
+        console.log(`Open your browser at: ${targetUrl}`);
+      } else if (err) {
+        console.log(`Open your browser at: ${targetUrl}`);
+      }
+      resolve();
+    });
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+(async () => {
+  const healthy = await healthCheck();
+
+  if (!healthy) {
+    console.warn(`⚠ Warning: Dashboard server does not appear to be running at ${url}`);
+    console.warn('  Start it with: node project/app/ui/scripts/dashboard-start.cjs');
+    console.log(`\nOpen your browser at: ${url}`);
+    process.exit(0);
+  }
+
+  await openBrowser(url);
+  process.exit(0);
+})();

package/project/app/ui/scripts/dashboard-start.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * jenga dashboard start
+ *
+ * Usage:
+ *   node scripts/dashboard-start.js [--port <number>] [--serve-app]
+ *
+ * Starts the Jenga AI API server. Accepts:
+ *   --port <number>   Port to listen on (default: 3001). Also respects
+ *                     JENGA_API_PORT env var. CLI flag takes precedence.
+ *   --serve-app       Also serve the dashboard/dist/ static files from Express.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+// ── Parse CLI flags ───────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+
+let port = parseInt(process.env.JENGA_API_PORT || '3001', 10);
+let serveApp = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && args[i + 1]) {
+    const p = parseInt(args[++i], 10);
+    if (isNaN(p) || p < 1 || p > 65535) {
+      console.error(`Error: --port must be a valid port number (1-65535), got: ${args[i]}`);
+      process.exit(1);
+    }
+    port = p;
+  } else if (args[i] === '--serve-app') {
+    serveApp = true;
+  }
+}
+
+// Pass port to the server via env var before requiring it
+process.env.JENGA_API_PORT = String(port);
+
+// ── Optionally patch the app to serve static files ────────────────────────────
+const APP_ROOT    = path.resolve(__dirname, '../..');
+const DIST_DIR    = path.join(APP_ROOT, 'ui', 'dist');
+const SERVER_PATH = path.join(APP_ROOT, 'api', 'server.js');
+
+if (!fs.existsSync(SERVER_PATH)) {
+  console.error(`Error: API server not found at ${SERVER_PATH}`);
+  console.error('Make sure you are running this script from the repository root.');
+  process.exit(1);
+}
+
+// ── Load the API server ───────────────────────────────────────────────────────
+const { app, registerShutdownHandlers, attachFallbackRoutes } = require(SERVER_PATH);
+
+if (serveApp) {
+  const express = require('express');
+  if (!fs.existsSync(DIST_DIR)) {
+    console.warn(`Warning: dashboard/dist/ not found at ${DIST_DIR}`);
+    console.warn('Run "npm run build" inside the dashboard/ directory first.');
+  }
+  app.use(express.static(DIST_DIR));
+  // Fallback to index.html for SPA routing, but leave /v1/* API routes alone
+  // so unmatched API paths still get a JSON 404 instead of the SPA shell.
+  app.get(/^(?!\/v1\/).*/, (_req, res) => {
+    const indexPath = path.join(DIST_DIR, 'index.html');
+    if (fs.existsSync(indexPath)) {
+      res.sendFile(indexPath);
+    } else {
+      res.status(404).send('Dashboard not built. Run "npm run build" in dashboard/.');
+    }
+  });
+  // rootRedirect: false — the static middleware above already serves
+  // index.html at '/'; the unconditional /v1/health redirect would shadow it.
+  attachFallbackRoutes(app, { rootRedirect: false });
+} else {
+  attachFallbackRoutes(app);
+}
+
+// ── Start listening ───────────────────────────────────────────────────────────
+const server = app.listen(port, () => {
+  console.log(`Dashboard API running at http://localhost:${port}`);
+  if (serveApp) {
+    console.log(`Dashboard app  running at http://localhost:${port}`);
+  }
+});
+
+registerShutdownHandlers(server);