@atelic-action/artifact 1.0.0 → 1.2.0

package/README.md

@@ -24,10 +24,10 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `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 in three beats, the plan in order | `/read` |
-| `readLabels`, `ReadLabels` | The fixed words the read sets (the gist table's columns, the three beats, the plan's heading), each overridable through `labels` | `/read` |
-| `ReadTier`, `ReadSection`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadSource`, `ReadLink`, `ReadParagraph` | The shapes a read'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, all three 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` |
@@ -36,7 +36,7 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `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).
+What a document is built from stays in `@atelic-action/ui`, and this package imports it rather than copying it: `GradeChip`, `gradeLabel`, `SignOff`, `Shot` (the owner's screen), `Paragraph`, `Runs`, `isEmpty`, `ArtifactAnchor` (the plain data paragraph of the note and the read), 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.
 
 ## Install
 
@@ -44,7 +44,7 @@ What a document is built from stays in `@atelic-action/ui`, and this package imp
 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.
+Peer dependencies: `@atelic-action/ui` at `^2.0.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";
@@ -57,13 +57,13 @@ 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)
+3. `@atelic-action/ui/styles/artifact.css`, the pieces the documents share (the grade chip, the sign off, the shot, the shell's logo, and the shell's print rules that drop the header, the credit band, and the skip link); it sets no `@page`
 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.
+From 1.2.0 the two sheets do not overlap: ui 2.0.0's `artifact.css` holds only the pieces, and this sheet holds only the documents and both `@page` rules. A site on ui 1.x stays on artifact 1.1.x, which carries the shot's rules and the shell's print rules itself.
 
 ## Tech Stack
 
@@ -89,7 +89,7 @@ No environment variables required. Visit [http://localhost:5173](http://localhos
 
 ## 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`, `publishConfig`, `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:
+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`.
@@ -149,7 +149,6 @@ A document is fixed or grown here, in `src/documents/`, with its test in `tst/do
 
 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,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "1.0.0",
+	"version": "1.2.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",
@@ -8,9 +8,6 @@
 		"type": "git",
 		"url": "git+https://github.com/atelic-action/artifact.git"
 	},
-	"publishConfig": {
-		"access": "public"
-	},
 	"files": [
 		"src/documents"
 	],
@@ -40,12 +37,12 @@
 		"format": "biome format . --write"
 	},
 	"peerDependencies": {
-		"@atelic-action/ui": "^1.1.0",
+		"@atelic-action/ui": "^2.0.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0"
 	},
 	"devDependencies": {
-		"@atelic-action/ui": "^1.1.0",
+		"@atelic-action/ui": "^2.0.0",
 		"@biomejs/biome": "^2.0.0",
 		"@playwright/test": "^1.60.0",
 		"@sentry/react": "^10.0.0",

package/src/documents/Note.tsx

@@ -1,13 +1,15 @@
-import { SignOff, type WriteupPerson } from "@atelic-action/ui/artifact";
-import { Callout } from "@atelic-action/ui/components";
 import {
 	type ArtifactLink,
 	type ArtifactParagraph,
 	isEmpty,
 	ArtifactAnchor as NoteAnchor,
 	Paragraph,
-} from "./Paragraph";
-import { Shot, type WriteupShot } from "./Shot";
+	Shot,
+	SignOff,
+	type WriteupPerson,
+	type WriteupShot,
+} from "@atelic-action/ui/artifact";
+import { Callout } from "@atelic-action/ui/components";
 
 /**
  * The note: the first touch, for a business whose site publishes no email

package/src/documents/Read.tsx

@@ -1,34 +1,45 @@
 import {
+	type ArtifactLink,
+	type ArtifactParagraph,
 	GradeChip,
 	gradeLabel,
+	isEmpty,
 	newTabProps,
+	Paragraph,
+	Runs,
+	Shot,
 	SignOff,
 	type WriteupGrade,
 	type WriteupPerson,
+	type WriteupShot,
 } from "@atelic-action/ui/artifact";
-import { ArrowUpRight } from "lucide-react";
-import { type ArtifactLink, type ArtifactParagraph, isEmpty, Paragraph, Runs } from "./Paragraph";
-import { Shot, type WriteupShot } from "./Shot";
+import { ArrowUpRight, Check } from "lucide-react";
 
 /**
  * The read: what a customer gets at the end of an engagement's first week,
  * before anything changes. Where the writeup says what letter each section
  * earned, the read says why, and what changes. Its shape is the practice's
  * FOOTPRINT.md, under What the Owner Gets: a title and a dated lede; the gist
- * table (every section, its grade, and one line); then the tiers, each
- * section a question in three beats (what we found, why, what changes) with
- * any proof pictures and the tools it was read from; then the plan, in order;
- * then one closing line and the sign off.
+ * table (every section, its grade, and one line); then the tiers; then the
+ * plan, in order; then one closing line and the sign off.
+ *
+ * Each section reads as an aggregator of the tools we looked through, top to
+ * bottom: where we looked (the tools, linked, each with an optional line);
+ * what it showed (a short paragraph or two, a compact table of facts, lists
+ * of examples, and any proof pictures); why, in one sentence on a tinted
+ * panel; today and after, a two column table of what a thing is and what it
+ * becomes; and what we recommend, as a checklist. A beat with nothing in it
+ * is left out, heading and all.
  *
  * It is the writeup's sibling, not a variant: it wears the writeup's column,
- * head, grade chip and key, tier heading, section card, screen, sources, and
- * close (the `.op` classes), and adds only what is its own (the `.rd`
- * classes). The gist table is drawn from the tiers, so a tier added later
- * (Conversion, once the analytics access lands) is one more entry in `tiers`
- * and appears in the table and the body alike, with no change to the props.
- * Every prop is plain data, so a routine can write a read as JSON; the one
- * exception is the sign off person's `role`, which takes a node and is
- * equally happy with a string.
+ * head, grade chip and key, tier heading, section card, screen, and close
+ * (the `.op` classes), and adds only what is its own (the `.rd` classes).
+ * The gist table is drawn from the tiers, so a tier added later (Conversion,
+ * once the analytics access lands) is one more entry in `tiers` and appears
+ * in the table and the body alike, with no change to the props. Every prop
+ * is plain data, so a routine can write a read as JSON; the one exception is
+ * the sign off person's `role`, which takes a node and is equally happy with
+ * a string.
  */
 
 /** A link inside running text: the words the reader clicks and where they go. */
@@ -37,13 +48,36 @@ export type ReadLink = ArtifactLink;
 /** A paragraph: a plain string, or runs of text and links in order. */
 export type ReadParagraph = ArtifactParagraph;
 
-/** A place a reading came from: the tool, opened in a new tab when it has an address. */
-export interface ReadSource {
+/** A tool we looked through: its name, where it opens (in a new tab), and a line on what we read there. */
+export interface ReadTool {
 	label: string;
 	href?: string;
+	/** One short line, e.g. "Page indexing, the last 90 days". */
+	note?: string;
+}
+
+/** The 1.0.0 name for a tool; the same shape. */
+export type ReadSource = ReadTool;
+
+/** One row of a section's facts: a short label and its value, e.g. "Pages on Google" and "9 of 9". */
+export interface ReadFact {
+	label: string;
+	value: ReadParagraph;
+}
+
+/** A list of examples under its own short heading; each item a paragraph that can carry links. */
+export interface ReadExamples {
+	title?: string;
+	items: ReadParagraph[];
+}
+
+/** One row of today and after: what a thing is now, and what it becomes. */
+export interface ReadChange {
+	now: ReadParagraph;
+	after: ReadParagraph;
 }
 
-/** One section of a tier: a question in three beats. */
+/** One section of a tier: a question, read top to bottom in five beats. */
 export interface ReadSection {
 	/** The anchor the gist table links to, e.g. "technical-seo". */
 	id: string;
@@ -55,18 +89,24 @@ export interface ReadSection {
 	grade?: WriteupGrade;
 	/** The one line in the gist table. */
 	gist: ReadParagraph;
-	/** What we found: one paragraph or more. */
+	/** Where we looked: the tools the readings came from, linked, at the top of the section. */
+	tools?: ReadTool[];
+	/** The 1.0.0 name for `tools`, still read and rendered in the same place; `tools` wins when both are set. */
+	sources?: ReadTool[];
+	/** What it showed: one or two short paragraphs. */
 	found: ReadParagraph[];
-	/** A few concrete examples of what was found, as a short list under it. */
-	examples?: ReadParagraph[];
+	/** What it showed, as a compact two column table of facts under the paragraphs. */
+	facts?: ReadFact[];
+	/** What it showed, as lists of examples, each under its own short heading. */
+	examples?: ReadExamples[];
 	/** Proof pictures, each over its caption, e.g. a search result capture per market. */
 	shots?: WriteupShot[];
 	/** Why, in one sentence, set apart. */
 	why: ReadParagraph;
-	/** What changes: one paragraph or more. */
-	changes: ReadParagraph[];
-	/** The tools the readings came from, linked, so the owner can open them. */
-	sources?: ReadSource[];
+	/** Today and after: what each thing is, and what it becomes. */
+	changes?: ReadChange[];
+	/** What we recommend, as a checklist. */
+	recommend?: ReadParagraph[];
 }
 
 /** A tier, e.g. Health: its heading, the question it answers, and its sections in order. */
@@ -109,6 +149,8 @@ export interface ReadClose {
 
 /** The fixed words the page sets, each overridable. */
 export interface ReadLabels {
+	/** The dateline's words before the business, e.g. "Prepared for". */
+	preparedFor: string;
 	/** The gist table's first column. */
 	section: string;
 	/** The gist table's second column. */
@@ -117,24 +159,34 @@ export interface ReadLabels {
 	gist: string;
 	/** What a screen reader hears for a section with no grade. */
 	notGraded: string;
+	/** The beat at the top of a section: the tools we looked through. */
+	tools: string;
+	/** The beat that says what the tools showed. */
 	found: string;
+	/** The one sentence beat. */
 	why: string;
-	changes: string;
-	/** The label over a section's tools. */
-	sources: string;
+	/** The today and after table's first column. */
+	now: string;
+	/** The today and after table's second column. */
+	after: string;
+	/** The checklist beat at the foot of a section. */
+	recommend: string;
 	/** The plan's heading when it names none. */
 	plan: string;
 }
 
 export const readLabels: ReadLabels = {
+	preparedFor: "Prepared for",
 	section: "Section",
 	grade: "Grade",
 	gist: "The Gist",
 	notGraded: "Not graded yet",
-	found: "What We Found",
+	tools: "Where We Looked",
+	found: "What It Showed",
 	why: "Why",
-	changes: "What Changes",
-	sources: "Sources",
+	now: "Today",
+	after: "After",
+	recommend: "What We Recommend",
 	plan: "The Plan",
 };
 
@@ -157,25 +209,101 @@ export interface ReadProps {
 	labels?: Partial<ReadLabels>;
 }
 
-function Sources({ sources, label }: { sources: ReadSource[]; label: string }) {
+/** A paragraph with something to read. Content may arrive as JSON, so a missing one counts as empty. */
+function filled(paragraph: ReadParagraph | undefined | null): paragraph is ReadParagraph {
+	return paragraph !== undefined && paragraph !== null && !isEmpty(paragraph);
+}
+
+function Tools({ tools, label }: { tools: ReadTool[]; label: string }) {
 	return (
-		<footer className="op-sources">
-			<span className="op-sources-label">{label}</span>
-			<ul>
-				{sources.map((source) => (
-					<li key={source.label}>
-						{source.href ? (
-							<a href={source.href} {...newTabProps(source.href, true)}>
-								{source.label}
-								<ArrowUpRight size={12} aria-hidden="true" />
+		<div className="rd-beat rd-tools">
+			<h4>{label}</h4>
+			<ul className="rd-tools-list">
+				{tools.map((tool, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: tools are static content in a fixed order, and a label may repeat
+					<li key={i}>
+						{tool.href ? (
+							<a href={tool.href} {...newTabProps(tool.href, true)}>
+								{tool.label}
+								<ArrowUpRight size={13} aria-hidden="true" />
 							</a>
 						) : (
-							source.label
+							<span className="rd-tool-name">{tool.label}</span>
 						)}
+						{tool.note && <span className="rd-tool-note">{tool.note}</span>}
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+function Facts({ facts }: { facts: ReadFact[] }) {
+	return (
+		<table className="rd-facts">
+			<tbody>
+				{facts.map((fact, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: facts are static content in a fixed order
+					<tr key={i}>
+						<th scope="row">{fact.label}</th>
+						<td>
+							<Runs paragraph={fact.value} />
+						</td>
+					</tr>
+				))}
+			</tbody>
+		</table>
+	);
+}
+
+function Changes({ changes, labels }: { changes: ReadChange[]; labels: ReadLabels }) {
+	return (
+		<div className="rd-beat rd-changes">
+			<table className="rd-changes-table">
+				<thead>
+					<tr>
+						<th scope="col" className="rd-now">
+							{labels.now}
+						</th>
+						<th scope="col" className="rd-after">
+							{labels.after}
+						</th>
+					</tr>
+				</thead>
+				<tbody>
+					{changes.map((change, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: rows are static content in a fixed order
+						<tr key={i}>
+							<td className="rd-now" data-label={labels.now}>
+								{filled(change.now) && <Runs paragraph={change.now} />}
+							</td>
+							<td className="rd-after" data-label={labels.after}>
+								{filled(change.after) && <Runs paragraph={change.after} />}
+							</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}
+
+function Recommend({ items, label }: { items: ReadParagraph[]; label: string }) {
+	return (
+		<div className="rd-beat rd-recommend">
+			<h4>{label}</h4>
+			<ul className="rd-checks">
+				{items.map((item, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: recommendations are static content in a fixed order
+					<li key={i}>
+						<Check size={16} strokeWidth={2.5} aria-hidden="true" />
+						<span>
+							<Runs paragraph={item} />
+						</span>
 					</li>
 				))}
 			</ul>
-		</footer>
+		</div>
 	);
 }
 
@@ -190,14 +318,15 @@ function Gist({
 	gradeKey?: ReadProps["gradeKey"];
 	labels: ReadLabels;
 }) {
+	const key = gradeKey ?? [];
 	return (
 		<section className="rd-gist" aria-label={title ? undefined : labels.gist}>
-			{(title || gradeKey) && (
+			{(title || key.length > 0) && (
 				<div className="op-ov-head">
 					{title && <h2 className="op-ov-title">{title}</h2>}
-					{gradeKey && (
+					{key.length > 0 && (
 						<ul className="op-legend">
-							{gradeKey.map((entry) => (
+							{key.map((entry) => (
 								<li key={entry.grade}>
 									<GradeChip grade={entry.grade} />
 									<span>{entry.label}</span>
@@ -263,9 +392,18 @@ function Gist({
 }
 
 function Section({ section, labels }: { section: ReadSection; labels: ReadLabels }) {
-	const found = section.found.filter((paragraph) => !isEmpty(paragraph));
-	const changes = section.changes.filter((paragraph) => !isEmpty(paragraph));
+	const tools = (section.tools ?? section.sources ?? []).filter((tool) => tool?.label?.trim());
+	const found = (section.found ?? []).filter(filled);
+	const facts = (section.facts ?? []).filter((fact) => filled(fact?.value));
+	const examples = (section.examples ?? [])
+		.map((list) => ({ title: list?.title, items: (list?.items ?? []).filter(filled) }))
+		.filter((list) => list.items.length > 0);
 	const shots = section.shots ?? [];
+	const changes = (section.changes ?? []).filter(
+		(change) => filled(change?.now) || filled(change?.after),
+	);
+	const recommend = (section.recommend ?? []).filter(filled);
+	const showed = found.length + facts.length + examples.length + shots.length > 0;
 	return (
 		<section className="op-topic rd-section" id={section.id}>
 			<header className="op-topic-head">
@@ -282,44 +420,46 @@ function Section({ section, labels }: { section: ReadSection; labels: ReadLabels
 					</>
 				)}
 			</header>
-			<div className="rd-beat rd-found">
-				<h4>{labels.found}</h4>
-				{found.map((paragraph, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-					<Paragraph paragraph={paragraph} key={i} />
-				))}
-				{section.examples && section.examples.length > 0 && (
-					<ul className="rd-examples">
-						{section.examples.map((example, i) => (
-							// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
-							<li key={i}>
-								<Runs paragraph={example} />
-							</li>
-						))}
-					</ul>
-				)}
-				{shots.length > 0 && (
-					<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
-						{shots.map((shot) => (
-							<Shot shot={shot} key={shot.src} />
-						))}
-					</div>
-				)}
-			</div>
-			<div className="rd-beat rd-why">
-				<h4>{labels.why}</h4>
-				<Paragraph paragraph={section.why} />
-			</div>
-			<div className="rd-beat rd-changes">
-				<h4>{labels.changes}</h4>
-				{changes.map((paragraph, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-					<Paragraph paragraph={paragraph} key={i} />
-				))}
-			</div>
-			{section.sources && section.sources.length > 0 && (
-				<Sources sources={section.sources} label={labels.sources} />
+			{tools.length > 0 && <Tools tools={tools} label={labels.tools} />}
+			{showed && (
+				<div className="rd-beat rd-found">
+					<h4>{labels.found}</h4>
+					{found.map((paragraph, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
+						<Paragraph paragraph={paragraph} key={i} />
+					))}
+					{facts.length > 0 && <Facts facts={facts} />}
+					{examples.map((list, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: lists are static content in a fixed order, and a title may repeat
+						<div className="rd-examples-block" key={i}>
+							{list.title && <h5>{list.title}</h5>}
+							<ul className="rd-examples">
+								{list.items.map((example, j) => (
+									// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
+									<li key={j}>
+										<Runs paragraph={example} />
+									</li>
+								))}
+							</ul>
+						</div>
+					))}
+					{shots.length > 0 && (
+						<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
+							{shots.map((shot) => (
+								<Shot shot={shot} key={shot.src} />
+							))}
+						</div>
+					)}
+				</div>
 			)}
+			{filled(section.why) && (
+				<div className="rd-beat rd-why">
+					<h4>{labels.why}</h4>
+					<Paragraph paragraph={section.why} />
+				</div>
+			)}
+			{changes.length > 0 && <Changes changes={changes} labels={labels} />}
+			{recommend.length > 0 && <Recommend items={recommend} label={labels.recommend} />}
 		</section>
 	);
 }
@@ -328,9 +468,7 @@ function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 	return (
 		<section className="rd-plan" id={plan.id}>
 			<h2>{plan.title ?? labels.plan}</h2>
-			{plan.lead && !isEmpty(plan.lead) && (
-				<Paragraph paragraph={plan.lead} className="rd-plan-lead" />
-			)}
+			{filled(plan.lead) && <Paragraph paragraph={plan.lead} className="rd-plan-lead" />}
 			<ol className="rd-steps">
 				{plan.steps.map((step) => (
 					<li className="rd-step" key={step.title}>
@@ -342,7 +480,7 @@ function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 									<span className="rd-step-who">{step.who}</span>
 								</>
 							)}
-							{step.body && !isEmpty(step.body) && (
+							{filled(step.body) && (
 								<>
 									{" "}
 									<Runs paragraph={step.body} />
@@ -375,14 +513,14 @@ export function Read({
 			<article className="op-doc rd-doc">
 				<header className="op-head">
 					<p className="op-meta">
-						Prepared for <b>{preparedFor}</b>
+						{labels.preparedFor} <b>{preparedFor}</b>
 						<span className="op-meta-sep" aria-hidden="true">
 							{" · "}
 						</span>
 						<span className="op-meta-date">{date}</span>
 					</p>
 					<h1>{title}</h1>
-					{!isEmpty(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
+					{filled(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
 				</header>
 				{shownTiers.length > 0 && (
 					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
@@ -399,7 +537,7 @@ export function Read({
 					</div>
 				))}
 				{plan.steps.length > 0 && <Plan plan={plan} labels={labels} />}
-				{!isEmpty(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
+				{filled(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
 				{close.signOff && close.person && (
 					<footer className="op-close rd-close">
 						<SignOff signOff={close.signOff} person={close.person} />

package/src/documents/Writeup.tsx

@@ -2,9 +2,11 @@ import {
 	GradeChip,
 	gradeLabel,
 	newTabProps,
+	Shot,
 	SignOff,
 	type WriteupGrade,
 	type WriteupPerson,
+	type WriteupShot,
 } from "@atelic-action/ui/artifact";
 import {
 	Callout,
@@ -25,10 +27,8 @@ import {
 } from "@atelic-action/ui/components";
 import { ArrowUpRight, ChevronRight, CircleAlert, CircleCheck, CircleX, Star } from "lucide-react";
 import type { ReactNode } from "react";
-import { Shot, type WriteupShot } from "./Shot";
 
-export type { WriteupGrade, WriteupPerson } from "@atelic-action/ui/artifact";
-export type { WriteupShot } from "./Shot";
+export type { WriteupGrade, WriteupPerson, WriteupShot } from "@atelic-action/ui/artifact";
 
 /**
  * The writeup: the graded document an owner gets. It is a web page first: an

package/src/documents/documents.css

@@ -7,11 +7,14 @@
    writeup's stays the one that wins.
 
    The pieces the documents share stay in @atelic-action/ui: the grade chip
-   (.op-grade), the sign off (.op-who, .op-sign), and the shell's logo rule,
-   in its styles/artifact.css; the login screen's vocabulary the sealed stage
-   reuses, in its styles/gate.css; the page components (the callout, the
-   checklist, the table, the charts), in its styles/components.css. Import
-   this sheet after all of them and before the site's theme.css.
+   (.op-grade), the sign off (.op-who, .op-sign), the shot (.op-shot), the
+   shell's logo rule, and the shell's print rules that drop the header, the
+   credit band, and the skip link on every artifact page, in its
+   styles/artifact.css, which sets no @page; the login screen's vocabulary
+   the sealed stage reuses, in its styles/gate.css; the page components (the
+   callout, the checklist, the table, the charts), in its
+   styles/components.css. Import this sheet after all of them and before the
+   site's theme.css. Both @page rules live only here.
 
    Every rule sits in the same atelic-ui layer as the package sheets, so any
    rule a site writes outside a layer still wins over it whatever its
@@ -521,7 +524,8 @@
 	     never reflowed, so a print of one sheet is the check.
 
 	   Tokens only (theme.css), except the printed sheet's white. The grade
-	   chip and the sign off are the shared classes in @atelic-action/ui's
+	   chip, the sign off, and the print rule that drops the header and the
+	   credit band are the shared classes in @atelic-action/ui's
 	   styles/artifact.css.
 	   ================================================================= */
 	.atelic-ui .rp {
@@ -797,11 +801,6 @@
 			padding: 0;
 			background: none;
 		}
-		.atelic-ui:has(.rp) .nav,
-		.atelic-ui:has(.rp) .skip-link,
-		.atelic-ui:has(.rp) .credit-bar {
-			display: none;
-		}
 		.atelic-ui .rp {
 			padding: 0;
 			background: none;
@@ -1345,33 +1344,6 @@
 		gap: 14px;
 		max-width: 340px;
 	}
-	.atelic-ui .op-shot {
-		display: flex;
-		flex-direction: column;
-		gap: 6px;
-		margin: 0;
-	}
-	.atelic-ui .op-shot a,
-	.atelic-ui .op-shot-frame {
-		display: block;
-		width: 100%;
-		border-radius: var(--radius-sm);
-		overflow: hidden;
-		border: 1px solid var(--neutral-200);
-		background: var(--op-card);
-	}
-	.atelic-ui .op-shot a {
-		cursor: zoom-in;
-	}
-	/* The expand badge on a linked crop: off here, the note turns it on. */
-	.atelic-ui .op-shot-open {
-		display: none;
-	}
-	.atelic-ui .op-shot img {
-		width: 100%;
-		height: auto;
-		display: block;
-	}
 	.atelic-ui .op-shot-brief {
 		display: grid;
 		place-items: center;
@@ -1384,11 +1356,6 @@
 		padding: 12px;
 		text-align: center;
 	}
-	.atelic-ui .op-shot figcaption {
-		font-size: 12.5px;
-		line-height: 1.45;
-		color: var(--op-ink-faint);
-	}
 
 	/* sources: the tools the readings came from */
 	.atelic-ui .op-sources {
@@ -1715,9 +1682,6 @@
 		html:has(.atelic-ui .op-doc) {
 			zoom: 0.74;
 		}
-		.atelic-ui .nav,
-		.atelic-ui .credit-bar,
-		.atelic-ui .skip-link,
 		.atelic-ui .op-ov-go,
 		.atelic-ui .op-topic h3 a svg {
 			display: none;
@@ -1808,9 +1772,6 @@
 		.atelic-ui .data-table thead {
 			break-after: avoid;
 		}
-		.atelic-ui .op-shot a {
-			cursor: auto;
-		}
 		.atelic-ui .op-twin {
 			display: flex;
 			align-items: center;
@@ -1851,17 +1812,17 @@
 	     aligned; the screen's column sizes to the picture, a phone crop
 	     about 260px and a wide card up to 45% of the row. A finding
 	     with no screen takes the full width.
-	   - Print: one letter sheet. The chrome steps aside (the writeup's print
-	     rules already hide the header and the credit band on any artifact
-	     page), the type comes down, and the screens shrink. The note sets
+	   - Print: one letter sheet. The chrome steps aside (ui's artifact.css
+	     hides the header and the credit band on any artifact page), the
+	     type comes down, and the screens shrink. The note sets
 	     no @page of its own: the writeup's, the later one in this sheet,
 	     sets letter paper for every artifact page.
 
 	   Tokens only. The finding is the shared Callout (@atelic-action/ui's components.css),
-	   the screen the writeup's .op-shot, the sign off the shared .op-who;
+	   the screen the shared .op-shot, the sign off the shared .op-who;
 	   this sheet sets the letter around them and their sizes here.
 	   ================================================================= */
-	/* The borrowed .op-shot reads the writeup's own two tokens, mapped here as
+	/* The shared .op-shot reads the writeup's own two tokens, mapped here as
 	   the writeup's .op root maps them. */
 	.atelic-ui .nt {
 		--op-card: var(--card);
@@ -2197,11 +2158,12 @@
 	   THE READ: the baseline's grades explained by cause (Read.tsx). The
 	   writeup's sibling: it sits inside the writeup's own .op root, so the
 	   column, the head, the grade chip and its key, the tier heading, the
-	   section card, the screen, the sources, the close, and every print
-	   rule of the writeup's are its own already. This block adds only what
-	   the read has and the writeup does not: the gist table, the three
-	   beats of a section, the proof pictures in a row, and the numbered
-	   plan. It sets no @page; the writeup's, earlier in this sheet and the
+	   section card, the screen, the close, and every print rule of the
+	   writeup's are its own already. This block adds only what the read has
+	   and the writeup does not: the gist table, the beats of a section (the
+	   tools we looked through, what they showed with its facts and
+	   examples, why, today and after, and what we recommend), the proof
+	   pictures in a row, and the numbered plan. It sets no @page; the writeup's, earlier in this sheet and the
 	   later of the two there, sets letter paper for every artifact page.
 
 	   Tokens only (theme.css).
@@ -2288,7 +2250,7 @@
 		min-width: 0;
 	}
 
-	/* ---- a section: the trade name over the question, then three beats ---- */
+	/* ---- a section: the trade name over the question, then its beats ---- */
 	.atelic-ui .rd-name {
 		margin: 0 0 4px;
 		font-family: var(--font-mono);
@@ -2304,7 +2266,7 @@
 		font-size: 21px;
 	}
 	.atelic-ui .rd-beat {
-		margin-top: 16px;
+		margin-top: 20px;
 		min-width: 0;
 	}
 	.atelic-ui .rd-beat h4 {
@@ -2324,12 +2286,99 @@
 	.atelic-ui .rd-beat p:last-child {
 		margin-bottom: 0;
 	}
+	/* Where we looked: the tools in a row at the top of the section, each a
+	   link with its line under it. */
+	.atelic-ui .rd-tools-list {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-wrap: wrap;
+		gap: 10px 28px;
+	}
+	.atelic-ui .rd-tools-list li {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		min-width: 0;
+		max-width: 100%;
+	}
+	.atelic-ui .rd-tools-list a,
+	.atelic-ui .rd-tool-name {
+		display: inline-flex;
+		align-items: center;
+		gap: 3px;
+		font-size: 15px;
+		font-weight: 600;
+		color: var(--op-accent);
+		text-decoration: none;
+	}
+	.atelic-ui .rd-tool-name {
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-tools-list a:hover {
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+	.atelic-ui .rd-tools-list svg {
+		flex: none;
+	}
+	.atelic-ui .rd-tool-note {
+		font-size: 13px;
+		line-height: 1.35;
+		color: var(--op-ink-faint);
+	}
+
+	/* What it showed: the facts as a compact table of label and value, in
+	   the writeup's table dress (an ink rule over thin row rules). */
+	.atelic-ui .rd-facts {
+		width: 100%;
+		max-width: 620px;
+		margin: 12px 0 0;
+		border-collapse: collapse;
+		border-top: 1.5px solid var(--op-ink);
+		font-size: 15px;
+		line-height: 1.4;
+	}
+	.atelic-ui .rd-facts th,
+	.atelic-ui .rd-facts td {
+		padding: 7px 14px 7px 0;
+		border-bottom: 1px solid var(--neutral-100);
+		text-align: left;
+		vertical-align: top;
+	}
+	.atelic-ui .rd-facts th {
+		width: 55%;
+		font-weight: 400;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-facts td {
+		padding-right: 0;
+		font-weight: 600;
+		color: var(--op-ink);
+		font-variant-numeric: tabular-nums;
+	}
+	.atelic-ui .rd-facts tr:last-child > * {
+		border-bottom: 0;
+	}
+
+	/* The examples: a list or more, each under its own short heading. */
+	.atelic-ui .rd-examples-block {
+		margin-top: 14px;
+		max-width: 68ch;
+	}
+	.atelic-ui .rd-examples-block h5 {
+		margin: 0 0 4px;
+		font-size: 15px;
+		font-weight: 650;
+		color: var(--op-ink);
+	}
 	.atelic-ui .rd-examples {
 		list-style: disc;
-		margin: 8px 0 0;
+		margin: 0;
 		padding-left: 1.2em;
-		max-width: 68ch;
 		color: var(--op-ink-soft);
+		text-wrap: pretty;
 	}
 	.atelic-ui .rd-examples li + li {
 		margin-top: 4px;
@@ -2355,6 +2404,92 @@
 		gap: 14px;
 		margin-top: 14px;
 	}
+	/* A lone picture keeps a screen's size rather than filling the card. */
+	.atelic-ui .rd-shots[data-count="1"] {
+		max-width: 380px;
+	}
+
+	/* Today and after: what a thing is, and what it becomes. Two columns
+	   wide; on a phone each row stacks, each half wearing its label. */
+	.atelic-ui .rd-changes-table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 15px;
+		line-height: 1.45;
+	}
+	.atelic-ui .rd-changes-table thead {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+	}
+	.atelic-ui .rd-changes-table,
+	.atelic-ui .rd-changes-table tbody,
+	.atelic-ui .rd-changes-table tr,
+	.atelic-ui .rd-changes-table td {
+		display: block;
+	}
+	.atelic-ui .rd-changes-table tbody tr {
+		padding: 10px 0;
+		border-bottom: 1px solid var(--neutral-100);
+	}
+	.atelic-ui .rd-changes-table tbody tr:first-child {
+		border-top: 1.5px solid var(--op-ink);
+	}
+	.atelic-ui .rd-changes-table tbody tr:last-child {
+		border-bottom: 0;
+		padding-bottom: 0;
+	}
+	.atelic-ui .rd-changes-table td {
+		text-align: left;
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-changes-table td + td {
+		margin-top: 6px;
+	}
+	.atelic-ui .rd-changes-table td::before {
+		content: attr(data-label);
+		display: block;
+		margin-bottom: 1px;
+		font-family: var(--font-mono);
+		font-size: 11px;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--op-ink-faint);
+	}
+	.atelic-ui .rd-changes-table td.rd-now {
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-changes-table td.rd-after {
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-changes-table td.rd-after::before {
+		color: var(--op-accent);
+	}
+
+	/* What we recommend: a checklist, each item led by the accent's check. */
+	.atelic-ui .rd-checks {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: grid;
+		gap: 8px;
+		max-width: 68ch;
+	}
+	.atelic-ui .rd-checks li {
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		column-gap: 10px;
+		align-items: start;
+		line-height: 1.45;
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-checks svg {
+		margin-top: 0.2em;
+		color: var(--op-accent);
+	}
 
 	/* ---- the plan: the steps in order, numbered ---- */
 	.atelic-ui .rd-plan {
@@ -2448,6 +2583,69 @@
 			padding-left: 20px;
 			padding-right: 16px;
 		}
+		.atelic-ui .rd-facts th {
+			width: 45%;
+		}
+		.atelic-ui .rd-changes-table {
+			display: table;
+			table-layout: fixed;
+		}
+		.atelic-ui .rd-changes-table thead {
+			display: table-header-group;
+			position: static;
+			width: auto;
+			height: auto;
+			overflow: visible;
+			clip: auto;
+		}
+		.atelic-ui .rd-changes-table tbody {
+			display: table-row-group;
+		}
+		.atelic-ui .rd-changes-table tr,
+		.atelic-ui .rd-changes-table tbody tr {
+			display: table-row;
+			padding: 0;
+			border: 0;
+		}
+		.atelic-ui .rd-changes-table th,
+		.atelic-ui .rd-changes-table td {
+			display: table-cell;
+			width: 50%;
+			padding: 9px 18px 9px 0;
+			border-bottom: 1px solid var(--neutral-100);
+			text-align: left;
+			vertical-align: top;
+		}
+		.atelic-ui .rd-changes-table th + th,
+		.atelic-ui .rd-changes-table td + td {
+			margin-top: 0;
+			padding-left: 18px;
+			padding-right: 0;
+			border-left: 1px solid var(--neutral-100);
+		}
+		.atelic-ui .rd-changes-table td::before {
+			content: none;
+		}
+		.atelic-ui .rd-changes-table tbody tr:first-child {
+			border-top: 0;
+		}
+		.atelic-ui .rd-changes-table thead th {
+			padding-top: 0;
+			padding-bottom: 8px;
+			border-bottom: 1.5px solid var(--op-ink);
+			font-family: var(--font-mono);
+			font-size: 11.5px;
+			font-weight: 500;
+			letter-spacing: 0.1em;
+			text-transform: uppercase;
+			color: var(--op-ink-faint);
+		}
+		.atelic-ui .rd-changes-table thead th.rd-after {
+			color: var(--op-accent);
+		}
+		.atelic-ui .rd-changes-table tbody tr:last-child td {
+			border-bottom: 0;
+		}
 		.atelic-ui .rd-shots[data-count="2"] {
 			grid-template-columns: repeat(2, minmax(0, 1fr));
 		}
@@ -2465,6 +2663,10 @@
 			border-color: var(--neutral-200);
 		}
 		.atelic-ui .rd-gist-table tr,
+		.atelic-ui .rd-changes-table tr,
+		.atelic-ui .rd-facts,
+		.atelic-ui .rd-tools,
+		.atelic-ui .rd-checks li,
 		.atelic-ui .rd-closing,
 		.atelic-ui .rd-why,
 		.atelic-ui .rd-step,
@@ -2473,6 +2675,7 @@
 			break-inside: avoid;
 		}
 		.atelic-ui .rd-beat h4,
+		.atelic-ui .rd-examples-block h5,
 		.atelic-ui .rd-plan h2 {
 			break-after: avoid;
 		}

package/src/documents/Paragraph.tsx

@@ -1,65 +0,0 @@
-import { newTabProps } from "@atelic-action/ui/artifact";
-
-/**
- * Plain data text for the documents a routine can write as JSON (the note
- * and the read): a paragraph is a string, or runs of text and links in
- * order. A link opens in a new tab when it leaves the page, and in place
- * when it is an anchor or a mail link.
- */
-
-/** A link inside running text: the words the reader clicks and where they go. */
-export interface ArtifactLink {
-	text: string;
-	href: string;
-}
-
-/** A paragraph: a plain string, or runs of text and links in order. */
-export type ArtifactParagraph = string | Array<string | ArtifactLink>;
-
-/** A link opens in a new tab when it leaves the page, and in place when it is an anchor or a mail link. */
-export function ArtifactAnchor({ href, children }: { href: string; children: string }) {
-	return (
-		<a href={href} {...newTabProps(href, /^https?:/i.test(href))}>
-			{children}
-		</a>
-	);
-}
-
-/** A paragraph with nothing to read: a blank string, or runs that are all blank strings. A link always counts. */
-export function isEmpty(paragraph: ArtifactParagraph): boolean {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return runs.every((run) => typeof run === "string" && run.trim() === "");
-}
-
-/** The runs alone, for a container that is not a paragraph (a list item, a table cell). */
-export function Runs({ paragraph }: { paragraph: ArtifactParagraph }) {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return (
-		<>
-			{runs.map((run, i) =>
-				typeof run === "string" ? (
-					run
-				) : (
-					// biome-ignore lint/suspicious/noArrayIndexKey: runs are static content in a fixed order
-					<ArtifactAnchor href={run.href} key={i}>
-						{run.text}
-					</ArtifactAnchor>
-				),
-			)}
-		</>
-	);
-}
-
-export function Paragraph({
-	paragraph,
-	className,
-}: {
-	paragraph: ArtifactParagraph;
-	className?: string;
-}) {
-	return (
-		<p className={className}>
-			<Runs paragraph={paragraph} />
-		</p>
-	);
-}

package/src/documents/Shot.tsx

@@ -1,38 +0,0 @@
-import { newTabProps } from "@atelic-action/ui/artifact";
-import { Maximize2 } from "lucide-react";
-
-export interface WriteupShot {
-	/** The crop shown on the page. */
-	src: string;
-	alt: string;
-	/** The full screenshot the crop opens in a new tab; omit to render the crop alone. */
-	href?: string;
-	caption: string;
-}
-
-/**
- * The owner's own screen: the crop, opening the full screenshot in a new tab
- * when it has one, over its caption. The writeup and the note both wear it;
- * its styles (.op-shot) are the writeup's, and the note only sizes it. A
- * linked crop says it opens: a hover title, and an expand badge the note
- * shows on its thumbnails and the writeup keeps hidden.
- */
-export function Shot({ shot }: { shot: WriteupShot }) {
-	return (
-		<figure className="op-shot">
-			{shot.href ? (
-				<a href={shot.href} title="Open the full picture" {...newTabProps(shot.href, true)}>
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
-					<span className="op-shot-open" aria-hidden="true">
-						<Maximize2 size={12} />
-					</span>
-				</a>
-			) : (
-				<span className="op-shot-frame">
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
-				</span>
-			)}
-			<figcaption>{shot.caption}</figcaption>
-		</figure>
-	);
-}