@glasshome/widget-cli 0.8.4 → 0.9.0

package/bin/cli.ts

@@ -27,6 +27,8 @@ Commands:
   build                  Build all widgets (per-widget, self-contained bundles)
   connect <url>          Connect to a running dashboard for live testing
                          --re-auth discards stored credentials and re-runs device approval
+  preview [name...]      Screenshot widgets' examples (light + dark) into preview/
+                         --isolate gives every render its own browser process
   validate [name]        Validate all widgets or a specific one
   publish [hub-url]      Build and publish a widget to Hub
   login [hub-url]        Authenticate with GlassHome Hub
@@ -42,6 +44,8 @@ Examples:
   glasshome-widget add
   glasshome-widget build
   glasshome-widget connect http://localhost:3333
+  glasshome-widget preview
+  glasshome-widget preview clock
   glasshome-widget validate
   glasshome-widget validate clock
   glasshome-widget info
@@ -65,6 +69,7 @@ const { values: flags, positionals } = parseArgs({
     bump: { type: "string" },
     scope: { type: "string" },
     "re-auth": { type: "boolean" },
+    isolate: { type: "boolean" },
     dry: { type: "boolean" },
     help: { type: "boolean", short: "h" },
   },
@@ -134,6 +139,14 @@ switch (effectiveCommand) {
     break;
   }
 
+  case "preview": {
+    const widgetDir = resolveWidgetDir();
+    await notifySdkUpdate(widgetDir);
+    const { runPreview } = await import("../src/commands/preview");
+    await runPreview(widgetDir, args, flags.isolate === true);
+    break;
+  }
+
   case "validate": {
     const widgetName = args[0];
     const widgetDir = resolveWidgetDir();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-cli",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "CLI for creating and managing GlassHome widgets",
   "type": "module",
   "bin": {
@@ -16,19 +16,36 @@
     "template"
   ],
   "devDependencies": {
+    "@iconify/types": "^2.0.0",
     "@types/bun": "latest",
-    "@types/semver": "^7.0.0"
+    "@types/semver": "^7.0.0",
+    "playwright": "^1.40.0"
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
+    "@fontsource-variable/caveat": "^5.2.8",
+    "@fontsource-variable/geist": "^5.2.9",
+    "@fontsource-variable/geist-mono": "^5.2.8",
+    "@glasshome/sync-layer": "0.4.0",
     "@glasshome/widget-contract": "0.2.0",
-    "@glasshome/widget-sdk": "1.6.1",
+    "@glasshome/widget-sdk": "1.7.0",
+    "@iconify-json/lucide": "^1.2.0",
+    "@iconify-json/mdi": "^1.2.3",
+    "@tailwindcss/vite": "^4.1.13",
     "open": "^11.0.0",
     "picocolors": "^1.1.1",
     "semver": "^7.6.0",
     "ts-morph": "^28.0.0",
     "vite-plugin-solid": "^2.11.0"
   },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/glasshome/widget-cli.git"

package/src/commands/preview.ts

@@ -0,0 +1,91 @@
+import { log } from "@clack/prompts";
+import color from "picocolors";
+import { runPreview as capturePreview } from "../preview/capture";
+import { withQuietStdout } from "../utils/quiet";
+
+/**
+ * Screenshot every widget's authored examples (light + dark) into
+ * `<project>/preview/`, rendered through the same constraints as the hub's
+ * render worker: frozen clock, DNS blackhole, per-render timeout, hash pin.
+ *
+ * Playwright is an OPTIONAL peer — the CLI stays Chromium-free by default — so
+ * detect it first and give an actionable install hint rather than a raw
+ * module-not-found when it is absent.
+ */
+export async function runPreview(cwd: string, names: string[], isolate: boolean): Promise<void> {
+  try {
+    await import("playwright");
+  } catch {
+    log.error("Preview needs Playwright + a Chromium build, which are not installed.");
+    log.info(`Install them with:\n  ${color.bold("bun add -d playwright && bunx playwright install chromium")}`);
+    process.exit(1);
+  }
+
+  // Capture the REAL stdout writer before withQuietStdout no-ops
+  // process.stdout.write. A clack spinner writes through that same override and
+  // would freeze inside the quiet block, so progress goes out this bound
+  // reference (which the override cannot intercept) as plain lines. Build/vite
+  // noise stays silenced; only these phase lines get through.
+  const realWrite = process.stdout.write.bind(process.stdout);
+  const progress = (m: string) => {
+    realWrite(`${color.gray("│")}  ${color.dim(m)}\n`);
+  };
+
+  log.info(names.length ? `Previewing ${names.join(", ")}` : "Previewing all widgets");
+
+  let summary: Awaited<ReturnType<typeof capturePreview>>;
+  try {
+    summary = await withQuietStdout(() =>
+      capturePreview({ projectDir: cwd, only: names, isolate, onProgress: progress }),
+    );
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  log.success(`Captured ${summary.shots} shot(s) across ${summary.widgets} widget(s)`);
+
+  if (summary.skipped.length) {
+    log.info(`No examples (skipped): ${summary.skipped.join(", ")}`);
+  }
+
+  const network = summary.failures.filter((f) => f.kind === "network");
+  const hangs = summary.failures.filter((f) => f.kind === "hang");
+  const integrity = summary.failures.filter((f) => f.kind === "integrity");
+
+  // Nothing can actually leave — DNS is blackholed. These are blocked attempts,
+  // i.e. what each widget wanted from the network and must degrade without.
+  if (network.length) {
+    log.warn(
+      `NETWORK: ${network.length} blocked request(s) — all denied, none left the machine\n` +
+        network.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
+    );
+  } else {
+    log.success("NETWORK: no widget attempted to reach the network");
+  }
+
+  if (hangs.length) {
+    log.error(
+      `RENDER: ${hangs.length} render(s) failed or timed out\n` +
+        hangs.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
+    );
+  } else {
+    log.success("RENDER: every render settled inside the timeout");
+  }
+
+  if (integrity.length) {
+    log.error(
+      `INTEGRITY: ${integrity.length} widget(s) changed after pinning\n` +
+        integrity.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
+    );
+  } else {
+    log.success("INTEGRITY: every bundle matched its pinned hash");
+  }
+
+  log.info(`Previews written to ${color.cyan("preview/")}`);
+
+  // Vite's dev server leaves live handles behind (file watchers, keep-alive
+  // sockets from browsers that crashed mid-render), so the process would sit
+  // idle forever after the verdict instead of exiting. Leave deliberately.
+  process.exit(hangs.length || integrity.length ? 1 : 0);
+}

package/src/preview/capture.ts

@@ -0,0 +1,254 @@
+import { copyFileSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildWidgets } from "@glasshome/widget-sdk/vite";
+import tailwindcss from "@tailwindcss/vite";
+import { createServer } from "vite";
+import solid from "vite-plugin-solid";
+import {
+  freezeClock,
+  hashWidgetArtifacts,
+  settleAnimations,
+  type SharedBrowser,
+  watchEgress,
+  withFreshBrowser,
+  withRenderTimeout,
+  withSharedBrowser,
+} from "./constraints";
+
+const THEMES = ["light", "dark"] as const;
+
+interface ShotListEntry {
+  label?: string;
+  size: { w: number; h: number };
+}
+
+export interface Failure {
+  widget: string;
+  kind: "network" | "hang" | "integrity";
+  detail: string;
+}
+
+export interface PreviewSummary {
+  shots: number;
+  widgets: number;
+  skipped: string[];
+  failures: Failure[];
+}
+
+export interface PreviewOptions {
+  projectDir: string;
+  only?: string[];
+  isolate?: boolean;
+  /** Phase updates for a caller-owned spinner; build + vite output is silenced. */
+  onProgress?: (message: string) => void;
+}
+
+// Filenames become CDN path segments, so keep them to [a-z0-9-]: an example
+// labelled "Solar, battery and EV" must not put a comma in a URL.
+function slug(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+// Every ancestor of the project dir, so vite's fs guard allows the harness to
+// reach node_modules hoisted anywhere up the workspace (bun hoists widget-cli's
+// deps to the project root, which may be several levels above a widget project).
+function ancestors(dir: string): string[] {
+  const out: string[] = [];
+  let d = dir;
+  for (;;) {
+    out.push(d);
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return out;
+}
+
+/**
+ * Build every widget, serve the harness, and screenshot each authored example
+ * in light and dark under the render worker's constraints (frozen clock, DNS
+ * blackhole, per-render timeout, verify-before-execute hash pin).
+ *
+ * The vite root is a temp dir created UNDER the project so that: the harness's
+ * `../dist/*.js` glob resolves to `<projectDir>/dist`, and every bare import
+ * (@glasshome/*, iconify, solid) resolves from the project's own node_modules —
+ * a single solid/ui instance, which the built bundle's external imports require.
+ */
+export async function runPreview(opts: PreviewOptions): Promise<PreviewSummary> {
+  const projectDir = resolve(opts.projectDir);
+  const only = opts.only ?? [];
+  const isolate = opts.isolate ?? false;
+  const progress = opts.onProgress ?? (() => {});
+
+  const distDir = resolve(projectDir, "dist");
+  const outDir = resolve(projectDir, "preview");
+  const harnessSrc = resolve(import.meta.dirname, "harness");
+  // Temp vite root under the project: keeps node_modules resolution and the
+  // `../dist` glob pointed at the project, and is removed when the run ends.
+  const tempRoot = resolve(projectDir, ".glasshome-preview");
+
+  // 1. Build the widget bundles so authored examples land in dist/<name>.js.
+  progress(only.length ? `Building ${only.join(", ")}...` : "Building widgets...");
+  process.chdir(projectDir);
+  await buildWidgets({
+    srcDir: "src",
+    outDir: "dist",
+    ...(only.length ? { only } : {}),
+    plugins: [solid({ solid: { delegateEvents: false } })],
+  });
+
+  const widgetNames = readdirSync(distDir)
+    .filter((f) => f.endsWith(".js"))
+    .map((f) => f.slice(0, -3))
+    .filter((n) => (only.length ? only.includes(n) : true))
+    .sort();
+
+  // 2. Stage the harness into the temp root and serve it.
+  rmSync(tempRoot, { recursive: true, force: true });
+  mkdirSync(tempRoot, { recursive: true });
+  copyFileSync(resolve(harnessSrc, "harness.tsx"), resolve(tempRoot, "harness.tsx"));
+  copyFileSync(resolve(harnessSrc, "index.html"), resolve(tempRoot, "index.html"));
+
+  const skipped: string[] = [];
+  let shot = 0;
+  const failures: Failure[] = [];
+  const shotLists = new Map<string, ShotListEntry[]>();
+
+  const server = await createServer({
+    root: tempRoot,
+    configFile: false,
+    // delegateEvents: false — widgets mount in closed shadow roots where Solid's
+    // document-level event delegation cannot see the target (matches the widgets
+    // build and dash mount). tailwindcss() compiles @glasshome/ui/styles so the
+    // app theme tokens land on :root exactly as they do in dash.
+    plugins: [tailwindcss(), solid({ solid: { delegateEvents: false } })],
+    server: { fs: { allow: [tempRoot, ...ancestors(projectDir)] } },
+  });
+
+  try {
+    await server.listen();
+    const base = server.resolvedUrls?.local[0];
+    if (!base) throw new Error("vite dev server has no local url");
+    const origin = new URL(base).origin;
+
+    mkdirSync(outDir, { recursive: true });
+
+    // 3. Enumerate each widget's shot list (one locked browser for the whole pass).
+    progress(`Loading ${widgetNames.length} widget(s)...`);
+    const pinnedHashes = new Map<string, string>();
+    await withFreshBrowser(async (page) => {
+      watchEgress(page, origin);
+      for (const widget of widgetNames) {
+        await page.goto(`${base}?widget=${widget}&ex=0&theme=light`, {
+          waitUntil: "domcontentloaded",
+        });
+        await page.waitForSelector("html[data-harness-examples]", {
+          state: "attached",
+          timeout: 30_000,
+        });
+        const examples: ShotListEntry[] = JSON.parse(
+          (await page.getAttribute("html", "data-harness-examples")) ?? "[]",
+        );
+        if (examples.length === 0) skipped.push(widget);
+        else {
+          shotLists.set(widget, examples);
+          // Pin the bytes now; every later render must match this.
+          pinnedHashes.set(widget, hashWidgetArtifacts(distDir, widget));
+        }
+      }
+    });
+
+    // 4. Render every shot under the worker's constraints.
+    const runAll = async (shared: SharedBrowser | null) => {
+      let done = 0;
+      const total = shotLists.size;
+      for (const [widget, examples] of shotLists) {
+        progress(`Rendering ${widget} (${++done}/${total})...`);
+        const widgetAttempts = new Set<string>();
+
+        // Verify-before-execute: refuse to render bytes that changed since the
+        // shot list was built.
+        const current = hashWidgetArtifacts(distDir, widget);
+        if (current !== pinnedHashes.get(widget)) {
+          failures.push({
+            widget,
+            kind: "integrity",
+            detail: `bundle changed after pinning (${pinnedHashes.get(widget)?.slice(0, 12)} -> ${current.slice(0, 12)})`,
+          });
+          console.log(`${widget}: SKIPPED — bundle hash mismatch`);
+          continue;
+        }
+
+        for (let i = 0; i < examples.length; i++) {
+          const label = slug(examples[i].label ?? `example-${i}`);
+          for (const theme of THEMES) {
+            const url = `${base}?widget=${widget}&ex=${i}&theme=${theme}`;
+            const file = resolve(outDir, `${widget}-${label}-${theme}.png`);
+
+            const shoot = async (page: import("playwright").Page) => {
+              const lock = watchEgress(page, origin);
+              await freezeClock(page);
+              await page.goto(url, { waitUntil: "domcontentloaded" });
+              await page.waitForSelector("html[data-harness-ready='1']", {
+                state: "attached",
+                timeout: 20_000,
+              });
+              // Fire rAF-gated mount animations before capturing.
+              await settleAnimations(page);
+              await page.locator("#stage").screenshot({ path: file, omitBackground: true });
+              for (const a of lock.attempts) widgetAttempts.add(a);
+            };
+
+            try {
+              await withRenderTimeout(`${widget} / ${label} / ${theme}`, async () => {
+                if (shared) {
+                  const page = await shared.newPage();
+                  try {
+                    await shoot(page);
+                  } finally {
+                    // The browser may already be gone; a failed cleanup must not
+                    // mask the real outcome of the render.
+                    await page
+                      .context()
+                      .close()
+                      .catch(() => {});
+                  }
+                } else {
+                  await withFreshBrowser(shoot);
+                }
+              });
+              shot++;
+            } catch (err) {
+              failures.push({
+                widget,
+                kind: "hang",
+                detail: `${label}/${theme}: ${err instanceof Error ? err.message : String(err)}`,
+              });
+              // A timed-out render leaves the browser wedged; drop it so the next
+              // shot starts clean instead of cascading into more timeouts.
+              await shared?.recycle().catch(() => {});
+            }
+          }
+        }
+
+        for (const a of widgetAttempts) {
+          failures.push({ widget, kind: "network", detail: a });
+        }
+        const flag = widgetAttempts.size ? `  ⚠ needs network (${widgetAttempts.size})` : "";
+        console.log(`${widget}: ${examples.length} example(s)${flag}`);
+      }
+    };
+
+    if (isolate) await runAll(null);
+    else await withSharedBrowser((shared) => runAll(shared));
+  } finally {
+    await server.close().catch(() => {});
+    // Temp root is throwaway staging; never leave it in the project tree.
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+
+  return { shots: shot, widgets: shotLists.size, skipped, failures };
+}

package/src/preview/constraints.ts

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import type { Browser, Page } from "playwright";
+import { chromium } from "playwright";
+import { nixLdLibraryPath } from "./nix-ld";
+
+/**
+ * Local rehearsal of the render worker's runtime constraints.
+ *
+ * The worker will execute attacker-controlled widget code on hub infra with no
+ * consent gate, so the screenshot itself is a potential exfiltration channel: a
+ * widget could fetch an internal endpoint and paint the response. Imposing the
+ * same constraints on the local harness answers "can widgets even render like
+ * this?" before any infrastructure exists.
+ */
+
+/** Hard wall-clock cap per render. A widget that hangs (camera waiting on a
+    stream that will never arrive) must be killed, not allowed to stall the run. */
+export const RENDER_TIMEOUT_MS = 30_000;
+
+export interface EgressLock {
+  /**
+   * Every non-local URL the page ATTEMPTED to reach. These were all blocked by
+   * the DNS blackhole, so nothing actually left the machine — this records
+   * intent, not leakage.
+   *
+   * A non-empty list is still a finding: it names what a widget needs from the
+   * network and therefore what it must degrade gracefully without.
+   */
+  readonly attempts: string[];
+}
+
+/**
+ * Chromium launch flags that blackhole DNS for everything except localhost.
+ *
+ * Enforcement lives at the browser, not in Playwright's request interception.
+ * Registering any `page.route` makes Playwright intercept EVERY request and
+ * round-trip it through Node — with multi-megabyte icon collections on the page
+ * that is pathologically slow. Resolver rules cost nothing at runtime and are a
+ * closer analogue of the container egress allowlist the worker will actually
+ * rely on.
+ */
+export const NO_EGRESS_ARGS = [
+  "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE localhost",
+];
+
+/**
+ * Record (do not intercept) every non-local request the page attempts.
+ *
+ * Passive listeners, so no proxying overhead. The DNS blackhole above does the
+ * blocking; this only answers "what did it try to reach?".
+ */
+export function watchEgress(page: Page, allowedOrigin: string): EgressLock {
+  const attempts: string[] = [];
+
+  const isLocal = (href: string): boolean =>
+    href.startsWith(allowedOrigin) ||
+    href.startsWith("data:") ||
+    href.startsWith("blob:") ||
+    href.startsWith("about:") ||
+    href.startsWith("chrome-extension:");
+
+  page.on("request", (req) => {
+    const url = req.url();
+    if (!isLocal(url)) attempts.push(url);
+  });
+
+  return { attempts };
+}
+
+/**
+ * Hash the exact bytes about to be rendered.
+ *
+ * Rehearses the worker's verify-before-execute rule (S6c). In production the
+ * hub pins a bundle's hash at publish time, but the author's presigned upload
+ * URL stays valid for another 300s — so the object in storage can be swapped
+ * after verification. The worker must therefore render the bytes the hub
+ * pinned, not whatever a re-fetch returns. Locally this proves the plumbing:
+ * hash both artifacts, and refuse to render if they don't match what was
+ * recorded when the shot list was built.
+ */
+export function hashWidgetArtifacts(distDir: string, widget: string): string {
+  const hash = createHash("sha256");
+  for (const file of [`${distDir}/${widget}.js`, `${distDir}/${widget}.css`]) {
+    // CSS is optional — a widget that ships no stylesheet is legitimate.
+    if (existsSync(file)) hash.update(readFileSync(file));
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * Fixed wall-clock instant every render starts from: a bright weekday midday, so
+ * time-of-day-dependent widgets (clock, weather, sun-driven energy) land in a
+ * flattering, stable state instead of drifting with the run.
+ */
+export const FROZEN_TIME = new Date("2026-06-15T12:34:00Z");
+
+/**
+ * Freeze time, then step it forward deliberately.
+ *
+ * Widgets gate their mount animation behind `requestAnimationFrame(() =>
+ * setMounted(true))` (sensor/sparkline.tsx, weather/forecast-chart.tsx). A
+ * fully paused clock never fires that callback, so those widgets would be
+ * screenshotted in their pre-mount state — or wait forever and die to the
+ * timeout. Installing the clock and then running it forward a short, fixed
+ * amount fires the rAF callbacks and any mount transition, while keeping the
+ * result byte-identical between runs.
+ */
+export async function freezeClock(page: Page): Promise<void> {
+  await page.clock.install({ time: FROZEN_TIME });
+}
+
+/** Advance the frozen clock enough to settle rAF-gated mount animations. */
+export async function settleAnimations(page: Page, ms = 1_000): Promise<void> {
+  await page.clock.runFor(ms);
+}
+
+/** Reject if a render exceeds the cap, so a hang surfaces as a failure rather
+    than a stalled run. */
+export async function withRenderTimeout<T>(
+  label: string,
+  fn: () => Promise<T>,
+  ms: number = RENDER_TIMEOUT_MS,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`render timeout after ${ms}ms: ${label}`)), ms);
+  });
+  try {
+    return await Promise.race([fn(), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Apply the nix-ld library path exactly once. `nixLdLibraryPath()` prepends the
+    existing value, so calling it per launch would grow the variable on every
+    render until the child's environment blows past the exec limit (E2BIG). */
+let nixLdApplied = false;
+function applyNixLdOnce(): void {
+  if (nixLdApplied) return;
+  nixLdApplied = true;
+  const nixLd = nixLdLibraryPath();
+  if (nixLd) process.env.NIX_LD_LIBRARY_PATH = nixLd;
+}
+
+/** Launch one browser and hand out a fresh context (own cache and storage) per
+    render. Enough isolation for the egress question, without paying a process
+    launch per shot. */
+/**
+ * Force a browser dead without hanging. A render that times out abandons its
+ * Playwright op but leaves the browser wedged: a graceful `browser.close()` on
+ * it never returns, so the next shot's recycle hangs on it forever. Race the
+ * graceful close against a short deadline, then SIGKILL the process outright.
+ */
+async function hardClose(browser: Browser): Promise<void> {
+  // `process()` exists at runtime on a launched Chromium but is absent from the
+  // base Browser type; narrow it here rather than at the call site.
+  const proc = (browser as Browser & { process?: () => { kill: (s: string) => void } | null })
+    .process?.();
+  await Promise.race([
+    browser.close().catch(() => {}),
+    new Promise((r) => setTimeout(r, 3_000)),
+  ]);
+  proc?.kill("SIGKILL");
+}
+
+export interface SharedBrowser {
+  newPage: () => Promise<Page>;
+  /** Drop the current browser (hard) and start fresh. Call after any render
+      failure: a timed-out render leaves the browser wedged, and reusing it
+      cascades into a 30s timeout on every following shot. */
+  recycle: () => Promise<void>;
+}
+
+export async function withSharedBrowser<T>(fn: (browser: SharedBrowser) => Promise<T>): Promise<T> {
+  applyNixLdOnce();
+
+  // Recycle the process every N pages. Each render pulls megabytes of icon data
+  // into a fresh context, and a single long-lived browser degrades and
+  // eventually wedges; recycling keeps cumulative state bounded.
+  const PAGES_PER_BROWSER = 8;
+
+  const launch = () => chromium.launch({ args: NO_EGRESS_ARGS });
+  let browser = await launch();
+  let served = 0;
+
+  const recycle = async (): Promise<void> => {
+    await hardClose(browser);
+    browser = await launch();
+    served = 0;
+  };
+
+  const newPage = async (): Promise<Page> => {
+    // Recycle on the counter or a dead browser. A wedged-but-connected browser
+    // is dropped explicitly by the caller via recycle() after a render failure.
+    if (served >= PAGES_PER_BROWSER || !browser.isConnected()) {
+      await recycle();
+    }
+    served++;
+    try {
+      const context = await browser.newContext({ deviceScaleFactor: 2 });
+      return await context.newPage();
+    } catch {
+      // Lost between the liveness check and the context: relaunch once so the
+      // crash costs one render rather than the rest of the pass.
+      await recycle();
+      served = 1;
+      const context = await browser.newContext({ deviceScaleFactor: 2 });
+      return context.newPage();
+    }
+  };
+
+  try {
+    return await fn({ newPage, recycle });
+  } finally {
+    await hardClose(browser);
+  }
+}
+
+/**
+ * Fresh browser process per render.
+ *
+ * The worker must not reuse a process across widgets — one widget's residue
+ * (globals, caches, service workers) must never reach another's shot.
+ */
+export async function withFreshBrowser<T>(fn: (page: Page, browser: Browser) => Promise<T>): Promise<T> {
+  // On NixOS the Playwright-downloaded Chromium can't find its system libs;
+  // point nix-ld at them so the bundled browser launches unmodified.
+  applyNixLdOnce();
+
+  const browser = await chromium.launch({ args: NO_EGRESS_ARGS });
+  try {
+    const context = await browser.newContext({ deviceScaleFactor: 2 });
+    const page = await context.newPage();
+    return await fn(page, browser);
+  } finally {
+    await browser.close();
+  }
+}

package/src/preview/harness/harness.tsx

@@ -0,0 +1,170 @@
+import type { ReactiveWidgetContext, WidgetDefinition } from "@glasshome/widget-sdk";
+import { instantiateWidget } from "@glasshome/widget-sdk/host";
+import { loadDemoData } from "@glasshome/sync-layer";
+import { getEntityView } from "@glasshome/sync-layer";
+import { byDomain, useAreas, useEntities } from "@glasshome/sync-layer/solid";
+import type { EntityDataAdapter } from "@glasshome/ui/solid";
+import { provideEntityData } from "@glasshome/ui/solid";
+import type { IconifyJSON } from "@iconify/types";
+// `?url` + runtime fetch, NOT a JSON import. Vite turns an imported JSON file
+// into an ES module — a multi-megabyte object literal the JS engine has to
+// evaluate on every page load, which cost ~200s per render. Fetching the same
+// file and letting the browser JSON.parse it natively is orders of magnitude
+// faster, and the request is local so the egress lock still holds.
+import lucideUrl from "@iconify-json/lucide/icons.json?url";
+import mdiUrl from "@iconify-json/mdi/icons.json?url";
+import { addAPIProvider, addCollection } from "iconify-icon";
+// The real built bundle + its separate CSS asset — the same artifacts the hub
+// serves. Rendering these (not the source) keeps previews honest.
+// App theme tokens (--radius, --border, --background, …), the same import dash's
+// styles.css uses. They land on :root and INHERIT into widget shadow roots
+// (custom properties cross the boundary; class rules don't). Without them,
+// shadow-side calc(var(--radius)+…) collapses — sharp corners, no border.
+import "@glasshome/ui/styles";
+// Fonts must load at the document (an @font-face in an adopted/shadow sheet
+// won't); the family name then inherits into the widget shadow. Same set dash's
+// styles.css loads.
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import "@fontsource-variable/caveat";
+
+// Preload every collection into iconify's shared icon storage before any widget
+// mounts. `iconify-icon` is a declared singleton host-provided module, so one
+// registration serves every widget. Full collections rather than a scanned
+// subset, because icon names are built at runtime (weather picks by condition,
+// light by on/off) and a static scan misses exactly those. All three prefixes
+// are needed: widgets use mdi, but @glasshome/ui components pull lucide.
+// (simple-icons is deliberately absent — nothing references it, and at 4.6MB it
+// was the single largest cost per page load.)
+async function preloadIcons(): Promise<void> {
+  const [mdi, lucide] = await Promise.all([
+    fetch(mdiUrl).then((r) => r.json() as Promise<IconifyJSON>),
+    fetch(lucideUrl).then((r) => r.json() as Promise<IconifyJSON>),
+  ]);
+  addCollection(mdi);
+  addCollection(lucide);
+}
+
+// No network fallback. Dash repoints this provider at its own /iconify/ proxy;
+// the render worker has no egress at all, so an unresolved icon must fail
+// visibly (blank) rather than reach out to api.iconify.design.
+addAPIProvider("", { resources: [] });
+
+// @glasshome/ui's smart-home components (pickers, entity rows) resolve data
+// through an injected adapter; dash binds the same four sync-layer functions in
+// main.tsx. Without it those components throw and the widget renders empty.
+// Host setup like this is duplicated per host today — see the mount
+// consolidation memo.
+const entityDataAdapter: EntityDataAdapter = {
+  entityIdsByDomain: byDomain,
+  useEntities,
+  getEntityView,
+  useAreas,
+};
+provideEntityData(entityDataAdapter);
+
+// Every built widget bundle + its CSS, selected by the `?widget=` param. Glob
+// keeps the imports static-analyzable while staying widget-agnostic — the same
+// real dist artifacts the hub serves.
+const bundles = import.meta.glob<{ default: WidgetDefinition }>("../dist/*.js");
+const styles = import.meta.glob<string>("../dist/*.css", {
+  query: "?raw",
+  import: "default",
+});
+
+async function loadWidget(name: string): Promise<{ def: WidgetDefinition; css: string | null }> {
+  const jsKey = `../dist/${name}.js`;
+  const loadJs = bundles[jsKey];
+  if (!loadJs) throw new Error(`no built bundle for widget "${name}" (${jsKey})`);
+  const def = (await loadJs()).default;
+  const loadCss = styles[`../dist/${name}.css`];
+  const css = loadCss ? await loadCss() : null;
+  return { def, css };
+}
+
+// Grid geometry mirrored from the dash route (rowHeight 70, margin 16, lg 12
+// cols at a 1024px reference container). A preview approximates one dashboard
+// width rather than mirroring every breakpoint.
+const CONTAINER = 1024;
+const COLS = 12;
+const GAP = 16;
+const ROW_H = 70;
+const COL_W = (CONTAINER - GAP * (COLS - 1)) / COLS;
+
+function tilePx(size: { w: number; h: number }): { width: number; height: number } {
+  return {
+    width: Math.round(COL_W * size.w + GAP * (size.w - 1)),
+    height: ROW_H * size.h + GAP * (size.h - 1),
+  };
+}
+
+/** Mount via the shared SDK recipe (`@glasshome/widget-sdk/host`): closed shadow
+    root, injected tokens, adopted widget CSS, WidgetCtx provider, `dark`
+    mirrored onto the host. No perf-blur/a11y override sheet — not needed for a
+    static shot, so no `extraSheets`; `dark` is the default `mirrorClasses`. The
+    `dark` document class is toggled by the caller before this runs. */
+function mount(
+  host: HTMLElement,
+  def: WidgetDefinition,
+  config: Record<string, unknown>,
+  ctx: ReactiveWidgetContext,
+  cssText: string | null,
+): void {
+  instantiateWidget(host, {
+    definition: def,
+    config: () => config,
+    ctx,
+    cssText,
+    onCrash: (err) => console.error("[harness] widget threw:", err),
+  });
+}
+
+async function main(): Promise<void> {
+  const params = new URLSearchParams(location.search);
+  const widgetName = params.get("widget") ?? "light";
+  const exIndex = Number(params.get("ex") ?? "0");
+  const dark = params.get("theme") === "dark";
+
+  const { def, css } = await loadWidget(widgetName);
+  const examples = def.manifest.examples ?? [];
+  // Publish the shot-list so the capture driver can enumerate without importing
+  // the widget's TSX source under a non-Solid JSX runtime.
+  document.documentElement.dataset.harnessExamples = JSON.stringify(
+    examples.map((e) => ({ label: e.label, size: e.size })),
+  );
+  const example = examples[exIndex];
+  if (!example) {
+    document.title = "harness-error: no example";
+    return;
+  }
+
+  document.documentElement.classList.toggle("dark", dark);
+
+  // Icons must be registered before the widget mounts, or its first paint
+  // triggers the (now dead) network lookup and renders blank.
+  await preloadIcons();
+
+  await loadDemoData();
+
+  // Background and padding are the renderer's job: the preview is the widget
+  // alone, tight and transparent (omitBackground on capture).
+  const { width, height } = tilePx(example.size);
+  const stage = document.getElementById("stage");
+  if (!stage) return;
+  stage.style.width = `${width}px`;
+  stage.style.height = `${height}px`;
+
+  const ctx: ReactiveWidgetContext = {
+    isEditMode: () => false,
+    updateConfig: () => {},
+    dimensions: () => ({ width, height }),
+  };
+
+  mount(stage, def, example.config as Record<string, unknown>, ctx, css);
+
+  await document.fonts.ready;
+  // Signal to the capture driver that mount + fonts settled.
+  document.documentElement.setAttribute("data-harness-ready", "1");
+}
+
+void main();

package/src/preview/harness/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Widget Preview Harness</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: transparent;
+      }
+      /* The capture target: the widget tile alone. Background and padding are
+         the renderer's job, so the screenshot is tight and transparent. */
+      #stage {
+        position: fixed;
+        top: 0;
+        left: 0;
+        display: block;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="stage"></div>
+    <script type="module" src="./harness.tsx"></script>
+  </body>
+</html>

package/src/preview/nix-ld.ts

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * The Playwright-downloaded Chromium ships a glibc dynamic linker
+ * (`/lib64/ld-linux-x86-64.so.2`) and expects system libs (glib, nss, X11, …)
+ * that do not exist on NixOS, so it dies with `libglib-2.0.so.0: cannot open
+ * shared object file`. NixOS's nix-ld provides the interpreter shim via
+ * `NIX_LD`; it just needs a library search path. This harvests that path from
+ * the installed nix Chromium's runtime closure — version-independent and
+ * offline — so the downloaded browser resolves every lib.
+ *
+ * Returns the `:`-joined path (existing `NIX_LD_LIBRARY_PATH` prepended), or
+ * null when not on NixOS or no nix Chromium is installed (caller should then
+ * launch normally).
+ */
+export function nixLdLibraryPath(): string | null {
+  if (!existsSync("/etc/NIXOS")) return null;
+
+  let chromePath: string;
+  try {
+    chromePath = execFileSync("bash", ["-lc", 'readlink -f "$(command -v chromium)"'], {
+      encoding: "utf-8",
+    }).trim();
+  } catch {
+    return null;
+  }
+  if (!chromePath || !existsSync(chromePath)) return null;
+
+  let closure: string[];
+  try {
+    closure = execFileSync("nix-store", ["-qR", chromePath], { encoding: "utf-8" })
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+
+  const dirs: string[] = [];
+  for (const p of closure) {
+    for (const sub of [`${p}/lib`, `${p}/lib64`]) {
+      if (existsSync(sub)) dirs.push(sub);
+    }
+  }
+  if (dirs.length === 0) return null;
+
+  const existing = process.env.NIX_LD_LIBRARY_PATH;
+  return existing ? `${existing}:${dirs.join(":")}` : dirs.join(":");
+}

package/template/.gitignore.template

@@ -1,4 +1,6 @@
 node_modules/
 dist/
+preview/
+.glasshome-preview/
 .env
 *.local

package/src/commands/dev-registry.ts

@@ -1,86 +0,0 @@
-import { log, outro, spinner } from "@clack/prompts";
-import { trpcMutate, trpcQuery } from "../utils/api";
-
-interface DevStatusResponse {
-  devMode: boolean;
-  registries: Array<{ url: string; name: string; isDefault: boolean }>;
-}
-
-export async function runAddDevRegistry(options: {
-  registryUrl?: string;
-  apiUrl?: string;
-}): Promise<void> {
-  const registryUrl = options.registryUrl || "http://localhost:5173/__widgets/registry.json";
-  const apiUrl = options.apiUrl || "http://localhost:3333";
-
-  const s = spinner();
-
-  // Step 1: Check if dev mode is enabled
-  s.start("Checking dev mode status...");
-  let devEnabled = false;
-  try {
-    const status = await trpcQuery<DevStatusResponse>({
-      apiUrl,
-      path: "appConfig.get",
-    });
-    devEnabled = status.devMode;
-  } catch (err) {
-    s.stop("Failed to connect");
-    log.error(
-      `Could not reach dashboard API at ${apiUrl}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    log.info("Make sure the dashboard API server is running and the URL is correct.");
-    process.exit(1);
-  }
-
-  // Step 2: Enable dev mode if needed
-  if (!devEnabled) {
-    s.message("Enabling dev mode...");
-    try {
-      const result = await trpcMutate<{ devMode: boolean }>({
-        apiUrl,
-        path: "appConfig.toggleDevMode",
-        input: {},
-      });
-      if (!result.devMode) {
-        s.stop("Failed");
-        log.error("Could not enable dev mode");
-        process.exit(1);
-      }
-    } catch (err) {
-      s.stop("Failed");
-      log.error(`Failed to enable dev mode: ${err instanceof Error ? err.message : String(err)}`);
-      process.exit(1);
-    }
-  }
-  s.stop("Dev mode enabled");
-
-  // Step 3: Add the registry via /dev/registries endpoint
-  s.start("Adding dev registry...");
-  try {
-    const res = await fetch(`${apiUrl.replace(/\/$/, "")}/dev/registries`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ url: registryUrl, name: "Local Dev Server" }),
-    });
-
-    if (res.status === 409) {
-      s.stop("Registry already registered");
-      log.info(`Registry ${registryUrl} is already configured`);
-    } else if (res.ok) {
-      s.stop("Registry added");
-      log.success(`Added registry: ${registryUrl}`);
-    } else {
-      const err = (await res.json()) as { error: string };
-      s.stop("Failed");
-      log.error(`Failed to add registry: ${err.error}`);
-      process.exit(1);
-    }
-  } catch (err) {
-    s.stop("Failed");
-    log.error(`Failed to add registry: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-
-  outro("Done! Refresh your dashboard to see dev widgets.");
-}