pi-soly 1.11.1 → 1.12.0

package/README.md

@@ -27,12 +27,17 @@ pi install npm:pi-soly
 Restart pi (`/reload`), and you have:
 
 - **Project management** — plans, state, phases, decisions
-- **Workflow engine** — `/plan`, `/execute`, `/resume`, `/inspect`, `/discuss`, `/quick`
+- **Workflow engine** — plain-text verbs: `soly discuss` · `plan` · `execute` · `verify` · `pause`/`resume`
+- **Self-review loop** — `soly verify` re-reviews the work until "No issues found."
+- **Visual chrome** — native footer, equalizer working spinner with live telemetry, gradient welcome banner
+- **Rules & docs modal** — `/rules` and `/docs` open a fuzzy list + preview panel (no chat dumps)
 - **Mandatory rules** — strict-mode directives injected every turn
-- **Multi-question picker** — `ask_pro` tool for the LLM
+- **Multi-question picker** — `ask_pro` tool for the LLM (single/multi-select, free-text, skip)
+- **Decision deck** — `decision_deck` tool: full-screen TUI cards for comparing design options by code shape
+- **HTML artifacts** — `html_artifact` tool serves self-contained HTML from a per-session browser gallery (live-updating, one stable URL)
 - **Skill-based execution** — LLM reads the `soly-framework` skill on demand
 
-No agents, no rotors, no mode cycling. The LLM is the executor. You focus on the work.
+The LLM drives execution; `plan`/`execute` delegate to a `worker` subagent when one is available (via pi-subagents), with first-party delegation on the roadmap. You focus on the work.
 
 ---
 
@@ -50,15 +55,15 @@ No agents, no rotors, no mode cycling. The LLM is the executor. You focus on the
 
 ## 📋 Commands
 
-### Workflow
+### Workflow — plain-text verbs (type `soly <verb>`, not slash)
 
 ```bash
-/plan              # generate PLAN.md for the current phase
-/execute           # execute plan directly (LLM does the work)
-/resume            # pick up a paused session
-/inspect           # show current state summary
-/discuss 3         # talk through decisions before planning phase 3
-/quick "fix typo"  # one-shot task with HANDOFF-style context
+soly discuss 3     # talk through decisions before planning phase 3
+soly plan 3        # generate PLAN.md for phase 3
+soly execute 3     # execute phase 3 (or `soly execute 3.02` for one plan)
+soly verify        # self-review loop until "No issues found." (`soly verify stop` to exit)
+soly pause         # save a handoff; `soly resume` to pick it back up
+soly status        # current position + progress (no LLM round-trip)
 ```
 
 ### State inspection (`/soly`)
@@ -178,6 +183,42 @@ ask_pro({
 ```
 
 The LLM calls `ask_pro` when it needs structured input. Tab through questions, pick ⭐ options, confirm.
+Per-option `preview` shows a side panel (fenced code is syntax-highlighted); `freeText: true` makes a typed-answer question; multi-select takes `minSelect`/`maxSelect`; press `s` to skip a question.
+
+---
+
+## 🃏 Decision Deck
+
+`decision_deck` tool for the LLM. A full-screen TUI deck — one framed card per option, each with a syntax-highlighted code snippet and pros/cons — for design/architecture forks where the choice hinges on seeing the concrete shape, not a label.
+
+```ts
+decision_deck({
+  title: "State management",
+  prompt: "How should modules communicate?",
+  options: [
+    { title: "Direct calls", summary: "Call modules directly.", pros: ["simple"], cons: ["coupling"] },
+    { title: "Event bus", code: "const bus = new Bus()\nbus.emit('x')", lang: "ts",
+      pros: ["decoupled"], cons: ["harder to trace"], recommended: true }
+  ]
+})
+```
+
+Flip cards with ←/→ (or 1-N), choose with Enter, Esc to cancel. Native TUI — no browser, no server.
+
+---
+
+## 🖼 HTML Artifacts
+
+`html_artifact` tool for the LLM — soly's local "artifacts". Renders HTML (a full document or just body content, themed light/dark) and serves it from a **per-session gallery SPA** — a sidebar of every artifact this session, an iframe viewer, a filter box, a light/dark toggle, and live SSE updates — on one stable localhost URL, opened in your browser. Pass `id` to update an artifact in place; pass `assets` to write sibling files (images/css/json) the HTML references; restyle everything via `.soly/artifact-theme.css`. (Falls back to opening the file directly if the server is disabled.)
+
+```ts
+html_artifact({
+  title: "API examples",
+  html: "<h2>Usage</h2><pre><code>client.send(msg)</code></pre>"
+})
+```
+
+Use it when a visual, rendered result beats terminal text (example galleries, comparisons, diagrams). The gallery URL lives only while the pi session runs. **`/artifacts`** reopens the gallery anytime (modal: Enter opens an artifact, `g` the gallery, `x` delete, `/artifacts clear` clears); a `▦ N` footer indicator shows the live count. Config under `artifacts` (`open`, `dir`, `server`, `theme`, `retentionDays`).
 
 ---
 
@@ -237,11 +278,16 @@ State lives in `.soly/` — portable, git-friendly, human-readable. Migrate to v
 ├── rules/               # rules (glob-matched or always-on)
 └── phases/
     └── 01-foundation/
-        ├── 01-CONTEXT.md    # domain + decisions for this phase
-        ├── 01-RESEARCH.md   # what we looked up
-        └── 01-PLAN.md       # ordered steps to execute
+        ├── 01-CONTEXT.md       # domain + decisions for this phase
+        ├── 01-RESEARCH.md      # what we looked up
+        └── tasks/              # unified model: one dir per task
+            └── auth-login-a3f9/
+                ├── PLAN.md     # frontmatter: id, kind, status, depends-on
+                └── SUMMARY.md
 ```
 
+> Legacy projects (standalone `NN-MM-PLAN.md` / a `features/` dir) still work; run `soly migrate` to convert them to this layout.
+
 ---
 
 ## 📚 Events
@@ -274,7 +320,7 @@ bun install
 ### Test + typecheck
 
 ```bash
-bun test          # 366 tests across 24 files
+bun test          # run the test suite
 bun run typecheck # tsc --noEmit
 bun run ci        # both
 ```

package/artifact/index.ts

@@ -0,0 +1,241 @@
+// =============================================================================
+// index.ts — pi-artifact extension entry point
+// =============================================================================
+//
+// Registers one LLM tool: `html_artifact`. Renders LLM-supplied HTML to a
+// self-contained file in a per-project dir and (by default) serves it from
+// a session-scoped HTTP server with a live gallery of every artifact made this
+// session — soly's local equivalent of Claude Code artifacts. Falls back to
+// opening the file directly when the server is disabled or can't bind.
+//
+// The pure HTML builders live in render.ts; the server in server.ts; this module
+// does the I/O wiring and teaches the LLM about the capability via the prompt.
+// =============================================================================
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { platform } from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { Type } from "typebox";
+import type { SolyConfig } from "../config.ts";
+import { atomicWriteFileSync } from "../util.ts";
+import { buildArtifactHtml, artifactFileName, artifactFileNameForId, DEFAULT_CSS } from "./render.ts";
+import {
+	artifactDir,
+	resolveArtifactBase,
+	ensureArtifactServer,
+	disposeArtifactServer,
+	invalidateArtifactServer,
+} from "./session.ts";
+
+type ToolText = { content: { type: "text"; text: string }[]; details: Record<string, unknown> };
+type Asset = { path: string; content: string; encoding?: string };
+
+/** Load the artifact CSS theme: config override → .soly/artifact-theme.css →
+ *  built-in DEFAULT_CSS. */
+function loadCss(themeCfg: string, cwd: string): string {
+	const candidates: string[] = [];
+	const t = themeCfg.trim();
+	if (t) candidates.push(path.isAbsolute(t) ? t : path.join(cwd, t));
+	candidates.push(path.join(cwd, ".soly", "artifact-theme.css"));
+	for (const c of candidates) {
+		try {
+			return fs.readFileSync(c, "utf-8");
+		} catch {
+			// try next
+		}
+	}
+	return DEFAULT_CSS;
+}
+
+/** Delete session artifact dirs older than `days` under `baseDir`. Best-effort;
+ *  skips when days <= 0. */
+function pruneOldSessions(baseDir: string, days: number): void {
+	if (days <= 0) return;
+	const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(baseDir, { withFileTypes: true });
+	} catch {
+		return; // base dir doesn't exist yet — nothing to prune
+	}
+	for (const e of entries) {
+		if (!e.isDirectory()) continue;
+		const p = path.join(baseDir, e.name);
+		try {
+			if (fs.statSync(p).mtimeMs < cutoff) fs.rmSync(p, { recursive: true, force: true });
+		} catch {
+			// best effort
+		}
+	}
+}
+
+/** Write sibling assets into the session dir (confined to it). Returns count. */
+function writeAssets(dir: string, assets: Asset[]): number {
+	const root = path.resolve(dir);
+	let n = 0;
+	for (const a of assets) {
+		const target = path.resolve(root, a.path);
+		if (target !== root && !target.startsWith(root + path.sep)) continue; // skip traversal
+		try {
+			fs.mkdirSync(path.dirname(target), { recursive: true });
+			const buf = a.encoding === "base64" ? Buffer.from(a.content, "base64") : Buffer.from(a.content, "utf-8");
+			fs.writeFileSync(target, buf);
+			n++;
+		} catch {
+			// best effort
+		}
+	}
+	return n;
+}
+
+/** Open a file or URL with the OS default handler (browser for .html / http). */
+async function openInBrowser(pi: ExtensionAPI, target: string): Promise<void> {
+	const o = platform();
+	const r =
+		o === "darwin"
+			? await pi.exec("open", [target])
+			: o === "win32"
+				? await pi.exec("cmd", ["/c", "start", "", target])
+				: await pi.exec("xdg-open", [target]);
+	if (r.code !== 0) throw new Error(r.stderr || `open failed (exit ${r.code})`);
+}
+
+/** Direct-file fallback: open the .html file itself (no server). */
+async function fileMode(
+	pi: ExtensionAPI,
+	file: string,
+	bytes: number,
+	shouldOpen: boolean,
+	note?: string,
+): Promise<ToolText> {
+	let opened = false;
+	let openError: string | undefined;
+	if (shouldOpen) {
+		try {
+			await openInBrowser(pi, file);
+			opened = true;
+		} catch (err) {
+			openError = String(err);
+		}
+	}
+	const lines = [`Artifact written: ${file}`];
+	if (note) lines.push(`(${note})`);
+	if (opened) lines.push("Opened in the default browser.");
+	else if (shouldOpen) lines.push(`(could not auto-open: ${openError ?? "unknown"} — open the file manually)`);
+	else lines.push("(not opened — open the file manually or set artifacts.open)");
+	return { content: [{ type: "text", text: lines.join("\n") }], details: { path: file, opened, bytes } };
+}
+
+export default function piArtifactExtension(pi: ExtensionAPI, getConfig: () => SolyConfig) {
+	// A stale owner server may linger in the shared holder after /reload — stop
+	// it (and clear its registry) so its pinned port is freed; the next artifact
+	// (or /artifacts) re-resolves and re-binds it, restoring the per-project
+	// manifest. No-op when nothing is running (fresh process).
+	disposeArtifactServer();
+
+	// Usage guidance lives in the soly-framework skill + the main soly prompt
+	// pointer — not injected here.
+	pi.on("session_start", async (_event, ctx) => {
+		const cfg = getConfig().artifacts;
+		pruneOldSessions(resolveArtifactBase(cfg.dir, ctx.cwd), cfg.retentionDays);
+	});
+	pi.on("session_shutdown", async () => {
+		// Stop the server only if we own it; if we were a client reusing another
+		// window's server, leave it running.
+		disposeArtifactServer();
+	});
+
+	pi.registerTool({
+		name: "html_artifact",
+		label: "soly · html_artifact",
+		description:
+			"Render HTML to a self-contained file and serve it from a per-project gallery in the browser — soly's artifacts. `html` is a full document or a body fragment (wrapped in a styled light/dark skeleton; theme overridable via .soly/artifact-theme.css). Pass `id` to update an existing artifact in place (re-render). Pass `assets` to write sibling files (images/css/json) the HTML references via relative paths. Use when a visual rendered result beats terminal text. Self-contained otherwise — no external URLs. The gallery is shared across every pi window in this folder and survives restarts. Returns the localhost URL + gallery.",
+		parameters: Type.Object({
+			title: Type.String({ description: "Title (used for <title>, header, gallery, filename)." }),
+			html: Type.String({
+				description:
+					"Full document or body fragment. Code in <pre><code>…</code></pre>. May reference sibling `assets` by relative path; otherwise self-contained.",
+			}),
+			id: Type.Optional(
+				Type.String({ description: "Stable id — re-calling with the same id updates that artifact in place." }),
+			),
+			assets: Type.Optional(
+				Type.Array(
+					Type.Object({
+						path: Type.String({ description: "Relative path within the artifact dir (e.g. 'data.json', 'img/logo.png')." }),
+						content: Type.String({ description: "File content." }),
+						encoding: Type.Optional(Type.String({ description: "'utf8' (default) or 'base64' for binary." })),
+					}),
+					{ description: "Sibling files the HTML references by relative path." },
+				),
+			),
+			open: Type.Optional(
+				Type.Boolean({ description: "Open the gallery in the browser (default: artifacts.open)." }),
+			),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx): Promise<ToolText> {
+			const cfg = getConfig().artifacts;
+			const dir = artifactDir(cfg.dir, ctx.cwd);
+			try {
+				fs.mkdirSync(dir, { recursive: true });
+			} catch (err) {
+				return {
+					content: [{ type: "text", text: `html_artifact: could not create ${dir}: ${String(err)}` }],
+					details: { error: "mkdir_failed", dir },
+				};
+			}
+
+			if (params.assets?.length) writeAssets(dir, params.assets);
+
+			const css = loadCss(cfg.theme, ctx.cwd);
+			const name = params.id ? artifactFileNameForId(params.id) : artifactFileName(params.title, Date.now().toString(36));
+			const file = path.join(dir, name);
+			const html = buildArtifactHtml(params.title, params.html, css);
+			atomicWriteFileSync(file, html);
+			const bytes = Buffer.byteLength(html);
+			const shouldOpen = params.open ?? cfg.open;
+
+			if (!cfg.server) return fileMode(pi, file, bytes, shouldOpen);
+
+			let server: Awaited<ReturnType<typeof ensureArtifactServer>>;
+			try {
+				server = await ensureArtifactServer(dir, ctx.cwd);
+			} catch (err) {
+				return fileMode(pi, file, bytes, shouldOpen, `artifact server unavailable: ${String(err)}`);
+			}
+
+			// Register over the shared server. If the owning window died mid-call
+			// (client POST fails), re-resolve — probe finds nothing, so we start our
+			// own server on the same pinned port (same URL) — then retry once.
+			let url: string;
+			try {
+				url = await server.register(params.title, file, params.id);
+			} catch {
+				invalidateArtifactServer();
+				server = await ensureArtifactServer(dir, ctx.cwd);
+				url = await server.register(params.title, file, params.id);
+			}
+			const gallery = server.galleryUrl();
+			let opened = false;
+			let openError: string | undefined;
+			if (shouldOpen && server.consumeFirstOpen()) {
+				try {
+					await openInBrowser(pi, gallery);
+					opened = true;
+				} catch (err) {
+					openError = String(err);
+				}
+			}
+			// No mid-turn ctx.ui.notify here: firing one while the model is still
+			// streaming forces a repaint that can garble the TUI (the toast collided
+			// with the footer + duplicated streamed lines). The user still sees the
+			// artifact via auto-open, the `🖼 N` footer indicator, this tool result,
+			// and `/artifacts`.
+			const lines = [`Artifact: ${url}`, `Gallery (all project artifacts): ${gallery}`];
+			if (opened) lines.push("Opened the gallery in your browser.");
+			else if (openError) lines.push(`(could not auto-open: ${openError})`);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { url, gallery, path: file, bytes, opened } };
+		},
+	});
+}

package/artifact/render.ts

@@ -0,0 +1,239 @@
+// =============================================================================
+// render.ts — pure HTML artifact builder + gallery shell (no I/O)
+// =============================================================================
+//
+// Turns LLM-supplied content into a nicely-styled HTML document and builds the
+// session gallery shell — soly's local "artifacts". Pure: every function takes
+// strings and returns strings; the stylesheet is passed in (loaded from a file
+// or the built-in DEFAULT_CSS by the caller) so a project can restyle every
+// artifact by dropping a `.soly/artifact-theme.css`.
+//
+// A body *fragment* is wrapped in the skeleton; a *full document* keeps its own
+// markup but gets the theme injected as a base layer (its own styles win).
+// =============================================================================
+
+/** Escape text for safe interpolation into HTML (title, header). */
+export function escapeHtml(s: string): string {
+	return s
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}
+
+/** kebab-case slug for filenames/ids; falls back to "artifact" when empty. */
+export function slugify(title: string): string {
+	const slug = title
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 48);
+	return slug || "artifact";
+}
+
+/** Deterministic artifact filename: `<slug>-<stamp>.html`. */
+export function artifactFileName(title: string, stamp: string): string {
+	return `${slugify(title)}-${stamp}.html`;
+}
+
+/** Stable filename for an id-keyed artifact (update-in-place). */
+export function artifactFileNameForId(id: string): string {
+	return `${slugify(id)}.html`;
+}
+
+/** True when content is already a complete HTML document. */
+export function isFullDocument(content: string): boolean {
+	const head = content.trimStart().slice(0, 256).toLowerCase();
+	return head.startsWith("<!doctype") || head.startsWith("<html");
+}
+
+/** Inject soly's base stylesheet into a full document as a fallback layer
+ *  (placed at the start of <head> so the document's own styles override it). */
+export function injectStyle(doc: string, css: string): string {
+	const style = `<style data-soly>${css}</style>`;
+	if (/<head[^>]*>/i.test(doc)) return doc.replace(/<head[^>]*>/i, (m) => `${m}\n${style}`);
+	if (/<html[^>]*>/i.test(doc)) return doc.replace(/<html[^>]*>/i, (m) => `${m}\n<head>${style}</head>`);
+	return `${style}\n${doc}`;
+}
+
+/**
+ * Build the final HTML. Fragments are wrapped in a styled skeleton; full
+ * documents keep their markup but get the theme injected as a base layer.
+ */
+export function buildArtifactHtml(title: string, content: string, css: string = DEFAULT_CSS): string {
+	if (isFullDocument(content)) return injectStyle(content, css);
+	const safeTitle = escapeHtml(title);
+	const header = title ? `<header><h1>${safeTitle}</h1></header>\n` : "";
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${safeTitle || "soly artifact"}</title>
+<style>${css}</style>
+</head>
+<body>
+<main>
+${header}${content}
+</main>
+</body>
+</html>
+`;
+}
+
+/** One artifact in the session gallery. */
+export type GalleryEntry = { id: string; title: string; file: string; createdAt: number };
+
+/**
+ * The session gallery SPA shell: a sidebar listing every artifact this session
+ * (fetched live from `/<token>/list`), a viewer iframe, filter box, light/dark
+ * toggle, and "open raw". An SSE stream re-fetches the list and refreshes the
+ * open artifact when something changes. Vanilla JS — no framework, no CDN.
+ */
+export function buildGalleryShell(token: string): string {
+	const t = JSON.stringify(token);
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>soly artifacts</title>
+<style>${SHELL_CSS}</style>
+</head>
+<body>
+<aside id="side">
+  <header><span>soly artifacts <span class="sub">this project</span></span><button id="theme" title="Toggle theme">◐</button></header>
+  <input id="q" placeholder="Filter…" autocomplete="off">
+  <ul id="list"></ul>
+  <p id="empty">No artifacts yet — they'll appear here as they're created.</p>
+</aside>
+<main>
+  <div id="bar"><span class="grow" id="cur">Select an artifact →</span><button id="raw">Open raw ↗</button></div>
+  <iframe id="view" title="artifact"></iframe>
+</main>
+<script>
+(function(){
+  var T=${t};
+  var list=document.getElementById('list'),q=document.getElementById('q'),
+      view=document.getElementById('view'),cur=document.getElementById('cur'),
+      empty=document.getElementById('empty');
+  var entries=[],activeFile=null;
+  function fmt(ts){try{return new Date(ts).toLocaleString()}catch(e){return ''}}
+  function show(e){activeFile=e.file;view.src='/'+T+'/a/'+encodeURIComponent(e.file)+'?t='+Date.now();cur.textContent=e.title;render();}
+  function render(){
+    var f=(q.value||'').toLowerCase();
+    empty.style.display=entries.length?'none':'block';
+    list.innerHTML='';
+    entries.filter(function(e){return e.title.toLowerCase().indexOf(f)>=0}).forEach(function(e){
+      var li=document.createElement('li');
+      if(e.file===activeFile)li.className='active';
+      var t=document.createElement('span');t.className='t';t.textContent=e.title;
+      var ts=document.createElement('span');ts.className='ts';ts.textContent=fmt(e.createdAt);
+      li.appendChild(t);li.appendChild(ts);
+      li.onclick=function(){show(e)};
+      list.appendChild(li);
+    });
+  }
+  function load(cb){fetch('/'+T+'/list').then(function(r){return r.json()}).then(function(d){entries=d||[];render();if(cb)cb()}).catch(function(){});}
+  q.oninput=render;
+  document.getElementById('raw').onclick=function(){if(view.src)window.open(view.src,'_blank')};
+  var th=document.getElementById('theme');
+  function applyTheme(x){if(x)document.documentElement.setAttribute('data-theme',x)}
+  applyTheme(localStorage.getItem('soly-theme'));
+  th.onclick=function(){var c=document.documentElement.getAttribute('data-theme');var n=c==='dark'?'light':'dark';applyTheme(n);try{localStorage.setItem('soly-theme',n)}catch(e){}};
+  load(function(){if(entries.length)show(entries[0])});
+  try{var es=new EventSource('/'+T+'/events');es.onmessage=function(){load(function(){
+    if(activeFile&&entries.some(function(e){return e.file===activeFile}))show(entries.filter(function(e){return e.file===activeFile})[0]);
+    else if(entries.length)show(entries[0]);
+  })};}catch(e){}
+})();
+</script>
+</body>
+</html>
+`;
+}
+
+// Self-contained artifact stylesheet — no external fonts, scripts, or CDN
+// requests. Overridable per project via .soly/artifact-theme.css.
+export const DEFAULT_CSS = `
+:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  color:#1c1c1e;background:#fbfbfd}
+main{max-width:860px;margin:0 auto;padding:2.5rem 1.25rem 4rem}
+header h1{margin:0 0 1.5rem;font-size:1.9rem;line-height:1.2;border-bottom:1px solid #e3e3e8;padding-bottom:.6rem}
+h1,h2,h3{line-height:1.25;font-weight:650}
+h2{margin-top:2rem;font-size:1.4rem}
+h3{margin-top:1.5rem;font-size:1.15rem}
+p{margin:.8rem 0}
+a{color:#0a66c2;text-decoration:none}
+a:hover{text-decoration:underline}
+code{font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace;font-size:.9em;
+  background:#f0f0f4;border-radius:4px;padding:.12em .35em}
+pre{background:#f5f5f7;border:1px solid #e3e3e8;border-radius:10px;padding:1rem 1.1rem;overflow-x:auto;
+  line-height:1.5}
+pre code{background:none;padding:0;font-size:.875rem}
+table{border-collapse:collapse;width:100%;margin:1rem 0;font-size:.95rem}
+th,td{border:1px solid #e3e3e8;padding:.5rem .7rem;text-align:left;vertical-align:top}
+th{background:#f0f0f4;font-weight:650}
+blockquote{margin:1rem 0;padding:.4rem 1rem;border-left:3px solid #c7c7cc;color:#48484a}
+img{max-width:100%;height:auto}
+hr{border:none;border-top:1px solid #e3e3e8;margin:2rem 0}
+.cols{display:flex;gap:1rem;flex-wrap:wrap}
+.cols>*{flex:1 1 280px;min-width:0}
+@media (prefers-color-scheme:dark){
+  body{color:#e6e6eb;background:#161618}
+  header h1,h2,h3{border-color:#2c2c2e}
+  code{background:#2c2c2e}
+  pre{background:#1f1f22;border-color:#2c2c2e}
+  th{background:#222225}
+  th,td,hr{border-color:#2c2c2e}
+  a{color:#5aa9ff}
+  blockquote{border-color:#48484a;color:#aeaeb2}
+}
+`;
+
+// Gallery app-shell chrome (distinct from artifact content styling above).
+const SHELL_CSS = `
+:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;height:100vh;display:flex;font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;color:#1c1c1e;background:#fbfbfd}
+#side{width:280px;flex:0 0 280px;display:flex;flex-direction:column;height:100vh;background:#f5f5f7;border-right:1px solid #e3e3e8}
+#side header{padding:1rem 1rem .6rem;font-weight:650;display:flex;align-items:center;justify-content:space-between;gap:.5rem}
+#side header .sub{font-size:.7rem;font-weight:400;color:#8a8a8e}
+#theme{font:inherit;border:1px solid #d0d0d5;background:#fff;border-radius:7px;cursor:pointer;padding:.1rem .45rem}
+#q{margin:.2rem 1rem .6rem;padding:.4rem .6rem;border:1px solid #d0d0d5;border-radius:8px;font:inherit}
+#list{list-style:none;margin:0;padding:0;overflow-y:auto;flex:1}
+#list li{padding:.55rem 1rem;border-bottom:1px solid #ececf0;cursor:pointer}
+#list li:hover{background:#ececf0}
+#list li.active{background:#e1e8ff}
+#list .t{font-weight:600;font-size:.92rem;display:block}
+#list .ts{color:#8a8a8e;font-size:.75rem}
+#empty{padding:1rem;color:#8a8a8e}
+main{flex:1;height:100vh;display:flex;flex-direction:column;min-width:0}
+#bar{display:flex;gap:.5rem;align-items:center;padding:.4rem .8rem;border-bottom:1px solid #e3e3e8;font-size:.85rem}
+#bar .grow{flex:1;color:#48484a;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#bar button{font:inherit;padding:.25rem .6rem;border:1px solid #d0d0d5;border-radius:7px;background:#fff;cursor:pointer}
+iframe{flex:1;border:0;width:100%;background:#fff}
+html[data-theme=dark]{color-scheme:dark}
+html[data-theme=light]{color-scheme:light}
+html[data-theme=dark] body{color:#e6e6eb;background:#161618}
+html[data-theme=dark] #side{background:#1c1c1e;border-color:#2c2c2e}
+html[data-theme=dark] #q,html[data-theme=dark] #theme,html[data-theme=dark] #bar button{background:#222;color:#e6e6eb;border-color:#3a3a3c}
+html[data-theme=dark] #list li{border-color:#242426}
+html[data-theme=dark] #list li:hover{background:#242426}
+html[data-theme=dark] #list li.active{background:#2a3358}
+html[data-theme=dark] #bar{border-color:#2c2c2e}
+html[data-theme=dark] iframe{background:#161618}
+@media (prefers-color-scheme:dark){
+  body{color:#e6e6eb;background:#161618}
+  #side{background:#1c1c1e;border-color:#2c2c2e}
+  #q,#theme,#bar button{background:#222;color:#e6e6eb;border-color:#3a3a3c}
+  #list li{border-color:#242426}
+  #list li:hover{background:#242426}
+  #list li.active{background:#2a3358}
+  #bar{border-color:#2c2c2e}
+  iframe{background:#161618}
+}
+`;