@supersuit/artifacts 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 `@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.42.0
+
+**One page can say who sees its version number and past versions: `history: everyone | admins` in
+front matter.** 0.41.0 made the number follow the host's `history` setting, which is one answer for
+every page on a host. A host carries both kinds of page: a letter to one person, where a version
+number is noise, and a spec its readers follow from draft to draft, where it is the point. The
+page's own line overrides the host's for that page; absent, nothing changes.
+
+- `history: everyone` shows that page's readers "Version N · Updated <minute>", Version history in
+  the page menu and every `/<id>/v/<n>`. `history: admins` keeps all three to admins on a host
+  configured `history: 'everyone'`. Admins always see them.
+- Content, like `toc:`: a republish without the line goes back to the host's setting.
+- Refused with `links: per-reader` (and so on a broadcast), because a per-reader page serves no past
+  versions and the list would be dead links. A page made per-reader by an earlier publish, whose
+  file no longer repeats the line, has its `history: everyone` ignored at render for the same reason.
+- `ArtifactMeta` and `ArtifactRecord` gain `history`; `PageHistory` and `PAGE_HISTORY` are exported
+  from the front matter module. `CoverProps.showVersion` follows the page's line.
+
+DETECTOR: a publisher that validates front matter keys itself, before the host does, refuses
+`history:` as unknown until it learns the key: `rg -n "comment_name" <your publisher>` finds such a
+list. A custom `ArtifactStore` that copies named fields drops `history` until it carries it.
+
+REMEDY: add `history` to such a list and to a custom store's saved fields. Nothing else: a page
+without the line behaves exactly as under 0.41.0.
+
+Tests: `src/artifacts/front-matter.test.ts` (both values, an unknown value, the per-reader and
+broadcast refusals), `src/artifacts/store.test.ts` (rides through; a republish without it clears
+it), `src/routes/page-menu.test.tsx` (a page's `everyone` on a default host, a page's `admins` on
+an `everyone` host, and who opens a past version). The three route tests fail when the route
+ignores the page's line.
+
 ## 0.41.0
 
 **A reader who may not see a page's history is no longer told its version number.** The line under

package/README.md

@@ -216,6 +216,14 @@ versions sees only "Updated <minute>" under the summary; admins, and every reade
 `history: 'everyone'`, see "Version N · Updated <minute>". A pack's `Cover` is handed
 `showVersion` alongside `version`, and draws the number itself only when it is true.
 
+**One page can choose for itself (0.42.0).** `history: everyone` in a page's front matter shows
+that page's readers the number, Version history and its past versions, on a host that keeps them
+to admins; `history: admins` does the reverse on a host that shows everyone. Use `everyone` for a
+document its readers follow from draft to draft (a spec, a plan, a paper under revision), and
+leave the line out of anything that reads as a message to someone. It is content, like `toc:`: a
+republish without the line goes back to the host's setting. A per-reader page serves no past
+versions, so `history: everyone` is refused there.
+
 ```ts
 createArtifactRoutes({ ..., ownerEmail: 'owner@example.com', admins: ['editor@example.com'] })
 ```
@@ -261,6 +269,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `links` | `per-reader`: the page opens only through a link made for one reader (see Per-reader links). Sticky: a republish whose file leaves the line out changes nothing |
 | `media` | `private`: the page's body media is kept private and served through short-lived signed URLs. Needs `links: per-reader`. Sticky like `links` |
 | `comment_name` | `required`: on a per-reader page, a comment through a group link needs a typed first name, and each browser on a group link is its own reader (see Per-reader links). Needs `links: per-reader` |
+| `history` | `everyone` or `admins`: who sees this page's version number and past versions, overriding the host's `history` for this one page (see Version history). Absent, the host decides. Refused as `everyone` on a per-reader page |
 | `change` | One line saying what this version changed (see Version history) |
 | `template` | `document` (the default, the read-along reader) or `broadcast` (one message card sent to several people; see Broadcasts) |
 

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

@@ -63,7 +63,15 @@ export type ArtifactMeta = {
     /** `comment_name: required` (0.40.0): on a per-reader page, a comment through a group link must
      *  carry a typed first name, and a named link is never asked for one. Opt-in; content, like `toc:`. */
     commentName?: 'required';
+    /** `history: everyone | admins` (0.42.0): who sees this page's version number and past versions,
+     *  overriding the host's `history` for this one page. `everyone` suits a document its readers
+     *  follow from draft to draft; a page that reads as a message leaves the line out. Content, like
+     *  `toc:`: a republish without the line goes back to the host's setting. */
+    history?: PageHistory;
 };
+/** Who sees a page's version number and past versions. */
+export type PageHistory = 'admins' | 'everyone';
+export declare const PAGE_HISTORY: readonly PageHistory[];
 /** What a page is. A broadcast is its own kind, not a document with extra flags: it renders as a
  *  message card, opens only through per-reader links, keeps its media private, has comments off
  *  and no narration by default, and expires 90 days after publish unless kept. */

package/lib/artifacts/front-matter.js

@@ -7,6 +7,7 @@ import { mergeChecklistState, mergeWidgetState, scanWidgets } from './widgets.js
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
+export const PAGE_HISTORY = ['admins', 'everyone'];
 export const ARTIFACT_KINDS = ['document', 'broadcast'];
 /** Any media in a body: an image, a video or an audio clip, written as markdown image syntax. */
 const MEDIA_IN_BODY = /!\[[^\]]*\]\(\s*<?([^)\s>]+)/g;
@@ -19,7 +20,7 @@ const PRIVATE_REF_IN_BODY = /^private:/;
 export const PACK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export const MAX_TO_CHARS = 60;
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name', 'history']);
 export function parseArtifactSource(text, 
 /** The kind a file that leaves `template:` out is read as: the stored page's kind on a
  *  republish, so a broadcast stays one (sticky, like `links:`). Default `document`. */
@@ -102,6 +103,11 @@ opts = {}) {
             return { ok: false, error: 'pack must be a pack name: lowercase letters, digits and dashes, up to 40 characters' };
         meta.pack = d.pack;
     }
+    if (d.history !== undefined && d.history !== null) {
+        if (!PAGE_HISTORY.includes(d.history))
+            return { ok: false, error: `history must be one of: ${PAGE_HISTORY.join(', ')}` };
+        meta.history = d.history;
+    }
     if (d.toc !== undefined) {
         if (typeof d.toc !== 'boolean')
             return { ok: false, error: 'toc must be true or false' };
@@ -150,6 +156,9 @@ opts = {}) {
     // People on one broadcast never see each other's comments, so a per-reader page cannot share them.
     if (meta.links === 'per-reader' && meta.commentsVisible === 'readers')
         return { ok: false, error: 'a per-reader page keeps each reader\'s comments to the owner: drop comments_visible: readers' };
+    // /<id>/v/<n> of a per-reader page is never served, so the history list would be dead links.
+    if (meta.history === 'everyone' && meta.links === 'per-reader')
+        return { ok: false, error: 'a per-reader page serves no past versions: drop history: everyone' };
     if (meta.commentName && meta.links !== 'per-reader')
         return { ok: false, error: 'comment_name: required needs links: per-reader' };
     // Widgets declare their own slots, so a notes block (and a checklist with send) is merged into state: here, before the

package/lib/artifacts/index.d.ts

@@ -1,4 +1,4 @@
-export { parseArtifactSource, ARTIFACT_KINDS, type ArtifactMeta, type ArtifactKind } from './front-matter.js';
+export { parseArtifactSource, ARTIFACT_KINDS, PAGE_HISTORY, type ArtifactMeta, type ArtifactKind, type PageHistory } from './front-matter.js';
 export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, kindOf, listOfKind, MAX_CHANGE_NOTE_CHARS, type ArtifactListItem, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';

package/lib/artifacts/index.js

@@ -1,4 +1,4 @@
-export { parseArtifactSource, ARTIFACT_KINDS } from './front-matter.js';
+export { parseArtifactSource, ARTIFACT_KINDS, PAGE_HISTORY } from './front-matter.js';
 export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, kindOf, listOfKind, MAX_CHANGE_NOTE_CHARS } from './store.js';

package/lib/artifacts/store.d.ts

@@ -33,6 +33,8 @@ export type ArtifactRecord = {
     pack?: string;
     toc?: boolean;
     commentName?: 'required';
+    /** The page's own `history:` line; absent, the host's setting decides. */
+    history?: 'admins' | 'everyone';
     definitions?: Definition[];
     /** Who may leave shared comments; absent is off. Personal notes need nothing. */
     comments?: CommentsMode;

package/lib/artifacts/store.js

@@ -164,6 +164,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.pack ? { pack: input.meta.pack } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
         ...(input.meta.commentName ? { commentName: input.meta.commentName } : {}),
+        ...(input.meta.history ? { history: input.meta.history } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
     };
     if (input.id) {
@@ -217,6 +218,7 @@ async function saveArtifact(col, input) {
             ...(input.meta.pack ? {} : { pack: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
             ...(input.meta.commentName ? {} : { commentName: FieldValue.delete() }),
+            ...(input.meta.history ? {} : { history: FieldValue.delete() }),
             ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
         };
         // `voice: none` is the page declaring it has no audio. An update merges, so the recording it

package/lib/routes/artifacts.js

@@ -86,8 +86,14 @@ export function createArtifactRoutes(config) {
     const owner = config.owner ?? brand.name;
     const ownerEmail = config.ownerEmail?.trim().toLowerCase();
     const admins = new Set([ownerEmail, ...(config.admins ?? []).map((e) => e.trim().toLowerCase())].filter((e) => !!e));
-    /** Whether this reader may see a page's past versions (config `history`). */
-    const seesHistory = (reader) => config.history === 'everyone' || (!!reader && admins.has(reader.email.trim().toLowerCase()));
+    /** Whether this reader may see this page's version number and past versions: the page's own
+     *  `history:` line when it has one, else the host's (config `history`). Admins always may. */
+    const seesHistory = (a, reader) => {
+        // A per-reader page serves no past versions, and `links:` is sticky host-side state a later
+        // file need not repeat, so the parser's refusal cannot catch every case: ignore the line here.
+        const page = a.history === 'everyone' && a.links === 'per-reader' ? undefined : a.history;
+        return (page ?? config.history) === 'everyone' || (!!reader && admins.has(reader.email.trim().toLowerCase()));
+    };
     const readerSecret = () => config.readerSecret?.();
     /** Who this reader is to this host's pages: the page menu's role. Owner and admins share a menu. */
     const roleOf = (reader) => {
@@ -230,7 +236,7 @@ export function createArtifactRoutes(config) {
             : a.password
                 ? (admin ? { url: `${pageUrl(a.id)}?key=${encodeURIComponent(a.password)}`, title: a.title, note: 'The link carries the password.' } : null)
                 : { url: pageUrl(a.id), title: a.title };
-        return (_jsx(PageMenu, { role: role, name: name, shutOut: shutOut, share: share, comments: !!comments, signIn: !reader && signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, signOut: reader ? signOutUrl(a.id) : null, history: history && history.length > 1 && seesHistory(reader) && viewing ? { items: history, base: pagePath(a.id), viewing } : null, markdown: admin && source ? source : null, settings: admin ? settings ?? null : null }));
+        return (_jsx(PageMenu, { role: role, name: name, shutOut: shutOut, share: share, comments: !!comments, signIn: !reader && signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, signOut: reader ? signOutUrl(a.id) : null, history: history && history.length > 1 && seesHistory(a, reader) && viewing ? { items: history, base: pagePath(a.id), viewing } : null, markdown: admin && source ? source : null, settings: admin ? settings ?? null : null }));
     }
     /** The kicker over every title: the pack's line, then who the page is for. Never spoken: the
      *  whole paragraph is data-nospeak, and narrationText has no `to` to read. */
@@ -434,7 +440,7 @@ export function createArtifactRoutes(config) {
     async function VersionBody(a, n, { top, reader }) {
         const { pack, brand } = lookOf(a);
         // Past versions are for admins unless the host says otherwise: to anyone else none exists.
-        if (!seesHistory(reader))
+        if (!seesHistory(a, reader))
             notFound();
         const v = store.version ? await store.version(a.id, n) : null;
         if (!v)
@@ -484,8 +490,8 @@ export function createArtifactRoutes(config) {
         const current = a.version ?? (a.versions?.length ?? 0) + 1;
         return (_jsxs(_Fragment, { children: [_jsx(Menu, { a: a, reader: reader, comments: mode !== 'off', history: history, viewing: current, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, a, a.markdown) : null }), toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
-                        const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt, numbered: seesHistory(reader) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
-                        const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, showVersion: seesHistory(reader), updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _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 }), meta] }));
+                        const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt, numbered: seesHistory(a, reader) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
+                        const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, showVersion: seesHistory(a, reader), updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _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 }), meta] }));
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, 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] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.41.0",
+  "version": "0.42.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",