@atelic-action/ui 0.15.0 → 0.16.0

package/src/scripts/check-wall.ts

@@ -0,0 +1,357 @@
+/**
+ * The deploy proof for a private artifact: the wall answers before any link
+ * goes out (the practice's FOOTPRINT.md, Privacy). It asks the live host
+ * for each document with no cookie and passes only when every one answers
+ * with the wall's redirect to /login. A document that answers 200 is
+ * readable by anyone holding the link, and a 5xx is a host that is down
+ * rather than walled; both fail.
+ *
+ * The documents are /writeup, plus /report and /proposal when this repo
+ * carries those routes. The wall holds files too (needsSession in @atelic-action/ui/gate), so it
+ * also asks for the printed copy at /writeup.pdf, the first real screenshot
+ * under public/images/, and, when the repo has been built, the first chunk
+ * under /assets/doc/, where a document's content compiles to. Each of those
+ * must answer with the same redirect: the wall holds a path whether or not
+ * the file is there, so a 404 means the wall never ran for it.
+ *
+ * One thing must stay open on purpose: when public/brand/ has a file, it
+ * asks for the first and requires a 200. Brand marks live there because the
+ * header draws them on every page, the login page included, and a mark the
+ * wall held would leave the login page asking for a file it cannot have.
+ *
+ * Then it proves the two sign in functions answer, because a wall whose
+ * functions cannot load holds every page and can send no link. It posts an
+ * address on no allowlist to /api/auth/request-link, so nothing is ever
+ * sent, and requires the 200 every address gets. It asks
+ * /api/auth/verify for a token that is not one and requires the function's
+ * own 302 back to /login?e=expired. A 5xx from either is a function that
+ * failed to load: on 2026-10-01 both failed on an extensionless import.
+ *
+ * Usage: atelic-check-wall <host> [path ...], or `bun run check:wall <host>`
+ * in a site, from the site's root
+ *   bun run check:wall summit.atelic.me
+ *   bun run check:wall https://summit.atelic.me /writeup /report
+ * The sign in functions are asked only when no path is named.
+ * Exits 1 unless every path answers as it must.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * One thing to ask the host for. Every probe but a sign in one is a GET with
+ * no body.
+ */
+export type Probe =
+	| {
+			path: string;
+			/**
+			 * A page the wall must stand in front of, a file it must hold back, or a
+			 * brand mark it must leave open.
+			 */
+			kind: "document" | "file" | "open";
+	  }
+	| {
+			path: string;
+			/**
+			 * A sign in function that must answer for itself: the request for a
+			 * link is a POST that must answer 200, and the verify is a GET that
+			 * must answer its own redirect back to /login.
+			 */
+			kind: "signin";
+			method: "GET" | "POST";
+			/** Sent as JSON with a POST. */
+			body?: Record<string, string>;
+	  };
+
+/** The shape of an answer the classifier reads; a fetch Response fits it. */
+export interface WallAnswer {
+	status: number;
+	headers: { get(name: string): string | null };
+}
+
+export interface WallVerdict {
+	ok: boolean;
+	reason: string;
+}
+
+/** A bare host or a full URL, as its origin. */
+export function toOrigin(host: string): string {
+	const withScheme = /^https?:\/\//.test(host) ? host : `https://${host}`;
+	return new URL(withScheme).origin;
+}
+
+export interface WallTargets {
+	/** Whether this repo carries a route, by its file name in src/routes/. */
+	hasRoute: (name: string) => boolean;
+	/** The first file under public/images/, as a path from the host root. */
+	image?: string;
+	/** The first chunk under dist/client/assets/doc/, when the repo is built. */
+	docChunk?: string;
+	/** The first file under public/brand/, which must stay open. */
+	brand?: string;
+}
+
+/** The paths to ask for: the documents this repo carries, the held files, then the open mark. */
+export function wallProbes({ hasRoute, image, docChunk, brand }: WallTargets): Probe[] {
+	const probes: Probe[] = [{ path: "/writeup", kind: "document" }];
+	if (hasRoute("report")) probes.push({ path: "/report", kind: "document" });
+	if (hasRoute("proposal")) probes.push({ path: "/proposal", kind: "document" });
+	probes.push({ path: "/writeup.pdf", kind: "file" });
+	if (image) probes.push({ path: image, kind: "file" });
+	if (docChunk) probes.push({ path: docChunk, kind: "file" });
+	if (brand) probes.push({ path: brand, kind: "open" });
+	return probes;
+}
+
+/** The address the sign in request posts: on no allowlist, so no link is ever sent. */
+export const CHECK_EMAIL = "wall-check@example.com";
+
+/** The two sign in functions, asked by default after the wall's own probes. */
+export function signinProbes(): Probe[] {
+	return [
+		{
+			path: "/api/auth/request-link",
+			kind: "signin",
+			method: "POST",
+			body: { email: CHECK_EMAIL },
+		},
+		{ path: "/api/auth/verify?token=not-a-token", kind: "signin", method: "GET" },
+	];
+}
+
+/** The first file in a directory, sorted, as `prefix/name`; none if it is empty or absent. */
+export function firstFile(dir: string, prefix: string): string | undefined {
+	if (!existsSync(dir)) return undefined;
+	const name = readdirSync(dir, { withFileTypes: true })
+		.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+		.map((entry) => entry.name)
+		.sort()[0];
+	return name ? `${prefix}/${encodeURIComponent(name)}` : undefined;
+}
+
+const HOST_DOWN =
+	"the host is failing, not walled. On 2026-09-09 a new artifact host answered MIDDLEWARE_INVOCATION_FAILED on every page (ATE-537): verify the host answers before any link goes out.";
+
+/** Whether a brand mark answered open, as it must. */
+function classifyOpen(answer: WallAnswer, origin: string): WallVerdict {
+	const { status } = answer;
+	if (status === 200) {
+		return { ok: true, reason: `${status}: open on purpose, a brand mark the header draws` };
+	}
+	if (status >= 300 && status < 400) {
+		const location = answer.headers.get("location");
+		const toLogin = location && new URL(location, origin).pathname === "/login";
+		return {
+			ok: false,
+			reason: toLogin
+				? `${status} to /login: the wall holds a brand mark, so the login page asks for a file it cannot have. Brand marks stay open under /brand/ (needsSession in @atelic-action/ui/gate)`
+				: `${status} to ${location ?? "nowhere"}: a brand mark should answer 200`,
+		};
+	}
+	if (status > 200 && status < 300) {
+		return {
+			ok: false,
+			reason: `${status}: a brand mark should answer 200 with the file, not another success code`,
+		};
+	}
+	if (status === 404) {
+		return { ok: false, reason: "404: the brand mark is not on the host. Check the deploy" };
+	}
+	if (status >= 500) return { ok: false, reason: `${status}: ${HOST_DOWN}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	return { ok: false, reason: `${status}: a brand mark should answer 200` };
+}
+
+const FUNCTION_FAILED =
+	"the sign in function failed to load. On 2026-10-01 the first host with the wall armed answered FUNCTION_INVOCATION_FAILED here (ERR_MODULE_NOT_FOUND on an extensionless import), so the wall held every page and could send no link: the two files under api/auth/ must each be a re export from @atelic-action/ui, whose gate ships compiled for this reason";
+
+/** Whether a sign in function answered for itself, as it must. */
+function classifySignin(
+	probe: Extract<Probe, { kind: "signin" }>,
+	answer: WallAnswer,
+	origin: string,
+): WallVerdict {
+	const { status } = answer;
+	if (status >= 500) return { ok: false, reason: `${status}: ${FUNCTION_FAILED}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	if (status === 401 || status === 403) {
+		return {
+			ok: false,
+			reason: `${status}: Vercel Deployment Protection or another lock answered, not the function. Turn Deployment Protection off (DEPLOY.md)`,
+		};
+	}
+	if (status === 404) {
+		return { ok: false, reason: "404: the sign in function is not on the host. Check the deploy" };
+	}
+	const location = answer.headers.get("location");
+	if (probe.method === "POST") {
+		if (status === 200) {
+			return { ok: true, reason: "200: the request for a link answered, sending nothing" };
+		}
+		return {
+			ok: false,
+			reason: `${status}${location ? ` to ${location}` : ""}: the request for a link answers 200 to every address`,
+		};
+	}
+	// A token that is not one gets the function's own redirect, marked expired;
+	// the wall's redirect carries ?next= instead, so the two cannot be mistaken.
+	const target = location ? new URL(location, origin) : undefined;
+	if (
+		status === 302 &&
+		target?.pathname === "/login" &&
+		target.searchParams.get("e") === "expired"
+	) {
+		return { ok: true, reason: "302 to /login?e=expired: the verify answered a bad token" };
+	}
+	return {
+		ok: false,
+		reason: `${status}${location ? ` to ${location}` : ""}: the verify answers a bad token with a 302 to /login?e=expired`,
+	};
+}
+
+/**
+ * Whether one answer is the wall (or, for a brand mark, open, or for a sign
+ * in function, its own answer), and if not, what it is instead.
+ */
+export function classifyWall(probe: Probe, answer: WallAnswer, origin: string): WallVerdict {
+	if (probe.kind === "open") return classifyOpen(answer, origin);
+	if (probe.kind === "signin") return classifySignin(probe, answer, origin);
+	const { status } = answer;
+	if (status >= 300 && status < 400) {
+		const location = answer.headers.get("location");
+		if (location && new URL(location, origin).pathname === "/login") {
+			return { ok: true, reason: `${status} to /login: the wall answered` };
+		}
+		return {
+			ok: false,
+			reason: `${status} to ${location ?? "nowhere"}, not the wall's /login: something other than the wall answered`,
+		};
+	}
+	if (status >= 200 && status < 300) {
+		const type = answer.headers.get("content-type") ?? "no content type";
+		return probe.kind === "file"
+			? {
+					ok: false,
+					reason: `${status} (${type}): the file is served outside the wall, so anyone with its address can open it. Check the middleware is the current one (needsSession in @atelic-action/ui/gate) and that the wall is armed`,
+				}
+			: {
+					ok: false,
+					reason: `${status} (${type}): the document is served with no wall, so anyone with the link can read it. Arm the wall (ACCESS-GATE.md), redeploy, and run this again`,
+				};
+	}
+	if (status === 404) {
+		return probe.kind === "file"
+			? {
+					ok: false,
+					reason:
+						"404: the wall never ran for this file. It holds a path whether or not the file is there, so a miss means the middleware let the request through",
+				}
+			: {
+					ok: false,
+					reason: "404: the host does not serve this page. Check the deploy and the prerender list",
+				};
+	}
+	if (status === 401 || status === 403) {
+		return {
+			ok: false,
+			reason: `${status}: Vercel Deployment Protection or another lock answered, not the wall. Turn Deployment Protection off (DEPLOY.md) so the wall is what a reader meets`,
+		};
+	}
+	if (status >= 500) return { ok: false, reason: `${status}: ${HOST_DOWN}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	return { ok: false, reason: `${status}: an answer the wall never gives` };
+}
+
+export type Fetcher = (url: string, init: RequestInit) => Promise<WallAnswer>;
+
+/** The request for one probe: a GET unless a sign in probe says otherwise, with no cookie. */
+export function probeRequest(probe: Probe): RequestInit {
+	const headers: Record<string, string> = {
+		"user-agent": "Mozilla/5.0 (wall-check; +https://atelic.me)",
+	};
+	const init: RequestInit = {
+		method: probe.kind === "signin" ? probe.method : "GET",
+		redirect: "manual",
+		headers,
+		signal: AbortSignal.timeout(15000),
+	};
+	if (probe.kind === "signin" && probe.body) {
+		headers["content-type"] = "application/json";
+		init.body = JSON.stringify(probe.body);
+	}
+	return init;
+}
+
+/** Asks for every probe with no cookie and never follows a redirect. */
+export async function checkWall(origin: string, probes: Probe[], fetcher: Fetcher) {
+	const results: Array<Probe & WallVerdict> = [];
+	for (const probe of probes) {
+		let answer: WallAnswer;
+		try {
+			answer = await fetcher(`${origin}${probe.path}`, probeRequest(probe));
+		} catch {
+			answer = { status: 0, headers: { get: () => null } };
+		}
+		results.push({ ...probe, ...classifyWall(probe, answer, origin) });
+	}
+	return results;
+}
+
+/**
+ * The command. The routes, the images, the brand marks, and the build it
+ * reads are the site's, found from the working directory.
+ */
+export async function main(args: string[], root: string = process.cwd()): Promise<void> {
+	const [host, ...paths] = args;
+	if (!host) {
+		console.error("usage: bun run check:wall <host> [path ...]");
+		process.exit(2);
+	}
+	const origin = toOrigin(host);
+	const probes: Probe[] = paths.length
+		? paths.map((path) => ({
+				path,
+				kind: path.startsWith("/brand/")
+					? "open"
+					: /\.[a-z0-9]+$/i.test(path)
+						? "file"
+						: "document",
+			}))
+		: [
+				...wallProbes({
+					hasRoute: (name) => existsSync(join(root, "src", "routes", `${name}.tsx`)),
+					image: firstFile(join(root, "public", "images"), "/images"),
+					docChunk: firstFile(join(root, "dist", "client", "assets", "doc"), "/assets/doc"),
+					brand: firstFile(join(root, "public", "brand"), "/brand"),
+				}),
+				...signinProbes(),
+			];
+	if (!probes.some((probe) => probe.path.startsWith("/images/"))) {
+		console.warn("[wall] no file under public/images/ to ask for; the screenshots go unproven");
+	}
+	if (!probes.some((probe) => probe.path.startsWith("/assets/doc/"))) {
+		console.warn(
+			"[wall] no build in dist/client/assets/doc/; run bun run build first to prove the content chunks",
+		);
+	}
+	console.log(`[wall] asking ${origin} for ${probes.length} paths with no cookie`);
+	const results = await checkWall(origin, probes, (url, init) => fetch(url, init));
+	for (const result of results) {
+		const line = `  ${result.ok ? "ok" : "FAIL"} ${result.path}: ${result.reason}`;
+		if (result.ok) console.log(line);
+		else console.error(line);
+	}
+	const failed = results.filter((result) => !result.ok).length;
+	if (failed > 0) {
+		console.error(
+			`[wall] ${failed} of ${results.length} failed. No link goes out until this passes.`,
+		);
+		process.exit(1);
+	}
+	const signin = probes.some((probe) => probe.kind === "signin");
+	console.log(
+		signin
+			? "[wall] the wall holds every document and file asked for, the brand mark is open, and the sign in functions answered"
+			: "[wall] the wall holds every document and file asked for, and the brand mark is open",
+	);
+}

package/src/scripts/reader-link.ts

@@ -0,0 +1,108 @@
+/**
+ * Mint a named reader and print the two things that come of it: the line
+ * that goes in site.config.ts and the link that goes in the email. Every
+ * link sent to a named person carries their token, so their open lands on
+ * their contact in HubSpot (DEPLOY.md, Who Opened It).
+ *
+ * The config line holds the reader sealed: a digest of the token and the
+ * email encrypted under it. The token itself appears only in the link, so
+ * keep the link; it cannot be printed again.
+ *
+ * A writeup's reader also gets the printed copy's QR: public/images/qr.png
+ * is written to carry the same link, so a scan of the sheet lands on that
+ * person's contact as an emailed open does. Mint the reader before printing.
+ *
+ * The sheet belongs to the first reader named. A later reader never
+ * repoints it: with a reader already in analytics.identify the QR is left
+ * alone unless --qr asks for it.
+ *
+ * Usage: atelic-reader-link <email> [path] [--token <existing token>] [--qr | --no-qr],
+ *   or `bun run reader <email>` in a site, from the site's root.
+ *   path defaults to /writeup. --token seals an email under a token that is
+ *   already in a sent link, so that link keeps working. --qr writes the QR
+ *   for this reader even when another is already named; --no-qr never writes it.
+ */
+import { resolve } from "node:path";
+import QRCode from "qrcode";
+import { mintToken, readerLink, sealReader } from "../artifact/readers";
+import { loadSite } from "./site-config";
+
+export const USAGE =
+	"Usage: bun run reader <email> [path] [--token <existing token>] [--qr | --no-qr]";
+
+/** What the command line asked for. */
+export interface ReaderArgs {
+	email: string;
+	/** The page the link opens, always with one leading slash and none trailing. */
+	path: string;
+	/** A token already in a sent link, when --token gave one. */
+	token?: string;
+	/** --qr: write the QR for this reader even when another is already named. */
+	forceQr: boolean;
+	/** --no-qr: never write the QR. */
+	noQr: boolean;
+}
+
+/** Reads the command line; undefined when it does not name a reader, which is a usage error. */
+export function parseReaderArgs(flags: string[]): ReaderArgs | undefined {
+	const noQr = flags.includes("--no-qr");
+	const forceQr = flags.includes("--qr");
+	const args = flags.filter((flag) => flag !== "--no-qr" && flag !== "--qr");
+	const at = args.indexOf("--token");
+	const given = at === -1 ? undefined : args[at + 1];
+	const rest = at === -1 ? args : args.filter((_, index) => index !== at && index !== at + 1);
+	const [email, givenPath = "/writeup"] = rest;
+	// "writeup", "/writeup", and "/writeup/" are one page.
+	const path = `/${givenPath.replace(/^\/+|\/+$/g, "")}`;
+
+	if (!email?.includes("@") || (at !== -1 && !given)) return undefined;
+	return { email, path, token: given, forceQr, noQr };
+}
+
+/**
+ * The command. The config it reads and the QR it writes are the site's,
+ * found from the working directory.
+ */
+export async function main(flags: string[], cwd: string = process.cwd()): Promise<void> {
+	const parsed = parseReaderArgs(flags);
+	if (!parsed) {
+		console.error(USAGE);
+		process.exit(1);
+	}
+	const { email, path, forceQr, noQr } = parsed;
+	let site: Awaited<ReturnType<typeof loadSite>>;
+	try {
+		site = await loadSite(cwd);
+	} catch (error) {
+		console.error(`[reader] ${(error as Error).message}`);
+		process.exit(1);
+	}
+
+	const token = parsed.token ?? mintToken();
+	const reader = await sealReader(email, token);
+	console.log("Add to analytics.identify in src/site.config.ts:");
+	console.log(`  { id: "${reader.id}", sealed: "${reader.sealed}" }, // ${email.split("@")[1]}`);
+	console.log("");
+	console.log("Send this link, and only to that person. Keep it: it cannot be printed again.");
+	const link = readerLink(site.url, token, path);
+	console.log(`  ${link}`);
+
+	// The sheet's QR is the reader's link. A private artifact identifies by sign
+	// in and never by a token, so its QR stays on the bare host.
+	const named = site.analytics?.identify.length ?? 0;
+	const sheetIsFree = named === 0 || forceQr;
+	if (path === "/writeup" && !noQr && site.access === "public" && !sheetIsFree) {
+		console.log("");
+		console.log(
+			"Left public/images/qr.png alone: a reader is already named, and the sheet is theirs. Pass --qr to give the sheet to this reader.",
+		);
+	}
+	if (path === "/writeup" && !noQr && site.access === "public" && sheetIsFree) {
+		const qr = resolve(cwd, "public/images/qr.png");
+		await QRCode.toFile(qr, link, { width: 330, margin: 4, errorCorrectionLevel: "M" });
+		console.log("");
+		console.log(
+			"Wrote public/images/qr.png with that link. Print the sheet after this, never before.",
+		);
+	}
+}

package/src/scripts/serve-static.ts

@@ -0,0 +1,47 @@
+/**
+ * Serves dist/client the way Vercel does for these sites: a file as is, a
+ * clean URL from its .html file or folder index, and anything else as
+ * 404.html with a real 404 status. Only the e2e suite uses it; production
+ * never runs a server. The build it serves is the site's, found from the
+ * working directory.
+ *
+ * Usage: atelic-serve-static   (PORT sets the port, 4173 unless given)
+ */
+import { existsSync, statSync } from "node:fs";
+import { join, normalize } from "node:path";
+
+/** The file a request path names under `root`, by Vercel's clean URL rules; none on a miss. */
+export function resolveFile(root: string, pathname: string): string | undefined {
+	const clean = normalize(decodeURIComponent(pathname)).replace(/^(\.\.[/\\])+/, "");
+	const candidates = [
+		join(root, clean),
+		join(root, `${clean}.html`),
+		join(root, clean, "index.html"),
+	];
+	return candidates.find(
+		(file) => file.startsWith(root) && existsSync(file) && statSync(file).isFile(),
+	);
+}
+
+/** The command: serves dist/client of the working directory until stopped. */
+export function main(cwd: string = process.cwd()): void {
+	const root = join(cwd, "dist", "client");
+	const port = Number(process.env.PORT ?? 4173);
+
+	Bun.serve({
+		// Loopback only: this serves the build to the local browser under test and
+		// has no business answering anyone else on the network.
+		hostname: "127.0.0.1",
+		port,
+		fetch(request) {
+			const file = resolveFile(root, new URL(request.url).pathname);
+			if (file) return new Response(Bun.file(file));
+			return new Response(Bun.file(join(root, "404.html")), {
+				status: 404,
+				headers: { "content-type": "text/html; charset=utf-8" },
+			});
+		},
+	});
+
+	console.log(`serving ${root} on http://127.0.0.1:${port}`);
+}

package/src/scripts/site-config.ts

@@ -0,0 +1,34 @@
+/**
+ * Finds the site a command was run in. A command lives in the package, so
+ * it cannot import the site's config by a relative path as a script in the
+ * site once did: it resolves src/site.config.ts against the directory it
+ * was run from and imports that.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ArtifactConfig } from "../artifact/artifactConfig";
+
+/** Where a site keeps its config, from the site's root. */
+export const SITE_CONFIG = "src/site.config.ts";
+
+/** The absolute path of the config for the site rooted at `cwd`. */
+export function siteConfigPath(cwd: string = process.cwd()): string {
+	return resolve(cwd, SITE_CONFIG);
+}
+
+/**
+ * The `site` export of the config in `cwd`. Throws one line naming the
+ * directory when there is no config there, or when it exports no `site`.
+ */
+export async function loadSite(cwd: string = process.cwd()): Promise<ArtifactConfig> {
+	const path = siteConfigPath(cwd);
+	if (!existsSync(path)) {
+		throw new Error(`no ${SITE_CONFIG} in ${cwd}. Run this from the root of an artifact site.`);
+	}
+	const module = (await import(pathToFileURL(path).href)) as { site?: ArtifactConfig };
+	if (!module.site) {
+		throw new Error(`${SITE_CONFIG} in ${cwd} exports no \`site\`.`);
+	}
+	return module.site;
+}

package/src/scripts/stamp-health.ts

@@ -0,0 +1,29 @@
+/**
+ * Writes dist/client/health.json after the build: a shallow health endpoint
+ * for uptime monitors that also answers "which build is live?".
+ * Runs as the last step of `bun build`, from the site's root.
+ *
+ * Usage: atelic-stamp-health
+ */
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+
+function commitSha(): string {
+	// Vercel builds have no .git directory; the CLI/CI export the sha instead.
+	const fromEnv = process.env.VERCEL_GIT_COMMIT_SHA ?? process.env.GITHUB_SHA;
+	if (fromEnv) return fromEnv.slice(0, 7);
+	const git = spawnSync("git", ["rev-parse", "--short", "HEAD"], { encoding: "utf8" });
+	return git.status === 0 ? git.stdout.trim() : "unknown";
+}
+
+/** The command: stamps the build in the working directory. */
+export function main(): void {
+	const health = {
+		status: "ok",
+		commit: commitSha(),
+		builtAt: new Date().toISOString(),
+	};
+
+	writeFileSync("dist/client/health.json", `${JSON.stringify(health, null, "\t")}\n`);
+	console.log(`[health] dist/client/health.json (${health.commit})`);
+}

package/src/vite/artifact-config.ts

@@ -0,0 +1,105 @@
+/**
+ * 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, type UserConfig } from "vite";
+import { privateChunks } from "./private-chunks.js";
+
+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 function artifactPages(pages: readonly string[]): ArtifactPage[] {
+	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): ArtifactPage => ({ 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 }: ArtifactConfigOptions): UserConfig {
+	const config: UserConfig = {
+		// 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;
+}