@fairfox/polly 0.23.0 → 0.25.0

package/README.md

@@ -125,6 +125,53 @@ First-time key exchange between devices uses a pairing token displayed as a QR c
 
 The three tiers coexist in one application — public settings in `$sharedState`, collaborative documents in `$peerState`, private notes in `$meshState`. See [docs/STATE.md](docs/STATE.md) for the full decision tree and [docs/RFC-041-choosing.md](docs/RFC-041-choosing.md) for the design rationale.
 
+### Node and Bun are first-class mesh peers
+
+Archival cron, LLM proxies, admin CLIs, headless bridges — every always-on participant gets the same state primitives as the browser, without monkey-patching globals or writing bespoke transport wiring. Polly ships a factory that accepts injectable transport and storage:
+
+```typescript
+import { createMeshClient, $meshState } from "@fairfox/polly/mesh";
+import { bootstrapCliKeyring, fileKeyringStorage } from "@fairfox/polly/mesh/node";
+import { RTCPeerConnection } from "werift";              // or '@roamhq/wrtc'
+
+const storage = fileKeyringStorage("~/.fairfox/keyring.json");
+const keyring = await bootstrapCliKeyring({ storage });   // first run prompts for a pairing token
+
+const client = await createMeshClient({
+  signaling: { url: "wss://example.com/polly/signaling", peerId: "cli-a1b2" },
+  rtc:       { RTCPeerConnection },
+  keyring,
+});
+
+const doc = $meshState("agenda", { items: [] });
+await doc.loaded;
+await client.close();
+```
+
+`createMeshClient` is runtime-agnostic — in a browser the `rtc` option is optional because `globalThis.RTCPeerConnection` exists. The `@fairfox/polly/mesh/node` subpath adds filesystem-backed keyring storage, atomic writes with `0600` permissions, and the stdin bootstrap flow. Neither `werift` nor `@roamhq/wrtc` is bundled; both are declared as optional peer dependencies. Pick the one that fits your deployment — `werift` installs cleanly anywhere (pure TypeScript, no native deps), `@roamhq/wrtc` is faster but needs prebuilt binaries for your platform.
+
+### Blob storage for large files
+
+CRDT documents shouldn't carry binary payloads — the op history grows with every sync. Polly ships a content-addressed blob store that transfers files peer-to-peer over the same WebRTC channels as `$meshState`, with no server storage. Documents hold lightweight `BlobRef` values; the bytes live in a local IndexedDB cache and move between peers in 64 KiB chunks.
+
+```typescript
+import { createBlobStore, createBlobRef } from "@fairfox/polly/mesh";
+
+const blobs = createBlobStore(webrtcAdapter, { encrypt: { key: docKey } });
+
+// Sender
+const bytes = new Uint8Array(await file.arrayBuffer());
+const ref = await createBlobRef({ bytes, filename: file.name, mimeType: file.type });
+await blobs.put(ref, bytes);       // caches locally, announces to peers
+doc.value = { ...doc.value, attachment: ref };
+
+// Receiver (on any connected peer)
+const received = await blobs.get(ref.hash);  // fetches from peers, verifies hash
+const url = await blobs.url(ref.hash);        // object URL for <img src>
+```
+
+SHA-256 content addressing deduplicates across peers and documents. Encryption is optional — when configured, the sender encrypts once (XSalsa20-Poly1305) and chunks the ciphertext; the receiver reassembles, decrypts, and verifies the plaintext hash against the `BlobRef`. See [docs/RFC-042-blob-sync.md](docs/RFC-042-blob-sync.md) for the design.
+
 ## Verification that plugs in
 
 A popup and a background script both write to the same state. A content script reads it mid-update. Tests miss these bugs because they depend on timing.
@@ -243,13 +290,20 @@ polly format            Format your code
 polly test              Run tests
 polly verify            Run formal verification
 polly visualize         Generate architecture diagrams (Structurizr DSL)
+polly quality           Run conformance checks (no-as-casting)
 ```
 
 ## Quality tooling
 
 Polly ships conformance checks and a browser test harness that consuming applications can adopt directly.
 
-**No-as-casting check.** Bans TypeScript `as` type assertions codebase-wide (only `as const` and the explicit escape hatch `as unknown as` are allowed). Violations include pattern-specific fix advice. Import it programmatically:
+**No-as-casting check.** Bans TypeScript `as` type assertions codebase-wide (only `as const` and the explicit escape hatch `as unknown as` are allowed). Violations include pattern-specific fix advice. Run as a CLI:
+
+```bash
+polly quality [--root <dir>] [--exclude-packages <names>] [--exclude-files <names>]
+```
+
+Or import it programmatically for integration into custom check scripts:
 
 ```typescript
 import { checkNoAsCasting } from "@fairfox/polly/quality";

package/dist/cli/polly.js

@@ -155,6 +155,22 @@ async function test() {
     throw new Error(`Tests failed with exit code ${exitCode}`);
   }
 }
+async function testBrowser() {
+  const bundledCli = `${__dirname2}/../tools/test/src/browser/run.js`;
+  const monorepoCli = `${__dirname2}/../tools/test/src/browser/run.ts`;
+  const browserCli = await Bun.file(bundledCli).exists() ? bundledCli : monorepoCli;
+  const proc = Bun.spawn(["bun", browserCli, ...commandArgs], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+    env: process.env
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    throw new Error(`Browser tests failed with exit code ${exitCode}`);
+  }
+}
 async function check() {
   const checks = [
     { name: "Type checking", fn: typecheck },
@@ -205,6 +221,7 @@ Usage:
   polly lint [--fix]               Lint your code
   polly format                     Format your code
   polly test [args]                Run tests
+  polly test:browser [dir]         Run *.browser.{ts,tsx} in Puppeteer
   polly verify [args]              Run formal verification
   polly visualize [args]           Generate architecture diagrams
   polly quality [args]             Run quality conformance checks
@@ -243,6 +260,9 @@ async function main() {
       case "test":
         await test();
         break;
+      case "test:browser":
+        await testBrowser();
+        break;
       case "verify":
         await verify();
         break;
@@ -272,4 +292,4 @@ async function main() {
 }
 main();
 
-//# debugId=B9B6663515E3E39364756E2164756E21
+//# debugId=962EF67B5CBBAF2264756E2164756E21

package/dist/cli/polly.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../cli/polly.ts"],
   "sourcesContent": [
-    "#!/usr/bin/env bun\n/**\n * Polly CLI\n *\n * Command-line tool for building multi-execution-context applications\n * with reactive state and cross-context messaging.\n *\n * Supports: Chrome extensions, PWAs, Node/Bun/Deno apps with workers\n *\n * Usage:\n *   polly init [name] [--type=TYPE]  Create a new project\n *   polly check                      Run all checks (typecheck, lint, test, build)\n *   polly build [options]            Build the project\n *   polly dev                        Build with watch mode\n *   polly typecheck                  Type check your code\n *   polly lint [--fix]               Lint your code\n *   polly format                     Format your code\n *   polly test [args]                Run tests (requires bun test)\n *   polly verify [args]              Run formal verification\n *   polly visualize [args]           Generate architecture diagrams\n *   polly quality [args]             Run quality conformance checks\n *   polly help                       Show help\n *\n * Project Types (init --type):\n *   extension           Chrome/Firefox extension (default)\n *   pwa                 Progressive Web App with workers\n *   websocket           WebSocket server application\n *   generic             Generic TypeScript project\n *\n * Options:\n *   --prod              Build for production (minified)\n *   --config <path>     Path to config file (default: polly.config.ts)\n *   --fix               Auto-fix lint/format issues\n *   --type=TYPE         Project type for init command\n */\n\n// Use Bun built-ins instead of Node.js APIs\nconst __dirname = import.meta.dir;\n\nconst command = process.argv[2];\nconst commandArgs = process.argv.slice(3);\nconst cwd = process.cwd();\n\n// Parse arguments\nconst args = {\n  prod: process.argv.includes(\"--prod\"),\n  config: process.argv.includes(\"--config\")\n    ? process.argv[process.argv.indexOf(\"--config\") + 1]\n    : undefined,\n};\n\n/**\n * Load user's configuration\n */\nasync function loadConfig() {\n  const configPaths = [\n    args.config,\n    `${cwd}/polly.config.ts`,\n    `${cwd}/polly.config.js`,\n    `${cwd}/polly.config.mjs`,\n  ].filter(Boolean) as string[];\n\n  for (const configPath of configPaths) {\n    // Use Bun.file().exists() instead of existsSync\n    if (await Bun.file(configPath).exists()) {\n      try {\n        const config = await import(configPath);\n        return config.default || config;\n      } catch (error) {\n        console.log(`❌ Failed to load config: ${configPath}`);\n        throw error;\n      }\n    }\n  }\n  return {\n    srcDir: \"src\",\n    distDir: \"dist\",\n    manifest: \"manifest.json\",\n  };\n}\n\n/**\n * Build command - build the extension\n */\nasync function build() {\n  const config = await loadConfig();\n\n  // Check if bundled (published) or in monorepo\n  const bundledScript = `${__dirname}/../scripts/build-extension.js`;\n  const monorepoScript = `${__dirname}/../scripts/build-extension.ts`;\n  const buildScriptPath = (await Bun.file(bundledScript).exists()) ? bundledScript : monorepoScript;\n\n  // Pass config via environment\n  process.env[\"WEB_EXT_SRC\"] = `${cwd}/${config.srcDir || \"src\"}`;\n  process.env[\"WEB_EXT_DIST\"] = `${cwd}/${config.distDir || \"dist\"}`;\n  process.env[\"WEB_EXT_MANIFEST\"] = `${cwd}/${config.manifest || \"manifest.json\"}`;\n  process.env[\"WEB_EXT_CWD\"] = cwd;\n  process.env[\"WEB_EXT_PROD\"] = args.prod ? \"true\" : \"false\";\n\n  // Run build\n  const proc = Bun.spawn([\"bun\", buildScriptPath], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    process.exit(exitCode);\n  }\n}\n\n/**\n * Dev command - build with watch mode\n */\nasync function dev() {\n  await build();\n}\n\n/**\n * Verify command - delegate to @fairfox/web-ext-verify\n */\nasync function verify() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/verify/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/verify/src/cli.ts`;\n  const verifyCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", verifyCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Verification failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Visualize command - delegate to @fairfox/polly-visualize\n */\nasync function visualize() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/visualize/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/visualize/src/cli.ts`;\n  const visualizeCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", visualizeCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Visualization failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Quality command - delegate to @fairfox/polly-quality\n */\nasync function quality() {\n  const bundledCli = `${__dirname}/../tools/quality/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/quality/src/cli.ts`;\n  const qualityCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", qualityCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Quality checks failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Typecheck command - run TypeScript type checking\n */\nasync function typecheck() {\n  const proc = Bun.spawn([\"bunx\", \"tsc\", \"--noEmit\"], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Type checking failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Lint command - run Biome linter\n */\nasync function lint() {\n  const fix = commandArgs.includes(\"--fix\");\n  const lintArgs = fix ? [\"check\", \"--write\", \".\"] : [\"check\", \".\"];\n\n  const proc = Bun.spawn([\"bunx\", \"@biomejs/biome\", ...lintArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Linting failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Format command - run Biome formatter\n */\nasync function format() {\n  const proc = Bun.spawn([\"bunx\", \"@biomejs/biome\", \"format\", \"--write\", \".\"], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Formatting failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Test command - delegate to @fairfox/polly-test\n */\nasync function test() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/test/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/test/src/cli.ts`;\n  const testCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", testCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Tests failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Check command - run all quality checks in sequence\n */\nasync function check() {\n  const checks = [\n    { name: \"Type checking\", fn: typecheck },\n    { name: \"Linting\", fn: lint },\n    { name: \"Testing\", fn: test },\n    { name: \"Building\", fn: build },\n    { name: \"Verification\", fn: verify, optional: true },\n    { name: \"Visualization\", fn: visualize, optional: true },\n  ];\n\n  for (const { name, fn, optional } of checks) {\n    try {\n      await fn();\n    } catch (_error) {\n      if (optional) {\n        continue;\n      }\n      console.log(`\\n\\x1b[31m✗ ${name} failed\\x1b[0m\\n`);\n      process.exit(1);\n    }\n  }\n}\n\n/**\n * Init command - delegate to @fairfox/polly-init\n */\nasync function init() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/init/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/init/src/cli.ts`;\n  const initCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", initCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Initialization failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Help command — prints usage from the docstring at the top of this file\n */\nfunction help() {\n  console.log(`Polly CLI — multi-execution-context framework\n\nUsage:\n  polly init [name] [--type=TYPE]  Create a new project\n  polly check                      Run all checks (typecheck, lint, test, build)\n  polly build [options]            Build the project\n  polly dev                        Build with watch mode\n  polly typecheck                  Type check your code\n  polly lint [--fix]               Lint your code\n  polly format                     Format your code\n  polly test [args]                Run tests\n  polly verify [args]              Run formal verification\n  polly visualize [args]           Generate architecture diagrams\n  polly quality [args]             Run quality conformance checks\n  polly help                       Show this help\n\nOptions:\n  --prod              Build for production (minified)\n  --config <path>     Path to config file (default: polly.config.ts)\n  --fix               Auto-fix lint/format issues\n  --type=TYPE         Project type for init command (pwa, extension, websocket, generic)`);\n}\n\n/**\n * Main entry point\n */\nasync function main() {\n  try {\n    switch (command) {\n      case \"init\":\n        await init();\n        break;\n      case \"check\":\n        await check();\n        break;\n      case \"build\":\n        await build();\n        break;\n      case \"dev\":\n        await dev();\n        break;\n      case \"typecheck\":\n        await typecheck();\n        break;\n      case \"lint\":\n        await lint();\n        break;\n      case \"format\":\n        await format();\n        break;\n      case \"test\":\n        await test();\n        break;\n      case \"verify\":\n        await verify();\n        break;\n      case \"visualize\":\n        await visualize();\n        break;\n      case \"quality\":\n        await quality();\n        break;\n      case \"help\":\n      case \"--help\":\n      case \"-h\":\n      case undefined:\n        help();\n        break;\n      default:\n        console.log(`❌ Unknown command: ${command}\\n`);\n        help();\n        process.exit(1);\n    }\n  } catch (error) {\n    console.log(\"\\n❌ Command failed:\", error);\n    process.exit(1);\n  }\n}\n\nmain();\n"
+    "#!/usr/bin/env bun\n/**\n * Polly CLI\n *\n * Command-line tool for building multi-execution-context applications\n * with reactive state and cross-context messaging.\n *\n * Supports: Chrome extensions, PWAs, Node/Bun/Deno apps with workers\n *\n * Usage:\n *   polly init [name] [--type=TYPE]  Create a new project\n *   polly check                      Run all checks (typecheck, lint, test, build)\n *   polly build [options]            Build the project\n *   polly dev                        Build with watch mode\n *   polly typecheck                  Type check your code\n *   polly lint [--fix]               Lint your code\n *   polly format                     Format your code\n *   polly test [args]                Run tests (requires bun test)\n *   polly test:browser [dir]         Run *.browser.{ts,tsx} in Puppeteer\n *   polly verify [args]              Run formal verification\n *   polly visualize [args]           Generate architecture diagrams\n *   polly quality [args]             Run quality conformance checks\n *   polly help                       Show help\n *\n * Project Types (init --type):\n *   extension           Chrome/Firefox extension (default)\n *   pwa                 Progressive Web App with workers\n *   websocket           WebSocket server application\n *   generic             Generic TypeScript project\n *\n * Options:\n *   --prod              Build for production (minified)\n *   --config <path>     Path to config file (default: polly.config.ts)\n *   --fix               Auto-fix lint/format issues\n *   --type=TYPE         Project type for init command\n */\n\n// Use Bun built-ins instead of Node.js APIs\nconst __dirname = import.meta.dir;\n\nconst command = process.argv[2];\nconst commandArgs = process.argv.slice(3);\nconst cwd = process.cwd();\n\n// Parse arguments\nconst args = {\n  prod: process.argv.includes(\"--prod\"),\n  config: process.argv.includes(\"--config\")\n    ? process.argv[process.argv.indexOf(\"--config\") + 1]\n    : undefined,\n};\n\n/**\n * Load user's configuration\n */\nasync function loadConfig() {\n  const configPaths = [\n    args.config,\n    `${cwd}/polly.config.ts`,\n    `${cwd}/polly.config.js`,\n    `${cwd}/polly.config.mjs`,\n  ].filter(Boolean) as string[];\n\n  for (const configPath of configPaths) {\n    // Use Bun.file().exists() instead of existsSync\n    if (await Bun.file(configPath).exists()) {\n      try {\n        const config = await import(configPath);\n        return config.default || config;\n      } catch (error) {\n        console.log(`❌ Failed to load config: ${configPath}`);\n        throw error;\n      }\n    }\n  }\n  return {\n    srcDir: \"src\",\n    distDir: \"dist\",\n    manifest: \"manifest.json\",\n  };\n}\n\n/**\n * Build command - build the extension\n */\nasync function build() {\n  const config = await loadConfig();\n\n  // Check if bundled (published) or in monorepo\n  const bundledScript = `${__dirname}/../scripts/build-extension.js`;\n  const monorepoScript = `${__dirname}/../scripts/build-extension.ts`;\n  const buildScriptPath = (await Bun.file(bundledScript).exists()) ? bundledScript : monorepoScript;\n\n  // Pass config via environment\n  process.env[\"WEB_EXT_SRC\"] = `${cwd}/${config.srcDir || \"src\"}`;\n  process.env[\"WEB_EXT_DIST\"] = `${cwd}/${config.distDir || \"dist\"}`;\n  process.env[\"WEB_EXT_MANIFEST\"] = `${cwd}/${config.manifest || \"manifest.json\"}`;\n  process.env[\"WEB_EXT_CWD\"] = cwd;\n  process.env[\"WEB_EXT_PROD\"] = args.prod ? \"true\" : \"false\";\n\n  // Run build\n  const proc = Bun.spawn([\"bun\", buildScriptPath], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    process.exit(exitCode);\n  }\n}\n\n/**\n * Dev command - build with watch mode\n */\nasync function dev() {\n  await build();\n}\n\n/**\n * Verify command - delegate to @fairfox/web-ext-verify\n */\nasync function verify() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/verify/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/verify/src/cli.ts`;\n  const verifyCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", verifyCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Verification failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Visualize command - delegate to @fairfox/polly-visualize\n */\nasync function visualize() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/visualize/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/visualize/src/cli.ts`;\n  const visualizeCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", visualizeCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Visualization failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Quality command - delegate to @fairfox/polly-quality\n */\nasync function quality() {\n  const bundledCli = `${__dirname}/../tools/quality/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/quality/src/cli.ts`;\n  const qualityCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", qualityCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Quality checks failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Typecheck command - run TypeScript type checking\n */\nasync function typecheck() {\n  const proc = Bun.spawn([\"bunx\", \"tsc\", \"--noEmit\"], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Type checking failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Lint command - run Biome linter\n */\nasync function lint() {\n  const fix = commandArgs.includes(\"--fix\");\n  const lintArgs = fix ? [\"check\", \"--write\", \".\"] : [\"check\", \".\"];\n\n  const proc = Bun.spawn([\"bunx\", \"@biomejs/biome\", ...lintArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Linting failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Format command - run Biome formatter\n */\nasync function format() {\n  const proc = Bun.spawn([\"bunx\", \"@biomejs/biome\", \"format\", \"--write\", \".\"], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Formatting failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Test command - delegate to @fairfox/polly-test\n */\nasync function test() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/test/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/test/src/cli.ts`;\n  const testCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", testCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Tests failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Browser test command — bundles *.browser.{ts,tsx} files, serves them,\n * opens a Puppeteer page, and collects results. Consumers use this to\n * run tests written with @fairfox/polly/test/browser in a real browser.\n */\nasync function testBrowser() {\n  const bundledCli = `${__dirname}/../tools/test/src/browser/run.js`;\n  const monorepoCli = `${__dirname}/../tools/test/src/browser/run.ts`;\n  const browserCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", browserCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n    env: process.env,\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Browser tests failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Check command - run all quality checks in sequence\n */\nasync function check() {\n  const checks = [\n    { name: \"Type checking\", fn: typecheck },\n    { name: \"Linting\", fn: lint },\n    { name: \"Testing\", fn: test },\n    { name: \"Building\", fn: build },\n    { name: \"Verification\", fn: verify, optional: true },\n    { name: \"Visualization\", fn: visualize, optional: true },\n  ];\n\n  for (const { name, fn, optional } of checks) {\n    try {\n      await fn();\n    } catch (_error) {\n      if (optional) {\n        continue;\n      }\n      console.log(`\\n\\x1b[31m✗ ${name} failed\\x1b[0m\\n`);\n      process.exit(1);\n    }\n  }\n}\n\n/**\n * Init command - delegate to @fairfox/polly-init\n */\nasync function init() {\n  // Check if bundled (published) or in monorepo\n  const bundledCli = `${__dirname}/../tools/init/src/cli.js`;\n  const monorepoCli = `${__dirname}/../tools/init/src/cli.ts`;\n  const initCli = (await Bun.file(bundledCli).exists()) ? bundledCli : monorepoCli;\n\n  const proc = Bun.spawn([\"bun\", initCli, ...commandArgs], {\n    cwd,\n    stdout: \"inherit\",\n    stderr: \"inherit\",\n    stdin: \"inherit\",\n  });\n\n  const exitCode = await proc.exited;\n  if (exitCode !== 0) {\n    throw new Error(`Initialization failed with exit code ${exitCode}`);\n  }\n}\n\n/**\n * Help command — prints usage from the docstring at the top of this file\n */\nfunction help() {\n  console.log(`Polly CLI — multi-execution-context framework\n\nUsage:\n  polly init [name] [--type=TYPE]  Create a new project\n  polly check                      Run all checks (typecheck, lint, test, build)\n  polly build [options]            Build the project\n  polly dev                        Build with watch mode\n  polly typecheck                  Type check your code\n  polly lint [--fix]               Lint your code\n  polly format                     Format your code\n  polly test [args]                Run tests\n  polly test:browser [dir]         Run *.browser.{ts,tsx} in Puppeteer\n  polly verify [args]              Run formal verification\n  polly visualize [args]           Generate architecture diagrams\n  polly quality [args]             Run quality conformance checks\n  polly help                       Show this help\n\nOptions:\n  --prod              Build for production (minified)\n  --config <path>     Path to config file (default: polly.config.ts)\n  --fix               Auto-fix lint/format issues\n  --type=TYPE         Project type for init command (pwa, extension, websocket, generic)`);\n}\n\n/**\n * Main entry point\n */\nasync function main() {\n  try {\n    switch (command) {\n      case \"init\":\n        await init();\n        break;\n      case \"check\":\n        await check();\n        break;\n      case \"build\":\n        await build();\n        break;\n      case \"dev\":\n        await dev();\n        break;\n      case \"typecheck\":\n        await typecheck();\n        break;\n      case \"lint\":\n        await lint();\n        break;\n      case \"format\":\n        await format();\n        break;\n      case \"test\":\n        await test();\n        break;\n      case \"test:browser\":\n        await testBrowser();\n        break;\n      case \"verify\":\n        await verify();\n        break;\n      case \"visualize\":\n        await visualize();\n        break;\n      case \"quality\":\n        await quality();\n        break;\n      case \"help\":\n      case \"--help\":\n      case \"-h\":\n      case undefined:\n        help();\n        break;\n      default:\n        console.log(`❌ Unknown command: ${command}\\n`);\n        help();\n        process.exit(1);\n    }\n  } catch (error) {\n    console.log(\"\\n❌ Command failed:\", error);\n    process.exit(1);\n  }\n}\n\nmain();\n"
   ],
-  "mappings": "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",
-  "debugId": "B9B6663515E3E39364756E2164756E21",
+  "mappings": "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",
+  "debugId": "962EF67B5CBBAF2264756E2164756E21",
   "names": []
 }

package/dist/src/actions/error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Global error surface for action handlers.
+ *
+ * Actions that fail set the errorState signal via `submitError`; a `<Toast>`
+ * component consumes that signal and renders a dismissable message. Handlers
+ * that catch expected failures (validation, quota) may call `setError` directly.
+ */
+export type ErrorSeverity = "error" | "warning" | "info";
+export type ErrorEntry = {
+    id: string;
+    message: string;
+    severity: ErrorSeverity;
+    action?: string;
+    createdAt: number;
+};
+export declare const errorState: import("@preact/signals-core").Signal<ErrorEntry[]>;
+export declare function setError(message: string, opts?: {
+    severity?: ErrorSeverity;
+    action?: string;
+}): string;
+export declare function clearError(id?: string): void;
+/**
+ * Convenience wrapper for an action's catch block.
+ * Logs the action name + error and surfaces a user-visible message.
+ */
+export declare function submitError(action: string, err: unknown): string;

package/dist/src/actions/event-delegation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Event delegation core.
+ *
+ * One document listener dispatches `data-action` events to typed handlers.
+ * Walks up the DOM with `closest('[data-action]')`, parses `data-action-*`
+ * attributes into a camelCase object, and hands the dispatch to the caller.
+ *
+ * Forms are skipped on click — a `<form data-action="...">` responds to
+ * submit only, so clicks on form children don't bubble into its action.
+ * Escape closes the topmost overlay by calling the overlay registry.
+ * Enter/Space on non-interactive elements with `data-action` fire the
+ * action (Space is prevented to stop page scroll). Click outside any
+ * `[data-overlay-id]` element also pops the top overlay.
+ */
+/** Elements that natively fire click on Enter/Space. */
+export declare const INTERACTIVE_TAGS: Set<string>;
+/** Event types that may trigger a data-action dispatch. */
+export declare const ACTION_EVENT_TYPES: Set<string>;
+/** Parsed action dispatch — what the runtime resolves before invoking a handler. */
+export type ActionDispatch = {
+    action: string;
+    element: HTMLElement;
+    event: Event;
+    data: Record<string, string>;
+};
+/**
+ * Parse `data-action-*` attributes into camelCase key-value pairs.
+ *
+ * `data-action-text-set-id="42"` becomes `{ textSetId: "42" }`.
+ */
+export declare function parseActionData(element: HTMLElement): Record<string, string>;
+/**
+ * Close the topmost overlay by dispatching `overlay:close` on its element.
+ * Overlays mark themselves with `data-overlay-id`.
+ */
+export declare function closeTopOverlay(): void;
+/**
+ * Resolve a DOM event to an ActionDispatch, or null if no data-action matches.
+ */
+export declare function resolveAction(event: Event): ActionDispatch | null;
+/**
+ * Install document-level listeners for the delegation system.
+ * Returns a cleanup function that removes every listener it installed.
+ */
+export declare function installEventDelegation(onDispatch: (dispatch: ActionDispatch) => void, options?: {
+    onEscape?: () => void;
+    onOutsideOverlayClick?: () => void;
+}): () => void;

package/dist/src/actions/form.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Form primitive.
+ *
+ * `createForm` returns a typed form store: per-field signals, an aggregated
+ * values signal, open/close/submit methods, and three auto-registered action
+ * handlers (`{name}:open`, `{name}:close`, `{name}:submit`) that callers spread
+ * into their global action registry.
+ *
+ * Lifecycle:
+ *   open  → resets fields to initialValues, applies onOpen overrides,
+ *           sets isOpen = true, records data-action-* data in openParams
+ *   typing → uncontrolled inputs keep their own state; controlled inputs
+ *           write fields.X.value directly
+ *   submit → reads FormData from the form element, merges into fields,
+ *           runs optional validate, calls user onSubmit with final values,
+ *           closes on success, sets errorState on failure
+ *   close  → resets and sets isOpen = false
+ *   guard  → autonomous effect; if guard() returns false while open, close()
+ */
+import { type ReadonlySignal, type Signal } from "@preact/signals";
+import type { ActionRegistry } from "./registry.ts";
+export type FormOpenContext<TStores> = {
+    data: Record<string, string>;
+    stores: TStores;
+};
+export type FormSubmitContext<TValues, TStores> = {
+    values: TValues;
+    stores: TStores;
+};
+export type FormConfig<TValues extends Record<string, string>, TStores> = {
+    /** Used as action namespace: `{name}:open`, `{name}:close`, `{name}:submit`. */
+    name: string;
+    initialValues: TValues;
+    onSubmit: (ctx: FormSubmitContext<TValues, TStores>) => void | Promise<void>;
+    /** Invoked on open; return partial overrides to pre-populate fields. */
+    onOpen?: (ctx: FormOpenContext<TStores>) => Partial<TValues> | undefined;
+    /** Returns false while open → form auto-closes (entity-deletion guard). */
+    guard?: (ctx: {
+        stores: TStores;
+    }) => boolean;
+    /** Synchronous validation. Returning keys blocks submit. */
+    validate?: (values: TValues) => Partial<Record<keyof TValues, string>> | null;
+};
+export type FormStore<TValues extends Record<string, string>, TStores> = {
+    readonly name: string;
+    readonly isOpen: ReadonlySignal<boolean>;
+    readonly values: ReadonlySignal<TValues>;
+    readonly fields: {
+        [K in keyof TValues]: Signal<TValues[K]>;
+    };
+    readonly errors: ReadonlySignal<Partial<Record<keyof TValues, string>>>;
+    readonly isSubmitting: ReadonlySignal<boolean>;
+    readonly openParams: ReadonlySignal<Record<string, string>>;
+    open(override?: Partial<TValues>, params?: Record<string, string>): void;
+    close(): void;
+    submit(event?: Event): Promise<void>;
+    /** Late-binds stores; required before guard/onOpen/onSubmit can access stores. */
+    bindStores(getStores: () => TStores): void;
+    /** Action handler entries. Spread into the user's ActionRegistry. */
+    actions: ActionRegistry<TStores>;
+};
+export declare function createForm<TValues extends Record<string, string>, TStores>(config: FormConfig<TValues, TStores>): FormStore<TValues, TStores>;
+/**
+ * Compose many forms into a single set: merged actions, closeAll, openForm signal.
+ */
+export type FormSet<TStores> = {
+    actions: ActionRegistry<TStores>;
+    openForm: ReadonlySignal<string | null>;
+    closeAll(): void;
+    bindStores(getStores: () => TStores): void;
+};
+export declare function createFormSet<TStores>(forms: readonly FormStore<Record<string, string>, TStores>[]): FormSet<TStores>;

package/dist/src/actions/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public API for `@fairfox/polly/actions`.
+ *
+ * The action registry pattern: one document listener, one typed registry,
+ * components are logic-free consumers of signals that emit `data-action`.
+ */
+export { clearError, type ErrorEntry, type ErrorSeverity, errorState, setError, submitError, } from "./error.ts";
+export { ACTION_EVENT_TYPES, type ActionDispatch, closeTopOverlay as closeTopOverlayViaDom, INTERACTIVE_TAGS, installEventDelegation, parseActionData, resolveAction, } from "./event-delegation.ts";
+export { createForm, createFormSet, type FormConfig, type FormOpenContext, type FormSet, type FormStore, type FormSubmitContext, } from "./form.ts";
+export { closeTopOverlay, hasOpenOverlay, type OverlayEntry, overlayStack, popOverlay, pushOverlay, resetOverlayStack, topOverlay, } from "./overlay.ts";
+export type { ActionContext, ActionHandler, ActionRegistry, } from "./registry.ts";
+export { createStore, StoreProvider, type StoreProviderProps, useStores } from "./store.tsx";
+export { createMockElement, createMockStores, createMockSubmitEvent, runAction, } from "./testing.ts";