@legionworks/facet 1.9.0

package/docs/reference/tsx.md

@@ -0,0 +1,101 @@
+# TSX reference
+
+## Publish
+
+```sh
+facet publish --artifact-id <id> --type tsx --file templates/tsx-status-report.tsx
+facet publish --artifact-id <id> --type tsx --execution interactive --file templates/tsx-interactive-counter.tsx
+```
+
+`static` is the default execution mode. `interactive` is declared with
+`--execution`; Facet does not infer it from hooks or handlers.
+
+## Static mode
+
+Static TSX compiles to HTML in Tier 0, then uses the existing HTML prediction
+and Tier 1 comparison pipeline. It can earn the same predict-and-compare claim
+as an HTML artifact.
+
+## Interactive mode
+
+Interactive TSX is client-rendered observation only. There is no SSR or
+hydration expectation. Tier 1 observes structure through CDP snapshot,
+`getDocument`, and an isolated-world channel, then repeats the observation
+after the bounded one-second stability window. Agreement is an observation that
+the artifact ran and held its structure; it is not a server-rendered prediction.
+
+Facet mounts the default export in both modes. Artifacts must export a component
+and must not call `createRoot` or self-mount.
+
+## Imports and styling
+
+The compiler accepts only vendored modules: `react`, `react-dom`,
+`react-dom/client`, `react/jsx-runtime`, and `react/jsx-dev-runtime`.
+Pinned versions are React and React DOM `19.2.8`, TypeScript `5.7.3`.
+
+TSX reuses the [HTML style vocabulary](html.md#vendored-styling-vocabulary):
+the shipped Tailwind/daisyUI classes, not JavaScript component kits. There is no
+promise of arbitrary npm, Base UI, forms, FormBridge, or animations.
+
+## Publish-time policy
+
+Tier 0 rejects direct `fetch`, `eval`, `new Function`, dynamic `import()`,
+`Worker`, `SharedWorker`, `require`, obvious denied-global aliases, and
+non-allowlisted imports. Capability errors use `tsx_capability_fetch`,
+`tsx_capability_eval`, `tsx_capability_function_constructor`,
+`tsx_capability_dynamic_import`, `tsx_capability_worker`,
+`tsx_capability_shared_worker`, `tsx_capability_computed_global`,
+`tsx_capability_require`, or `tsx_capability_global_alias`; imports report
+`tsx_import_denied`. This AST policy is early feedback, not the enforcement
+boundary: aliases and indirect JavaScript forms are deliberately not exhaustively
+modeled. The frame document's CSP and netns runtime controls make denied
+capabilities unreachable.
+
+## Execution boundary
+
+Interactive bundles mount directly in the artifact's own gallery frame: the
+compiled bundle imports as a `blob:` module in that frame document, with no
+nested iframe. The frame is served under an ordinary restrictive CSP (`self`,
+plus `blob:` for the compiled module import) — not the frozen Tier 1
+verification CSP, which remains a validation-only concern. The artifact code
+has no host port or service capability.
+
+## Storage and export
+
+Revision source remains immutable. Compilation creates derived bytes recorded at
+the run's `compiled_path`; TSX source export writes the original `.tsx` bytes.
+Render export remains the retained Tier 1 screenshot. Evidence retains the last
+10 non-retained runs per artifact.
+
+## Verdicts
+
+TSX verdicts carry `execution: "static" | "interactive"`. In interactive mode,
+`partial:unstable` means the first observation changed during the stability
+re-check. It loses to timeout, channel divergence, channel availability, and
+durable errors, but outranks single-snapshot structural claims.
+
+## Measurements and limits
+
+The supported Bun floor and CI pin is `1.4.0`; it includes the fd-reuse fix
+needed for reliable CDP-pipe operation. Measured determinism, compiler bytes,
+and nested-channel observations are in the separate [Bun 1.3.14](../verification/tsx-measurements.md#bun-1314)
+and [Bun 1.4.0](../verification/tsx-measurements.md#bun-140) tables. The
+evidence is runtime-scoped: do not treat hashes as invariant across Bun
+versions.
+
+Interactive TSX declares eligibility for animated WebP evidence without a
+probe. Static TSX, HTML, and SVG can become eligible when live CSS or Web
+Animations are detected. Eligibility does not assert visible motion.
+
+New retained screenshots are WebP and may contain multiple frames. Source
+export remains the original `.tsx` bytes, and the `execution` marker remains
+conditional on TSX responses.
+
+Interactive bundles explicitly select production React. They remain unminified
+so operators can audit emitted bundle bytes; the current measured bundle size,
+retention cost, and 2 MiB-cap headroom are derived in the evidence tables.
+
+## Starters
+
+- [Static status report](../../templates/tsx-status-report.tsx)
+- [Interactive counter](../../templates/tsx-interactive-counter.tsx)

package/docs/reference/validation.md

@@ -0,0 +1,212 @@
+# Validation reference
+
+The tiered validation contract every read-back response is bound to.
+Covers the `RenderStatus` taxonomy, what evidence each tier persists,
+the retention policy, and the revision-binding guarantee.
+
+## Tier taxonomy
+
+`RenderStatus` is the closed enum the verifier assigns to one run. The
+verdict is decided in exactly one place (`src/validation/tier1/verdict.ts`).
+Every other layer is bound to it through `VerdictSchema.status`.
+
+| status                       | meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ok`                         | Counts agree across protocol + shim + isolated worlds, layout observable, no discriminative errors.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `error`                      | Counts disagree with the lexical expectation OR the protocol surfaced a discriminative error.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `partial:layout_unverified`  | Counts agree but the layout pass is unverified (no SVG rendered with a non-degenerate viewBox). MUST carry a screenshot path on the wire.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `partial:opaque_content`     | An opaque DOM region was observed, so structural contents were not verified. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently.                                                                                                                                                                                                                                                                                                                                                                   |
+| `partial:external_resources` | The artifact references external HTTPS images the no-egress verifier could not observe. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently.                                                                                                                                                                                                                                                                                                                                                        |
+| `partial:unstable`           | TSX interactive mode: the structure observed at the render barrier differed from the structure observed after a bounded stability window. Deliberately NOT `tampered` — a legitimately animated or async-loading component also changes structure between observations, and branding that a forgery would manufacture the false-verdict class this project has spent three arcs eliminating. `tampered` stays reserved for channel divergence. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently. |
+| `tampered`                   | Page-shim or isolated-world observation diverges from protocol authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `timeout`                    | The harness did not emit `render-complete` within `TIER1_RENDER_BARRIER_MS`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `shim_only`                  | Isolated-world channel missing; only the untrusted page-shim produced usable counts.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `probe_only`                 | Both the page-shim and the isolated-world channel are missing; only the protocol channel is usable.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `insecure:unvalidated`       | Level 3 intentionally skipped validation. The artifact is not represented as validated.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+A `partial:*` verdict is a verdict the verifier could not finalize, NOT
+a degraded `ok`. The screenshot is mandatory FOR `partial:` so a human
+or a re-verifier can see what the verifier saw — it is not a thing
+that upgrades the verdict. When capture fails transiently, the typed
+`screenshotError` marker records that honest degraded path. A `partial:`
+without a screenshot or marker is rejected at the schema parse boundary.
+
+### `partial:unstable` precedence slot
+
+`partial:unstable` splits the error paths in two, because `error` is not a
+single tier. The discriminating question is whether a status rests on ONE
+observation or on something a structure change cannot invalidate. The full
+ordering, top to bottom:
+
+1. `timeout` — lifecycle failed at the render barrier (`renderComplete === false`).
+2. `tampered` — channel divergence; the page contradicts protocol authority.
+3. `probe_only` / `shim_only` — channel availability (meta-claim about the channels, not the page).
+4. `error` — discriminative errors are non-empty, or observed counts disagree with the lexical expectation. Both survive a structure change: a parse error is a parse error whenever it was observed, and a count that never matched the source's expectation never matches.
+5. **`partial:unstable`** — TSX interactive mode; structure changed between the render barrier and the stability window.
+6. `error` (declared-opaque, observed-zero) — the artifact declared opaque regions and none were seen. This sits BELOW `partial:unstable` deliberately: it compares the expectation against a SINGLE observation, so a structure change makes it unsafe to assert. A canvas that painted after the barrier would otherwise be reported as an artifact that never painted at all — a false accusation, which is the failure class the whole partial taxonomy exists to avoid.
+7. `partial:opaque_content` — single-snapshot claim: structure has opaque regions.
+8. `partial:external_resources` — single-snapshot claim: structure has external HTTP references.
+9. `partial:layout_unverified` — single-snapshot claim: visible SVG with zeroed viewBoxes.
+10. `ok`.
+
+The rule generalizing rows 4 and 6: a claim that depends on ONE observation
+loses to `partial:unstable`; a claim that holds regardless of when it was
+observed outranks it.
+
+The reasoning: when structure is changing between two observation snapshots, the verifier cannot honestly claim "this artifact has structure X" — every single-snapshot claim (opaque, external, layout) is moot. `partial:unstable` is a meta-claim about the page's runtime behavior that dominates the single-snapshot structural claims. `tampered` stays above it because channel divergence (the page contradicting protocol authority) is the more catastrophic reading of the page's behavior. The decision is pinned by `tests/unit/verdict.test.ts` (unstable outranks opaque, external, layout-unverified; unstable loses to tampered, timeout, and channel-availability).
+
+## Evidence captured per tier
+
+| tier | evidence retained                                                                                                                                                                                                                                                                                                     |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | DB row only (expected + observed JSON, status, timing). No on-disk evidence.                                                                                                                                                                                                                                          |
+| 1    | DB row + per-run directory under `<evidence>/tier1/<revisionSha>/<runId>/`: `screenshot.webp` for new captures, legacy `screenshot.png` when retained, `console.txt`, and `protocol-observation.json`. Captures cover the whole artifact within the 4096-pixel axis, 8,388,608-pixel total, and 8 MiB encoded limits. |
+
+The evidence root is the XDG state path `paths.evidence` (or the
+`FACET_HOME/evidence` override). Every directory the runner creates is
+mode 0700 — the canonical secret-bearing layout matches the DB file
+permissions.
+
+Tier 1 capture happens AFTER the verdict is derived so the
+`partial:layout_unverified`, `partial:opaque_content`, `partial:external_resources`, and `partial:unstable` screenshot mandates are honored. The runner
+measures the whole artifact, bounds each axis at 4096 pixels and the total at
+8,388,608 pixels, and encodes evidence under the 8 MiB cap. New captures are
+WebP; legacy PNG evidence remains readable and exportable. Before static
+capture it emulates `prefers-reduced-motion: reduce` and awaits
+`document.fonts.ready`; these pre-flights keep repeated captures byte-identical.
+
+Interactive TSX declares animated-capture eligibility; it does not imply that
+the component is always visibly changing. CSS/Web Animations are probed, and
+eligible captures may contain multiple WebP frames. Static artifacts retain a
+single frame. Whole-artifact capture is downscaled to fit the axis,
+decoded-pixel, and encoded-size bounds; it is never clipped. If the complete
+image cannot fit the encoded cap, the verdict remains honest with
+`screenshotError.code = screenshot_unavailable` rather than claiming a partial
+capture.
+
+Levels 0–2 record Tier 0 on publish. A Tier 1 run is explicit: visual
+read-back records it on demand, then reuses the revision-bound result. A
+browser or network-namespace failure records a Tier 1 `error` verdict with its
+typed `tier1_*` code; it does not erase the Tier 0 verdict or turn visual
+read-back into `revision_not_found`.
+
+## Observed fields and renderer expectations
+
+The canonical observed fields include `rendererRootSvgCount`, `graphCount`,
+`mermaidNodeCount`, `visibleSvgCount`, `opaqueRegionCount`, `viewBoxes`,
+`errorCount`, and `discriminativeErrors`. `opaqueRegionCount` counts DOM
+regions whose contents are not structurally observable.
+
+Renderer literals are `svg` and `canvas`. The `canvas` renderer is chart-only:
+a canvas chart expects `rendererRootSvgCount = 0` and `opaqueRegionCount = 1`;
+SVG renderers retain their structural root expectations.
+
+HTML artifacts carry their own structural observable — `HtmlStructureCounts` —
+anchored on the frame-owned `data-facet-renderer-root` wrapper. The fields
+are `rendererRootCount`, `headingCount`, `tableCount`, `listCount`,
+`imageCount`, `canvasCount`, and `externalImageCount`. The first is the
+HTML analogue of `rendererRootSvgCount`; the rest are scoped beneath the
+marker. See the [HTML reference](html.md) for the verdict claim these
+counts support and the precedence over `partial:opaque_content` and
+`partial:external_resources`.
+
+## Tier 0 vs Tier 1 channels for HTML
+
+Tier 0 is a WHATWG parser (`parse5@8.0.1`, `scriptingEnabled: false`)
+running in the existing netns worker with no egress. It produces the
+structural prediction that is stored with the revision SHA and forwarded
+to Tier 1. The parser handles every recovery family that the differential
+corpus accepts; three families — UTF-8 encoding ambiguity, `<select>`
+containing table-scoped markup, and nesting depth beyond the cap — are
+rejected before Tier 1 ever runs.
+
+Tier 1 is `chrome-headless-shell` `151.0.7922.77` inside its netns,
+rendering the artifact through the gallery's vendored HTML renderer. It
+observes the rendered DOM through CDP protocol authority, not the page
+shim, and computes its own `HtmlStructureCounts` from the snapshot.
+Agreement on every field is `ok`; disagreement is `tampered`.
+
+The two channels are independent: one parses bytes with no egress, the
+other renders in a browser. Their expected-vs-observed comparison is
+what makes an HTML verdict a real prediction rather than a self-claim.
+
+An HTML Tier 0 response is a normal publish/read-back verdict, for example:
+
+```json
+{
+  "status": "ok",
+  "tier": 0,
+  "artifactId": "art-123",
+  "revisionSha": "<sha256>",
+  "observed": { "htmlElementCount": 4, "htmlTextNodeCount": 2 }
+}
+```
+
+The differential corpus at `tests/acceptance/html-differential.test.ts`
+is the live gate that keeps the two parsers in agreement over a body
+of real documents. Any divergence in the corpus is a design input
+(shrink the accepted input set), never a verdict-comparison weakening.
+
+## TSX modes
+
+Tier 0 compiles TSX after direct AST-policy checks. Static output enters the
+HTML pipeline above. Interactive output runs in the nested artifact frame and
+is observed through CDP snapshot, `getDocument`, and isolated-world channels at
+the render barrier and after the one-second stability window. There is no SSR or
+hydration expectation. `partial:unstable` records a changed structure; channel
+divergence remains `tampered`.
+
+Theme switching affects gallery Tier 2 display only. Tier 1 structural
+verdicts and captures remain dark-theme parity behavior so counts and layout
+comparisons are stable across display preferences.
+
+## Retention policy
+
+Last-N retention runs INSIDE `recordRenderRun`'s write path. The
+canonical knob is `EVIDENCE_LAST_N_PER_ARTIFACT` (default 10); the
+policy keeps the N most recent non-retained runs per artifact and
+unlinks the on-disk evidence of everything older.
+
+Retained-evidence carve-out: a row marked `retained: true` is exempt
+from the cutoff. Pin and template call sites set the flag (Task 14
+wires them); the cleanup walker skips `retained = 1` rows.
+
+Cleanup is best-effort: a row is the authoritative state, a stale
+file is recoverable by the next orphan sweep. A failed `INSERT` runs
+the converse cleanup — any caller-supplied `screenshotPath` /
+`consolePath` is unlinked so no orphan pixels accumulate.
+
+Retention controls evidence files, not read-back payload history. Read-back
+reconstructs a revision-bound verdict from its stored render-run row; an
+evicted screenshot or console path is intentionally not returned as bytes.
+
+## Revision-binding guarantee
+
+Every `read-back` response is bound to the EXACT `(artifactId,
+revisionSha)` the caller supplied. The lookup
+(`repository.getRevisionBySha`) is keyed on both columns; a stale or
+mismatched sha returns `revision_not_found` BEFORE any verdict row is
+read, so two revisions to the same artifact can never cross-pollinate
+their verdicts.
+
+The dispatcher enriches every Tier 1 verdict with the real
+`artifactId` + `revisionSha` it is committing (the worker runs out of
+process and does not know the artifactId). Read-back returns the
+enriched verdict — never the worker's placeholder identity.
+
+## Layering
+
+Insecure execution conditions are metadata: every insecure-level verdict carries a `Verdict.insecure` marker with the effective level and reason, but verdict derivation never consumes that marker.
+Level 3 additionally produces the `insecure:unvalidated` status.
+
+```
+shared/contracts/validation.ts   VerdictSchema, RenderStatus, and Tier 1 refinements
+shared/contracts/artifact.ts     RenderRunSchema and screenshot error metadata
+service/store/schema.ts          additive v2–v9 schema fragments
+service/store/migrations.ts      transactional migration application
+service/store/evidence-retention.ts
+                                  last-N cleanup and 0700 directory enforcement
+service/store/repository.ts      render-run persistence and cleanup-on-failure
+service/dispatcher.ts            revision binding and screenshot-path handoff
+validation/tier1/runner.ts       post-verdict capture and evidence paths
+```

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@legionworks/facet",
+  "version": "1.9.0",
+  "private": false,
+  "keywords": [
+    "artifacts",
+    "bun",
+    "facet",
+    "gallery",
+    "rendering",
+    "validation"
+  ],
+  "homepage": "https://github.com/legion-works/facet#readme",
+  "bugs": {
+    "url": "https://github.com/legion-works/facet/issues"
+  },
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/legion-works/facet.git"
+  },
+  "bin": {
+    "facet": "./src/cli/main.ts",
+    "facet-mcp": "./src/harness-adapters/mcp/main.ts"
+  },
+  "files": [
+    "src/**",
+    "scripts/launch-netns.sh",
+    "scripts/build-gallery.ts",
+    "templates/**",
+    "dist/gallery/**",
+    "skills/**",
+    "README.md",
+    "LICENSE-*",
+    "docs/reference/**"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build-gallery.ts",
+    "prepack": "bun scripts/build-gallery.ts --if-stale",
+    "lint": "oxlint --deny-warnings",
+    "format": "oxfmt",
+    "format:check": "bun scripts/check-format.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.runtime-egress-fixture.json",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov",
+    "coverage:check": "bun scripts/check-coverage.ts",
+    "check:boundaries": "bun scripts/check-boundaries.ts",
+    "verify:package-install": "bun scripts/verify-package-install.ts",
+    "perf-gate": "bun scripts/perf-gate.ts",
+    "perf-gate:quick": "bun scripts/perf-gate.ts --quick",
+    "verify-adapter-size": "bun scripts/verify-adapter-size.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "fast-xml-parser": "5.10.1",
+    "linkedom": "0.18.13",
+    "marked": "18.0.9",
+    "mermaid": "11.16.1",
+    "parse5": "8.0.1",
+    "puppeteer-core": "25.5.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "sharp": "^0.35.3",
+    "typescript": "5.7.3",
+    "vega": "6.3.1",
+    "vega-interpreter": "^2.3.1",
+    "vega-lite": "6.4.3",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.3.3",
+    "@types/bun": "1.4.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "daisyui": "5.7.16",
+    "lefthook": "1.11.13",
+    "oxfmt": "0.54.0",
+    "oxlint": "1.73.0",
+    "tailwindcss": "4.3.3"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "packageManager": "bun@1.4.0"
+}

package/scripts/build-gallery.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/**
+ * Build the gallery shell + type-specific frame bundles into static assets
+ * the service can serve.
+ *
+ *   1. `dist/gallery/app.js` — the shell controller. Loaded as a
+ *      `<script type="module">` in `index.html`.
+ *   2. `dist/gallery/frame/runtime/<type>.js` — one trusted frame bundle
+ *      per artifact type. The frame URL selects the bundle before any
+ *      artifact bytes reach the renderer.
+ *
+ * The build target is `browser` and minify is OFF — we want the
+ * emitted bundle to be human-readable so an audit can verify no
+ * artifact bytes leak into it. The `dist/` directory is gitignored.
+ */
+
+import { copyFileSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { frameBundlePlugins } from "../src/shared/build/frame-bundle-plugins";
+import { ARTIFACT_TYPES } from "../src/shared/contracts/artifact-types";
+import { resolveGalleryRoot } from "../src/shared/config/paths";
+
+const REPO_ROOT = import.meta.dir.replace(/\/scripts$/, "");
+const FRAME_ENTRY_DIR = join(REPO_ROOT, "src", "gallery-web", "frame", "entries");
+const FRAME_STYLE_DIR = join(REPO_ROOT, "src", "gallery-web", "frame", "styles");
+const GALLERY_INPUTS = [
+  join(REPO_ROOT, "scripts", "build-gallery.ts"),
+  join(REPO_ROOT, "src", "gallery-web"),
+  join(REPO_ROOT, "src", "shared", "build", "frame-bundle-plugins.ts"),
+  join(REPO_ROOT, "src", "shared", "contracts", "artifact-types.ts"),
+];
+
+function latestMtime(path: string): number {
+  const stats = statSync(path);
+  if (!stats.isDirectory()) return stats.mtimeMs;
+  return Math.max(
+    stats.mtimeMs,
+    ...readdirSync(path).map((entry) => latestMtime(join(path, entry))),
+  );
+}
+
+function galleryNeedsBuild(outDir: string): boolean {
+  const outputPath = join(outDir, "index.html");
+  try {
+    return GALLERY_INPUTS.some((input) => latestMtime(input) > statSync(outputPath).mtimeMs);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * All frame entries build in ONE `Bun.build` call, not one call per
+ * artifact type. Splitting still applies (plain markdown must not pay
+ * Mermaid's multi-megabyte load + parse cost when it has no fence),
+ * but a shared dependency — Mermaid, reached from BOTH the `mermaid`
+ * and `markdown` entries — now gets ONE tree-shaking pass and ONE set
+ * of lazy diagram-type chunks instead of two independently rebuilt,
+ * NOT-byte-identical copies. Two separate `Bun.build` invocations per
+ * entry produced two divergent tree-shakes of Mermaid's lazy-loaded
+ * flowchart renderer; the copy reached through `markdown`'s dynamic
+ * `import("./mermaid")` silently dropped every flowchart label while
+ * the copy reached through `mermaid`'s own top-level entry did not
+ * (`nodes 6 · errors 0 · ok` either way — no gate saw it). One shared
+ * build graph means one shared chunk, so there is nothing left to
+ * diverge.
+ */
+async function buildFrameEntries(entries: string[], outDir: string): Promise<void> {
+  const result = await Bun.build({
+    entrypoints: entries,
+    outdir: outDir,
+    target: "browser",
+    minify: false,
+    splitting: true,
+    naming: {
+      entry: "frame/runtime/[name].[ext]",
+      chunk: "frame/chunks/[name]-[hash].[ext]",
+      asset: "frame/assets/[name].[ext]",
+    },
+    plugins: frameBundlePlugins(),
+  });
+  if (!result.success) {
+    const messages = result.logs.map((log) => log.message).join("\n");
+    throw new Error(`Frame entry build failed:\n${messages}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const outDir = resolveGalleryRoot(REPO_ROOT);
+  if (process.argv.includes("--if-stale") && !galleryNeedsBuild(outDir)) {
+    process.stderr.write(`${JSON.stringify({ event: "gallery.current", outdir: outDir })}\n`);
+    return;
+  }
+  mkdirSync(outDir, { recursive: true });
+  rmSync(join(outDir, "frame", "bootstrap.js"), { force: true });
+  rmSync(join(outDir, "frame", "bootstrap"), { recursive: true, force: true });
+  rmSync(join(outDir, "frame", "runtime"), { recursive: true, force: true });
+  rmSync(join(outDir, "frame", "chunks"), { recursive: true, force: true });
+  rmSync(join(outDir, "frame", "assets"), { recursive: true, force: true });
+  rmSync(join(outDir, "frame", "frame.css"), { force: true });
+  rmSync(join(outDir, "frame", "artifact.css"), { force: true });
+  await buildFrameEntries(
+    ARTIFACT_TYPES.map((artifactType) => join(FRAME_ENTRY_DIR, `${artifactType}.ts`)),
+    outDir,
+  );
+  mkdirSync(join(outDir, "frame"), { recursive: true });
+  copyFileSync(join(FRAME_STYLE_DIR, "frame.css"), join(outDir, "frame", "frame.css"));
+  copyFileSync(join(FRAME_STYLE_DIR, "artifact.css"), join(outDir, "frame", "artifact.css"));
+  // The shell controller is bundled from index.html so the CSS imports
+  // + app.ts are wired into a single bundle the service serves.
+  const shellResult = await Bun.build({
+    entrypoints: [join(REPO_ROOT, "src", "gallery-web", "index.html")],
+    outdir: outDir,
+    target: "browser",
+    minify: false,
+    naming: "[dir]/[name].[ext]",
+  });
+  if (!shellResult.success) {
+    const messages = shellResult.logs.map((log) => log.message).join("\n");
+    throw new Error(`Shell build failed:\n${messages}`);
+  }
+  process.stderr.write(`${JSON.stringify({ event: "gallery.built", outdir: outDir })}\n`);
+}
+
+if (import.meta.main) {
+  await main();
+}

package/scripts/launch-netns.sh

@@ -0,0 +1,67 @@
+#!/bin/sh
+#
+# Tier 1 production netns launcher.
+#
+# Wraps the PINNED `chrome-headless-shell` (ADR 0001 D3) inside a
+# rootless network namespace so every egress channel (HTTP, WS,
+# EventSource, sendBeacon, anchor ping, DNS, WebRTC STUN, raw IP,
+# future IP APIs) has no reachable interface or route.
+#
+# The boundary is the `unshare --map-current-user --net` namespace,
+# not any flag passed to the shell. The egress penetration harness
+# (scripts/egress-penetration.ts) is the regression test for this
+# boundary; the spike at .facet-build/phase-0-spikes/egress/
+# demonstrated that 12 of 12 attempted channels block under this
+# wrapper on the same chromium-build family.
+#
+# Sandbox-flag trade (pinned chrome-headless-shell 151.0.7922.77):
+#
+#   We DELIBERATELY keep Chromium's browser sandbox (`--no-sandbox` is
+#   NOT added). The fidelity spike ran with `--no-sandbox` because it
+#   was an isolated disposable experiment. The production tier keeps
+#   the sandbox because:
+#
+#     1. `unshare --map-current-user` keeps the user uid (no root
+#        transition), so Chromium does not require `--no-sandbox` to
+#        start under the new userns.
+#     2. A compromised renderer reaching the netns (no interfaces)
+#        still benefits from the Chromium sandbox's syscall filter.
+#
+#   If a future shell release regresses this, the wrapper surfaces a
+#   typed `tier1_launcher_missing` / `tier1_unavailable` and the
+#   runner falls back to erroring — NEVER to running un-sandboxed.
+#
+# Usage: this script is invoked by puppeteer-core with `pipe: true`;
+# it must `exec` so the unshare PID is reused (otherwise signals
+# targeting the shell PID bypass the namespace).
+
+set -eu
+
+if [ -z "${FACET_TIER1_BROWSER_CACHE:-}" ]; then
+  FACET_TIER1_BROWSER_CACHE="${HOME}/.cache/puppeteer/chrome-headless-shell"
+fi
+
+if [ -z "${FACET_TIER1_PINNED_VERSION:-}" ]; then
+  FACET_TIER1_PINNED_VERSION="151.0.7922.77"
+fi
+
+# Resolve the pinned shell binary inside the cache. The wrapper does
+# not hard-code the layout because the cache directory can be relocated
+# via env var (CI runners, vendored copies).
+candidate_a="${FACET_TIER1_BROWSER_CACHE}/${FACET_TIER1_PINNED_VERSION}/chrome-headless-shell-linux64/chrome-headless-shell"
+candidate_b="${FACET_TIER1_BROWSER_CACHE}/linux-${FACET_TIER1_PINNED_VERSION}/chrome-headless-shell-linux64/chrome-headless-shell"
+
+if [ -x "${candidate_a}" ]; then
+  SHELL_BIN="${candidate_a}"
+elif [ -x "${candidate_b}" ]; then
+  SHELL_BIN="${candidate_b}"
+else
+  echo "tier1 launcher: pinned chrome-headless-shell ${FACET_TIER1_PINNED_VERSION} not found in ${FACET_TIER1_BROWSER_CACHE}" >&2
+  exit 127
+fi
+
+# Hand off to unshare. The `--` terminates unshare's option parsing so
+# a flag-shaped argv from puppeteer-core cannot be mistaken for a
+# wrapper flag. `exec` replaces the shell process so the unshare PID
+# is the chrome PID (signals reach the namespace directly).
+exec unshare --map-current-user --net -- "${SHELL_BIN}" "$@"