@supersuit/artifacts 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.7.0 (2026-09-27)
+
+**A real version history: every page names its version, lists every version with its change note,
+and serves each past version at its own URL.**
+
+- The line under the summary reads "Version N · Updated <minute> · History". History opens a
+  panel (`VersionHistory`, a client component) drawn through a portal on `document.body` like the
+  definition layer, so it never reflows the page: a bottom sheet above the narration bar on a
+  phone, a side panel on a desk. Each row is the version number, the exact minute in the reader's
+  zone, and the note. Authors were hand-writing "Version history" sections at the end of their
+  markdown; the store already kept every version, so the page now shows them.
+- Past versions render read-only at `/<id>/v/<n>` (`VersionPage`, `generateVersionMetadata`) under
+  a banner, "You are reading version N of M", linking the current page. Same password and
+  confidential gate as the page, looked up only after the gate opens; no narration, no answers,
+  no view counted. The current number redirects to the page; anything else missing is a 404.
+- A change note travels with each version: `?note=` on the publish POST or `change:` in the
+  front matter. None given, none stored. A note identical to the one it replaces is dropped as a
+  stale front matter line.
+- `?amend=1` finishes the same publish, so a publisher's image and narration POSTs no longer mint
+  two or three versions per publish; a republish with an unchanged body and no note is not a new
+  version either. History docs now keep the title, subtitle and summary they were published with.
+- New store methods `history`, `version`, `setNote` (optional on the interface); new route
+  `VERSIONS` (`GET` lists, `POST {version, note}` backfills a note); `safeReturnPath` accepts
+  `/<id>/v/<n>` so signing in from a past version returns to it.
+- **DETECTOR:** a page whose line under the summary has no "Version N", or a markdown file ending
+  in a hand-written "Version history" section. A host with no `app/[id]/v/[n]/page.tsx` 404s
+  every History link.
+- **REMEDY:** take 0.7.0, and add two route files: `app/[id]/v/[n]/page.tsx` (default
+  `VersionPage`, `generateMetadata` = `generateVersionMetadata`) and
+  `app/api/artifacts/[id]/versions/route.ts` (`GET`, `POST` = `VERSIONS`). Publishers pass
+  `note=` on the first POST and `amend=1` on the ones that follow it.
+- **Tests:** `store.test.ts` (notes ride and move to history, none invented, stale note dropped,
+  unchanged body and amend make no version, listing without bodies, one version, legacy array,
+  backfill), `versions.test.tsx` (header line, banner, no narration or view, redirect, 404s, gate
+  parity for password and confidential pages case by case, no history leaked through a door,
+  sign-in returns to the version, the API, note and amend reach the store),
+  `version-history.test.tsx` (portal on body, no text change, rows and links, close paths),
+  `reader.test.ts` (return paths), `front-matter.test.ts` (`change:`). Mutation-checked: removing
+  the gate for versions fails four parity tests; dropping the stale-note rule and the current
+  redirect each fail their test.
+
+## 0.6.0 (2026-09-27)
+
+**"Updated" names the exact minute, in the reader's own time zone.**
+
+- The line under an artifact's summary read "Updated September 27, 2026", so a page republished
+  three times in one evening looked the same each time. It now reads "Updated September 27, 2026
+  at 8:07 AM CDT": the server renders UTC, and a small client component, `UpdatedTime`, swaps in
+  the viewer's zone once the page runs. The value is a `<time dateTime>` carrying the ISO stamp.
+- New `formatUpdated(iso, timeZone?)` in `src/artifacts/updated-at.ts`; a bad value renders
+  nothing rather than an invented time.
+- DETECTOR: an artifact page whose "Updated" line has no clock time.
+- REMEDY: take 0.6.0; nothing to configure.
+- Tests: `updated-at.test.ts` (exact minute and zone, UTC default, bad input), verified red with
+  the minute removed.
+
 ## 0.5.0 (2026-09-27)
 
 **Inline definitions: a page can define its jargon, and a reader sees it in line.**

package/README.md

@@ -68,12 +68,14 @@ The rest, each exporting the named handler(s) from `artifacts`:
 
 | File | Handlers |
 |---|---|
+| `app/[id]/v/[n]/page.tsx` | `default` = `VersionPage`, `generateMetadata` = `generateVersionMetadata` |
 | `app/[id]/share.png/route.tsx` | `GET` = `SHARE_IMAGE` |
 | `app/api/artifacts/route.ts` | `POST` (publish) |
 | `app/api/artifacts/[id]/route.ts` | `GET`, `DELETE` |
 | `app/api/artifacts/[id]/assets/[name]/route.ts` | `PUT` = `PUT_ASSET` |
 | `app/api/artifacts/[id]/access/route.ts` | `GET`, `POST` = `ACCESS` |
 | `app/api/artifacts/[id]/reads/route.ts` | `GET` = `READS` |
+| `app/api/artifacts/[id]/versions/route.ts` | `GET`, `POST` = `VERSIONS` |
 | `app/api/reader/enter/route.ts` | `GET` = `ENTER` |
 | `app/api/reader/leave/route.ts` | `GET` = `LEAVE` |
 | `app/api/reader/ack/route.ts` | `POST` = `ACK` |
@@ -109,6 +111,28 @@ hostname and pick by the `host` header.
 body. The response carries the page's id and URL. Posting a file whose front matter carries
 that `id:` republishes it in place, keeping every earlier version.
 
+## Version history
+
+Every page names its version under the summary, "Version 4 · Updated <minute> · History", and
+History opens a panel listing every version newest first: its number, the minute it went live in
+the reader's own time zone, and its change note. The panel is drawn over the page (a sheet on a
+phone, a side panel on a desk), so opening it moves no text. Each past version is readable at
+`/<id>/v/<n>`, read-only, under a banner naming it and linking the current page, behind exactly
+the same password or confidential door as the page itself. A version that does not exist is a
+404; on a shut page the door comes first, so it never says which versions exist.
+
+**Do not write a "Version history" section in the markdown.** Say what changed when you publish:
+
+- `POST /api/artifacts?id=<id>&note=<one line>`, or a `change:` line in the front matter. The query
+  wins. A note is one line, 280 characters at most.
+- No note records the version with none. A `change:` still in the file from the previous publish
+  is recognised as stale and not repeated on the next version.
+- `&amend=1` finishes the publish the previous POST started (a publisher's second and third POSTs,
+  carrying uploaded image URLs and then narration) instead of starting a new version. A republish
+  whose body is unchanged and carries no note is not a new version either.
+- `GET /api/artifacts/<id>/versions` lists the history; `POST` it `{ "version": 2, "note": "..." }`
+  (or `"note": null`) to write a note onto a version after the fact.
+
 ## Front matter
 
 ```markdown
@@ -133,6 +157,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `theme` | `light`, `dark` or `system` (follow the reader's device). Overrides the brand pack's mode for this page |
 | `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
 | `definitions` | Terms defined inline (below). A republish without it removes them |
+| `change` | One line saying what this version changed (see Version history) |
 | `template` | `document`, the only one so far |
 
 An unknown key is refused, so a typo fails loudly instead of being ignored.

package/lib/artifacts/front-matter.d.ts

@@ -36,6 +36,9 @@ export type ArtifactMeta = {
     /** Terms this page defines inline: the first occurrence of each is underlined and opens its
      *  definition. Content, like the body: a republish without it removes them. */
     definitions?: Definition[];
+    /** One line saying what changed in this version. Stored with the version it arrives on; a line
+     *  left in the file from the previous publish is recognised and not repeated. */
+    change?: string;
 };
 export declare function parseArtifactSource(text: string): {
     ok: true;

package/lib/artifacts/front-matter.js

@@ -6,7 +6,7 @@ import { parseStateConfig } from './state.js';
 import { mergeWidgetState, scanWidgets } from './widgets.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -32,6 +32,12 @@ export function parseArtifactSource(text) {
         if (typeof v === 'string' && v)
             meta[k] = v;
     }
+    if (d.change !== undefined && d.change !== null) {
+        if (typeof d.change !== 'string')
+            return { ok: false, error: 'change must be one line of text' };
+        if (d.change.trim())
+            meta.change = d.change.replace(/\s+/g, ' ').trim();
+    }
     if (d.access !== undefined) {
         if (d.access !== 'public' && !ACCESS_LEVELS.includes(d.access))
             return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };

package/lib/artifacts/index.d.ts

@@ -1,7 +1,7 @@
 export { parseArtifactSource, type ArtifactMeta } from './front-matter.js';
 export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
-export { createArtifactStore, newArtifactId, type ArtifactStore, type ArtifactRecord, type SaveResult } from './store.js';
+export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
 export { isPublishAuthed } from './auth.js';
 export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';

package/lib/artifacts/index.js

@@ -1,7 +1,7 @@
 export { parseArtifactSource } from './front-matter.js';
 export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
-export { createArtifactStore, newArtifactId } from './store.js';
+export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
 export { isPublishAuthed } from './auth.js';
 export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';

package/lib/artifacts/reader.js

@@ -104,6 +104,7 @@ export function signInUrl(signInOrigin, pageUrl) {
 export function safeReturnPath(to, prefix = '/') {
     if (typeof to !== 'string')
         return null;
-    const m = new RegExp(`^${prefix.replace(/\//g, '\\/')}([abcdefghjkmnpqrstuvwxyz23456789]{8})$`).exec(to);
-    return m ? `${prefix}${m[1]}` : null;
+    // One page, or one past version of it (/<id>/v/<n>): nothing else on this host, nothing off it.
+    const m = new RegExp(`^${prefix.replace(/\//g, '\\/')}([abcdefghjkmnpqrstuvwxyz23456789]{8})(\\/v\\/[1-9]\\d{0,5})?$`).exec(to);
+    return m ? `${prefix}${m[1]}${m[2] ?? ''}` : null;
 }

package/lib/artifacts/store.d.ts

@@ -32,8 +32,29 @@ export type ArtifactRecord = {
         markdown: string;
         at: string;
     }[];
+    /** The one-line change note the current version was published with. Absent when none was
+     *  given: a version is never described by anything its author did not write. */
+    note?: string;
     views: number;
 };
+/** One line of a page's history. `at` is when that version went live. */
+export type VersionEntry = {
+    version: number;
+    at: string;
+    note?: string;
+    current?: true;
+};
+/** One version, readable: its body and the title it carried (absent on versions filed before
+ *  0.7.0, which kept only the body; the page's current title stands in). */
+export type VersionRecord = VersionEntry & {
+    markdown: string;
+    title?: string;
+    subtitle?: string;
+    summary?: string;
+};
+/** A change note is one line: whitespace collapsed, capped, empty means none. */
+export declare const MAX_CHANGE_NOTE_CHARS = 280;
+export declare function cleanNote(note: unknown): string | undefined;
 export declare function newArtifactId(): string;
 export type SaveResult = {
     id: string;
@@ -42,17 +63,29 @@ export type SaveResult = {
 } | {
     notFound: true;
 };
+export type SaveInput = {
+    id?: string;
+    meta: ArtifactMeta;
+    markdown: string;
+    /** What changed in this version, in the author's words. Falls back to the front matter's `change:`. */
+    note?: string;
+    /** Finish the SAME publish rather than start a new version: the publisher's second and third
+     *  POSTs (uploaded image URLs, then narration) amend the version its first POST created. */
+    amend?: boolean;
+};
 export interface ArtifactStore {
     get(id: string): Promise<ArtifactRecord | null>;
-    save(input: {
-        id?: string;
-        meta: ArtifactMeta;
-        markdown: string;
-    }): Promise<SaveResult>;
+    save(input: SaveInput): Promise<SaveResult>;
     delete(id: string): Promise<boolean>;
     bumpViews(id: string): Promise<void>;
     /** Set who may read a page without republishing it; 'public' opens it. False if no such page. */
     setAccess?(id: string, access: Access | 'public'): Promise<boolean>;
+    /** Every version, newest first, current included, without bodies. Null when no such page. */
+    history?(id: string): Promise<VersionEntry[] | null>;
+    /** One version by number, current included. Null when the page or the version does not exist. */
+    version?(id: string, n: number): Promise<VersionRecord | null>;
+    /** Write (or, with null, clear) the change note on one version after the fact. */
+    setNote?(id: string, n: number, note: string | null): Promise<boolean>;
 }
 /** The Firestore-backed store. The instance hands in its own Firestore, so the shell
  *  never knows which project it is writing to; a hosted tenant passes a namespaced one. */

package/lib/artifacts/store.js

@@ -9,6 +9,14 @@
 // first save of a page still carrying the array moves it into the subcollection.
 import { randomInt } from 'node:crypto';
 import { FieldValue } from 'firebase-admin/firestore';
+/** A change note is one line: whitespace collapsed, capped, empty means none. */
+export const MAX_CHANGE_NOTE_CHARS = 280;
+export function cleanNote(note) {
+    if (typeof note !== 'string')
+        return undefined;
+    const one = note.replace(/\s+/g, ' ').trim();
+    return one ? one.slice(0, MAX_CHANGE_NOTE_CHARS) : undefined;
+}
 // No 0/o, 1/l/i: an id read aloud or retyped from a screenshot must survive it.
 const ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789';
 export function newArtifactId() {
@@ -33,8 +41,74 @@ export function createArtifactStore(db, collection = 'artifacts') {
             await ref.update({ access: access === 'public' ? FieldValue.delete() : access });
             return true;
         },
+        history: (id) => historyOf(col, id),
+        version: (id, n) => versionOf(col, id, n),
+        setNote: (id, n, note) => setNote(col, id, n, note),
     };
 }
+const vid = (n) => String(n).padStart(6, '0');
+const currentOf = (a) => a.version ?? (a.versions?.length ?? 0) + 1;
+async function historyOf(col, id) {
+    const a = await getArtifact(col, id);
+    if (!a)
+        return null;
+    const current = { version: currentOf(a), at: a.updatedAt, ...(a.note ? { note: a.note } : {}), current: true };
+    let past;
+    if (a.versions) {
+        past = a.versions.map((v, i) => ({ version: i + 1, at: v.at }));
+    }
+    else {
+        // `select` keeps the bodies out: a 55 KB page republished 40 times is 2 MB of history.
+        const snap = await col().doc(id).collection('versions').select('version', 'at', 'note').get();
+        past = snap.docs.map((d) => {
+            const v = d.data();
+            return { version: v.version, at: v.at, ...(v.note ? { note: v.note } : {}) };
+        });
+    }
+    return [current, ...past.filter((v) => v.version < current.version).sort((x, y) => y.version - x.version)];
+}
+async function versionOf(col, id, n) {
+    if (!Number.isInteger(n) || n < 1)
+        return null;
+    const a = await getArtifact(col, id);
+    if (!a)
+        return null;
+    const cur = currentOf(a);
+    if (n === cur) {
+        return { version: n, at: a.updatedAt, markdown: a.markdown, title: a.title, summary: a.summary, current: true,
+            ...(a.subtitle ? { subtitle: a.subtitle } : {}), ...(a.note ? { note: a.note } : {}) };
+    }
+    if (n > cur)
+        return null;
+    if (a.versions) {
+        const v = a.versions[n - 1];
+        return v ? { version: n, at: v.at, markdown: v.markdown } : null;
+    }
+    const snap = await col().doc(id).collection('versions').doc(vid(n)).get();
+    if (!snap.exists)
+        return null;
+    const v = snap.data();
+    return { ...v, version: n };
+}
+async function setNote(col, id, n, note) {
+    const a = await getArtifact(col, id);
+    if (!a || !Number.isInteger(n) || n < 1)
+        return false;
+    const clean = note === null ? undefined : cleanNote(note);
+    const value = clean ?? FieldValue.delete();
+    if (n === currentOf(a)) {
+        await col().doc(id).update({ note: value });
+        return true;
+    }
+    // A legacy array is moved out on the next save; notes go on the moved docs, so move it first.
+    if (a.versions)
+        return false;
+    const ref = col().doc(id).collection('versions').doc(vid(n));
+    if (!(await ref.get()).exists)
+        return false;
+    await ref.update({ note: value });
+    return true;
+}
 async function getArtifact(col, id) {
     const snap = await col().doc(id).get();
     if (!snap.exists)
@@ -43,6 +117,7 @@ async function getArtifact(col, id) {
 }
 async function saveArtifact(col, input) {
     const now = new Date().toISOString();
+    const note = cleanNote(input.note) ?? cleanNote(input.meta.change);
     const fields = {
         title: input.meta.title,
         summary: input.meta.summary,
@@ -69,12 +144,25 @@ async function saveArtifact(col, input) {
         const history = ref.collection('versions');
         const legacy = existing.versions ?? [];
         const current = existing.version ?? legacy.length + 1;
-        const vid = (n) => String(n).padStart(6, '0');
-        // Move any legacy array out first, then file the body being replaced under its own number.
+        // Move any legacy array out first, whatever else this save does.
         for (let i = 0; i < legacy.length; i++)
             await history.doc(vid(i + 1)).set({ version: i + 1, ...legacy[i] });
-        await history.doc(vid(current)).set({ version: current, markdown: existing.markdown, at: existing.updatedAt });
-        const next = current + 1;
+        // Three ways a save is NOT a new version: the publisher finishing the publish it started
+        // (amend), and a republish whose body is unchanged with nothing to say about it (narration
+        // attached by an older publisher, a metadata-only fix). Either way the version and its note
+        // stand, and only the fields move.
+        const same = input.markdown === existing.markdown && !note;
+        const fresh = !input.amend && !same;
+        // A note the file still carries from the version it replaces is a stale line, not news.
+        const nextNote = fresh ? (note && note !== existing.note ? note : undefined) : (note ?? existing.note);
+        if (fresh) {
+            await history.doc(vid(current)).set({
+                version: current, markdown: existing.markdown, at: existing.updatedAt,
+                title: existing.title, summary: existing.summary,
+                ...(existing.subtitle ? { subtitle: existing.subtitle } : {}), ...(existing.note ? { note: existing.note } : {}),
+            });
+        }
+        const next = fresh ? current + 1 : current;
         // An update merges, so a password the file no longer carries has to be cleared on purpose:
         // otherwise removing the line from the file would leave the door up on the live page.
         const password = input.meta.password ? {} : { password: FieldValue.delete() };
@@ -92,7 +180,10 @@ async function saveArtifact(col, input) {
             ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
         };
         await ref.update({
-            ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, updatedAt: now, version: next,
+            ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, version: next,
+            // `updatedAt` is when this version went live; finishing its own publish does not move it.
+            ...(fresh || input.markdown !== existing.markdown ? { updatedAt: now } : {}),
+            note: nextNote ?? FieldValue.delete(),
             ...(existing.versions ? { versions: FieldValue.delete() } : {}),
         });
         return { id: input.id, version: next, created: false };
@@ -105,6 +196,7 @@ async function saveArtifact(col, input) {
         createdAt: now,
         updatedAt: now,
         version: 1,
+        ...(note ? { note } : {}),
         views: 0,
     };
     await col().doc(id).set(rec);

package/lib/artifacts/updated-at.d.ts

@@ -0,0 +1 @@
+export declare function formatUpdated(iso: string, timeZone?: string): string;

package/lib/artifacts/updated-at.js

@@ -0,0 +1,11 @@
+// The "Updated" line under an artifact's summary, to the exact minute with its zone named.
+// The server renders UTC; the reader swaps in the viewer's own zone once it runs, so the minute
+// is always one a person can place (Gary, 2026-09-27).
+export function formatUpdated(iso, timeZone = 'UTC') {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return '';
+    const date = d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone });
+    const time = d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', timeZone, timeZoneName: 'short' });
+    return `${date} at ${time}`;
+}

package/lib/reader/updated-time.d.ts

@@ -0,0 +1,4 @@
+/** The exact minute a page was last updated, in the reader's own time zone once the page runs. */
+export declare function UpdatedTime({ iso }: {
+    iso: string;
+}): import("react").JSX.Element;

package/lib/reader/updated-time.js

@@ -0,0 +1,12 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { formatUpdated } from '../artifacts/updated-at.js';
+/** The exact minute a page was last updated, in the reader's own time zone once the page runs. */
+export function UpdatedTime({ iso }) {
+    const [text, setText] = useState(() => formatUpdated(iso));
+    useEffect(() => {
+        setText(formatUpdated(iso, Intl.DateTimeFormat().resolvedOptions().timeZone));
+    }, [iso]);
+    return (_jsx("time", { dateTime: iso, suppressHydrationWarning: true, children: text }));
+}

package/lib/reader/version-history.d.ts

@@ -0,0 +1,14 @@
+export type HistoryItem = {
+    version: number;
+    at: string;
+    note?: string;
+    current?: boolean;
+};
+export declare function VersionHistory({ items, base, viewing }: {
+    /** Newest first, current included. */
+    items: HistoryItem[];
+    /** The current page's path, e.g. "/abc23456"; a past version lives at `${base}/v/<n>`. */
+    base: string;
+    /** The version this page shows. */
+    viewing: number;
+}): import("react").JSX.Element;

package/lib/reader/version-history.js

@@ -0,0 +1,97 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The page's history, opened from the "Version N" line under the summary. The list renders
+// through a portal on document.body, OUTSIDE the text flow, like the definition layer, so opening
+// it cannot reflow a word of the page: on a phone it is a sheet pinned to the bottom, above the
+// narration bar; on a desk it is a panel pinned to the right of the window. Escape, the close
+// button, or a tap outside closes it.
+//
+// It exists so an author never hand-writes a "Version history" section at the end of the
+// markdown again (2026-09-27): the store already keeps every version, and each one carries
+// the one-line note it was published with.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { formatUpdated } from '../artifacts/updated-at.js';
+const PHONE = '(max-width: 639px)';
+const MARGIN = 16;
+const VARS = ['--a-ground', '--a-ink', '--a-accent', '--a-line'];
+export function VersionHistory({ items, base, viewing }) {
+    const [open, setOpen] = useState(false);
+    const [phone, setPhone] = useState(false);
+    const [bottom, setBottom] = useState(MARGIN);
+    const [vars, setVars] = useState({});
+    const [zone, setZone] = useState('UTC');
+    const button = useRef(null);
+    const panel = useRef(null);
+    const measure = useCallback(() => {
+        const el = button.current;
+        if (!el)
+            return;
+        const cs = getComputedStyle(el);
+        setVars({ ...Object.fromEntries(VARS.map((v) => [v, cs.getPropertyValue(v).trim()]).filter(([, x]) => x)), fontFamily: cs.fontFamily });
+        const isPhone = window.matchMedia ? window.matchMedia(PHONE).matches : window.innerWidth < 640;
+        setPhone(isPhone);
+        const bar = document.querySelector('[data-artifact-player]')?.getBoundingClientRect();
+        setBottom((bar && bar.top < window.innerHeight ? window.innerHeight - bar.top : 0) + MARGIN);
+    }, []);
+    const close = useCallback(() => {
+        setOpen(false);
+        button.current?.focus();
+    }, []);
+    useEffect(() => {
+        setZone(Intl.DateTimeFormat().resolvedOptions().timeZone);
+    }, []);
+    useEffect(() => {
+        if (!open)
+            return;
+        measure();
+        panel.current?.focus();
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                close();
+        };
+        const onDown = (e) => {
+            const t = e.target;
+            if (panel.current?.contains(t) || button.current?.contains(t))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener('keydown', onKey);
+        document.addEventListener('pointerdown', onDown);
+        window.addEventListener('resize', measure);
+        return () => {
+            document.removeEventListener('keydown', onKey);
+            document.removeEventListener('pointerdown', onDown);
+            window.removeEventListener('resize', measure);
+        };
+    }, [open, measure, close]);
+    const style = {
+        ...vars,
+        zIndex: 60,
+        boxSizing: 'border-box',
+        borderRadius: 12,
+        background: 'var(--a-ground, #fff)',
+        color: 'var(--a-ink, #111)',
+        border: '1px solid var(--a-line, rgba(127,127,127,0.3))',
+        boxShadow: '0 16px 40px rgba(0,0,0,0.3)',
+        fontSize: 15,
+        lineHeight: 1.45,
+        fontStyle: 'normal',
+        textAlign: 'left',
+        overflowY: 'auto',
+        overscrollBehavior: 'contain',
+        outline: 'none',
+        ...(phone
+            ? { position: 'fixed', left: MARGIN, right: MARGIN, bottom: `calc(${bottom}px + env(safe-area-inset-bottom, 0px))`, maxHeight: '65vh' }
+            : { position: 'fixed', top: 80, right: 24, width: 380, maxHeight: 'calc(100vh - 120px)' }),
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: button, type: "button", "data-version-history": true, "aria-haspopup": "dialog", "aria-expanded": open, onClick: () => setOpen((o) => !o), style: { font: 'inherit', color: 'inherit', background: 'none', border: 0, padding: 0, cursor: 'pointer', textDecoration: 'underline', textUnderlineOffset: '0.2em' }, children: "History" }), _jsx("span", { hidden: true, "data-version-list": true, children: items.map((v) => (_jsx("a", { href: v.current ? base : `${base}/v/${v.version}`, children: `Version ${v.version}${v.note ? `: ${v.note}` : ''}` }, v.version))) }), open && typeof document !== 'undefined'
+                ? createPortal(_jsxs("div", { ref: panel, "data-version-panel": true, role: "dialog", "aria-label": "Version history", tabIndex: -1, style: style, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '14px 18px 8px' }, children: [_jsx("span", { style: { fontSize: 11, fontWeight: 500, letterSpacing: '0.2em', textTransform: 'uppercase', opacity: 0.6 }, children: "Version history" }), _jsx("button", { type: "button", "aria-label": "Close", onClick: close, style: { font: 'inherit', fontSize: 20, lineHeight: 1, color: 'inherit', background: 'none', border: 0, padding: 4, cursor: 'pointer', opacity: 0.6 }, children: "\u00D7" })] }), _jsx("ol", { style: { listStyle: 'none', margin: 0, padding: '0 8px 10px' }, children: items.map((v) => {
+                                const here = v.version === viewing;
+                                return (_jsx("li", { children: _jsxs("a", { href: v.current ? base : `${base}/v/${v.version}`, "aria-current": here ? 'page' : undefined, style: {
+                                            display: 'block', padding: '10px 10px', borderRadius: 8, color: 'inherit', textDecoration: 'none',
+                                            background: here ? 'color-mix(in srgb, var(--a-accent, #888) 14%, transparent)' : undefined,
+                                        }, children: [_jsxs("span", { style: { display: 'flex', gap: 8, alignItems: 'baseline', flexWrap: 'wrap' }, children: [_jsx("strong", { style: { fontWeight: 600 }, children: `Version ${v.version}` }), v.current ? _jsx("span", { style: { fontSize: 12, color: 'var(--a-accent)' }, children: "current" }) : null, _jsx("time", { dateTime: v.at, style: { fontSize: 12, opacity: 0.6 }, children: formatUpdated(v.at, zone) })] }), v.note ? _jsx("span", { style: { display: 'block', marginTop: 2, fontSize: 14, opacity: 0.85 }, children: v.note }) : null] }) }, v.version));
+                            }) })] }), document.body)
+                : null] }));
+}

package/lib/routes/artifacts.d.ts

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next';
 import { NextRequest, NextResponse } from 'next/server';
-import type { ArtifactStore } from '../artifacts/store.js';
+import { type ArtifactStore, type VersionEntry } from '../artifacts/store.js';
 import type { StateStore } from '../artifacts/state-store.js';
 import { type ArtifactAssets } from '../artifacts/assets.js';
 import type { BrandPack } from '../brand/pack.js';
@@ -51,6 +51,17 @@ type PageProps = Params & {
         key?: string | string[];
     }>;
 };
+type VersionParams = {
+    params: Promise<{
+        id: string;
+        n: string;
+    }>;
+};
+type VersionProps = VersionParams & {
+    searchParams?: Promise<{
+        key?: string | string[];
+    }>;
+};
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     dynamic: "force-dynamic";
     maxDuration: number;
@@ -71,6 +82,14 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     }) => Promise<NextResponse<unknown>>;
     Page: ({ params, searchParams }: PageProps) => Promise<import("react").JSX.Element>;
     generateMetadata: ({ params }: Params) => Promise<Metadata>;
+    VersionPage: ({ params, searchParams }: VersionProps) => Promise<import("react").JSX.Element>;
+    generateVersionMetadata: ({ params }: VersionParams) => Promise<Metadata>;
+    VERSIONS: (request: NextRequest, { params }: Params) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        id: string;
+        versions: VersionEntry[] | null;
+    }>>;
     POST: (request: NextRequest) => Promise<NextResponse<{
         error: string;
     }> | NextResponse<{

package/lib/routes/artifacts.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { revalidatePath } from 'next/cache';
-import { notFound } from 'next/navigation';
+import { notFound, redirect } from 'next/navigation';
 import { NextResponse } from 'next/server';
 import { isPublishAuthed } from '../artifacts/auth.js';
 import { parseArtifactSource } from '../artifacts/front-matter.js';
@@ -8,6 +8,7 @@ import { narrationText } from '../artifacts/narration.js';
 import { ArtifactMarkdown } from '../artifacts/render.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
+import { cleanNote } from '../artifacts/store.js';
 import { shapeChanges } from '../artifacts/state.js';
 import { ASSET_DIGEST, ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
@@ -16,6 +17,8 @@ import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
 import { renderShareCard } from '../brand/share-card.js';
 import { ArtifactReader } from '../reader/artifact-reader.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
+import { UpdatedTime } from '../reader/updated-time.js';
+import { VersionHistory } from '../reader/version-history.js';
 import { ACCESS_LEVELS, GRANT_COOKIE, GRANT_TTL_SECONDS, decide, firstName, mintGrant, safeReturnPath, signInUrl, verifyGrant, verifyPass, } from '../artifacts/reader.js';
 import { FLAG_KINDS, summarize } from '../artifacts/readers-store.js';
 import { AckDoor, ConfidentialBanner, NO_PRINT_CSS, NotAllowedDoor, SignInDoor, Watermark, ackText } from '../artifacts/confidential.js';
@@ -23,6 +26,8 @@ import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
+/** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
+const VERSION_N = /^[1-9]\d{0,5}$/;
 async function defaultReadCookie(name) {
     const { cookies } = await import('next/headers');
     return (await cookies()).get(name)?.value;
@@ -75,13 +80,34 @@ export function createArtifactRoutes(config) {
             },
         };
     }
+    /** GET /<id>/v/<n>: the metadata of a past version. Never indexed, like every page. */
+    async function generateVersionMetadata({ params }) {
+        const { id, n } = await params;
+        const m = await generateMetadata({ params: Promise.resolve({ id }) });
+        if (!VERSION_N.test(n) || m.title === 'Not found')
+            return { title: 'Not found', robots: { index: false, follow: false } };
+        return { ...m, title: `${String(m.title)} (version ${n})`, alternates: { canonical: `${pagePath(id)}/v/${n}` } };
+    }
     async function Page({ params, searchParams }) {
         const { id } = await params;
+        return serve(id, searchParams, null);
+    }
+    /** /<id>/v/<n>: one past version, read-only, behind exactly the door the current page has. */
+    async function VersionPage({ params, searchParams }) {
+        const { id, n } = await params;
+        if (!VERSION_N.test(n))
+            notFound();
+        return serve(id, searchParams, Number(n));
+    }
+    /** The current page (n null) or one past version, through the same gate. The version is looked
+     *  up only AFTER the gate opens, so a shut page never says which versions exist. */
+    async function serve(id, searchParams, n) {
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
         if (!a)
             notFound();
+        const render = (top) => (n === null ? Body(a, { top }) : VersionBody(a, n, { top }));
         if (a.access)
-            return GatedPage(a, id);
+            return GatedPage(a, id, render, n);
         // A password shuts the body, never the title: the header stays so the reader knows which
         // page they were sent, and the unfurl (generateMetadata) keeps reading as the page.
         const sp = (await searchParams) ?? {};
@@ -106,12 +132,15 @@ export function createArtifactRoutes(config) {
         if (!open) {
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }), _jsx(ArtifactDoor, { brand: brand, wrongKey: key !== undefined })] }));
         }
-        void store.bumpViews(id);
-        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, await Body(a, { top: true })] }));
+        const page = await render(true);
+        if (n === null)
+            void store.bumpViews(id);
+        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, page] }));
     }
     /** A page with `access:`. The body is rendered only after the reader is known and allowed;
      *  everyone else gets the title, the summary, and a door. */
-    async function GatedPage(a, id) {
+    async function GatedPage(a, id, render, n) {
+        const here = n === null ? pageUrl(id) : `${pageUrl(id)}/v/${n}`;
         const readCookie = config.readCookie ?? defaultReadCookie;
         const reader = verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE));
         const allow = config.readers && reader ? await config.readers.allowList(id) : [];
@@ -122,15 +151,42 @@ export function createArtifactRoutes(config) {
                 void config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, d.why === 'not-allowed'
                         ? _jsx(NotAllowedDoor, { brand: brand, reader: d.reader, signOutUrl: signOutUrl(id) })
-                        : _jsx(SignInDoor, { brand: brand, href: signInOrigin ? signInUrl(signInOrigin, pageUrl(id)) : undefined })] }));
+                        : _jsx(SignInDoor, { brand: brand, href: signInOrigin ? signInUrl(signInOrigin, here) : undefined })] }));
         }
         const r = reader;
         // The agreement comes before the body, every reader, once per page. No agreement, no body.
         if (config.readers && !(await config.readers.acknowledged(id, r.email))) {
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, _jsx(AckDoor, { brand: brand, name: firstName(r, allow), email: r.email, owner: owner, pageId: id, signOutUrl: signOutUrl(id) })] }));
         }
-        void store.bumpViews(id);
-        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: NO_PRINT_CSS } }), _jsx(Watermark, { email: r.email }), _jsx("div", { className: "px-6 pt-20 sm:pt-24", children: _jsx(ConfidentialBanner, { name: firstName(r, allow), email: r.email, reason: d.reason, owner: owner, brand: brand, signOutUrl: signOutUrl(id) }) }), await Body(a, { top: false }), _jsx(ReaderWatch, { artifactId: id, endpoint: "/api/reader/track", accent: brand.accent })] }));
+        const page = await render(false);
+        if (n === null)
+            void store.bumpViews(id);
+        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: NO_PRINT_CSS } }), _jsx(Watermark, { email: r.email }), _jsx("div", { className: "px-6 pt-20 sm:pt-24", children: _jsx(ConfidentialBanner, { name: firstName(r, allow), email: r.email, reason: d.reason, owner: owner, brand: brand, signOutUrl: signOutUrl(id) }) }), page, _jsx(ReaderWatch, { artifactId: id, endpoint: "/api/reader/track", accent: brand.accent })] }));
+    }
+    /** Every version of a page, newest first, or null when the store keeps none. A failed read hides
+     *  the History control rather than failing the page. */
+    async function historyOf(id) {
+        if (!store.history)
+            return null;
+        return store.history(id).catch(() => null);
+    }
+    /** "Version N · Updated <minute> · History": the line under the summary. */
+    function VersionLine({ a, n, at, history }) {
+        return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
+    }
+    /** A past version: its own body and title, read-only (no narration, no answers), under a banner. */
+    async function VersionBody(a, n, { top }) {
+        const v = store.version ? await store.version(a.id, n) : null;
+        if (!v)
+            notFound();
+        if (v.current)
+            redirect(pagePath(a.id));
+        const history = await historyOf(a.id);
+        const of = history?.[0]?.version ?? n;
+        const title = v.title ?? a.title;
+        const summary = v.summary ?? a.summary;
+        const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history })] }), _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions })] })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top }) {
@@ -145,9 +201,8 @@ export function createArtifactRoutes(config) {
                 words = [];
             }
         }
-        const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
         const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsx(VersionLine, { a: a, n: a.version ?? (a.versions?.length ?? 0) + 1, at: a.updatedAt, history: await historyOf(a.id) })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
@@ -316,7 +371,11 @@ export function createArtifactRoutes(config) {
                     return NextResponse.json({ error: dodged.join('; ') }, { status: 400 });
             }
         }
-        const result = await store.save({ id, meta: parsed.meta, markdown: parsed.body });
+        // What changed, in the author's words: `?note=` from the publisher, else the file's `change:`.
+        // `?amend=1` is the publisher finishing the publish it started (image URLs, then narration).
+        const note = cleanNote(request.nextUrl.searchParams.get('note')) ?? parsed.meta.change;
+        const amend = request.nextUrl.searchParams.get('amend') === '1';
+        const result = await store.save({ id, meta: parsed.meta, markdown: parsed.body, note, amend });
         if ('notFound' in result)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         revalidatePath(pagePath(result.id));
@@ -403,6 +462,27 @@ export function createArtifactRoutes(config) {
             return new NextResponse(`no artifact with id ${id}`, { status: 404 });
         return renderShareCard(pack, a.title);
     }
+    /** GET|POST /api/artifacts/<id>/versions, publish key: the history, and a note written onto one
+     *  version after the fact. POST body: { version: number, note: string | null }. */
+    async function VERSIONS(request, { params }) {
+        if (!isPublishAuthed(request, config.publishKey()))
+            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        const { id } = await params;
+        if (!store.history || !store.setNote)
+            return NextResponse.json({ error: 'this store keeps no history' }, { status: 501 });
+        const history = ARTIFACT_ID.test(id) ? await store.history(id) : null;
+        if (!history)
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        if (request.method === 'GET')
+            return NextResponse.json({ id, current: history[0]?.version, versions: history }, { headers: { 'cache-control': 'no-store' } });
+        const b = (await request.json().catch(() => null));
+        if (!b || !Number.isInteger(b.version) || (b.note !== null && typeof b.note !== 'string'))
+            return NextResponse.json({ error: 'body is { version: <number>, note: <one line, or null to clear> }' }, { status: 400 });
+        if (!(await store.setNote(id, b.version, b.note)))
+            return NextResponse.json({ error: `no version ${String(b.version)} of ${id}` }, { status: 404 });
+        revalidatePath(pagePath(id));
+        return NextResponse.json({ id, versions: await store.history(id) });
+    }
     async function DELETE(request, { params }) {
         if (!isPublishAuthed(request, config.publishKey()))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
@@ -413,5 +493,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",