@atelic-action/ui 3.3.1 → 3.5.0

package/README.md

@@ -22,6 +22,7 @@ Every export, grouped by the entry it is imported from. The gallery column links
 | `Checklist` | `@atelic-action/ui/components` | A short list of checks, each passed or failed | [#checklist](https://ui.atelic.me/#checklist) |
 | `IconList` | `@atelic-action/ui/components` | A list whose bullets are icons, one for the list or one per item, each in a tone | [#icon-list](https://ui.atelic.me/#icon-list) |
 | `DataTable` | `@atelic-action/ui/components` | A table whose first column names each row, sortable, stacking on a phone | [#data-table](https://ui.atelic.me/#data-table) |
+| `Hint` | `@atelic-action/ui/components` | An info icon that opens a short explainer beside a word, or beside a table heading | [#hint](https://ui.atelic.me/#hint) |
 | `ReportCard` | `@atelic-action/ui/components` | A name, a grade, and a line per row, in labeled groups, each row a link to its section | [#report-card](https://ui.atelic.me/#report-card) |
 | `reportCardLabels`, `ReportCardLabels` | `@atelic-action/ui/components` | The words a screen reader hears around a report card's letters by default, and their type | none |
 | `Rank` | `@atelic-action/ui/components` | A figure with its badge in a tone, for a table cell: a rank, a place in an answer, or a dash | [#rank](https://ui.atelic.me/#rank) |
@@ -366,7 +367,7 @@ The pieces import no stylesheet of their own. A site imports `@atelic-action/ui/
 // vite.config.ts
 import { artifactConfig } from "@atelic-action/ui/vite";
 
-export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
+export default artifactConfig({ pages: ["/the-read", "/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", "@atelic-action/artifact"]`, so the documents compile too. 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.
@@ -375,7 +376,7 @@ A site with a real need of its own passes `extend`, which is merged over the res
 
 ```ts
 export default artifactConfig({
-	pages: ["/writeup"],
+	pages: ["/the-read"],
 	extend: { server: { port: 5180 } },
 });
 ```
@@ -398,7 +399,7 @@ The package installs the scripts every artifact site used to carry as files, so
 | `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-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 read'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 that `@atelic-action/artifact`'s `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` |
@@ -703,7 +704,8 @@ The blocks a page composes, each styled in `styles/components.css` inside the `a
 | `IconList` | A list whose bullets are icons | `icon` and `tone` on the list set every bullet; an item's own override them. The bullet is decoration, so a screen reader hears only the items. A dot when no icon is set; the text's color when no tone is |
 | `ReportCard` | A name, a grade, and one line on it per row, in labeled groups, each row's parts centered on it | A row with `href` is a link from edge to edge with a chevron at its end; a link inside `line` still goes where it points. `before` sets the earlier grade faded beside the grade; no `grade` draws a dash read as not graded. `legend` explains the letters beside the `title`, or under the card with `legendAt="foot"`; `labels` sets the screen reader's words. The grade is `GradeChip` |
 | `Rank` | A figure with its badge, for a table cell | `figure` is the rank, the place, or a dash for none; `tone` colors the badge and `meaning` names it for a screen reader; `href` links the figure, in a new tab with `newTab`. The figure's slot is a fixed width, so the badges line up down a column |
-| `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server. Every other row sits on a tinted ground; `striped={false}` turns that off. A column marked `fit` hugs its content, for a swatch or a mark beside a figure |
+| `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server. Every other row sits on a tinted ground; `striped={false}` turns that off. A column marked `fit` hugs its content, for a swatch or a mark beside a figure. A column with a `hint` draws a `Hint` beside its heading, before the label when the column is right aligned; on a phone the heading row is hidden, so the hint is too |
+| `Hint` | An info icon that opens a short explainer beside a word | Opens on hover or focus, stays open on a click or a tap, closes on Escape or a tap elsewhere. The bubble opens from the icon's left edge and slides left when it would run off the screen. `side="before"` puts the icon before its word, for a right aligned heading. `label` is what a screen reader calls the button; the bubble is its description. Print hides it |
 | `StatRow` | A row of large figures, each over what it counts and its `period`. `variant="quiet"` is the glance row for a working page: a light figure in the text color over a small capitalized label, hairlines between; `unit` sets a figure's unit small beside it | `trend` draws an arrow before a figure that is itself a change. `deltas` list comparisons beneath: an arrow, how far, against what (`basis`), and the earlier figure (`was`), each in its own tone, since a spend falling and a cost falling read differently |
 | `Callout` | One finding: an icon in its tone beside the title, the explainer under it | `variant="box"` sets it apart on a tinted ground, for something missing or owed |
 | `Disclosure` | A section the reader opens and closes, in two forms chosen by whether `open` is passed | Controlled (`open` and `onToggle`), it is an app's card: the caller remembers what was folded, a closed body is not rendered, the label is the toggle, `meta` (a count, a flag) sits beside it outside its name, and `headingLevel` makes the label a real heading. Uncontrolled, it is a document's fold: a native `details` with a `summary` line that carries the point and `defaultOpen`, so it works before any script loads, find in page opens it, and it prints open. `Collapsible`, the fold's old name, was folded in at 0.18.0 |

package/bin/atelic-print-sheets.sh

@@ -1,21 +1,21 @@
 #!/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
+# count. The read flows across as many letter pages as it needs, its
 # native disclosures 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 public/the-read.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
+#   atelic-print-sheets https://summit.atelic.me/the-read ../2026-09-10-the-read.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 is the path printed from it, /the-read unless named. A URL is printed
+# as given. The read's PDF belongs in public/ as the-read.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.
@@ -24,7 +24,7 @@ set -euo pipefail
 TARGET=${1:?url or built directory required}
 OUT=${2:?output pdf path required}
 EXPECT=${3:-}
-PAGE=${4:-/writeup}
+PAGE=${4:-/the-read}
 PORT=${5:-8765}
 CHROME=${CHROME:-"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"}
 [[ -x "$CHROME" ]] || { echo "Chrome not found at $CHROME" >&2; exit 1; }

package/dist/artifact/readers.js

@@ -110,7 +110,7 @@ export async function whoIsReading(visit) {
     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") {
+export function readerLink(siteURL, token, path = "/the-read") {
     const url = new URL(path, siteURL);
     url.searchParams.set("k", token);
     return url.toString();

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

@@ -1,7 +1,7 @@
 import { type UserConfig } from "vite";
 export interface ArtifactConfigOptions {
     /**
-     * The path of each artifact page the site carries, such as "/writeup".
+     * The path of each artifact page the site carries, such as "/the-read".
      * The root and the 404 page are always prerendered and need no entry.
      */
     pages: readonly string[];

package/dist/vite/artifact-config.js

@@ -5,7 +5,7 @@
  *
  *   import { artifactConfig } from "@atelic-action/ui/vite";
  *
- *   export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
+ *   export default artifactConfig({ pages: ["/the-read", "/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.
@@ -19,7 +19,7 @@ import { privateChunks } from "./private-chunks.js";
 export function artifactPages(pages) {
     const named = pages.filter((path) => path !== "/" && path !== "/404");
     return [
-        // The root holds no document: it sends the reader to /writeup
+        // The root holds no document: it sends the reader to /the-read
         // (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 } },
@@ -44,10 +44,10 @@ export function artifactConfig({ pages, extend }) {
                 prerender: {
                     enabled: true,
                     crawlLinks: true,
-                    // The writeup links each screenshot crop to its full image, and
+                    // The read 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,
+                    // over the real file in dist/client (found on a client's read,
                     // 2026-09-24).
                     filter: ({ path }) => !path.startsWith("/images/"),
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "3.3.1",
+	"version": "3.5.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/artifact/readers.ts

@@ -139,7 +139,7 @@ export async function whoIsReading(visit: {
 }
 
 /** The link to send a reader: the artifact's page with their token on it. */
-export function readerLink(siteURL: string, token: string, path = "/writeup"): string {
+export function readerLink(siteURL: string, token: string, path = "/the-read"): string {
 	const url = new URL(path, siteURL);
 	url.searchParams.set("k", token);
 	return url.toString();

package/src/components/DataTable.tsx

@@ -1,5 +1,6 @@
 import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
 import { type ReactNode, useId, useMemo, useState } from "react";
+import { Hint } from "./Hint";
 
 export type SortDirection = "asc" | "desc";
 
@@ -15,6 +16,10 @@ export interface DataTableColumn {
 	firstSort?: SortDirection;
 	/** The column hugs its content (a swatch, a mark) instead of sharing the width. */
 	fit?: boolean;
+	/** A short explainer behind an info icon beside the heading, for a measure a reader may not know. */
+	hint?: ReactNode;
+	/** What a screen reader calls the hint's button; defaults to "About" and the label. */
+	hintLabel?: string;
 }
 
 /** A cell whose display is not what it sorts by, e.g. an icon over a number. */
@@ -140,9 +145,22 @@ export function DataTable({
 						{columns.map((column, index) => {
 							const active = sort?.column === index;
 							const Icon = !active ? ArrowUpDown : sort?.direction === "asc" ? ArrowUp : ArrowDown;
+							// The explainer's icon sits after the label, or before it when the
+							// column is right aligned, so the icon stays on the inside edge.
+							const before = column.align === "right";
+							const hint = column.hint ? (
+								<Hint
+									label={column.hintLabel ?? `About ${column.label}`}
+									side={before ? "before" : "after"}
+								>
+									{column.hint}
+								</Hint>
+							) : null;
 							const head = {
 								"data-align": column.align ?? "left",
 								"data-fit": column.fit || undefined,
+								// The hint button sits in the heading; the heading is still named by its label.
+								"aria-label": column.hint && column.label ? column.label : undefined,
 								"aria-sort": column.sortable
 									? active
 										? sort?.direction === "asc"
@@ -154,6 +172,7 @@ export function DataTable({
 							return (
 								// biome-ignore lint/suspicious/noArrayIndexKey: columns sit in order, and two may share a blank label
 								<th scope="col" key={index} {...head}>
+									{before && hint}
 									{column.sortable ? (
 										<button
 											type="button"
@@ -166,6 +185,7 @@ export function DataTable({
 									) : (
 										column.label
 									)}
+									{!before && hint}
 								</th>
 							);
 						})}

package/src/components/Hint.tsx

@@ -0,0 +1,138 @@
+import { Info } from "lucide-react";
+import {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useId,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+
+export interface HintProps {
+	/** What the button is called, for a screen reader, e.g. "About First paint". */
+	label: string;
+	/** Which side of its word the icon sits on; `before` for a right aligned heading. */
+	side?: "before" | "after";
+	className?: string;
+	/** The bubble's text: a sentence or two in plain words. */
+	children: ReactNode;
+}
+
+/**
+ * An info bubble: a small icon beside a word that opens a short explainer.
+ * It opens on hover or focus and stays open on a click or a tap, so it works
+ * on a phone, and Escape or a tap elsewhere closes it. The bubble opens
+ * from the icon's left edge and flips to its right edge when it would run
+ * off the screen. It is read to a screen reader as the button's
+ * description; print hides the icon, since a printed sheet cannot be tapped.
+ */
+export function Hint({ label, side = "after", className, children }: HintProps) {
+	const [open, setOpen] = useState(false);
+	const [pinned, setPinned] = useState(false);
+	// Keyboard focus holds the bubble open until it leaves; mouse focus, which
+	// a click also gives the button, must not, or a later hover sticks open.
+	const [keyboard, setKeyboard] = useState(false);
+	const [shift, setShift] = useState(0);
+	const id = useId();
+	const root = useRef<HTMLSpanElement>(null);
+	const bubble = useRef<HTMLSpanElement>(null);
+
+	const close = useCallback(() => {
+		setOpen(false);
+		setPinned(false);
+		setKeyboard(false);
+	}, []);
+
+	useEffect(() => {
+		if (!open) return;
+		const away = (event: PointerEvent) => {
+			if (!root.current?.contains(event.target as Node)) close();
+		};
+		const key = (event: KeyboardEvent) => {
+			if (event.key === "Escape") close();
+		};
+		document.addEventListener("pointerdown", away);
+		document.addEventListener("keydown", key);
+		return () => {
+			document.removeEventListener("pointerdown", away);
+			document.removeEventListener("keydown", key);
+		};
+	}, [open, close]);
+
+	// Opens from the icon's left edge, then slides left just far enough to
+	// stay on screen, and never past the screen's left edge.
+	useLayoutEffect(() => {
+		if (!open || !bubble.current || !root.current) return;
+		const icon = root.current.getBoundingClientRect();
+		const width = bubble.current.getBoundingClientRect().width;
+		const room = document.documentElement.clientWidth - 8;
+		const slide = Math.min(0, room - (icon.left + width));
+		setShift(Math.max(slide, 8 - icon.left));
+	}, [open]);
+
+	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: focusout bubbles to the root so focus leaving the button or the bubble closes it
+		<span
+			ref={root}
+			className={["hint", className].filter(Boolean).join(" ")}
+			data-side={side}
+			data-open={open || undefined}
+			onBlur={(event) => {
+				// Focus moving between the button and the bubble is not leaving.
+				if (root.current?.contains(event.relatedTarget as Node | null)) return;
+				close();
+			}}
+			onPointerEnter={(event) => {
+				// A finger never hovers: a tap opens through the click instead.
+				if (event.pointerType !== "touch") setOpen(true);
+			}}
+			onPointerLeave={(event) => {
+				if (event.pointerType === "touch" || pinned || keyboard) return;
+				setOpen(false);
+			}}
+		>
+			<button
+				type="button"
+				aria-label={label}
+				aria-describedby={id}
+				aria-expanded={open}
+				onFocus={(event) => {
+					// :focus-visible is the browser's own word for keyboard focus; a press
+					// that focuses the button does not match it. Where the selector is
+					// unknown, focus counts as the keyboard's.
+					let visible = true;
+					try {
+						visible = event.currentTarget.matches(":focus-visible");
+					} catch {
+						visible = true;
+					}
+					if (visible) {
+						setKeyboard(true);
+						setOpen(true);
+					}
+				}}
+				onClick={() => {
+					if (pinned) close();
+					else {
+						setPinned(true);
+						setOpen(true);
+					}
+				}}
+			>
+				<Info size={14} aria-hidden="true" />
+			</button>
+			<span
+				ref={bubble}
+				role="tooltip"
+				id={id}
+				className="hint-bubble"
+				style={shift ? { left: shift } : undefined}
+				// A press on the bubble's text must not pull focus off the button.
+				onMouseDown={(event) => event.preventDefault()}
+			>
+				{children}
+			</span>
+		</span>
+	);
+}

package/src/components/index.ts

@@ -23,6 +23,7 @@ export {
 	type DisclosureProps,
 } from "./Disclosure";
 export { GateLogin, type GateLoginProps } from "./GateLogin";
+export { Hint, type HintProps } from "./Hint";
 export { IconList, type IconListItem, type IconListProps } from "./IconList";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { Rank, type RankProps } from "./Rank";

package/src/scripts/check-wall.ts

@@ -6,9 +6,9 @@
  * 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
+ * The documents are /the-read, 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
+ * also asks for the printed copy at /the-read.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
@@ -30,7 +30,7 @@
  * 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
+ *   bun run check:wall https://summit.atelic.me /the-read /report
  * The sign in functions are asked only when no path is named.
  * Exits 1 unless every path answers as it must.
  */
@@ -93,10 +93,10 @@ export interface WallTargets {
 
 /** 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" }];
+	const probes: Probe[] = [{ path: "/the-read", 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" });
+	probes.push({ path: "/the-read.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" });

package/src/scripts/reader-link.ts

@@ -8,7 +8,7 @@
  * 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
+ * A read'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.
  *
@@ -18,7 +18,7 @@
  *
  * 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
+ *   path defaults to /the-read. --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.
  */
@@ -51,8 +51,8 @@ export function parseReaderArgs(flags: string[]): ReaderArgs | undefined {
 	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 [email, givenPath = "/the-read"] = rest;
+	// "the-read", "/the-read", and "/the-read/" are one page.
 	const path = `/${givenPath.replace(/^\/+|\/+$/g, "")}`;
 
 	if (!email?.includes("@") || (at !== -1 && !given)) return undefined;
@@ -91,13 +91,13 @@ export async function main(flags: string[], cwd: string = process.cwd()): Promis
 	// 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) {
+	if (path === "/the-read" && !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) {
+	if (path === "/the-read" && !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("");

package/src/styles/components.css

@@ -899,6 +899,78 @@
 		white-space: nowrap;
 	}
 
+	/* ---- Hint: an info icon that opens a short bubble on hover, focus, or a
+	   tap, from the icon's left edge unless that runs off the screen; hidden
+	   in print ---- */
+	.atelic-ui .hint {
+		position: relative;
+		display: inline-block;
+		vertical-align: middle;
+		margin-left: 4px;
+		line-height: 0;
+	}
+	.atelic-ui .hint[data-side="before"] {
+		margin: 0 4px 0 0;
+	}
+	.atelic-ui .hint > button {
+		display: inline-grid;
+		place-items: center;
+		width: 18px;
+		height: 18px;
+		padding: 0;
+		border: 0;
+		border-radius: 999px;
+		background: transparent;
+		color: var(--neutral-500);
+		cursor: pointer;
+	}
+	.atelic-ui .hint > button:hover,
+	.atelic-ui .hint > button:focus-visible,
+	.atelic-ui .hint[data-open] > button {
+		color: var(--ink);
+	}
+	.atelic-ui .hint-bubble {
+		display: none;
+		position: absolute;
+		top: calc(100% + 6px);
+		left: 0;
+		z-index: 20;
+		width: max-content;
+		max-width: min(280px, 80vw);
+		padding: 8px 10px;
+		border: 1px solid var(--neutral-200);
+		border-radius: var(--radius-sm);
+		background: var(--ui-card, var(--card));
+		box-shadow: var(--shadow-md, 0 6px 20px rgb(0 0 0 / 0.1));
+		color: var(--ink);
+		font-family: var(--font-sans, inherit);
+		font-size: 0.8rem;
+		font-weight: 400;
+		line-height: 1.45;
+		letter-spacing: normal;
+		text-transform: none;
+		text-align: left;
+		white-space: normal;
+		text-wrap: pretty;
+	}
+	/* Bridges the gap to the icon so the pointer can cross into the bubble. */
+	.atelic-ui .hint-bubble::before {
+		content: "";
+		position: absolute;
+		left: 0;
+		right: 0;
+		top: -8px;
+		height: 8px;
+	}
+	.atelic-ui .hint[data-open] .hint-bubble {
+		display: block;
+	}
+	@media print {
+		.atelic-ui .hint {
+			display: none;
+		}
+	}
+
 	/* ---- DataTable: on a phone each row stacks, its facts wearing their
 	   column's label, and a dropdown sorts; wide, it is a table whose
 	   headings sort ---- */
@@ -1058,6 +1130,19 @@
 			flex: none;
 			opacity: 0.55;
 		}
+		/* A Hint's button is not a sort button: keep its own look against the bare heading rules. */
+		.atelic-ui .data-table thead th .hint > button {
+			display: inline-grid;
+			color: var(--neutral-500);
+		}
+		.atelic-ui .data-table thead th .hint > button:hover,
+		.atelic-ui .data-table thead th .hint > button:focus-visible,
+		.atelic-ui .data-table thead th .hint[data-open] > button {
+			color: var(--ink);
+		}
+		.atelic-ui .data-table thead th .hint > button svg {
+			opacity: 1;
+		}
 		.atelic-ui .data-table thead th button[data-active] svg {
 			opacity: 1;
 		}
@@ -1076,6 +1161,12 @@
 			border-bottom: 0;
 		}
 	}
+	/* The phone hides the heading row, so a column hint goes with it. */
+	@media screen and (width < 721px) {
+		.atelic-ui .data-table thead .hint {
+			display: none;
+		}
+	}
 	@media print {
 		.atelic-ui .data-table thead th button svg {
 			display: none;

package/src/vite/artifact-config.ts

@@ -5,7 +5,7 @@
  *
  *   import { artifactConfig } from "@atelic-action/ui/vite";
  *
- *   export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
+ *   export default artifactConfig({ pages: ["/the-read", "/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.
@@ -18,7 +18,7 @@ import { privateChunks } from "./private-chunks.js";
 
 export interface ArtifactConfigOptions {
 	/**
-	 * The path of each artifact page the site carries, such as "/writeup".
+	 * The path of each artifact page the site carries, such as "/the-read".
 	 * The root and the 404 page are always prerendered and need no entry.
 	 */
 	pages: readonly string[];
@@ -40,7 +40,7 @@ export interface ArtifactPage {
 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
+		// The root holds no document: it sends the reader to /the-read
 		// (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 } },
@@ -66,10 +66,10 @@ export function artifactConfig({ pages, extend }: ArtifactConfigOptions): UserCo
 				prerender: {
 					enabled: true,
 					crawlLinks: true,
-					// The writeup links each screenshot crop to its full image, and
+					// The read 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,
+					// over the real file in dist/client (found on a client's read,
 					// 2026-09-24).
 					filter: ({ path }) => !path.startsWith("/images/"),
 				},