@atelic-action/ui 0.15.0 → 0.16.0

package/README.md

@@ -10,7 +10,7 @@ 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`.
+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 +46,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 +55,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 +197,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
 
@@ -226,7 +227,7 @@ The two pieces a reader sees are ordinary components, in `@atelic-action/ui/comp
 
 `@atelic-action/ui/artifact` is everything the artifact template shared across its cuts, so a fix reaches every business's documents with one version bump:
 
-- **The documents:** `Writeup`, `Report`, and `Gate` (the sealed document, with its `GatePayload` type), plus the `GradeChip` and `SignOff` the first two share, and every content type they take (`WriteupProps`, `ReportProps`, `GateProps`, and the rest).
+- **The documents:** `Writeup`, `Report`, and `Gate` (the sealed document, with its `GatePayload` type; a reader's address is the key, so a payload never lists it, and the component identifies a reader to HubSpot by the address they typed), plus the `GradeChip` and `SignOff` the first two share, and every content type they take (`WriteupProps`, `ReportProps`, `GateProps`, and the rest).
 - **The shell:** `ArtifactShell`, the `.mkt` scope with the skip link, the dark header, the credit band, and the watermark around a page.
 - **The contract and the head:** the `ArtifactConfig` types, and `buildPageHead` and `canonicalUrl` with their `PageMeta` type.
 - **Who opened it:** `mintToken`, `sealReader`, `openReader`, `readerId`, `readerLink`, and `whoIsReading`. The same six are also built and exported alone as `@atelic-action/ui/artifact/readers`, because a Playwright spec and a script run under Node, which compiles nothing inside `node_modules`.
@@ -247,15 +248,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 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
 
-export default defineConfig({ plugins: [tanstackStart(), react(), privateChunks()] });
+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.0",
+	"version": "0.16.0",
 	"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/artifact/Gate.tsx

@@ -19,10 +19,13 @@ export interface GatePerson {
 	/** Stable handle for the reader, used in the payload and in `onUnlock`. */
 	id: string;
 	/**
-	 * The reader's email address: the secret their key derives from, and,
-	 * when it matches `identifyDomain`, the identity pushed to HubSpot.
+	 * Never read, and a payload sealed today does not carry it. The reader's
+	 * address is the secret their key derives from, so a payload that lists
+	 * it hands the key to anyone who reads the page's script; payloads sealed
+	 * before 2026-10-08 did. The address a reader types is the one this
+	 * component uses.
 	 */
-	email: string;
+	email?: string;
 	/** Base64: this reader's PBKDF2 salt, GCM nonce, and wrapped content key. */
 	salt: string;
 	iv: string;
@@ -83,6 +86,8 @@ function fromBase64(value: string): Uint8Array {
 
 interface Opened {
 	person: GatePerson;
+	/** The address that opened the document, as the reader gave it. */
+	email: string;
 	html: string;
 }
 
@@ -137,7 +142,7 @@ async function openDocument(payload: GatePayload, rawEmail: string): Promise<Ope
 				contentKey,
 				fromBase64(payload.ct) as BufferSource,
 			);
-			return { person, html: new TextDecoder().decode(plain) };
+			return { person, email: rawEmail, html: new TextDecoder().decode(plain) };
 		} catch {
 			// Wrong email for this reader. Try the next one; say nothing.
 		}
@@ -145,11 +150,18 @@ async function openDocument(payload: GatePayload, rawEmail: string): Promise<Ope
 	return null;
 }
 
-function identifyReader(person: GatePerson, domain: string | undefined) {
-	if (!domain || !person.email) return;
-	if (!person.email.toLowerCase().endsWith(`@${domain.toLowerCase()}`)) return;
+/**
+ * Tells HubSpot who opened the document, from the address the reader gave:
+ * the payload names no one. The key forgives what the reader types (case,
+ * spaces, even a missing at sign), so the address is sent only when it reads
+ * as one, and only on the domain the site names.
+ */
+function identifyReader(rawEmail: string, domain: string | undefined) {
+	const email = rawEmail.trim().toLowerCase();
+	if (!domain || !/^[^\s@]+@[^\s@]+$/.test(email)) return;
+	if (!email.endsWith(`@${domain.toLowerCase()}`)) return;
 	window._hsq = window._hsq || [];
-	window._hsq.push(["identify", { email: person.email }]);
+	window._hsq.push(["identify", { email }]);
 	window._hsq.push(["setPath", window.location.pathname]);
 	window._hsq.push(["trackPageView"]);
 }
@@ -238,7 +250,7 @@ export function Gate({
 				if (cancelled) return;
 				if (opened) {
 					writeStored(storageKey, fromQuery);
-					identifyReader(opened.person, identifyDomain);
+					identifyReader(opened.email, identifyDomain);
 					setHtml(opened.html);
 					onUnlockRef.current?.(opened.person);
 					return;
@@ -252,7 +264,7 @@ export function Gate({
 			if (!stored) return;
 			const opened = await openDocument(payload, stored);
 			if (cancelled || !opened) return;
-			identifyReader(opened.person, identifyDomain);
+			identifyReader(opened.email, identifyDomain);
 			setHtml(opened.html);
 			onUnlockRef.current?.(opened.person);
 		}
@@ -275,7 +287,7 @@ export function Gate({
 			return;
 		}
 		writeStored(storageKey, value);
-		identifyReader(opened.person, identifyDomain);
+		identifyReader(opened.email, identifyDomain);
 		setHtml(opened.html);
 		onUnlockRef.current?.(opened.person);
 	}