@atelic-action/ui 0.15.1 → 0.16.1

package/README.md

@@ -1,6 +1,6 @@
 # @atelic-action/ui
 
-Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the not found page and the routing that keeps it alive, the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update`.
+Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the not found page and the routing that keeps it alive, the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update @atelic-action/ui --latest`.
 
 The package ships source, not a build. Its TSX and CSS arrive as written and compile inside each site's own Vite. The one exception is the access gate's server side, which ships compiled (see [The Access Gate](#the-access-gate)).
 
@@ -10,7 +10,9 @@ The package ships source, not a build. Its TSX and CSS arrive as written and com
 bun add @atelic-action/ui
 ```
 
-Peer dependencies: `react` and `react-dom` at `^19.0.0`, and `lucide-react` at `^1.23.0`.
+The package is below 1.0, where a caret range admits patches only, so a site takes a new minor with `bun update @atelic-action/ui --latest`: a plain `bun update` leaves it on the minor it has and reports nothing wrong.
+
+Peer dependencies: `react` and `react-dom` at `^19.0.0`, and `lucide-react` at `^1.23.0`. Three more are optional, needed only by a site whose `vite.config.ts` imports `@atelic-action/ui/vite`: `vite`, `@tanstack/react-start`, and `@vitejs/plugin-react`. The commands the package installs run under `bun`, with `node` for the sealing command.
 
 ## Vite Config
 
@@ -46,7 +48,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
 | `@atelic-action/ui/components` | `NotFound`, the access gate's `GateLogin` and `Watermark` (with `readCookie`), and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`, `Disclosure`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
 | `@atelic-action/ui/artifact` | `Writeup`, `Report`, `Gate`, `GradeChip`, `SignOff`, `ArtifactShell`, the `ArtifactConfig` types, `buildPageHead`, the reader helpers, `AppErrorBoundary`, `newTabProps`, and their prop types (see [The Artifact Documents](#the-artifact-documents)) |
-| `@atelic-action/ui/artifact/readers` | The reader helpers alone, built, for what Node runs as shipped: a site's browser tests and its reader script |
+| `@atelic-action/ui/artifact/readers` | The reader helpers alone, built, for what Node runs as shipped: a site's browser tests |
 | `@atelic-action/ui/primitives` | `Button`, `Chip`, `Eyebrow`, `Lead`, `SectionHeading`, and their prop types (see [Primitives](#primitives)) |
 | `@atelic-action/ui/email` | The email components, the theme provider, the plain text helpers, and their prop types (see [Email](#email)) |
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
@@ -55,7 +57,8 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/styles/primitives.css` | Styles for everything under `primitives`, the `.btn` classes included |
 | `@atelic-action/ui/styles/gate.css` | Styles for `GateLogin` and `Watermark` |
 | `@atelic-action/ui/styles/artifact.css` | Styles for everything under `artifact`: the writeup, the monthly page, the sealed document stage, the grade chip, and the sign off |
-| `@atelic-action/ui/vite` | `privateChunks`, the Vite plugin that keeps private content in `/assets/doc/`, with `isPrivateContent` and `DOC_DIR` |
+| `@atelic-action/ui/vite` | `artifactConfig`, the whole Vite configuration of an artifact site as one call, with `artifactPages`; and `privateChunks`, the Vite plugin that keeps private content in `/assets/doc/`, with `isPrivateContent` and `DOC_DIR` (see [The Artifact Vite Config](#the-artifact-vite-config)) |
+| The `bin` commands | Eight commands a site's `package.json` calls by name, from `atelic-check-access` to `atelic-seal-document` (see [The Commands](#the-commands)) |
 | `@atelic-action/ui/gate` | `signToken`, `verifyToken`, `safeNext`, `needsSession`, and the token types |
 | `@atelic-action/ui/gate/request-link` | `POST`, the handler that emails a sign in link, and `createRequestLink` |
 | `@atelic-action/ui/gate/verify` | `GET`, the handler that turns a link into a session |
@@ -196,7 +199,7 @@ What it holds to, each with a test in `tst/gate/`:
 
 What it does not do, by having no store: a link can be used more than once until it expires, and link requests are not rate limited. Rotating the secret ends every session at once. The `gate_email` and `gate_wm` cookies that feed the watermark are readable and unsigned on purpose: the watermark is drawn in the reader's own browser, so it deters and attributes nothing a reader set on removing it could not already remove.
 
-This is one of the two corners of the package that ship compiled (the other is the Vite plugin, under [The Artifact Documents](#the-artifact-documents)). Vercel runs a function's and a middleware's package imports as shipped and compiles nothing inside `node_modules`, so `bun run build` emits `src/gate/` to `dist/gate/`, and `prepack` runs it before every publish.
+This is one of the two corners of the package that ship compiled (the other is the Vite entry, under [The Artifact Vite Config](#the-artifact-vite-config)). Vercel runs a function's and a middleware's package imports as shipped and compiles nothing inside `node_modules`, so `bun run build` emits `src/gate/` to `dist/gate/`, and `prepack` runs it before every publish.
 
 ### The Screen and the Watermark
 
@@ -247,15 +250,62 @@ export function ArtifactShell(props: Omit<ArtifactShellProps, "currentPath">) {
 
 The documents import no stylesheet of their own. A site imports `@atelic-action/ui/styles/artifact.css` in its base sheet after `gate.css` and before its `theme.css`, so every page carries the rules whichever route it is. The sheet holds two `@page` rules, the monthly page's and then the writeup's, and the later one wins for every page a site prints; the order inside the sheet is the order the template's build bundled them in and is load bearing.
 
-`@atelic-action/ui/vite` is `privateChunks`, the Vite plugin that writes every chunk carrying private content to `/assets/doc/`, where the access wall holds it, and fails the build when one lands anywhere else. A `vite.config.ts` is run by Node as shipped, so the plugin is built to `dist/vite/` like the gate:
+### The Artifact Vite Config
+
+`@atelic-action/ui/vite` holds the whole Vite configuration of an artifact site, so a site's `vite.config.ts` is one call that names its pages:
 
 ```ts
 // vite.config.ts
-import { privateChunks } from "@atelic-action/ui/vite";
+import { artifactConfig } from "@atelic-action/ui/vite";
 
-export default defineConfig({ plugins: [tanstackStart(), react(), privateChunks()] });
+export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
 ```
 
+`artifactConfig` returns the TanStack Start plugin with prerendering on, the crawler following links but kept out of `/images/` (where a prerendered page would overwrite a real file), one prerendered page for `/`, for each path the site names, and for `/404`, and no sitemap; the React plugin; `privateChunks()`; the `@` alias to the site's `src`, resolved from the directory Vite is run in; and `ssr.noExternal: ["@atelic-action/ui"]`. Nothing links to an artifact page, so a page a site leaves out of `pages` ships with no HTML in it. `artifactPages` is the list alone.
+
+A site with a real need of its own passes `extend`, which is merged over the result with Vite's `mergeConfig`:
+
+```ts
+export default artifactConfig({
+	pages: ["/writeup"],
+	extend: { server: { port: 5180 } },
+});
+```
+
+`privateChunks` is the plugin inside it, exported for a site that writes its own configuration: it writes every chunk carrying private content to `/assets/doc/`, where the access wall holds it, and fails the build when one lands anywhere else.
+
+A `vite.config.ts` is run by Node as shipped, so `src/vite/` is built to `dist/vite/` like the gate. The entry imports `@tanstack/react-start` and `@vitejs/plugin-react` when it loads, so a site that imports anything from it has both installed; they are optional peers only because a site that never imports this entry needs neither.
+
+### The Commands
+
+The package installs the scripts every artifact site used to carry as files, so a site's `package.json` calls a command by name and holds no script of its own. Each reads the site it is run in from the working directory: `src/site.config.ts`, `public/`, and `dist/client` are the site's, found from where the command is run, which is the site's root.
+
+| Command | What It Does | Where a Site Calls It |
+|---|---|---|
+| `atelic-check-access` | Fails the build when `src/site.config.ts` says `access: "private"`, the build is on Vercel, and the wall's three variables are not set; warns on a local build of a private site | First step of `build` |
+| `atelic-stamp-health` | Writes `dist/client/health.json` with the status, the commit, and the build time | Last step of `build` |
+| `atelic-check-links` | Asks for every external link in the prerendered pages and exits 1 when one is dead | `check:links`, after a build |
+| `atelic-check-wall <host> [path ...]` | Asks a deployed host for each document and held file with no cookie, and passes only when the wall answers every one and the sign in functions respond | `check:wall`, before any private link goes out |
+| `atelic-reader-link <email> [path] [--token <token>] [--qr \| --no-qr]` | Mints a named reader: prints the sealed line for `analytics.identify` and the link to send, and writes `public/images/qr.png` for a public writeup's first reader | `reader` |
+| `atelic-serve-static` | Serves `dist/client` on `127.0.0.1` the way Vercel does, on `PORT` or 4173 | The `webServer` command in `playwright.config.ts` |
+| `atelic-print-sheets <url or dist/client> <out.pdf> [sheets] [page] [port]` | Prints a page to PDF with headless Chrome, reports the sheet count, and fails when a count is given and missed | `print` |
+| `atelic-seal-document <config.json> [out.json]` | Seals a document into the payload `Gate` reads, one wrapped key for each reader. The payload names no one: no address, and readers numbered `r1`, `r2` whatever the config calls them | `seal` |
+
+A site's scripts, whole:
+
+```json
+{
+	"build": "atelic-check-access && tsc -b && vite build && cp dist/client/404/index.html dist/client/404.html && atelic-stamp-health",
+	"check:links": "atelic-check-links",
+	"check:wall": "atelic-check-wall",
+	"reader": "atelic-reader-link",
+	"print": "atelic-print-sheets",
+	"seal": "atelic-seal-document"
+}
+```
+
+The logic lives in `src/scripts/` as modules with their functions exported, which is what the tests import, and each file in `bin/` only reads the command line and calls one. The TypeScript commands open on `#!/usr/bin/env bun` and run as source, since `bun` runs TypeScript inside `node_modules`. The sealing command is plain `.mjs` under `#!/usr/bin/env node`, and the print command is `bash`; it needs Chrome (the `CHROME` variable names another binary), `python3`, and `curl`.
+
 ## Email
 
 `@atelic-action/ui/email` is the runner email design as React components, ported one to one from the jq library the runners compose their mail from (homebase `runners/lib/email.jq`). The components are born inline: every layout is a table, every style is an inline style object, and there is no CSS file and no `className`, because Gmail strips a style block and ignores media queries on some accounts. The same components therefore mount on a web page as happily as they render into a mail client.

package/bin/atelic-check-access.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-check-access: fails a build when a private artifact has no wall.
+import { main } from "../src/scripts/check-access";
+
+await main();

package/bin/atelic-check-links.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-check-links: checks every external link in the built pages.
+import { main } from "../src/scripts/check-links";
+
+await main();

package/bin/atelic-check-wall.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-check-wall <host> [path ...]: probes a deployed host's access wall.
+import { main } from "../src/scripts/check-wall";
+
+await main(process.argv.slice(2));

package/bin/atelic-print-sheets.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Print an artifact page to PDF with headless Chrome and report its sheet
+# count. The writeup flows across as many letter pages as it needs, its
+# collapsibles printed open, so its count is a record of the print and not a
+# layout check. The monthly page is one sheet by construction, so pass 1 for
+# it and the script fails when it prints as anything else.
+#
+# Usage: atelic-print-sheets <url | dist/client> <out.pdf> [expected sheets] [page] [port]
+#   atelic-print-sheets dist/client public/writeup.pdf
+#   atelic-print-sheets dist/client ../2026-10-01-report.pdf 1 /report
+#   atelic-print-sheets https://summit.atelic.me/writeup ../2026-09-10-writeup.pdf
+# A site offers the same as `bun run print <...>`. Both paths are read from
+# the directory the command is run in, which is the site's root.
+#
+# A directory is served on a local port for the print (the page loads its
+# fonts and images by absolute path) and the server is stopped after; the
+# page is the path printed from it, /writeup unless named. A URL is printed
+# as given. The writeup's PDF belongs in public/ as writeup.pdf beside the
+# page (on a private artifact the wall holds it like the page, see
+# ACCESS-GATE.md), and a dated copy goes in the client folder of the
+# practice repo.
+set -euo pipefail
+
+TARGET=${1:?url or built directory required}
+OUT=${2:?output pdf path required}
+EXPECT=${3:-}
+PAGE=${4:-/writeup}
+PORT=${5:-8765}
+CHROME=${CHROME:-"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"}
+[[ -x "$CHROME" ]] || { echo "Chrome not found at $CHROME" >&2; exit 1; }
+# Chromium refuses to start as root with its sandbox on, and a cloud run is root.
+SANDBOX=()
+[[ $(id -u) -eq 0 ]] && SANDBOX=(--no-sandbox)
+
+URL="$TARGET"
+if [[ -d "$TARGET" ]]; then
+	PAGE="/${PAGE#/}"
+	PAGE="${PAGE%/}"
+	[[ -f "$TARGET$PAGE/index.html" ]] || { echo "no $PAGE/index.html in $TARGET (run bun build first)" >&2; exit 1; }
+	if curl -s -o /dev/null "http://127.0.0.1:$PORT/"; then
+		echo "port $PORT is already in use" >&2
+		exit 1
+	fi
+	python3 -m http.server "$PORT" --bind 127.0.0.1 --directory "$TARGET" >/dev/null 2>&1 &
+	SERVER=$!
+	trap 'kill $SERVER 2>/dev/null || true' EXIT
+	for _ in 1 2 3 4 5 6 7 8 9 10; do
+		curl -s -o /dev/null "http://127.0.0.1:$PORT/" && break
+		sleep 0.3
+	done
+	URL="http://127.0.0.1:$PORT$PAGE/"
+fi
+
+"$CHROME" --headless=new ${SANDBOX[@]+"${SANDBOX[@]}"} --disable-gpu --no-pdf-header-footer \
+	--virtual-time-budget=8000 --print-to-pdf="$OUT" "$URL" 2>/dev/null
+[[ -s "$OUT" ]] || { echo "Chrome wrote no PDF for $URL" >&2; exit 1; }
+
+PAGES=$(python3 - "$OUT" <<'PY'
+import re, sys
+data = open(sys.argv[1], "rb").read()
+m = re.findall(rb"/Type\s*/Pages\b[^>]*?/Count\s+(\d+)", data)
+print(max(int(x) for x in m) if m else 0)
+PY
+)
+echo "printed $OUT: $PAGES sheets, $(wc -c <"$OUT" | tr -d ' ') bytes"
+if [[ -n "$EXPECT" && "$PAGES" != "$EXPECT" ]]; then
+	echo "expected $EXPECT sheets; a sheet overflowed or one is missing" >&2
+	exit 1
+fi

package/bin/atelic-reader-link.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-reader-link <email> [path] [--token <token>] [--qr | --no-qr]: mints a reader link and its QR.
+import { main } from "../src/scripts/reader-link";
+
+await main(process.argv.slice(2));

package/bin/atelic-seal-document.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// atelic-seal-document <config.json> [out.json]: seals a document for its readers.
+import { argv } from "node:process";
+import { cli } from "../src/scripts/build-gate-payload.mjs";
+
+await cli(argv.slice(2));

package/bin/atelic-serve-static.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-serve-static: serves dist/client for the browser tests.
+import { main } from "../src/scripts/serve-static";
+
+main();

package/bin/atelic-stamp-health.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-stamp-health: writes dist/client/health.json after a build.
+import { main } from "../src/scripts/stamp-health";
+
+main();

package/dist/vite/artifact-config.d.ts

@@ -0,0 +1,24 @@
+import { type UserConfig } from "vite";
+export interface ArtifactConfigOptions {
+    /**
+     * The path of each artifact page the site carries, such as "/writeup".
+     * The root and the 404 page are always prerendered and need no entry.
+     */
+    pages: readonly string[];
+    /**
+     * The escape hatch for a site with a real need of its own: merged over
+     * the result with Vite's `mergeConfig`, so a site adds a setting without
+     * going back to a configuration written by hand.
+     */
+    extend?: UserConfig;
+}
+/** One entry of the prerender list. */
+export interface ArtifactPage {
+    path: string;
+    prerender: {
+        enabled: true;
+    };
+}
+/** The prerender list for a site: the root, each page it names, then the 404. */
+export declare function artifactPages(pages: readonly string[]): ArtifactPage[];
+export declare function artifactConfig({ pages, extend }: ArtifactConfigOptions): UserConfig;

package/dist/vite/artifact-config.js

@@ -0,0 +1,83 @@
+/**
+ * The whole Vite configuration of an artifact site, as one call. Every site
+ * cut from the artifact template carried its own copy of this configuration;
+ * here it is written once, and a site's vite.config.ts names its pages:
+ *
+ *   import { artifactConfig } from "@atelic-action/ui/vite";
+ *
+ *   export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
+ *
+ * The site's own paths (the `@` alias to its src) are found from the
+ * directory Vite is run in, which is the site's root.
+ */
+import { resolve } from "node:path";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import { mergeConfig } from "vite";
+import { privateChunks } from "./private-chunks.js";
+/** The prerender list for a site: the root, each page it names, then the 404. */
+export function artifactPages(pages) {
+    const named = pages.filter((path) => path !== "/" && path !== "/404");
+    return [
+        // The root holds no document: it sends the reader to /writeup
+        // (vercel.json does the same on the host), and its prerendered
+        // index.html is what a static preview serves at the bare host.
+        { path: "/", prerender: { enabled: true } },
+        ...named.map((path) => ({ path, prerender: { enabled: true } })),
+        // The 404 page, rendered by the catch all route and copied to
+        // dist/client/404.html by the build for the host to serve on any miss.
+        { path: "/404", prerender: { enabled: true } },
+    ];
+}
+export function artifactConfig({ pages, extend }) {
+    const config = {
+        // Every stylesheet rides in the one base sheet the root route links
+        // (src/styles/base.css), the documents' own included, since they come from
+        // @atelic-action/ui. Nothing imports CSS from a component, so there is no
+        // component bundle to fold: `build.cssCodeSplit: false`, which sat here to
+        // fold it, now fails the build, because TanStack Start looks for the
+        // `style.css` that setting emits and none is written. A site that gives a
+        // component its own stylesheet again restores the setting through `extend`.
+        plugins: [
+            tanstackStart({
+                prerender: {
+                    enabled: true,
+                    crawlLinks: true,
+                    // The writeup links each screenshot crop to its full image, and
+                    // the crawler follows every href it finds: without this filter it
+                    // prerenders /images/<shot>.png as an HTML page and writes that
+                    // over the real file in dist/client (found on a client's writeup,
+                    // 2026-09-24).
+                    filter: ({ path }) => !path.startsWith("/images/"),
+                },
+                // Nothing links to an artifact page, so the crawler would miss every
+                // one of them; each is listed by the site to be prerendered at all. A
+                // site names the pages it uses and no others.
+                pages: artifactPages(pages),
+                // No sitemap. A sitemap is a page asking to be crawled, and every
+                // page here is a document prepared for one business; public/robots.txt
+                // disallows the whole host to match.
+                sitemap: { enabled: false },
+            }),
+            react(),
+            // A document's content builds into /assets/doc/, which the access wall
+            // holds back, and the build fails if any lands where the login page
+            // can load it (privateChunks beside this file, needsSession in
+            // @atelic-action/ui/gate).
+            privateChunks(),
+        ],
+        resolve: {
+            alias: {
+                // The site's src, from the directory Vite is run in: this file lives
+                // in the package, so nothing here can be found relative to it.
+                "@": resolve(process.cwd(), "./src"),
+            },
+        },
+        // @atelic-action/ui ships TSX and CSS as written, so the prerender's server build
+        // has to compile it rather than hand it to Node as an external.
+        ssr: {
+            noExternal: ["@atelic-action/ui"],
+        },
+    };
+    return extend ? mergeConfig(config, extend) : config;
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What a site's vite.config.ts imports (`@atelic-action/ui/vite`): the
+ * configuration of an artifact site as one call, and the plugin inside it
+ * for a site that writes its own.
+ */
+export { type ArtifactConfigOptions, type ArtifactPage, artifactConfig, artifactPages, } from "./artifact-config.js";
+export { DOC_DIR, isPrivateContent, privateChunks } from "./private-chunks.js";

package/dist/vite/index.js

@@ -0,0 +1,7 @@
+/**
+ * What a site's vite.config.ts imports (`@atelic-action/ui/vite`): the
+ * configuration of an artifact site as one call, and the plugin inside it
+ * for a site that writes its own.
+ */
+export { artifactConfig, artifactPages, } from "./artifact-config.js";
+export { DOC_DIR, isPrivateContent, privateChunks } from "./private-chunks.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.15.1",
+	"version": "0.16.1",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -13,8 +13,19 @@
 	},
 	"files": [
 		"src",
-		"dist"
+		"dist",
+		"bin"
 	],
+	"bin": {
+		"atelic-check-access": "./bin/atelic-check-access.ts",
+		"atelic-check-links": "./bin/atelic-check-links.ts",
+		"atelic-check-wall": "./bin/atelic-check-wall.ts",
+		"atelic-print-sheets": "./bin/atelic-print-sheets.sh",
+		"atelic-reader-link": "./bin/atelic-reader-link.ts",
+		"atelic-seal-document": "./bin/atelic-seal-document.mjs",
+		"atelic-serve-static": "./bin/atelic-serve-static.ts",
+		"atelic-stamp-health": "./bin/atelic-stamp-health.ts"
+	},
 	"sideEffects": [
 		"**/*.css"
 	],
@@ -56,8 +67,8 @@
 			"default": "./dist/gate/verify.js"
 		},
 		"./vite": {
-			"types": "./dist/vite/private-chunks.d.ts",
-			"default": "./dist/vite/private-chunks.js"
+			"types": "./dist/vite/index.d.ts",
+			"default": "./dist/vite/index.js"
 		},
 		"./package.json": "./package.json"
 	},
@@ -73,24 +84,36 @@
 		"gallery:build": "vite build gallery"
 	},
 	"dependencies": {
-		"jose": "^6.2.12"
+		"jose": "^6.2.12",
+		"qrcode": "^1.5.4"
 	},
 	"peerDependencies": {
+		"@tanstack/react-start": "^1.168.0",
+		"@vitejs/plugin-react": "^5.0.0 || ^6.0.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"vite": "^7.0.0 || ^8.0.0"
 	},
 	"peerDependenciesMeta": {
+		"@tanstack/react-start": {
+			"optional": true
+		},
+		"@vitejs/plugin-react": {
+			"optional": true
+		},
 		"vite": {
 			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.13",
+		"@tanstack/react-start": "^1.168.60",
 		"@testing-library/jest-dom": "^6.6.2",
 		"@testing-library/react": "^16.0.1",
+		"@types/bun": "^1.4.2",
 		"@types/node": "^24.0.0",
+		"@types/qrcode": "^1.5.6",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
 		"@vitejs/plugin-react": "^6.1.1",

package/src/scripts/build-gate-payload.mjs

@@ -0,0 +1,177 @@
+/**
+ * Seals a document into the payload the `Gate` component reads.
+ *
+ * One content key encrypts the document once (AES-GCM). That key is then
+ * wrapped once per reader, under a key derived from that reader's own email
+ * address with PBKDF2. So every reader opens the same document with the one
+ * thing they always know, and the emitted payload carries no plaintext: not
+ * the document, and not even a hash the reader list could be checked
+ * against. Nor a reader's address: it is the secret their key derives from,
+ * so listing it beside their wrapped key would hand the document to anyone
+ * who reads the page's script. Payloads sealed before 2026-10-08 did list
+ * it; the gate now tells HubSpot who opened the document from the address
+ * the reader typed. The secret is still never anything beyond that address,
+ * which is the gate's deliberate, documented security tier. See GATE.md.
+ *
+ * Node's webcrypto is the same algorithm surface the browser exposes, so the
+ * two sides are byte compatible by construction rather than by agreement.
+ * The parameters below are the contract; changing one here without changing
+ * the matching constant in `Gate` (@atelic-action/ui/artifact) makes every
+ * existing payload unopenable.
+ *
+ * CLI (bin/atelic-seal-document.mjs runs this file's `main` under Node):
+ *   atelic-seal-document <config.json> [out.json]
+ *   bun run seal <config.json> [out.json]   (the form a site offers)
+ *
+ * Config shape (paths resolve relative to the config file):
+ *   { "content": "./proposal.html",
+ *     "people": [{ "id": "kyle", "email": "kyle@example.com" }] }
+ */
+import { webcrypto } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+
+/** PBKDF2 work factor. Mirrored by Gate; changing it breaks old payloads. */
+export const PBKDF2_ITERATIONS = 200000;
+export const PBKDF2_HASH = "SHA-256";
+/** Byte lengths: content key, GCM nonce, per person PBKDF2 salt. */
+export const KEY_BYTES = 32;
+export const IV_BYTES = 12;
+export const SALT_BYTES = 16;
+
+const encoder = new TextEncoder();
+
+/**
+ * The one normalization both sides share: an email is its letters and
+ * digits, uppercased. So "Dana@Example.com", "dana@example.com" and a stray
+ * space are all the same key, and a reader typing their own address cannot
+ * miss by punctuation or case. Mirrored in Gate; the two implementations
+ * must agree exactly.
+ */
+export function normalizeEmail(email) {
+	return String(email ?? "")
+		.toUpperCase()
+		.replace(/[^A-Z0-9]/g, "");
+}
+
+function toBase64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+
+function randomBytes(length) {
+	return webcrypto.getRandomValues(new Uint8Array(length));
+}
+
+/** Derive one reader's wrapping key from their email and their own salt. */
+async function deriveKey(email, salt) {
+	const material = await webcrypto.subtle.importKey(
+		"raw",
+		encoder.encode(normalizeEmail(email)),
+		"PBKDF2",
+		false,
+		["deriveKey"],
+	);
+	return webcrypto.subtle.deriveKey(
+		{ name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: PBKDF2_HASH },
+		material,
+		{ name: "AES-GCM", length: 256 },
+		false,
+		["encrypt", "decrypt"],
+	);
+}
+
+/**
+ * Encrypt `contentHtml` once and wrap the content key for each person.
+ * `people` is [{ id, email }]. The email is the reader's secret, the thing
+ * their key derives from, so it never reaches the payload; nor does the id,
+ * which is often a first name. A sealed reader is an ordinal (`r1`, `r2`)
+ * and their wrap, and nothing that says who they are.
+ */
+export async function sealDocument(contentHtml, people) {
+	if (typeof contentHtml !== "string" || contentHtml.length === 0) {
+		throw new Error("contentHtml is empty; nothing to seal");
+	}
+	if (!Array.isArray(people) || people.length === 0) {
+		throw new Error("no people; a payload nobody can open is not worth building");
+	}
+
+	const contentKeyBytes = randomBytes(KEY_BYTES);
+	const contentKey = await webcrypto.subtle.importKey(
+		"raw",
+		contentKeyBytes,
+		{ name: "AES-GCM" },
+		false,
+		["encrypt"],
+	);
+	const civ = randomBytes(IV_BYTES);
+	const ct = new Uint8Array(
+		await webcrypto.subtle.encrypt(
+			{ name: "AES-GCM", iv: civ },
+			contentKey,
+			encoder.encode(contentHtml),
+		),
+	);
+
+	const seen = new Set();
+	const sealed = [];
+	for (const person of people) {
+		const id = person?.id;
+		if (!id) throw new Error("every person needs an id");
+		if (seen.has(id)) throw new Error(`duplicate person id: ${id}`);
+		seen.add(id);
+		if (!person.email || !normalizeEmail(person.email)) {
+			throw new Error(`person ${id} has no email (or none that survives normalization)`);
+		}
+
+		const salt = randomBytes(SALT_BYTES);
+		const iv = randomBytes(IV_BYTES);
+		const key = await deriveKey(person.email, salt);
+		const wrapped = new Uint8Array(
+			await webcrypto.subtle.encrypt({ name: "AES-GCM", iv }, key, contentKeyBytes),
+		);
+		// The id a config gives a reader is often their first name, which
+		// beside the site's domain all but spells the address that is their
+		// key. So the payload carries a plain ordinal, and the config's id
+		// stays in the config, where it names a reader in an error message.
+		sealed.push({
+			id: `r${sealed.length + 1}`,
+			salt: toBase64(salt),
+			iv: toBase64(iv),
+			wrapped: toBase64(wrapped),
+		});
+	}
+
+	return { civ: toBase64(civ), ct: toBase64(ct), people: sealed };
+}
+
+/**
+ * The command: `args` is the command line after the command's own name.
+ * Both paths resolve against the working directory.
+ */
+export async function main(args = argv.slice(2)) {
+	const [configPath, outPath] = args;
+	if (!configPath) {
+		stderr.write("usage: atelic-seal-document <config.json> [out.json]\n");
+		exit(1);
+	}
+
+	const configFile = resolve(configPath);
+	const config = JSON.parse(readFileSync(configFile, "utf8"));
+	if (!config.content) throw new Error(`${configPath} has no "content" path`);
+
+	const contentHtml = readFileSync(resolve(dirname(configFile), config.content), "utf8");
+	const payload = await sealDocument(contentHtml, config.people);
+
+	const out = resolve(outPath ?? "gate-payload.json");
+	writeFileSync(out, `${JSON.stringify(payload, null, "\t")}\n`);
+	stdout.write(`[gate] ${out} (${payload.people.length} readers)\n`);
+}
+
+/** Runs `main` and turns a failure into the one line the command prints. */
+export function cli(args = argv.slice(2)) {
+	return main(args).catch((error) => {
+		stderr.write(`[gate] ${error.message}\n`);
+		exit(1);
+	});
+}