@glasshome/widget-cli 0.13.6 → 0.14.1

package/bin/cli.ts

@@ -29,6 +29,13 @@ Commands:
                          --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
+                         --sizes <WxH,...|grid> renders at pixel sizes into preview/sweep/, with a
+                           contact sheet per example (grid: common dashboard sizes)
+                         --theme light|dark, --example <n,...> narrow the render
+                         --config <json> merges over the example's config
+                         --service <domain.service|entity_id|json> changes demo state first (repeatable)
+                         --at <iso time> sets the clock, --click <selector> taps before the shot
+                         --eval <expr> prints an expression per render (root = widget shadow root)
   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
@@ -46,6 +53,8 @@ Examples:
   glasshome-widget connect http://localhost:3333
   glasshome-widget preview
   glasshome-widget preview clock
+  glasshome-widget preview light --sizes 150x156,340x242 --theme dark
+  glasshome-widget preview clock --at 2026-06-15T21:00:00 --config '{"style":"analog"}'
   glasshome-widget validate
   glasshome-widget validate clock
   glasshome-widget info
@@ -72,6 +81,14 @@ const { values: flags, positionals } = parseArgs({
     to: { type: "string" },
     "re-auth": { type: "boolean" },
     isolate: { type: "boolean" },
+    sizes: { type: "string" },
+    theme: { type: "string" },
+    example: { type: "string" },
+    at: { type: "string" },
+    config: { type: "string" },
+    service: { type: "string", multiple: true },
+    click: { type: "string" },
+    eval: { type: "string" },
     dry: { type: "boolean" },
     help: { type: "boolean", short: "h" },
   },
@@ -144,8 +161,19 @@ switch (effectiveCommand) {
   case "preview": {
     const widgetDir = resolveWidgetDir();
     await notifySdkUpdate(widgetDir);
-    const { runPreview } = await import("../src/commands/preview");
-    await runPreview(widgetDir, args, flags.isolate === true);
+    const { runPreview, runSweepPreview, wantsSweep } = await import("../src/commands/preview");
+    const sweep = {
+      sizes: flags.sizes,
+      theme: str(flags.theme),
+      example: str(flags.example),
+      at: str(flags.at),
+      config: str(flags.config),
+      service: flags.service?.flatMap((s) => str(s) ?? []),
+      click: str(flags.click),
+      eval: str(flags.eval),
+    };
+    if (wantsSweep(sweep)) await runSweepPreview(widgetDir, args, sweep);
+    else await runPreview(widgetDir, args, flags.isolate === true);
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-cli",
-  "version": "0.13.6",
+  "version": "0.14.1",
   "description": "CLI for creating and managing GlassHome widgets",
   "type": "module",
   "bin": {
@@ -28,11 +28,12 @@
     "@fontsource-variable/caveat": "^5.2.8",
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/geist-mono": "^5.2.8",
-    "@glasshome/sync-layer": "0.8.2",
-    "@glasshome/widget-contract": "0.2.1",
-    "@glasshome/widget-sdk": "1.16.0",
+    "@glasshome/sync-layer": "0.9.0",
+    "@glasshome/widget-contract": "0.3.0",
+    "@glasshome/widget-sdk": "1.17.1",
     "@iconify-json/lucide": "^1.2.0",
     "@iconify-json/mdi": "^1.2.3",
+    "@iconify/utils": "^3.1.4",
     "@tailwindcss/vite": "^4.1.13",
     "open": "^11.0.0",
     "picocolors": "^1.1.1",

package/src/commands/preview.ts

@@ -1,6 +1,7 @@
 import { log } from "@clack/prompts";
 import color from "picocolors";
 import { runPreview as capturePreview } from "../preview/capture";
+import { type Box, DEFAULT_SIZES, runSweep, type Theme } from "../preview/sweep";
 import { withQuietStdout } from "../utils/quiet";
 
 /**
@@ -12,7 +13,7 @@ import { withQuietStdout } from "../utils/quiet";
  * 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> {
+async function requirePlaywright(): Promise<void> {
   try {
     await import("playwright");
   } catch {
@@ -20,10 +21,14 @@ export async function runPreview(cwd: string, names: string[], isolate: boolean)
     log.info(`Install them with:\n  ${color.bold("bun add -d playwright && bunx playwright install chromium")}`);
     process.exit(1);
   }
+}
 
-  const progress = (m: string) => {
-    process.stdout.write(`${color.gray("│")}  ${color.dim(m)}\n`);
-  };
+const progress = (m: string) => {
+  process.stdout.write(`${color.gray("│")}  ${color.dim(m)}\n`);
+};
+
+export async function runPreview(cwd: string, names: string[], isolate: boolean): Promise<void> {
+  await requirePlaywright();
 
   log.info(names.length ? `Previewing ${names.join(", ")}` : "Previewing all widgets");
 
@@ -92,3 +97,86 @@ export async function runPreview(cwd: string, names: string[], isolate: boolean)
   // idle forever after the verdict instead of exiting. Leave deliberately.
   process.exit(hangs.length || integrity.length ? 1 : 0);
 }
+
+export interface SweepFlags {
+  sizes?: string | boolean;
+  theme?: string;
+  example?: string;
+  at?: string;
+  config?: string;
+  service?: string[];
+  click?: string;
+  eval?: string;
+}
+
+export function wantsSweep(flags: SweepFlags): boolean {
+  return Object.values(flags).some((v) => v !== undefined && !(Array.isArray(v) && v.length === 0));
+}
+
+function fail(message: string): never {
+  log.error(message);
+  process.exit(1);
+}
+
+function parseSizes(value: string | boolean | undefined): Box[] {
+  if (value === undefined) return [];
+  if (value === "grid") return DEFAULT_SIZES;
+  return String(value)
+    .split(",")
+    .map((s) => {
+      const m = s.trim().match(/^(\d+)x(\d+)$/);
+      if (!m) fail(`--sizes takes grid, or WIDTHxHEIGHT pairs in pixels like 150x156,340x242 (got "${s}")`);
+      return { width: Number(m[1]), height: Number(m[2]) };
+    });
+}
+
+function parseThemes(value: string | undefined): Theme[] {
+  if (!value) return ["light", "dark"];
+  const themes = value.split(",");
+  for (const t of themes) if (t !== "light" && t !== "dark") fail(`--theme is light, dark or both (got "${t}")`);
+  return themes as Theme[];
+}
+
+function parseConfig(value: string | undefined): Record<string, unknown> | undefined {
+  if (!value) return undefined;
+  try {
+    return JSON.parse(value);
+  } catch {
+    fail(`--config must be a JSON object (got ${value})`);
+  }
+}
+
+/**
+ * Render widgets at chosen pixel sizes, with the config, demo state or clock
+ * overridden, into `<project>/preview/sweep/`, plus a contact sheet per example
+ * and theme when several sizes are rendered.
+ */
+export async function runSweepPreview(cwd: string, names: string[], flags: SweepFlags): Promise<void> {
+  await requirePlaywright();
+  const at = flags.at ? new Date(flags.at) : undefined;
+  if (at && Number.isNaN(at.getTime())) fail(`--at takes an ISO time like 2026-06-15T21:00:00 (got "${flags.at}")`);
+  const examples = flags.example ? flags.example.split(",").map(Number) : [];
+  if (examples.some((n) => !Number.isInteger(n) || n < 0)) fail("--example takes example numbers, starting at 0");
+
+  const summary = await withQuietStdout(() =>
+    runSweep({
+      projectDir: cwd,
+      only: names,
+      themes: parseThemes(flags.theme),
+      examples,
+      sizes: parseSizes(flags.sizes),
+      at,
+      config: parseConfig(flags.config),
+      services: flags.service ?? [],
+      click: flags.click,
+      evaluate: flags.eval,
+      onProgress: progress,
+      onResult: (line) => process.stdout.write(`${line}\n`),
+    }),
+  ).catch((err: unknown) => fail(err instanceof Error ? err.message : String(err)));
+
+  const sheets = summary.sheets ? ` and ${summary.sheets} contact sheet(s)` : "";
+  log.success(`Rendered ${summary.shots} image(s)${sheets} into ${color.cyan("preview/sweep/")}`);
+  if (summary.failures.length) log.warn(summary.failures.map((f) => `  · ${f}`).join("\n"));
+  process.exit(summary.failures.length ? 1 : 0);
+}

package/src/preview/capture.ts

@@ -1,9 +1,5 @@
-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 { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
 import {
   freezeClock,
   hashWidgetArtifacts,
@@ -14,6 +10,7 @@ import {
   withRenderTimeout,
   withSharedBrowser,
 } from "./constraints";
+import { serveHarness } from "./serve";
 
 const THEMES = ["light", "dark"] as const;
 
@@ -45,37 +42,17 @@ export interface PreviewOptions {
 
 // 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 {
+export 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);
@@ -83,57 +60,16 @@ export async function runPreview(opts: PreviewOptions): Promise<PreviewSummary>
   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 server = await serveHarness(projectDir, only, progress);
+  const { base, origin, distDir, widgets: widgetNames } = server;
 
   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).
@@ -250,9 +186,7 @@ export async function runPreview(opts: PreviewOptions): Promise<PreviewSummary>
     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 });
+    await server.close();
   }
 
   return { shots: shot, widgets: shotLists.size, skipped, failures };

package/src/preview/constraints.ts

@@ -44,6 +44,10 @@ export const NO_EGRESS_ARGS = [
   "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE localhost",
 ];
 
+/** `CHROMIUM_PATH` points at a system Chromium where Playwright's own build is absent or cannot run. */
+const launchLocked = () =>
+  chromium.launch({ executablePath: process.env.CHROMIUM_PATH || undefined, args: NO_EGRESS_ARGS });
+
 /**
  * Record (do not intercept) every non-local request the page attempts.
  *
@@ -153,6 +157,9 @@ function applyNixLdOnce(): void {
  * 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.
  */
+// A still shows the settled state: the theme zeroes transitions under reduced motion.
+const CONTEXT_OPTIONS = { deviceScaleFactor: 2, reducedMotion: "reduce" } as const;
+
 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.
@@ -181,13 +188,12 @@ export async function withSharedBrowser<T>(fn: (browser: SharedBrowser) => Promi
   // 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 browser = await launchLocked();
   let served = 0;
 
   const recycle = async (): Promise<void> => {
     await hardClose(browser);
-    browser = await launch();
+    browser = await launchLocked();
     served = 0;
   };
 
@@ -199,14 +205,14 @@ export async function withSharedBrowser<T>(fn: (browser: SharedBrowser) => Promi
     }
     served++;
     try {
-      const context = await browser.newContext({ deviceScaleFactor: 2 });
+      const context = await browser.newContext(CONTEXT_OPTIONS);
       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 });
+      const context = await browser.newContext(CONTEXT_OPTIONS);
       return context.newPage();
     }
   };
@@ -229,9 +235,9 @@ export async function withFreshBrowser<T>(fn: (page: Page, browser: Browser) =>
   // point nix-ld at them so the bundled browser launches unmodified.
   applyNixLdOnce();
 
-  const browser = await chromium.launch({ args: NO_EGRESS_ARGS });
+  const browser = await launchLocked();
   try {
-    const context = await browser.newContext({ deviceScaleFactor: 2 });
+    const context = await browser.newContext(CONTEXT_OPTIONS);
     const page = await context.newPage();
     return await fn(page, browser);
   } finally {

package/src/preview/harness/harness.tsx

@@ -1,10 +1,11 @@
 import type { ReactiveWidgetContext, WidgetDefinition } from "@glasshome/widget-sdk";
 import { instantiateWidget } from "@glasshome/widget-sdk/host";
-import { claimHostApi, getEntityView } from "@glasshome/sync-layer";
+import { callService, claimHostApi, 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 { provideEntityData, provideIcons } from "@glasshome/ui/solid";
 import type { IconifyJSON } from "@iconify/types";
+import { getIconData } from "@iconify/utils";
 // `?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
@@ -43,6 +44,18 @@ async function preloadIcons(): Promise<void> {
   ]);
   addCollection(mdi);
   addCollection(lucide);
+  const collections: Record<string, IconifyJSON> = { mdi, lucide };
+  provideIcons({
+    bundled: {},
+    load: async (names) =>
+      Object.fromEntries(
+        names.map((name) => {
+          const [prefix = "", ...rest] = name.split(":");
+          const set = collections[prefix];
+          return [name, set ? (getIconData(set, rest.join(":")) ?? null) : null];
+        }),
+      ),
+  });
 }
 
 // No network fallback. Dash repoints this provider at its own /iconify/ proxy;
@@ -162,6 +175,10 @@ async function main(): Promise<void> {
   document.documentElement.dataset.harnessExamples = JSON.stringify(
     examples.map((e) => ({ label: e.label, size: e.size })),
   );
+  document.documentElement.dataset.harnessBounds = JSON.stringify({
+    min: def.manifest.minSize,
+    max: def.manifest.maxSize,
+  });
   const example = examples[exIndex];
   if (!example) {
     document.title = "harness-error: no example";
@@ -179,10 +196,17 @@ async function main(): Promise<void> {
   const hostApi = claimHostApi();
   if (!hostApi) throw new Error("harness: host API already claimed");
   await hostApi.loadDemoData();
+  for (const call of params.getAll("svc")) {
+    const [service = "", entityId, data] = call.split("|");
+    const [domain = "", name = ""] = service.split(".");
+    await callService(domain, name, JSON.parse(data ?? "{}"), { entity_id: entityId });
+  }
 
   // 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 { width, height } = params.has("pw")
+    ? { width: Number(params.get("pw")), height: Number(params.get("ph")) }
+    : tilePx(example.size);
   const stage = document.getElementById("stage");
   if (!stage) return;
   stage.style.width = `${width}px`;
@@ -193,8 +217,14 @@ async function main(): Promise<void> {
     dimensions: () => ({ width, height }),
   };
 
-  mount(stage, def, example.config as Record<string, unknown>, ctx, css);
+  const config = {
+    ...(example.config as Record<string, unknown>),
+    ...JSON.parse(params.get("cfg") ?? "{}"),
+  };
+  mount(stage, def, config, ctx, css);
 
+  // fonts.ready settles before the shadow root's text is laid out, so a cold page captures the fallback face.
+  await Promise.all([...document.fonts].map((face) => face.load().catch(() => undefined)));
   await document.fonts.ready;
   // Signal to the capture driver that mount + fonts settled.
   document.documentElement.setAttribute("data-harness-ready", "1");

package/src/preview/serve.ts

@@ -0,0 +1,94 @@
+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";
+
+export interface HarnessServer {
+  base: string;
+  origin: string;
+  distDir: string;
+  widgets: string[];
+  close: () => Promise<void>;
+}
+
+// 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 the widget bundles and serve the render harness over them.
+ *
+ * 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 serveHarness(
+  projectDir: string,
+  only: string[],
+  progress: (message: string) => void,
+): Promise<HarnessServer> {
+  const distDir = resolve(projectDir, "dist");
+  const harnessSrc = resolve(import.meta.dirname, "harness");
+  const tempRoot = resolve(projectDir, ".glasshome-preview");
+
+  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 widgets = readdirSync(distDir)
+    .filter((f) => f.endsWith(".js"))
+    .map((f) => f.slice(0, -3))
+    .filter((n) => (only.length ? only.includes(n) : true))
+    .sort();
+
+  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 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)] } },
+  });
+
+  const close = async () => {
+    await server.close().catch(() => {});
+    // Temp root is throwaway staging; never leave it in the project tree.
+    rmSync(tempRoot, { recursive: true, force: true });
+  };
+
+  try {
+    await server.listen();
+    const base = server.resolvedUrls?.local[0];
+    if (!base) throw new Error("vite dev server has no local url");
+    return { base, origin: new URL(base).origin, distDir, widgets, close };
+  } catch (err) {
+    await close();
+    throw err;
+  }
+}

package/src/preview/sweep.ts

@@ -0,0 +1,244 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Page } from "playwright";
+import { slug } from "./capture";
+import {
+  freezeClock,
+  settleAnimations,
+  watchEgress,
+  withRenderTimeout,
+  withSharedBrowser,
+} from "./constraints";
+import { serveHarness } from "./serve";
+
+export type Theme = "light" | "dark";
+
+export interface Box {
+  width: number;
+  height: number;
+}
+
+export interface SweepOptions {
+  projectDir: string;
+  only: string[];
+  themes: Theme[];
+  /** Example indexes to render; all when empty. */
+  examples: number[];
+  /** Pixel boxes to render; each example's own size when empty. */
+  sizes: Box[];
+  at?: Date;
+  config?: Record<string, unknown>;
+  /** `domain.service|entity_id|json`, replayed against the demo home before mount. */
+  services: string[];
+  click?: string;
+  evaluate?: string;
+  onProgress?: (message: string) => void;
+  onResult?: (line: string) => void;
+}
+
+export interface SweepSummary {
+  shots: number;
+  sheets: number;
+  outDir: string;
+  failures: string[];
+}
+
+interface Example {
+  label?: string;
+  size: { w: number; h: number };
+}
+
+interface Bounds {
+  min: { w: number; h: number };
+  max: { w: number; h: number };
+}
+
+export const DEFAULT_SIZES: Box[] = [70, 156, 242, 328].flatMap((height) =>
+  [84, 150, 200, 270, 340, 420].map((width) => ({ width, height })),
+);
+
+// Inverse of the harness's tilePx height: rows * 70 + (rows - 1) * 16.
+const rowsFor = (height: number) => Math.round((height + 16) / 86);
+
+// Roots stay closed as in dash, so a handler that cannot fire there fails here too; --eval and --click reach in through this.
+function keepShadowRoots(): void {
+  const attach = Element.prototype.attachShadow;
+  Element.prototype.attachShadow = function (init) {
+    const root = attach.call(this, init);
+    Object.defineProperty(this, "__widgetRoot", { value: root });
+    return root;
+  };
+}
+
+export async function runSweep(opts: SweepOptions): Promise<SweepSummary> {
+  const progress = opts.onProgress ?? (() => {});
+  const report = opts.onResult ?? (() => {});
+  const projectDir = resolve(opts.projectDir);
+  const outDir = resolve(projectDir, "preview", "sweep");
+  const server = await serveHarness(projectDir, opts.only, progress);
+  const failures: string[] = [];
+  let shots = 0;
+  let sheets = 0;
+
+  const query = (widget: string, ex: number, theme: Theme, box?: Box) => {
+    const q = new URLSearchParams({ widget, ex: String(ex), theme });
+    if (box) {
+      q.set("pw", String(box.width));
+      q.set("ph", String(box.height));
+    }
+    if (opts.config) q.set("cfg", JSON.stringify(opts.config));
+    for (const s of opts.services) q.append("svc", s);
+    return `${server.base}?${q}`;
+  };
+
+  const render = async (page: Page, url: string, file: string): Promise<unknown> => {
+    watchEgress(page, server.origin);
+    await page.addInitScript(keepShadowRoots);
+    if (opts.at) await page.clock.install({ time: opts.at });
+    else await freezeClock(page);
+    await page.goto(url, { waitUntil: "domcontentloaded" });
+    await page.waitForSelector("html[data-harness-ready='1']", {
+      state: "attached",
+      timeout: 20_000,
+    });
+    await settleAnimations(page);
+    if (opts.click) {
+      // Playwright's actionability checks wait on animation frames, which a frozen clock never runs.
+      await page.clock.resume();
+      const at = await page.evaluate((selector) => {
+        const stage = document.getElementById("stage") as { __widgetRoot?: ShadowRoot } | null;
+        const box = stage?.__widgetRoot?.querySelector(selector)?.getBoundingClientRect();
+        return box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : null;
+      }, opts.click);
+      if (!at) throw new Error(`--click: nothing matches ${opts.click} inside the widget`);
+      await page.mouse.click(at.x, at.y);
+      await page.waitForTimeout(1_500);
+    }
+    await page.locator("#stage").screenshot({ path: file, omitBackground: true });
+    if (!opts.evaluate) return undefined;
+    return page.evaluate((code) => {
+      const root = (document.getElementById("stage") as { __widgetRoot?: ShadowRoot } | null)
+        ?.__widgetRoot;
+      return new Function("root", `return (${code});`)(root);
+    }, opts.evaluate);
+  };
+
+  try {
+    mkdirSync(outDir, { recursive: true });
+    await withSharedBrowser(async (browser) => {
+      for (const widget of server.widgets) {
+        const probe = await browser.newPage();
+        let examples: Example[] = [];
+        let bounds: Bounds | undefined;
+        try {
+          await probe.goto(query(widget, 0, "light"), { waitUntil: "domcontentloaded" });
+          await probe.waitForSelector("html[data-harness-bounds]", {
+            state: "attached",
+            timeout: 30_000,
+          });
+          examples = JSON.parse((await probe.getAttribute("html", "data-harness-examples")) ?? "[]");
+          bounds = JSON.parse((await probe.getAttribute("html", "data-harness-bounds")) ?? "null");
+        } finally {
+          await probe.context().close();
+        }
+        if (!examples.length || !bounds) {
+          failures.push(`${widget}: no examples to render`);
+          continue;
+        }
+        const fits = (box: Box) => {
+          const rows = rowsFor(box.height);
+          return bounds !== undefined && rows >= bounds.min.h && rows <= bounds.max.h;
+        };
+
+        const indexes = opts.examples.length ? opts.examples : examples.map((_, i) => i);
+        for (const ex of indexes) {
+          const example = examples[ex];
+          if (!example) {
+            failures.push(`${widget}: no example ${ex}`);
+            continue;
+          }
+          const label = slug(example.label ?? `example-${ex}`);
+          const boxes = opts.sizes.length ? opts.sizes.filter(fits) : [undefined];
+          for (const theme of opts.themes) {
+            progress(`Rendering ${widget} / ${label} / ${theme}...`);
+            const shot: { box: Box | undefined; file: string }[] = [];
+            for (const box of boxes) {
+              const size = box ? `-${box.width}x${box.height}` : "";
+              const file = resolve(outDir, `${widget}-${label}-${theme}${size}.png`);
+              const page = await browser.newPage();
+              try {
+                const result = await withRenderTimeout(`${widget} ${label} ${theme}${size}`, () =>
+                  render(page, query(widget, ex, theme, box), file),
+                );
+                shots++;
+                shot.push({ box, file });
+                if (opts.evaluate) {
+                  report(`${widget} ${label} ${theme}${size}: ${JSON.stringify(result)}`);
+                }
+              } catch (err) {
+                failures.push(`${widget} ${label} ${theme}${size}: ${(err as Error).message}`);
+                await browser.recycle().catch(() => {});
+              } finally {
+                await page
+                  .context()
+                  .close()
+                  .catch(() => {});
+              }
+            }
+            if (shot.length > 1) {
+              const page = await browser.newPage();
+              try {
+                await writeSheet(page, theme, shot, resolve(outDir, `${widget}-${label}-${theme}.png`));
+                sheets++;
+              } finally {
+                await page
+                  .context()
+                  .close()
+                  .catch(() => {});
+              }
+            }
+          }
+        }
+      }
+    });
+  } finally {
+    await server.close();
+  }
+
+  return { shots, sheets, outDir, failures };
+}
+
+// One row per height, widths left to right, each shot at its CSS size.
+async function writeSheet(
+  page: Page,
+  theme: Theme,
+  shots: { box: Box | undefined; file: string }[],
+  path: string,
+): Promise<void> {
+  const rows = new Map<number, { box: Box; file: string }[]>();
+  for (const s of shots) {
+    if (!s.box) continue;
+    rows.set(s.box.height, [...(rows.get(s.box.height) ?? []), { box: s.box, file: s.file }]);
+  }
+  const background =
+    theme === "light"
+      ? "linear-gradient(135deg,#e9edf3,#cfd8e3)"
+      : "linear-gradient(135deg,#1b2230,#0d1117)";
+  const body = [...rows.keys()]
+    .sort((a, b) => a - b)
+    .map((height) => {
+      const cells = (rows.get(height) ?? [])
+        .sort((a, b) => a.box.width - b.box.width)
+        .map(
+          ({ box, file }) =>
+            `<figure><img width="${box.width}" height="${box.height}" src="data:image/png;base64,${readFileSync(file).toString("base64")}"><figcaption>${box.width}x${box.height}</figcaption></figure>`,
+        )
+        .join("");
+      return `<div class="row">${cells}</div>`;
+    })
+    .join("");
+  await page.setContent(
+    `<style>body{margin:0}#sheet{display:inline-block;padding:20px 20px 4px;background:${background};font:12px sans-serif;color:#888}.row{display:flex;gap:16px;align-items:flex-start;margin-bottom:16px}figure{margin:0}img{display:block}</style><div id="sheet">${body}</div>`,
+  );
+  await page.locator("#sheet").screenshot({ path });
+}