@atelic-action/artifact 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @atelic-action/artifact
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The documents the practice hands or sends a business, as a published package and as the site a business's folder is cut from. This repo is two things at once:
+
+- **The package**, `@atelic-action/artifact` on npm: the composed documents (the writeup, the read, the monthly page, the note, and the sealed document), each with its prop types and its default labels, and the stylesheet they wear. It ships `src/documents/` and nothing else, as source, the way `@atelic-action/ui` does, and depends on that package for every piece a document is built from.
+- **The seed**: the routes, the content stubs, the config, the stub files the host finds by path, and the tests a new folder of `atelic-action/writeups` is cut from, and the template site that shows every document on fictional content.
+
+Three layers, each a version the next depends on (ATE-671): `@atelic-action/ui` holds the pieces, this package holds the documents built from them, and each business's folder holds only its content, routes, and config. A document fix reaches a folder by bumping this package; a piece fix by bumping ui here, then this package in the folder.
+
+Five artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause with the plan in order; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
+
+The method behind them (the seven sections, the four grades from A to D, the rented line, what moved, and when an artifact is private) is the practice repo's `FOOTPRINT.md`. This repo builds to it and never restates it.
+
+The example inside is **Summit Movement Studio**, a fictional physical therapy practice with invented numbers that exercise the components. Replace it; never ship it.
+
+This repo was cut from [template-marketing](https://github.com/atelic-action/template-marketing) on 2026-09-09 with its history kept, so it shares the stack below. The two split apart on 2026-09-10: each template now owns its own files and nothing merges between them. It was named `template-artifact` until 2026-10-15, when it became the package's home as well; GitHub redirects the old name.
+
+## Component Index
+
+Every export of the package, all from the one entry, `@atelic-action/artifact`. The route column is the template page that shows it on fictional content.
+
+| Export | What it is | Route |
+|---|---|---|
+| `Writeup`, `WriteupProps` | The graded document an owner gets: the overview, the three tiers of section cards, the close | `/writeup` |
+| `ratingCell` | A star rating table cell for a writeup table, sorted by its figure | `/writeup` |
+| `WriteupBlock`, `WriteupTopic`, `WriteupPart`, `WriteupSheet`, `WriteupSummary`, `WriteupSummaryRow`, `WriteupMarkets`, `WriteupRented`, `WriteupMark`, `WriteupCell`, `WriteupTone`, and the rest of the `Writeup*` types | The shapes a writeup's content is written in | none |
+| `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document (the first two are re exported from ui) | none |
+| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table; each section read top to bottom as where we looked (the tools, linked, at the top), what it showed (a short paragraph or two, a compact table of facts, lists of examples under their own headings, and any proof pictures), why (one sentence on a tinted panel), today and after (a two column table), and what we recommend (a checklist); then the plan in order. A beat with no data is left out, heading and all | `/read` |
+| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Where We Looked, What It Showed, Why, Today, After, What We Recommend, the plan's heading), each overridable through `labels` | `/read` |
+| `ReadTier`, `ReadSection`, `ReadTool`, `ReadFact`, `ReadExamples`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in, all plain data so a routine can write a read as JSON. A section's `tools` were its `sources` in 1.0.0; `sources` is still read, and rendered at the top as tools, and `ReadSource` names the same shape as `ReadTool` | none |
+| `Report`, `ReportProps` | The monthly page: the four questions, the seven grades now and before, the sign off, on one letter sheet | `/report` |
+| `ReportLead`, `ReportLeads`, `ReportGradeRow` | The shapes a monthly page's content is written in | none |
+| `Note`, `NoteProps` | The first touch set as a page: the opener, two lanes of findings, where the work would start, the close | `/notes` |
+| `NoteLane`, `NoteFinding`, `NoteStart`, `NoteStep`, `NoteClose`, `NoteLink`, `NoteParagraph` | The shapes a note's content is written in | none |
+| `Gate`, `GateProps`, `GatePayload`, `GatePerson` | The sealed document, opened in the browser by the reader's own address, and the payload it opens | `/proposal` |
+| `normalizeEmail` | How a typed address becomes the key a payload opens with; the sealing command mirrors it | none |
+| `documents.css` | The documents' styles, at `@atelic-action/artifact/styles/documents.css` | every route |
+
+What a document is built from stays in `@atelic-action/ui`, and this package imports it rather than copying it: `GradeChip`, `gradeLabel`, `SignOff`, and `newTabProps` from `@atelic-action/ui/artifact`; `Callout`, `Checklist`, `ColumnChart`, `DataTable`, `Disclosure`, `StackedBar`, `StatRow`, `ThresholdScale`, and their types from `@atelic-action/ui/components`; `Button` from `@atelic-action/ui/primitives`. The shell around a page (`ArtifactShell`), the head (`buildPageHead`), the contract (`ArtifactConfig`), the reader helpers, the error boundary, the access wall, the Vite configuration, and the commands are ui's too, and a site imports them from there. Two small helpers live here unexported, because ui 1.1.0 does not export them: `Shot` (the owner's screen, in the writeup, the note, and the read) and `Paragraph` (the plain data paragraph of the note and the read).
+
+## Install
+
+```bash
+bun add @atelic-action/artifact @atelic-action/ui
+```
+
+Peer dependencies: `@atelic-action/ui` at `^1.1.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
+
+```tsx
+import { Writeup } from "@atelic-action/artifact";
+import { buildPageHead } from "@atelic-action/ui/artifact";
+```
+
+### CSS Import Order
+
+The documents' sheet goes after every ui sheet and before the site's `theme.css`:
+
+1. The site's fonts (`fonts.css`)
+2. `@atelic-action/ui/styles/base.css`, `chrome.css`, `components.css`, `primitives.css`, and `gate.css`, in that order
+3. `@atelic-action/ui/styles/artifact.css`, the pieces the documents share (the grade chip, the sign off, the shell's logo)
+4. `@atelic-action/artifact/styles/documents.css`
+5. The site's `theme.css`, last
+
+Every rule in the sheet sits in the `atelic-ui` layer and under the `.atelic-ui` root class, exactly as ui's sheets do, so any rule a site writes outside a layer still wins over it. 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; their order is load bearing.
+
+Under ui 1.x the overlap is deliberate: ui's `artifact.css` still carries the documents' rules beside the pieces, so a site importing both sheets carries those rules twice, identical and in the same order, until ui 2.0.0 drops them from its sheet (ATE-671, step 3). On the template that is about 39 KB of the built base sheet, 6 KB gzipped.
+
+## Tech Stack
+
+| Category | Technology | Purpose |
+|----------|------------|---------|
+| Runtime | Bun | Fast JS runtime with built in tooling |
+| Framework | React 19 + TypeScript | Strict mode throughout |
+| Meta framework | TanStack Start | File based routing with static prerendering (SSG) |
+| Styling | Semantic CSS tokens | One theme file per artifact; component CSS on top; no utility framework |
+| Confidentiality | Web Crypto | The sealed document gate, plus an optional email tied wall over the whole host |
+| Error tracking | Sentry | Optional, activates only when a DSN is set |
+| Testing | Vitest + Testing Library | Tests in `tst/` mirroring `src/` |
+| Lint and format | Biome | Pre commit hook lints; pre push mirrors CI |
+
+## Quick Start
+
+```bash
+bun install
+bun dev
+```
+
+No environment variables required. Visit [http://localhost:5173](http://localhost:5173).
+
+## Building a Client Artifact
+
+A business's artifacts live in one folder of `atelic-action/writeups`, named by the business's short name and served at `<short>.atelic.me` as its own Vercel project with the folder as its root directory, one path per artifact. That host is the business's one address with the practice: the website build, when one is previewed, sits on it at `/proto`, proxied from its own project ([DEPLOY.md](DEPLOY.md), The Website Build Under /proto). Cut it from this one with `git subtree add --prefix=<short> https://github.com/atelic-action/artifact.git main`, run in `writeups`. A cut is a site, not the package, so it then takes the package from npm instead of carrying its source: delete `src/documents/` and `tst/documents/`, give `package.json` the folder's own name and drop the package's fields (`version`, `files`, `exports`, `sideEffects`, `peerDependencies`), and run `bun add @atelic-action/artifact`. The routes and content already import the documents by the package's name, so nothing else changes. Nothing is pulled forward from here afterward: a document reaches the folder with `bun update @atelic-action/artifact`, and everything else with logic in it is `@atelic-action/ui`'s and arrives with `bun update @atelic-action/ui` ([CLAUDE.md](CLAUDE.md), What a Cut Takes From Here). Delete the artifacts the engagement does not need (the route, the content module, and the prerender entry), then touch four surfaces:
+
+1. **Content**, in `src/content/`. One module per artifact: the real read, every number dated and defensible in the room, graded and shaped by the practice's `FOOTPRINT.md` and written to its pitch surface rules (`Brand/voice.md`, Pitch Surfaces 15 to 21). In `writeup.tsx`, `sheets[]` only groups the blocks; print flows the page across as many letter pages as it needs, and `writeupStops` names the header's stops.
+2. **Images**, split by what they are. Logos are brand marks and go in `public/brand/` (the recipient's logo, e.g. `public/brand/<name>.svg`), which the access wall leaves open so the header and the login page can draw them. The owner's own screens (the full screenshot for the click through and a tight crop for the column) and the QR for the twin, pointing at the bare host (`qr "https://<short>.atelic.me" > public/images/qr.png` with the `qrcode` package), go in `public/images/`, which the wall holds on a private artifact. A cut made before this split moves its recipient logo from `public/images/` to `public/brand/` and repoints `recipient.logo.src`.
+3. **Config**, in `src/site.config.ts`. `url` is the host, `access` is `"public"` or `"private"` (private when anything came from the owner's own consoles), `recipient` is the business it was prepared for (with its `logo` under `/brand/`), `sender` is the practice, and `analytics` is the HubSpot loader so an open reports to the CRM, with `identify` naming who each link identifies so the open lands on that person's contact (`bun run reader <email>` mints a reader, sealed so no address ships in the page's script, and prints their link; a private artifact needs nobody listed, because the wall identifies whoever signs in; [DEPLOY.md](DEPLOY.md), Who Opened It).
+4. **The printed copy**: `bun build`, then `bun run print dist/client public/writeup.pdf`, which prints with every collapsible open and reports the sheet count, or `bun run print dist/client <out.pdf> 1 /report` for the monthly page, which fails if it misses its one sheet. Commit the writeup's PDF beside the page, and file a dated copy in the client's folder of the practice repo.
+
+A private artifact deploys only behind the armed wall, which holds the screenshots, the PDF, and the built content chunks as well as the pages, and `bun run check:wall <short>.atelic.me` must pass before any link goes out ([ACCESS-GATE.md](ACCESS-GATE.md)).
+
+The theme stays the practice's (Geist, ink, the orange) unless the artifact should wear the client's brand, in which case `src/styles/theme.css` and the two font files swap and nothing else moves. Check the phone at 390 wide in a real browser before deploying.
+
+## Documentation Map
+
+| Doc | Covers |
+|-----|--------|
+| [CLAUDE.md](CLAUDE.md) | Architecture, conventions, and gotchas (agents start here) |
+| [src/components/README.md](src/components/README.md) | The component catalog: every component, its props, where it's used |
+| [src/components/CLAUDE.md](src/components/CLAUDE.md) | Rules for changing or growing the components |
+| [src/content/README.md](src/content/README.md) | Authoring the content modules |
+| [src/styles/README.md](src/styles/README.md) | The theming system and how to derive a new palette |
+| [GATE.md](GATE.md) | The sealed document gate: opens with the reader's own email, with HubSpot open tracking |
+| [ACCESS-GATE.md](ACCESS-GATE.md) | The email tied sign in wall over the whole host, required for a private artifact, with the build guard and the wall check |
+| [DEPLOY.md](DEPLOY.md) | The deploy motion: Vercel, the subdomain, the wall for a private artifact, the observability layers |
+| [LAUNCH.md](LAUNCH.md) | The per artifact send checklist template, stamped into a Linear ticket |
+| [TEARDOWN.md](TEARDOWN.md) | The reverse motion: retiring a subdomain and its Vercel project |
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun dev` | Dev server |
+| `bun build` | Access guard + typecheck + build + prerender every page |
+| `bun test` / `bun test:run` | Tests (watch / once) |
+| `bun lint` / `bun lint:fix` | Biome check / auto fix |
+| `bun run print <url or dist/client> <out.pdf> [sheets] [page]` | Prints a page (the writeup unless named) through headless Chrome, reports the sheet count, and checks it when one is given |
+| `bun run check:wall <host> [path ...]` | Proves a private artifact's live host answers every document with the wall |
+| `bun run seal <config.json> [out.json]` | Seals a document for its named readers ([GATE.md](GATE.md)) |
+
+## Deployment
+
+Static files. `vercel.json` points Vercel at `dist/client` with no framework preset. The full motion, the subdomain, the observability layers, and why every `.atelic.me` host is noindexed automatically live in [DEPLOY.md](DEPLOY.md).
+
+## Contributing Back
+
+A document is fixed or grown here, in `src/documents/`, with its test in `tst/documents/`, and released as a version of this package; a folder takes it with `bun update @atelic-action/artifact`. A piece a document is built from (the grade chip, the sign off, a page component, the chrome, the wall, a command) is fixed in `@atelic-action/ui` and released there first, then taken here by bumping the ui range. An improvement to the seed itself (a route, a stub file, the example content) is made here and copied into the folders by hand.
+
+## Releasing
+
+1. Bump `version` in `package.json` and merge it to `main`: patch for a fix, minor for a new document or prop, major for a breaking prop, type, or class rename.
+2. Tag the merged commit `vX.Y.Z` with the same version and push the tag:
+
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+3. The Publish workflow (`.github/workflows/publish.yml`) checks that the tag matches the version, runs lint, the tests, and the build, and publishes to npm. It authenticates through npm trusted publishing, as ui's does: the package's Trusted Publisher names this repo and `publish.yml`, and its allowed actions must permit direct `npm publish`, since a configuration created after 2026-09-03 allows only `npm stage publish` by default. No token is stored, and it needs npm 11.5.1 or later, which Node 24 ships.
+
+Two things differ from ui. A Trusted Publisher is set on a package that already exists, so the first version, 1.0.0, is published by hand by an owner of the `@atelic-action` scope (`npm publish --access public` from a clean checkout of the tag) before the Trusted Publisher is added and the workflow takes over. And this repo is private, so npm attaches no provenance to what it publishes; the package's source is public on npm all the same, which is why `files` ships only `src/documents/` (README.md and package.json ride along, as npm always includes them), and why nothing in them may name a client.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,69 @@
 {
-  "name": "@atelic-action/artifact",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@atelic-action/artifact",
+	"version": "1.1.0",
+	"description": "The composed documents the Atelic practice hands or sends a business (the writeup, the read, the monthly page, the note, and the sealed document), built from the pieces in @atelic-action/ui",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/atelic-action/artifact.git"
+	},
+	"files": [
+		"src/documents"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		".": "./src/documents/index.ts",
+		"./styles/documents.css": "./src/documents/documents.css",
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+		"dev": "vite",
+		"build": "atelic-check-access && tsc -b && vite build && cp dist/client/404/index.html dist/client/404.html && atelic-stamp-health",
+		"preview": "vite preview",
+		"test": "vitest",
+		"test:run": "vitest run",
+		"test:e2e": "playwright test",
+		"lint": "biome check .",
+		"lint:fix": "biome check . --write",
+		"check:links": "atelic-check-links",
+		"check:wall": "atelic-check-wall",
+		"reader": "atelic-reader-link",
+		"print": "atelic-print-sheets",
+		"seal": "atelic-seal-document",
+		"format": "biome format . --write"
+	},
+	"peerDependencies": {
+		"@atelic-action/ui": "^1.1.0",
+		"lucide-react": "^1.23.0",
+		"react": "^19.0.0"
+	},
+	"devDependencies": {
+		"@atelic-action/ui": "^1.1.0",
+		"@biomejs/biome": "^2.0.0",
+		"@playwright/test": "^1.60.0",
+		"@sentry/react": "^10.0.0",
+		"@tanstack/react-router": "^1.170.41",
+		"@tanstack/react-router-devtools": "^1.167.2",
+		"@tanstack/react-start": "^1.168.60",
+		"@testing-library/jest-dom": "^6.6.2",
+		"@testing-library/react": "^16.0.1",
+		"@types/node": "^24.10.1",
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.0.0",
+		"@vitejs/plugin-react": "^5.0.0",
+		"jsdom": "^25.0.1",
+		"lucide-react": "^1.23.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"typescript": "^5.6.3",
+		"vite": "^7.0.0",
+		"vitest": "^4.0.0"
+	},
+	"trustedDependencies": [
+		"@biomejs/biome"
+	]
+}

package/src/documents/Gate.tsx

@@ -0,0 +1,342 @@
+import { Button } from "@atelic-action/ui/primitives";
+import { type FormEvent, useEffect, useRef, useState } from "react";
+
+/**
+ * PBKDF2 work factor and hash. Mirrored by the sealing command, which
+ * @atelic-action/ui ships (atelic-seal-document, its src/scripts/seal-document.mjs);
+ * the two must agree exactly or every sealed payload stops opening, and
+ * tst/documents/gate.test.tsx seals with that command to prove it.
+ */
+const PBKDF2_ITERATIONS = 200000;
+const PBKDF2_HASH = "SHA-256";
+
+declare global {
+	interface Window {
+		/** HubSpot tracking queue; the loader drains anything pushed before it loads. */
+		_hsq?: unknown[];
+	}
+}
+
+export interface GatePerson {
+	/** Stable handle for the reader, used in the payload and in `onUnlock`. */
+	id: string;
+	/**
+	 * 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;
+	/** Base64: this reader's PBKDF2 salt, GCM nonce, and wrapped content key. */
+	salt: string;
+	iv: string;
+	wrapped: string;
+}
+
+export interface GatePayload {
+	/** Base64: the document's GCM nonce and ciphertext. */
+	civ: string;
+	ct: string;
+	people: GatePerson[];
+}
+
+export interface GateProps {
+	/** Built by atelic-seal-document, from @atelic-action/ui. Carries no plaintext. */
+	payload: GatePayload;
+	/** localStorage key holding the reader's email, so a return visit walks straight in. */
+	storageKey?: string;
+	/**
+	 * Query parameter a sent link may carry the reader's email in, so the
+	 * link opens the document in one click. Checked once on mount and
+	 * stripped from the address bar either way.
+	 */
+	queryParam?: string;
+	/**
+	 * When set, a reader whose email ends with this domain is pushed to
+	 * HubSpot on unlock, so the open lands on their contact timeline.
+	 * Readers on another domain identify nobody. Leave it unset and the
+	 * gate tracks no one.
+	 */
+	identifyDomain?: string;
+	/** Gate copy. Defaults are neutral; a client document overrides what it needs. */
+	kicker?: string;
+	heading?: string;
+	sub?: string;
+	placeholder?: string;
+	inputLabel?: string;
+	errorText?: string;
+	/** Fired once, after a successful unlock. */
+	onUnlock?: (person: GatePerson) => void;
+}
+
+/**
+ * An email is its letters and digits, uppercased, so "Dana@Example.com",
+ * "dana@example.com" and even a stray space all open the same document.
+ * Mirrored in the build script.
+ */
+export function normalizeEmail(email: string): string {
+	return email.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
+
+function fromBase64(value: string): Uint8Array {
+	const binary = atob(value);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+
+interface Opened {
+	person: GatePerson;
+	/** The address that opened the document, as the reader gave it. */
+	email: string;
+	html: string;
+}
+
+/**
+ * Try the entered email against every reader in the payload. An email that
+ * matches nobody fails the GCM tag check on each attempt and returns null,
+ * which is the only signal the gate ever gives: it never reveals who is on
+ * the list or how close a guess came.
+ */
+async function openDocument(payload: GatePayload, rawEmail: string): Promise<Opened | null> {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) return null;
+	const normalized = normalizeEmail(rawEmail);
+	if (!normalized) return null;
+
+	const material = await subtle.importKey(
+		"raw",
+		new TextEncoder().encode(normalized),
+		"PBKDF2",
+		false,
+		["deriveKey"],
+	);
+
+	for (const person of payload.people) {
+		try {
+			const wrapper = await subtle.deriveKey(
+				{
+					name: "PBKDF2",
+					salt: fromBase64(person.salt) as BufferSource,
+					iterations: PBKDF2_ITERATIONS,
+					hash: PBKDF2_HASH,
+				},
+				material,
+				{ name: "AES-GCM", length: 256 },
+				false,
+				["decrypt"],
+			);
+			const contentKeyBytes = await subtle.decrypt(
+				{ name: "AES-GCM", iv: fromBase64(person.iv) as BufferSource },
+				wrapper,
+				fromBase64(person.wrapped) as BufferSource,
+			);
+			const contentKey = await subtle.importKey(
+				"raw",
+				contentKeyBytes,
+				{ name: "AES-GCM" },
+				false,
+				["decrypt"],
+			);
+			const plain = await subtle.decrypt(
+				{ name: "AES-GCM", iv: fromBase64(payload.civ) as BufferSource },
+				contentKey,
+				fromBase64(payload.ct) as BufferSource,
+			);
+			return { person, email: rawEmail, html: new TextDecoder().decode(plain) };
+		} catch {
+			// Wrong email for this reader. Try the next one; say nothing.
+		}
+	}
+	return null;
+}
+
+/**
+ * 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 }]);
+	window._hsq.push(["setPath", window.location.pathname]);
+	window._hsq.push(["trackPageView"]);
+}
+
+function readStored(key: string): string {
+	try {
+		return globalThis.localStorage?.getItem(key) ?? "";
+	} catch {
+		return ""; // Storage blocked (private mode); the reader just retypes their email.
+	}
+}
+
+function writeStored(key: string, value: string) {
+	try {
+		globalThis.localStorage?.setItem(key, value);
+	} catch {
+		// Same: persistence is a courtesy, never a requirement.
+	}
+}
+
+/** Read and strip the gate's query parameter in one motion. */
+function takeQueryParam(name: string): string {
+	try {
+		const url = new URL(window.location.href);
+		const value = url.searchParams.get(name) ?? "";
+		if (value) {
+			url.searchParams.delete(name);
+			window.history.replaceState(window.history.state, "", url.toString());
+		}
+		return value;
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * The gate: an email field standing in front of a sealed document.
+ *
+ * The document ships as ciphertext inside the page, so there is no server to
+ * ask and nothing to gate at the edge. The reader's own email address derives
+ * the key that unwraps the content key, the document decrypts in the browser,
+ * and the gate replaces itself with it. Wrong emails get one line of copy and
+ * no hint. A sent link can carry the email in a query parameter (`?email=`)
+ * to open the document in one click.
+ *
+ * Sized for a document sent to named people: the reader types the one thing
+ * they always know, no sign in, no inbox round trip. The access gate
+ * (ACCESS-GATE.md, GateLogin in @atelic-action/ui/components) is the other shape, for a whole
+ * site preview behind an email tied session with inbox verified identity.
+ */
+export function Gate({
+	payload,
+	storageKey = "gate-email",
+	queryParam = "email",
+	identifyDomain,
+	kicker = "Private Document",
+	heading = "Enter Your Email",
+	sub = "This document opens with the email address it was sent to.",
+	placeholder = "you@company.com",
+	inputLabel = "Your email",
+	errorText = "That email does not open this document. Use the address it was sent to.",
+	onUnlock,
+}: GateProps) {
+	const [html, setHtml] = useState<string | null>(null);
+	const [failed, setFailed] = useState(false);
+	const [busy, setBusy] = useState(false);
+	const [value, setValue] = useState("");
+
+	// Held in a ref so a caller passing an inline function cannot re-run the
+	// auto unlock effect on every render.
+	const onUnlockRef = useRef(onUnlock);
+	onUnlockRef.current = onUnlock;
+
+	// Silent auto unlock, in order: a sent link's query parameter first, then
+	// the stored email of a reader who has been here before. A value that no
+	// longer opens anything (the payload was rebuilt) fails quietly; a failed
+	// query value pre fills the field and surfaces the error, since the
+	// reader arrived expecting the door to open.
+	useEffect(() => {
+		let cancelled = false;
+
+		async function attempt() {
+			const fromQuery = takeQueryParam(queryParam);
+			if (fromQuery) {
+				const opened = await openDocument(payload, fromQuery);
+				if (cancelled) return;
+				if (opened) {
+					writeStored(storageKey, fromQuery);
+					identifyReader(opened.email, identifyDomain);
+					setHtml(opened.html);
+					onUnlockRef.current?.(opened.person);
+					return;
+				}
+				setValue(fromQuery);
+				setFailed(true);
+				return;
+			}
+
+			const stored = readStored(storageKey);
+			if (!stored) return;
+			const opened = await openDocument(payload, stored);
+			if (cancelled || !opened) return;
+			identifyReader(opened.email, identifyDomain);
+			setHtml(opened.html);
+			onUnlockRef.current?.(opened.person);
+		}
+
+		attempt();
+		return () => {
+			cancelled = true;
+		};
+	}, [payload, storageKey, identifyDomain, queryParam]);
+
+	async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+		event.preventDefault();
+		if (busy) return;
+		setBusy(true);
+		setFailed(false);
+		const opened = await openDocument(payload, value);
+		setBusy(false);
+		if (!opened) {
+			setFailed(true);
+			return;
+		}
+		writeStored(storageKey, value);
+		identifyReader(opened.email, identifyDomain);
+		setHtml(opened.html);
+		onUnlockRef.current?.(opened.person);
+	}
+
+	if (html !== null) {
+		return (
+			<div className="gate-doc">
+				<div className="wrap">
+					{/* biome-ignore lint/security/noDangerouslySetInnerHtml: the document is the practice's own HTML, sealed at build time and decrypted here. Injecting it is the whole point of the component. */}
+					<div className="gate-content" dangerouslySetInnerHTML={{ __html: html }} />
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="gate-hall">
+			<div className="wrap">
+				<div className="gate-card">
+					{kicker && <p className="gate-eyebrow">{kicker}</p>}
+					<h1 className="gate-headline">{heading}</h1>
+					{sub && <p className="gate-lead">{sub}</p>}
+					<form className="gate-form" onSubmit={handleSubmit} noValidate>
+						<input
+							className="gate-input"
+							type="email"
+							inputMode="email"
+							name="email"
+							value={value}
+							onChange={(event) => setValue(event.target.value)}
+							placeholder={placeholder}
+							aria-label={inputLabel}
+							autoComplete="email"
+							autoCapitalize="none"
+							spellCheck={false}
+						/>
+						<Button type="submit" size="lg">
+							{busy ? "Opening…" : "Open Document"}
+						</Button>
+					</form>
+					{failed && (
+						<p className="gate-error" role="alert">
+							{errorText}
+						</p>
+					)}
+				</div>
+			</div>
+		</div>
+	);
+}