@atelic-action/ui 0.14.0 → 0.15.1

package/README.md

@@ -33,8 +33,9 @@ Import the stylesheets in this order, from the root route or the site's base she
 4. `@atelic-action/ui/styles/components.css`
 5. `@atelic-action/ui/styles/primitives.css`
 6. `@atelic-action/ui/styles/gate.css`, on a site that mounts the access gate
-7. The site's own CSS
-8. The site's `theme.css`, last
+7. `@atelic-action/ui/styles/artifact.css`, on a site that hosts the artifact documents
+8. The site's own CSS
+9. The site's `theme.css`, last
 
 The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the `.btn` classes, which `primitives.css` defines and a site may restyle.
 
@@ -44,6 +45,8 @@ 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/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` |
@@ -51,6 +54,8 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/hooks` | `useScrollSpy` and its `PageStop` type |
 | `@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/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 |
@@ -191,7 +196,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 the one corner of the package that ships compiled. 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 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.
 
 ### The Screen and the Watermark
 
@@ -217,6 +222,40 @@ The two pieces a reader sees are ordinary components, in `@atelic-action/ui/comp
 
 `GateLogin` posts to `/api/auth/request-link`; a site served under a base path passes its own `endpoint`. Its button wears the site's `.btn` classes, as the chrome's do. `Watermark` reads the `gate_email` cookie and draws nothing without one. `readCookie`, exported beside them, is the reader `Watermark` uses and a site's own code can: empty during prerender, for a missing cookie, and for one that will not decode. `GateLogin` says so when an address is not an email, holds a second submit while the first is in flight, and announces each outcome to a screen reader.
 
+## The Artifact Documents
+
+`@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; 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`.
+- **The error boundary:** `AppErrorBoundary` and its `ErrorFallback`.
+- **`newTabProps`,** for the links a content module writes.
+
+The package imports no router, so `ArtifactShell` takes the path being read as its `currentPath` prop. A site keeps a wrapper a few lines long that reads the path from its own router and passes it down:
+
+```tsx
+import { ArtifactShell as Shell, type ArtifactShellProps } from "@atelic-action/ui/artifact";
+import { useLocation } from "@tanstack/react-router";
+
+export function ArtifactShell(props: Omit<ArtifactShellProps, "currentPath">) {
+	const currentPath = useLocation({ select: (location) => location.pathname });
+	return <Shell {...props} currentPath={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:
+
+```ts
+// vite.config.ts
+import { privateChunks } from "@atelic-action/ui/vite";
+
+export default defineConfig({ plugins: [tanstackStart(), react(), privateChunks()] });
+```
+
 ## 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/dist/artifact/artifactConfig.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The contract between an artifact and the components that host it.
+ *
+ * An artifact is a document, not a business's website, so this is a fraction
+ * of a marketing site's config: who it is from, who it was prepared for,
+ * where it is hosted, who may read it, and whether an open reports to the
+ * CRM. Everything a reader sees on the page itself arrives as content, never
+ * from here.
+ */
+/**
+ * Copy for the access-gate login screen. Present in the config so the login
+ * page is themed and worded per artifact with no code edits. The gate itself
+ * is turned on by setting GATE_SESSION_SECRET on the Vercel project, not by
+ * this block; `access` below says whether it must be. See ACCESS-GATE.md.
+ */
+export interface GateConfig {
+    /** Mono eyebrow above the headline, e.g. "Private preview". */
+    eyebrow?: string;
+    /** Login headline. */
+    headline: string;
+    /** Sub-lead under the headline. */
+    lead: string;
+    /** Fine-print attribution, e.g. "Built by Jane Maker". Defaults to the sender's name. */
+    builtBy?: string;
+    /** Contact email shown in the fine print. Defaults to the sender's email. */
+    contactEmail?: string;
+}
+/**
+ * A named reader, sealed. This config ships in the script every page loads,
+ * so it lists neither the reader's email nor their token: `id` is a digest
+ * of the token, and `sealed` is the email encrypted under a key derived from
+ * it. Only the reader's own link opens it (readers.ts).
+ */
+export interface ArtifactReader {
+    id: string;
+    sealed: string;
+}
+/**
+ * Who the document is from: the practice, on every artifact. The lockup in
+ * the header renders from `logo` exactly as the marketing chrome's does, so
+ * a client branded artifact host keeps the sender's chrome over the client's
+ * palette (GATE.md, Branding an Artifact Host).
+ */
+export interface ArtifactSender {
+    /** The sender's name, worn in the header and the gate's fine print. */
+    name: string;
+    /**
+     * The chrome identity. `src` is the mark image; omit it for a pure text
+     * wordmark. `tile` renders a CSS glyph tile instead of an image (a dark
+     * rounded square bearing the given character in the brand's own webfont,
+     * with the accent bar beneath, since an SVG-as-img mark cannot load
+     * webfonts). `wordmark` overrides the rendered text when it should differ
+     * from `name`; `run` appends the trailing fade bar after it.
+     */
+    logo: {
+        src?: string;
+        alt: string;
+        tile?: string;
+        wordmark?: string;
+        run?: boolean;
+    };
+    /** Where the header lockup points; the sender's own site. */
+    href?: string;
+    /** Reply address, shown in the access gate's fine print. */
+    email: string;
+}
+/** Who the document was prepared for; the business's name suffixes every title. */
+export interface ArtifactRecipient {
+    name: string;
+    /**
+     * The recipient's mark for the header lockup ("atelic × <mark>"), cut for
+     * the dark bar (a light mark on transparent). Unset, the header wears the
+     * sender's lockup alone. ArtifactShell passes it to the ui header as
+     * `brand.recipient` (@atelic-action/ui 0.6.0 and later).
+     *
+     * A logo is a brand mark, not a private signal, so the file lives under
+     * public/brand/, which the access wall leaves open: the router's pending
+     * page carries the header, so every page preloads this mark, the login
+     * page included, and one under public/images/ would be held there. The
+     * writeup's printed copy is white paper, so the lockup it prints in place
+     * of the header takes a mark cut for a light ground (`recipient.logoSrc`
+     * in the writeup's content).
+     */
+    logo?: {
+        src: string;
+        alt: string;
+    };
+}
+export interface ArtifactConfig {
+    /** Canonical origin of the hosted twin, no trailing slash, e.g. "https://og.atelic.me". */
+    url: string;
+    /**
+     * Who may read it, which decides where it may be hosted (the practice's
+     * FOOTPRINT.md, Privacy). "public" when everything on it was read from
+     * public signals, a prospect's writeup; "private" when anything came from
+     * the owner's own consoles, which is every customer's writeup and every
+     * monthly page. A private artifact deploys only behind the armed wall:
+     * the build fails on Vercel without the wall's variables
+     * (scripts/check-access.ts), and scripts/check-wall.ts proves the live
+     * host answers with the wall before any link goes out (ACCESS-GATE.md).
+     */
+    access: "public" | "private";
+    sender: ArtifactSender;
+    recipient: ArtifactRecipient;
+    /** Social card image; a site-relative path resolves against `url`. */
+    ogImage?: string;
+    /**
+     * Robots line for every page. Artifacts default to "noindex, nofollow"
+     * and there is no reason to raise it: a document handed to one business
+     * is never search inventory.
+     */
+    robots?: string;
+    /**
+     * Analytics wiring. When `hubspotPortalId` is set, the HubSpot tracking
+     * code loads and records the open; because an artifact lives on its own
+     * host, every visit is attributable to that engagement. `hubspotRegion`
+     * picks the loader host and defaults to "na1"; na2 portals load from
+     * js-na2.hs-scripts.com.
+     *
+     * `identify` says who each link identifies, and every cut says it: a
+     * reader for every named person a link goes to, or an empty list. When a
+     * visit arrives with `?k=<token>` (the token on that person's link), the
+     * visitor is identified to HubSpot by their email, so the open lands on
+     * their contact timeline. Visits without a token stay anonymous. Mint a
+     * reader with `bun run reader <email>`.
+     *
+     * A private artifact needs nobody listed: its readers sign in at the
+     * wall and are identified by the email they signed in with. DEPLOY.md,
+     * Who Opened It, is the procedure.
+     */
+    analytics?: {
+        hubspotPortalId: string;
+        hubspotRegion?: "na1" | "na2" | "eu1";
+        identify: ArtifactReader[];
+    };
+    /** Copy for the access-gate login screen (see GateConfig). */
+    gate?: GateConfig;
+}

package/dist/artifact/artifactConfig.js

@@ -0,0 +1,10 @@
+/**
+ * The contract between an artifact and the components that host it.
+ *
+ * An artifact is a document, not a business's website, so this is a fraction
+ * of a marketing site's config: who it is from, who it was prepared for,
+ * where it is hosted, who may read it, and whether an open reports to the
+ * CRM. Everything a reader sees on the page itself arrives as content, never
+ * from here.
+ */
+export {};

package/dist/artifact/readers.d.ts

@@ -0,0 +1,33 @@
+import type { ArtifactReader } from "./artifactConfig.js";
+/** What a config lists a token under: a digest, so the token itself never ships. */
+export declare function readerId(token: string): Promise<string>;
+/** A fresh token for one reader's links: twelve characters, safe in a URL. */
+export declare function mintToken(): string;
+/** Seal a reader's email under their token: the entry site.config.ts lists. */
+export declare function sealReader(email: string, token: string): Promise<ArtifactReader>;
+/** The email a link's token opens, or undefined when it opens nobody's. */
+export declare function openReader(readers: ArtifactReader[] | undefined, token: string | null | undefined): Promise<string | undefined>;
+/**
+ * The email this visit should be identified as, or undefined to leave it
+ * anonymous.
+ *
+ * On a private artifact the sign in decides, and a link's token never
+ * overrides it: the wall checked who this is, and a token only says who a
+ * link was sent to. So a signed in reader is identified by their own email,
+ * and a reader on the sender's domain is nobody's open even through someone
+ * else's link, since that is the practice reading its own document. A
+ * visit with no sign in (the wall not armed, as in local dev) falls back to
+ * the link.
+ *
+ * A public artifact has no wall, so a `gate_email` cookie there proves
+ * nothing and is never read: the link's token is the only identity.
+ */
+export declare function whoIsReading(visit: {
+    readers: ArtifactReader[] | undefined;
+    search: string;
+    access: "public" | "private";
+    gateEmail: string;
+    senderEmail: string;
+}): Promise<string | undefined>;
+/** The link to send a reader: the artifact's page with their token on it. */
+export declare function readerLink(siteUrl: string, token: string, path?: string): string;

package/dist/artifact/readers.js

@@ -0,0 +1,117 @@
+/**
+ * Who opened it. An artifact reports every open to the practice's HubSpot
+ * portal, and an open lands on a person's contact record only when the visit
+ * says who they are. A visit says so one of two ways:
+ *
+ * - **Their link.** Every link sent to a named person carries
+ *   `?k=<their token>`, and site.config.ts lists that reader.
+ * - **The wall.** A reader who signed in on a private host is known by the
+ *   email they signed in with, read from the `gate_email` cookie.
+ *
+ * site.config.ts ships in the script every page loads, so a reader is listed
+ * sealed, never in the clear: `id` is a digest of the token, and `sealed` is
+ * the email encrypted under a key derived from the token. Only the link can
+ * open it, and the link is in one person's inbox. Reading the page's source
+ * gives nobody's address.
+ *
+ * Nothing here touches the page or the network, so it tests without a
+ * browser. The root route does the one impure thing, the push to HubSpot.
+ *
+ * This file is also built to dist/ and exported on its own as
+ * `@atelic-action/ui/artifact/readers`, because a site's browser tests and
+ * its reader script import it under Node, which runs no TypeScript inside
+ * node_modules. So it keeps the built corner's rules: no JSX, and `.js` on
+ * its relative imports.
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64Url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+function fromBase64Url(text) {
+    const padded = text.replaceAll("-", "+").replaceAll("_", "/");
+    return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+}
+async function digest(text) {
+    return crypto.subtle.digest("SHA-256", encoder.encode(text));
+}
+/** What a config lists a token under: a digest, so the token itself never ships. */
+export async function readerId(token) {
+    const bytes = new Uint8Array(await digest(`id:${token}`));
+    return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function keyFor(token) {
+    return crypto.subtle.importKey("raw", await digest(`key:${token}`), "AES-GCM", false, [
+        "encrypt",
+        "decrypt",
+    ]);
+}
+/** A fresh token for one reader's links: twelve characters, safe in a URL. */
+export function mintToken() {
+    return toBase64Url(crypto.getRandomValues(new Uint8Array(9)));
+}
+/** Seal a reader's email under their token: the entry site.config.ts lists. */
+export async function sealReader(email, token) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, await keyFor(token), encoder.encode(email)));
+    const packed = new Uint8Array(iv.length + sealed.length);
+    packed.set(iv);
+    packed.set(sealed, iv.length);
+    return { id: await readerId(token), sealed: toBase64Url(packed) };
+}
+/** The email a link's token opens, or undefined when it opens nobody's. */
+export async function openReader(readers, token) {
+    if (!token || !readers?.length)
+        return undefined;
+    const id = await readerId(token);
+    const reader = readers.find((entry) => entry.id === id);
+    if (!reader)
+        return undefined;
+    try {
+        const packed = fromBase64Url(reader.sealed);
+        const opened = await crypto.subtle.decrypt({ name: "AES-GCM", iv: packed.slice(0, 12) }, await keyFor(token), packed.slice(12));
+        return decoder.decode(opened);
+    }
+    catch {
+        return undefined;
+    }
+}
+function domainOf(email) {
+    return email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+}
+/**
+ * The email this visit should be identified as, or undefined to leave it
+ * anonymous.
+ *
+ * On a private artifact the sign in decides, and a link's token never
+ * overrides it: the wall checked who this is, and a token only says who a
+ * link was sent to. So a signed in reader is identified by their own email,
+ * and a reader on the sender's domain is nobody's open even through someone
+ * else's link, since that is the practice reading its own document. A
+ * visit with no sign in (the wall not armed, as in local dev) falls back to
+ * the link.
+ *
+ * A public artifact has no wall, so a `gate_email` cookie there proves
+ * nothing and is never read: the link's token is the only identity.
+ */
+export async function whoIsReading(visit) {
+    if (visit.access === "private") {
+        const signedIn = visit.gateEmail.trim();
+        if (signedIn.includes("@")) {
+            if (domainOf(signedIn) === domainOf(visit.senderEmail))
+                return undefined;
+            return signedIn;
+        }
+    }
+    const token = new URLSearchParams(visit.search).get("k");
+    return openReader(visit.readers, token);
+}
+/** The link to send a reader: the artifact's page with their token on it. */
+export function readerLink(siteUrl, token, path = "/writeup") {
+    const url = new URL(path, siteUrl);
+    url.searchParams.set("k", token);
+    return url.toString();
+}

package/dist/vite/private-chunks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Keeps a document's content out of every file the login page can load.
+ *
+ * With the wall armed, /assets/ stays open because the login page needs its
+ * own hashed CSS and JS to render (needsSession in src/gate/wall.ts). A content module that
+ * lands in a chunk there would be readable by anyone who opens /login, which
+ * is exactly how the example writeup and report first shipped: their route
+ * heads imported the content, so all of it rode in the entry bundle. So the
+ * client build writes every chunk carrying a private content module into
+ * /assets/doc/, which the wall holds back, and fails outright when one turns
+ * up anywhere else.
+ *
+ * Public content is the short list that is safe to ship to every page: the
+ * 404's copy, the sealed proposal (ciphertext by design, GATE.md), and the
+ * heads in `*.meta.ts`, which carry a title and nothing a snapshot produced.
+ * Every other module under src/content/ is treated as private, so a new
+ * artifact starts behind the wall.
+ */
+import type { Plugin } from "vite";
+/** Where the client build writes the chunks the wall holds back. */
+export declare const DOC_DIR = "assets/doc";
+/** Whether a module id is content that must never ship to the login page. */
+export declare function isPrivateContent(id: string): boolean;
+export declare function privateChunks(): Plugin;

package/dist/vite/private-chunks.js

@@ -0,0 +1,42 @@
+/** Where the client build writes the chunks the wall holds back. */
+export const DOC_DIR = "assets/doc";
+const PUBLIC_CONTENT = /\/src\/content\/(not-found\.tsx|proposal[^/]*|[^/]+\.meta\.ts)$/;
+/** Whether a module id is content that must never ship to the login page. */
+export function isPrivateContent(id) {
+    const path = id.split("?")[0].replaceAll("\\", "/");
+    return path.includes("/src/content/") && !PUBLIC_CONTENT.test(path);
+}
+export function privateChunks() {
+    return {
+        name: "atelic:private-chunks",
+        configEnvironment(name) {
+            if (name !== "client")
+                return;
+            return {
+                build: {
+                    rollupOptions: {
+                        output: {
+                            chunkFileNames: (chunk) => chunk.moduleIds.some(isPrivateContent)
+                                ? `${DOC_DIR}/[name]-[hash].js`
+                                : "assets/[name]-[hash].js",
+                        },
+                    },
+                },
+            };
+        },
+        generateBundle(_options, bundle) {
+            if (this.environment?.name !== "client")
+                return;
+            for (const file of Object.values(bundle)) {
+                if (file.type !== "chunk" || file.fileName.startsWith(`${DOC_DIR}/`))
+                    continue;
+                const leaked = Object.entries(file.modules)
+                    .filter(([id, module]) => module.renderedLength > 0 && isPrivateContent(id))
+                    .map(([id]) => id.slice(id.indexOf("/src/") + 1));
+                if (leaked.length > 0) {
+                    this.error(`${file.fileName} would ship ${leaked.join(", ")} outside ${DOC_DIR}/, where the login page can load it with no session. A route's head is the usual cause: give it a *.meta.ts module and keep the content to the component.`);
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.14.0",
+	"version": "0.15.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",
@@ -19,6 +19,11 @@
 		"**/*.css"
 	],
 	"exports": {
+		"./artifact": "./src/artifact/index.ts",
+		"./artifact/readers": {
+			"types": "./dist/artifact/readers.d.ts",
+			"default": "./dist/artifact/readers.js"
+		},
 		"./chrome": "./src/chrome/index.ts",
 		"./components": "./src/components/index.ts",
 		"./email": "./src/email/index.ts",
@@ -27,6 +32,7 @@
 		"./primitives": "./src/primitives/index.ts",
 		"./routing": "./src/routing/index.ts",
 		"./tokens": "./src/tokens/index.ts",
+		"./styles/artifact.css": "./src/styles/artifact.css",
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
@@ -49,11 +55,15 @@
 			"types": "./dist/gate/verify.d.ts",
 			"default": "./dist/gate/verify.js"
 		},
+		"./vite": {
+			"types": "./dist/vite/private-chunks.d.ts",
+			"default": "./dist/vite/private-chunks.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.server.json",
-		"build:smoke": "node --input-type=module -e \"for (const entry of ['', '/middleware', '/request-link', '/verify']) await import('@atelic-action/ui/gate' + entry)\"",
+		"build:smoke": "node --input-type=module -e \"for (const entry of ['gate', 'gate/middleware', 'gate/request-link', 'gate/verify', 'vite', 'artifact/readers']) await import('@atelic-action/ui/' + entry)\"",
 		"prepack": "bun run build",
 		"lint": "biome check .",
 		"lint:fix": "biome check . --write",
@@ -68,7 +78,13 @@
 	"peerDependencies": {
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
-		"react-dom": "^19.0.0"
+		"react-dom": "^19.0.0",
+		"vite": "^7.0.0 || ^8.0.0"
+	},
+	"peerDependenciesMeta": {
+		"vite": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.13",

package/src/artifact/AppErrorBoundary.tsx

@@ -0,0 +1,36 @@
+import { Component, type ReactNode } from "react";
+
+import { ErrorFallback } from "./ErrorFallback";
+
+interface AppErrorBoundaryState {
+	error: unknown;
+	hasError: boolean;
+}
+
+/**
+ * Plain React error boundary rendering the dependency-free ErrorFallback.
+ * Replaces Sentry.ErrorBoundary so @sentry/react stays out of the critical
+ * bundle: on PSI-class hardware the SDK's hydration cost ran ahead of first
+ * paint and Google clocked the page as seconds slower than it is. When a
+ * DSN is configured, Sentry's global handlers (attached by the lazy init in
+ * router.tsx) still capture errors, including ones caught here.
+ */
+export class AppErrorBoundary extends Component<{ children: ReactNode }, AppErrorBoundaryState> {
+	state: AppErrorBoundaryState = { error: null, hasError: false };
+
+	static getDerivedStateFromError(error: unknown): AppErrorBoundaryState {
+		return { error, hasError: true };
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return (
+				<ErrorFallback
+					error={this.state.error}
+					resetError={() => this.setState({ error: null, hasError: false })}
+				/>
+			);
+		}
+		return this.props.children;
+	}
+}

package/src/artifact/ArtifactShell.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+import { CreditBar } from "../chrome/CreditBar";
+import { SiteHeader } from "../chrome/SiteHeader";
+import { SkipLink } from "../chrome/SkipLink";
+import { Watermark } from "../components/Watermark";
+import type { PageStop } from "../hooks/useScrollSpy";
+import type { ArtifactConfig } from "./artifactConfig";
+
+export interface ArtifactShellProps {
+	site: ArtifactConfig;
+	/**
+	 * The path of the page being read. The package imports no router, so the
+	 * site reads it from its own and passes it down.
+	 */
+	currentPath: string;
+	/** The page's own stops; the header renders them scroll spied. */
+	stops?: PageStop[];
+	children: ReactNode;
+}
+
+/**
+ * The wrapper every artifact page uses: the `.mkt` theming
+ * scope, the skip link, the header, the credit band, and the access gate's
+ * watermark, composed from the chrome. The header is always the dark
+ * variant with the sender's lockup and never a site nav or a CTA, because the
+ * document's own close is the ask. There is no footer and no sticky bar by
+ * design: a document ends on its own sign off, and the credit band is the
+ * one line allowed after it.
+ */
+export function ArtifactShell({ site, currentPath, stops, children }: ArtifactShellProps) {
+	const { name, href, logo } = site.sender;
+	// The lockup names both parties of a sent document: the sender's wordmark
+	// and run, then the recipient's mark after a times sign (ui 0.6.0).
+	const recipient = site.recipient.logo;
+
+	return (
+		<div className="mkt">
+			<SkipLink />
+			<SiteHeader
+				brand={{ name, href, logo, recipient }}
+				variant="dark"
+				currentPath={currentPath}
+				stops={stops}
+			/>
+			<main id="main">{children}</main>
+			<CreditBar />
+			<Watermark />
+		</div>
+	);
+}