@atelic-action/ui 1.0.0 → 2.0.0

package/src/vite/artifact-config.ts

@@ -55,7 +55,8 @@ export function artifactConfig({ pages, extend }: ArtifactConfigOptions): UserCo
 	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
+		// @atelic-action/artifact and its pieces 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
@@ -95,10 +96,11 @@ export function artifactConfig({ pages, extend }: ArtifactConfigOptions): UserCo
 				"@": 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.
+		// @atelic-action/ui and @atelic-action/artifact (the documents) both ship
+		// TSX and CSS as written, so the prerender's server build has to compile
+		// them rather than hand them to Node as externals.
 		ssr: {
-			noExternal: ["@atelic-action/ui"],
+			noExternal: ["@atelic-action/ui", "@atelic-action/artifact"],
 		},
 	};
 	return extend ? mergeConfig(config, extend) : config;

package/src/artifact/Gate.tsx

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

package/src/artifact/Note.tsx

@@ -1,188 +0,0 @@
-import { Callout } from "../components";
-import { newTabProps } from "../lib/newTabProps";
-import { Shot, type WriteupShot } from "./Shot";
-import { SignOff, type WriteupPerson } from "./SignOff";
-
-/**
- * The note: the first touch, for a business whose site publishes no email
- * address, written as a short page and left at `<short>.atelic.me/notes`. It
- * is the first touch email set as a document, so it carries no grades, no
- * sections, and no tables: a title, the opener, what the customer sees and
- * what sits under the hood, where the work would start, and the close. It
- * reads on a phone first and prints to one letter sheet.
- *
- * It is the writeup's sibling, not a variant of it: a site wraps it in
- * ArtifactShell exactly as it wraps the writeup, and it reuses the writeup's
- * pieces where they fit (the Callout a finding is set in, the owner's screen,
- * the sign off). Every prop is plain data, so a routine can write a note 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. */
-export interface NoteLink {
-	text: string;
-	href: string;
-}
-
-/** A paragraph: a plain string, or runs of text and links in order. */
-export type NoteParagraph = string | Array<string | NoteLink>;
-
-/** One defect and what it costs, with the owner's screen under it when there is one. */
-export interface NoteFinding {
-	/** The defect, in a full sentence. */
-	lead: string;
-	/** The consequence: what it costs the business. */
-	body: string;
-	/**
-	 * Where the defect can be seen for oneself. The lead links there: in a new
-	 * tab for an http(s) link, in place otherwise.
-	 */
-	href?: string;
-	/** The owner's own screen, rendered under the finding. */
-	shot?: WriteupShot;
-}
-
-/** One side of the read, e.g. "What your customer sees", with one or two findings. */
-export interface NoteLane {
-	heading: string;
-	findings: NoteFinding[];
-}
-
-/** One place the work would start. */
-export interface NoteStep {
-	/** The step, set in bold. */
-	lead: string;
-	/** What it does, after the lead. */
-	body?: string;
-}
-
-/** Where the work would start: the line that introduces it, then the steps. */
-export interface NoteStart {
-	/** The line over the steps, e.g. "I would start by:". */
-	lead: string;
-	items: NoteStep[];
-}
-
-/** The close: who is writing and the offer, then the sign off. */
-export interface NoteClose {
-	/** The sender paragraph, then the offer line with its scheduling link and the exit sentence. */
-	paragraphs: NoteParagraph[];
-	signOff: string;
-	person: WriteupPerson;
-}
-
-export interface NoteProps {
-	title: string;
-	/** The business, set in the dateline: "Prepared for <business>, <date>". */
-	preparedFor: string;
-	/** The ISO date, e.g. "2026-10-09". */
-	date: string;
-	/** The street sighting and a kudos, then the gap sentence. */
-	opener: NoteParagraph;
-	/** "What your customer sees" and "What I see under the hood", in that order. */
-	lanes: NoteLane[];
-	start: NoteStart;
-	close: NoteClose;
-}
-
-/** A link opens in a new tab when it leaves the page, and in place when it is an anchor or a mail link. */
-function NoteAnchor({ 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. */
-function isEmpty(paragraph: NoteParagraph): boolean {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return runs.every((run) => typeof run === "string" && run.trim() === "");
-}
-
-function Paragraph({ paragraph, className }: { paragraph: NoteParagraph; className?: string }) {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return (
-		<p className={className}>
-			{runs.map((run, i) =>
-				typeof run === "string" ? (
-					run
-				) : (
-					// biome-ignore lint/suspicious/noArrayIndexKey: runs are static content in a fixed order
-					<NoteAnchor href={run.href} key={i}>
-						{run.text}
-					</NoteAnchor>
-				),
-			)}
-		</p>
-	);
-}
-
-function Finding({ finding }: { finding: NoteFinding }) {
-	return (
-		<li className={finding.shot ? "nt-finding has-shot" : "nt-finding"}>
-			<Callout
-				tone="warn"
-				title={
-					finding.href ? <NoteAnchor href={finding.href}>{finding.lead}</NoteAnchor> : finding.lead
-				}
-			>
-				{finding.body}
-			</Callout>
-			{finding.shot && <Shot shot={finding.shot} />}
-		</li>
-	);
-}
-
-export function Note({ title, preparedFor, date, opener, lanes, start, close }: NoteProps) {
-	const shownLanes = lanes.filter((lane) => lane.findings.length > 0);
-	const paragraphs = close.paragraphs.filter((paragraph) => !isEmpty(paragraph));
-	return (
-		<div className="nt">
-			<article className="nt-doc">
-				<header className="nt-head">
-					<p className="nt-meta">
-						Prepared for <b>{preparedFor}</b>, <span className="nt-meta-date">{date}</span>
-					</p>
-					<h1>{title}</h1>
-				</header>
-				{!isEmpty(opener) && <Paragraph paragraph={opener} className="nt-opener" />}
-				{shownLanes.length > 0 && (
-					<div className="nt-lanes">
-						{shownLanes.map((lane) => (
-							<section className="nt-lane" key={lane.heading}>
-								<h2>{lane.heading}</h2>
-								<ul className="nt-findings">
-									{lane.findings.map((finding) => (
-										<Finding finding={finding} key={finding.lead} />
-									))}
-								</ul>
-							</section>
-						))}
-					</div>
-				)}
-				{start.items.length > 0 && (
-					<section className="nt-start">
-						<p className="nt-start-lead">{start.lead}</p>
-						<ul>
-							{start.items.map((step) => (
-								<li key={step.lead}>
-									<b>{step.lead}</b>
-									{step.body && <> {step.body}</>}
-								</li>
-							))}
-						</ul>
-					</section>
-				)}
-				<footer className="nt-close">
-					{paragraphs.map((paragraph, i) => (
-						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-						<Paragraph paragraph={paragraph} key={i} />
-					))}
-					<SignOff signOff={close.signOff} person={close.person} />
-				</footer>
-			</article>
-		</div>
-	);
-}

package/src/artifact/Report.tsx

@@ -1,131 +0,0 @@
-import type { ReactNode } from "react";
-import { GradeChip, type WriteupGrade } from "./GradeChip";
-import { SignOff, type WriteupPerson } from "./SignOff";
-
-/**
- * The monthly page: what an Operate client gets each month, as one printed
- * letter sheet and its hosted twin. Its shape is the practice's
- * FOOTPRINT.md, under What the Owner Gets: the title and the period, then
- * the leads block answering the four questions the Statement of Work
- * promises, in that order, each a figure and one plain sentence; then the
- * seven grades with what moved since last month and since the baseline; then
- * the sign off. It wears the writeup's grade chip and sign off, and the
- * artifact shell's header on screen; print drops the header and the credit
- * band, so the sheet is the document alone.
- */
-
-export interface ReportLead {
-	/** The figure, e.g. "31 leads" or "$1,240". */
-	figure: ReactNode;
-	/** One plain sentence on what the figure means to the owner. */
-	sentence: ReactNode;
-}
-
-/** The four questions, answered in this order on every monthly page. */
-export interface ReportLeads {
-	cameIn: ReportLead;
-	fromWhere: ReportLead;
-	cost: ReportLead;
-	closed: ReportLead;
-}
-
-export interface ReportGradeRow {
-	/** The tier, e.g. "Health". */
-	tier: string;
-	/** The section's trade name, e.g. "Local SEO". */
-	section: string;
-	/** The grade this month: the one judgement, in full color. */
-	now: WriteupGrade;
-	/** The grade last month; omit on the first month. */
-	lastMonth?: WriteupGrade;
-	/** The grade in the baseline snapshot, the first taken on private sources. */
-	baseline?: WriteupGrade;
-	/** One line on what moved, in the owner's words. */
-	moved: string;
-}
-
-export interface ReportProps {
-	title: string;
-	/** The period as printed, e.g. "September 2026". */
-	period: string;
-	leads: ReportLeads;
-	/** The seven sections, in the footprint's order. */
-	grades: ReportGradeRow[];
-	/** The sign off, the same lockup the writeup closes on. */
-	close: { signOff: string; person: WriteupPerson };
-}
-
-/**
- * The questions are the monthly page's contract with the Statement of Work,
- * the same on every client's page, so they live here rather than in content.
- */
-const QUESTIONS: { key: keyof ReportLeads; label: string }[] = [
-	{ key: "cameIn", label: "What Came In" },
-	{ key: "fromWhere", label: "From Where" },
-	{ key: "cost", label: "What It Cost" },
-	{ key: "closed", label: "What It Closed" },
-];
-
-function Earlier({ grade, label }: { grade?: WriteupGrade; label: string }) {
-	return (
-		<td className="rp-earlier" data-label={label}>
-			{grade && <GradeChip grade={grade} />}
-		</td>
-	);
-}
-
-export function Report({ title, period, leads, grades, close }: ReportProps) {
-	let lastTier = "";
-	return (
-		<div className="rp">
-			<article className="rp-sheet">
-				<header className="rp-head">
-					<div className="rp-period">{period}</div>
-					<h1>{title}</h1>
-				</header>
-				<div className="rp-leads">
-					{QUESTIONS.map(({ key, label }) => (
-						<section className="rp-lead" key={key}>
-							<h2 className="rp-q">{label}</h2>
-							<div className="rp-figure">{leads[key].figure}</div>
-							<p>{leads[key].sentence}</p>
-						</section>
-					))}
-				</div>
-				<table className="rp-grades">
-					<thead>
-						<tr>
-							<th scope="col">Tier</th>
-							<th scope="col">Section</th>
-							<th scope="col">Now</th>
-							<th scope="col">Last Month</th>
-							<th scope="col">Baseline</th>
-							<th scope="col">What Moved</th>
-						</tr>
-					</thead>
-					<tbody>
-						{grades.map((row) => {
-							const tier = row.tier === lastTier ? "" : row.tier;
-							lastTier = row.tier;
-							return (
-								<tr key={row.section} className={tier ? "is-tier-start" : undefined}>
-									<td className="rp-tier">{tier}</td>
-									<td className="rp-section">{row.section}</td>
-									<td className="rp-now" data-label="Now">
-										<GradeChip grade={row.now} />
-									</td>
-									<Earlier grade={row.lastMonth} label="Last Month" />
-									<Earlier grade={row.baseline} label="Baseline" />
-									<td className="rp-moved">{row.moved}</td>
-								</tr>
-							);
-						})}
-					</tbody>
-				</table>
-				<footer className="rp-close">
-					<SignOff signOff={close.signOff} person={close.person} />
-				</footer>
-			</article>
-		</div>
-	);
-}