@supersuit/artifacts 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -3,6 +3,117 @@
 `@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.41.0
+
+**A reader who may not see a page's history is no longer told its version number.** The line under
+the summary read "Version N · Updated <minute>" to everyone. A page sent to someone reads as a
+message, and "Version 9" on a message tells its reader about eight drafts they were never meant to
+think about. The number now goes with the history: whoever `history` lets see past versions
+(the owner and `admins` by default, every reader under `history: 'everyone'`) sees
+"Version N · Updated <minute>", and everyone else sees "Updated <minute>". There is no new config
+key; the existing `history` setting is the toggle, and its default is off for readers.
+
+- `CoverProps` gains `showVersion: boolean`, true exactly when this reader may see the number. The
+  `meta` node a Cover places already follows it. `version` is still handed over unchanged, so a
+  Cover that draws the number itself keeps drawing it until it reads `showVersion`.
+- A past version's page (`/<id>/v/<n>`) is unchanged: only a reader who may see the history reaches
+  it, so it still names its version.
+
+DETECTOR: a host whose pack has a `Cover` that renders `version`: `rg -n "version" <your packs>`.
+Such a Cover still shows the number to every reader after this release, because the shell cannot
+take a prop away from a pack. A host that relied on every reader seeing the version line and does
+not set `history: 'everyone'` will find the number gone for signed-out readers.
+
+REMEDY: in a Cover that draws the number, draw it only when `showVersion` is true. To show every
+reader the number (and the history with it), set `history: 'everyone'`.
+
+Tests: `src/routes/page-menu.test.tsx` (a visitor, a reader and a stranger get "Updated" with no
+version number; an admin and `history: 'everyone'` get "Version 2 · Updated"),
+`src/routes/extension-points.test.tsx` (a Cover is handed `showVersion` false for a reader and true
+under `history: 'everyone'`), `src/routes/versions.test.tsx` and `src/routes/broadcast.test.tsx`
+(the two tests that pinned the old line now pin the new one). All three new tests failed against
+0.40.1.
+
+## 0.40.1
+
+**0.40.0 was tagged and never published: this is the first release carrying it.** The publish
+workflow runs the tests before it publishes, and one test failed there, so nothing reached npm
+under 0.40.0. Everything in the 0.40.0 entry below ships in this version, unchanged.
+
+- The failing test was the comment card's, and the defect was in the tests, not the card: a name
+  one test saved was still remembered by the next wherever the runtime has a working
+  `localStorage` (Node 24, which the workflow uses) and gone where it does not (Node 25), so
+  "asks for a first name before sending" passed on one and failed on the other. Every card test
+  now starts with its own empty storage.
+
+DETECTOR: `npm view @supersuit/artifacts versions --json` lists no `0.40.0`. A host pinned to
+exactly `0.40.0` cannot install.
+
+REMEDY: take `0.40.1`. There is no code difference from what 0.40.0 described.
+
+Tests: `src/reader/comment-card.test.tsx` gives each test a fresh storage; the old file fails three
+tests when storage persists between tests, and the new one passes either way.
+
+## 0.40.0
+
+**A per-reader page can be a feedback round: a window per reader, a name on every note where the
+page asks for one, a reply the commenter can see.** Nothing changes for a page that uses none of it.
+
+- A reader carries `closesAt`. The recipients route sets it (`add[].closes`), moves or clears it
+  (`closes: { rids, at }`), and reports it (`closesAt` in the listing and in `/views`). Past it the
+  state route refuses a new shared comment or an edit with `403 { closed: true }`; the page and the
+  reader's own comments stay readable, and deleting their own still works. `RecipientsStore.setCloses`
+  is optional, so a host's own store keeps working (the route answers 501 to a `closes` change
+  without it).
+- The page draws it: whose draft, the publisher's note to that reader, and a live countdown, in
+  place of the `For <label>: <note>` line. A reader with no window sees what they saw before.
+- `comment_name: required` (front matter, per-reader pages only): a group reader's shared comment
+  needs a typed first name (`400 { needsName: true }` without one); a reader on a named link is
+  never asked, in the card or the reply form, and a typed name is dropped.
+- Under `comment_name: required`, and only there, **each browser on a group link is its own
+  reader**. Until now a group link was one reader (`r:<rid>`): everyone holding it saw every note
+  left through it as their own, could edit and delete them, and saw the publisher's reply to any of
+  them. With the line, a browser's notes are stored under `r:<rid>.<24 hex>`, which the server
+  derives (an HMAC keyed by the recipient secret) from the page, the link's verified rid and the
+  anonymous-reader cookie (`artifact_anon`) it sets with that browser's first note. A client cannot
+  name a key or work out another browser's, and the stored key is not the cookie. A browser that
+  clears its cookies is a new reader. A named link is unchanged, and so is a group link on a page
+  without the line (one shared reader, as in 0.39.0). The window, the feed's `reader.rid` and the
+  `/views` comments stay per link.
+- `POST /api/artifacts/<id>/reply` (publish key): the publisher's one reply in a thread, optionally
+  pinned to the passage that changed. On a per-reader page only the thread's own writer is shown it
+  (under `comment_name: required`, only the browser that wrote it). It never reopens a resolved
+  thread under `open=1`.
+- A `template: broadcast` page with comments on hands its comment layer the window and the name
+  rule, as a document does: a group reader is asked for a first name, and a closed window stops
+  offering Share. A broadcast draws no banner.
+- An owner added with `closes` gets no window (the owner never has one).
+- Feed rows gain `reader: { rid, label } | null`, `by` and `publisher`. No field is removed.
+
+DETECTOR: on a page with at least one reader,
+`curl -s -H "Authorization: Bearer $KEY" "$HOST/api/artifacts/<id>/recipients" | grep -c closesAt`
+answers 0 on a host older than this (a page with no readers answers 0 on any version). For the
+group link: a host is affected if it has sent one group link to people who should not read each
+other's notes. `GET /api/artifacts/<id>/responses` shows it: rows in the `comments` slot whose
+`reader` is the bare `r:<rid>` of a link `GET /recipients` lists with `group: true` were written as
+the one shared reader.
+
+REMEDY: take 0.40.0 and add the reply route file (README, "Replying as the publisher"). A host with
+its own `RecipientsStore` adds `setCloses` to use feedback windows. A publisher that strips unknown
+front matter keys lets `comment_name` through. To give the people on a group link their own notes,
+republish the page with `comment_name: required`; the host needs nothing else (the cookie is the
+one anonymous readers already get). Notes left through that link before the republish stay with
+the publisher and are shown to no browser afterwards. Anything that matched a reader key to a link
+with `key === 'r:' + rid` now reads the rid with `ridOfReaderKey(key)` instead, or it misses the
+notes of a browser on a group link.
+
+Tests: `recipients-store.test.ts`, `recipients-api.test.tsx`, `recipients.test.ts`,
+`front-matter.test.ts`, `store.test.ts`, `comments.test.tsx` (closed window, names, reply
+visibility, two browsers on one group link with and without the line), `comments-feed.test.tsx`,
+`feedback-window.test.tsx`, `comment-card.test.tsx`, `comment-layer.test.tsx`,
+`per-reader.test.tsx`, `broadcast-feedback.test.tsx`; `unchanged-default.test.tsx` and
+`broadcast.test.tsx` unedited.
+
 ## 0.39.0
 
 **A session demo's frame fits its player, and is wider than the reading column on a wide screen.**

package/README.md

@@ -194,7 +194,8 @@ before 0.31.0 has no `declared` and takes its file on its next publish, as every
 
 ## Version history
 
-Every page names its version under the summary, "Version 4 · Updated <minute>", and the page
+Every page says when it was last updated under the summary, and to its admins that line also names
+the version: "Version 4 · Updated <minute>". The page
 menu's **Version 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
@@ -205,9 +206,15 @@ the same password or confidential door as the page itself. A version that does n
 **Past versions are for admins by default (0.21.0).** An earlier draft can hold what the current
 one was edited to remove, so only the page's admins see Version history in the page menu or open
 `/<id>/v/<n>`: the reader signed in as `ownerEmail` or any address in `admins` (case does not
-matter). Everyone else still sees "Version N · Updated <minute>", and a past version is a 404 to
-them. With neither configured, nobody does. `history: 'everyone'` in the config restores the old
-behaviour, where every reader who can open the page reads its history.
+matter). A past version is a 404 to everyone else. With neither configured, nobody does.
+`history: 'everyone'` in the config restores the old behaviour, where every reader who can open
+the page reads its history.
+
+**The version number goes with the history (0.41.0).** A page sent to someone reads as a message,
+and "Version 9" on a message tells its reader about eight drafts. So whoever may not see past
+versions sees only "Updated <minute>" under the summary; admins, and every reader under
+`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.
 
 ```ts
 createArtifactRoutes({ ..., ownerEmail: 'owner@example.com', admins: ['editor@example.com'] })
@@ -253,6 +260,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `definitions` | Terms defined inline (below). A republish without it removes 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` |
 | `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) |
 
@@ -748,6 +756,36 @@ type Ctx = { params: Promise<{ id: string }> }
 export function POST(request: NextRequest, ctx: Ctx) { return artifacts.RESOLVE(request, ctx) }
 ```
 
+
+### Replying as the publisher (0.40.0)
+
+    POST /api/artifacts/<id>/reply
+    Authorization: Bearer <publish key or publisher pass>
+    Content-Type: application/json
+
+    { "entry": "<entryId>", "body": "Named the river in the second paragraph.", "by": "Pat", "quote": "the river Ash" }
+
+    200 { id, entry, parent, existing }
+
+One reply per thread when calls do not overlap. `entry` may name a reply: the thread it belongs to
+is answered. A second call for a thread already answered changes nothing and names the first reply
+back with `existing: true`, so a caller that retries does not post twice. The check is a read and
+then an append, so two overlapping calls can both post. `by` defaults to "the publisher". `quote`
+(text on the page, at most 500 characters) pins the reply to the passage that changed, and the
+thread then offers "Show what changed"; without it the reply sits where its thread does. On a
+per-reader page the reply is shown to the reader whose comment started the thread and to no other
+reader. It is allowed after that reader's window has closed. On a page that is not per-reader
+and whose comments are owner-only (`comments_visible: owner`), `REPLY` still answers 200 and stores
+the reply, but the commenter is not shown it: only the owner, the admins and the feed are. The feed lists it with
+`publisher: true`, and a publisher reply never reopens a resolved thread under `open=1`. 404 for a
+page or comment that is not there, 501 with no `state`.
+
+    // app/api/artifacts/[id]/reply/route.ts
+    import type { NextRequest } from 'next/server'
+    import { artifacts } from '@/lib/artifacts'
+    type Ctx = { params: Promise<{ id: string }> }
+    export function POST(request: NextRequest, ctx: Ctx) { return artifacts.REPLY(request, ctx) }
+
 ### Telling commenters their comments were resolved (`createResolveDigests`)
 
 When threads are resolved, each signed-in reader whose comments were in them can get ONE email per
@@ -800,12 +838,12 @@ appear (the privacy test covers this handler like every other).
 GET /api/comments?since=2026-09-28T12:00:00Z
 Authorization: Bearer <publish key>
 
-200 { now, cursor, more, comments: [ { artifactId, title, entryId, parent, name, quote, region,
-                                       body, transcript, audioUrl, at, resolved, link } ] }
+200 { now, cursor, more, comments: [ { artifactId, title, entryId, parent, name, reader, by, publisher,
+                                       quote, region, body, transcript, audioUrl, at, resolved, link } ] }
 ```
 
 Oldest first, at most 200, strictly after `since` (an ISO 8601 time with a zone; anything else is
-a 400). `name` is null for an anonymous reader; `quote` is the text the comment is pinned to, or
+a 400). `name` is null for an anonymous reader; `reader` is `{ rid, label }` for a comment left through a per-reader link, else null; `by` is the name its writer typed, else null; `publisher` is true for a reply written through the reply route; `quote` is the text the comment is pinned to, or
 null for a box (`region: true`); `parent` is the comment a reply answers; `audioUrl` is a signed
 URL to the recording, when there is one and the host can sign it. `link` is the page with
 `#comment-<entryId>`: opening it scrolls to the pin and opens its thread (a reply opens its
@@ -863,7 +901,7 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 | Route | Who | What |
 |---|---|---|
 | `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
-| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group? }], revoke?: [rid] or '*', expires?: ISO time or null }`. `add` answers each new reader's link; `expires: null` is Keep |
+| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null } }`. `add` answers each new reader's link; `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window |
 | `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
 | `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
 
@@ -879,6 +917,58 @@ A view is the page rendered in a real browser, visible, for at least 2 seconds.
 
 `expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
 
+### A feedback window (0.40.0)
+
+A reader may carry `closesAt`, the time their feedback window closes. It is per reader, set when
+the reader is added (`add[].closes`) or afterwards (`closes: { rids, at }`, where `rids` is a list
+of reader ids or `'*'` for every reader but the owner, and `at: null` clears the window). The owner
+never has one: `closes` on an `add` entry with `owner: true` is dropped. It is
+separate from the page's `expires`: a reader past their window still opens the page and reads
+their own comments. A time in the past closes the window now, and a window that cannot be read as
+a time counts as closed. `closes` answers `windowed`, the reader ids it changed, beside `added` and
+`revoked`. A host with its own `RecipientsStore` needs `setCloses` for this; without it the route
+answers 501 to a `closes` change.
+
+Once the window is closed, a new shared comment or an edit is refused with
+`403 { error: "Feedback on this draft is closed. Your note was not sent.", closed: true }`.
+Deleting their own comment (`remove`) still works. `GET /state` answers
+`feedback: { closesAt, closed }` for a reader who has a window, and `GET /recipients` and
+`GET /views` carry each reader's `closesAt` (null when there is none).
+
+The page says so. A reader with a window sees, above the title, "A draft from <owner>, for
+<label>" (a group link names nobody), the note the publisher wrote for them, and how long is left,
+counted in days from two days up, then hours from two hours, then minutes, and live while the page
+stays open. Past it the line reads "Feedback is closed. You can still read the draft and your own
+notes." A reader with no window sees the `For <label>: <note>` line as before. In a thread, a
+comment of theirs that nobody has answered shows "Waiting for a reply." while the window exists.
+
+### A name on every note: `comment_name: required` (0.40.0)
+
+A per-reader page that says `comment_name: required` in its front matter puts a name on every
+shared comment. A `group` reader (one link shared by several people) must type a first name:
+without one the state route answers `400 { error: "Add your first name, so your note has a name on
+it.", needsName: true }`, and the comment card, the reply form and a signed-in reader's card all
+ask before they send. A reader on a named link is never asked, and a name sent for them is
+dropped: the label is who they are. The line needs `links: per-reader` (a page without it is
+refused), and a republish that leaves it out removes it. A page without the line takes names
+exactly as before.
+
+**Who a group link is.** Without `comment_name: required`, a group link is one shared reader:
+everyone who opens it sees every note left through it as their own, can edit or delete any of
+them, and sees the publisher's reply to any of them. Do not send one to people who should not read
+each other's notes. With the line, each browser on a group link is its own reader: it sees, edits
+and deletes only the notes written from that browser, and is shown only the publisher's replies to
+those. The browser is known by the anonymous-reader cookie (`artifact_anon`, HttpOnly, a year), set
+with its first note, and its notes are stored under a key the server derives from the link and that
+cookie (`r:<rid>.<24 hex>`), never under the cookie itself; `ridOfReaderKey(key)` reads the
+link's rid out of either shape. A browser that clears its cookies, or a
+second device, is a new reader: the notes it left stay with the publisher and are no longer shown
+to it. So does a reader who signs in on another page of the same host, since signing in clears the
+anonymous cookie. Notes left through a group link before the page gained the line were written as
+the one shared reader (`r:<rid>`) and are shown to no browser afterwards. A named link is one
+reader either way. The feedback window, the feed's `reader: { rid, label }` and the `/views` line
+stay per link: every browser on a group link shares them.
+
 ## Broadcasts (`template: broadcast`)
 
 A broadcast is its own page kind, not a document with extra flags. It is one message sent to several people, each through their own link, and it renders as one card: the sender's words at the top, then the media in the order the words put it (a video with sound and controls, photos, a voice note's player, link cards), then that person's own note. None of the document's furniture: no table of contents, no version line, no read-along, and no page menu for a reader.
@@ -902,7 +992,7 @@ What the kind decides, so the file does not have to:
 - **Per-reader links, always.** `links: per-reader` is implied. The kind is sticky like `links:`: a republish that leaves `template:` out stays a broadcast, and one that says `document` is refused (409). `access`, `password` and `comments_visible: readers` are refused in words.
 - **Private media wherever there is media.** `media: private` is implied as soon as the body carries a stored private file or a local one (a remote URL alone stores nothing, so it does not count). A body that points at a local file (one the publisher will upload) must still say `media: private`, because that line is what makes the publisher upload it privately; without it the page is refused before anything is uploaded.
 - **Expires 90 days after it is published** (`BROADCAST_TTL_MS`), set by `POST /api/artifacts` when the page has no date yet, and answered as `expireAt` in its response. A date set on the recipients route stands, a republish never moves it, and Keep (`expires: null`) holds.
-- **Comments off** unless the file turns them on. **No narration player**, ever: a voice note is its own audio (`![Voice note](note.m4a)` draws a player). Write `voice: none` so the publisher does not record one.
+- **Comments off** unless the file turns them on. With them on, a reader's feedback window and `comment_name: required` work as on a document: past the window the card stops offering Share, and a group reader is asked for a first name. A broadcast draws no banner, though: no "A draft from" line, no countdown and no "Feedback is closed" line above the card. **No narration player**, ever: a voice note is its own audio (`![Voice note](note.m4a)` draws a player). Write `voice: none` so the publisher does not record one.
 - **Silent view tracking**: the quiet view beacon, as on every per-reader page.
 
 Routes:

package/lib/artifacts/comments.d.ts

@@ -16,6 +16,12 @@ export declare function mergeCommentsState(state: StateConfig | undefined, comme
 };
 export declare const MAX_COMMENT_CHARS = 4000;
 export declare const MAX_COMMENT_NAME_CHARS = 80;
+/** What a reader is told when their feedback window has closed (0.40.0). The card shows it under the
+ *  words they typed, which stay in the box. */
+export declare const FEEDBACK_CLOSED = "Feedback on this draft is closed. Your note was not sent.";
+/** What a reader on an open (group) link is told when a comment arrives with no name, on a page
+ *  that says `comment_name: required` (0.40.0). */
+export declare const NAME_NEEDED = "Add your first name, so your note has a name on it.";
 export declare const COMMENT_TRANSCRIPTS: readonly ["browser", "host", "typed"];
 /** One shared comment or personal note. `parent` makes it a reply to a top-level comment (one
  *  level only). `audio` and `transcript` are filled by voice memos; a memo may have an empty body. */
@@ -28,6 +34,9 @@ export type CommentValue = {
     transcript?: (typeof COMMENT_TRANSCRIPTS)[number];
     /** The name a reader typed so the owner can credit them. A signed-in reader's account name wins. */
     by?: string;
+    /** On a reply only: the publisher wrote it, through the reply route with the publish key (0.40.0).
+     *  Never set by a reader: `validateComment` refuses the key. */
+    publisher?: true;
     /** On a thread's top-level comment only: the owner, an admin or the publisher marked the thread
      *  done (0.33.0). Written by the resolve route, never by a reader: `validateComment` refuses the
      *  key, and an edit keeps whatever the comment already carried. */

package/lib/artifacts/comments.js

@@ -15,6 +15,12 @@ export function mergeCommentsState(state, comments, visible) {
 }
 export const MAX_COMMENT_CHARS = 4000;
 export const MAX_COMMENT_NAME_CHARS = 80;
+/** What a reader is told when their feedback window has closed (0.40.0). The card shows it under the
+ *  words they typed, which stay in the box. */
+export const FEEDBACK_CLOSED = 'Feedback on this draft is closed. Your note was not sent.';
+/** What a reader on an open (group) link is told when a comment arrives with no name, on a page
+ *  that says `comment_name: required` (0.40.0). */
+export const NAME_NEEDED = 'Add your first name, so your note has a name on it.';
 export const COMMENT_TRANSCRIPTS = ['browser', 'host', 'typed'];
 export const MAX_RESOLVE_NOTE_CHARS = 280;
 /** The resolve route's check on a note: absent, null or blank means no note; otherwise one line of

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

@@ -60,6 +60,9 @@ export type ArtifactMeta = {
     comments?: CommentsMode;
     /** Who sees shared comments: `owner` (the default) or every reader (`readers`). */
     commentsVisible?: CommentsVisible;
+    /** `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';
 };
 /** 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

package/lib/artifacts/front-matter.js

@@ -19,7 +19,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']);
+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']);
 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`. */
@@ -87,6 +87,11 @@ opts = {}) {
             return { ok: false, error: 'media must be private' };
         meta.privateMedia = true;
     }
+    if (d.comment_name !== undefined && d.comment_name !== null) {
+        if (d.comment_name !== 'required')
+            return { ok: false, error: 'comment_name must be required' };
+        meta.commentName = 'required';
+    }
     if (d.theme !== undefined) {
         if (!THEME_MODES.includes(d.theme))
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
@@ -145,6 +150,8 @@ 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' };
+    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
     // page is stored, and the state API and the republish shape checks see it like any slot.
     // Errors name the line in the FILE: the body's lines are counted after the front matter's.

package/lib/artifacts/index.d.ts

@@ -24,6 +24,6 @@ export { deepgramTranscriber, openaiTranscriber, type Transcriber } from './tran
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey, type DeclaredSettings, type LiveSettings, type SettingsPatch } from './settings.js';
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
-export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
+export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';

package/lib/artifacts/index.js

@@ -24,6 +24,6 @@ export { deepgramTranscriber, openaiTranscriber } from './transcribe.js';
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey } from './settings.js';
 // Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
-export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
+export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';

package/lib/artifacts/recipients-store.d.ts

@@ -7,6 +7,7 @@ export type Recipient = {
     group?: true;
     addedAt: string;
     revokedAt?: string;
+    closesAt?: string | null;
 };
 export type RecipientsRecord = {
     recipients: Record<string, Recipient>;
@@ -29,6 +30,7 @@ export type RecipientSummary = {
     label: string;
     group: boolean;
     revoked: boolean;
+    closesAt: string | null;
     opened: boolean;
     firstOpenAt: string | null;
     cameBack: boolean;
@@ -40,15 +42,21 @@ export type RecipientSummary = {
         text: string;
     }[];
 };
+type NewRecipient = {
+    label: string;
+    note?: string;
+    owner?: boolean;
+    group?: boolean;
+    closesAt?: string;
+};
 export interface RecipientsStore {
     get(artifactId: string): Promise<RecipientsRecord | null>;
-    add(artifactId: string, input: {
-        label: string;
-        note?: string;
-        owner?: boolean;
-        group?: boolean;
-    }[]): Promise<Recipient[]>;
+    add(artifactId: string, input: NewRecipient[]): Promise<Recipient[]>;
     revoke(artifactId: string, rids: string[] | '*'): Promise<string[]>;
+    /** Set (an ISO time) or clear (null) the feedback window of the named readers, or of every reader
+     *  with '*'. Never the owner's. Returns the rids changed. Optional so a host's own store keeps
+     *  working; without it the recipients route answers 501 to a `closes` change. */
+    setCloses?(artifactId: string, rids: string[] | '*', closesAt: string | null): Promise<string[]>;
     setExpiry(artifactId: string, expireAt: string | null): Promise<void>;
     useToken(key: string, expiresAt: number): Promise<boolean>;
     recordView(v: {
@@ -73,3 +81,4 @@ export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[],
     at: string;
     text: string;
 }[]): RecipientSummary[];
+export {};

package/lib/artifacts/recipients-store.js

@@ -1,4 +1,4 @@
-import { newRid } from './recipients.js';
+import { newRid, ridOfReaderKey } from './recipients.js';
 export const CAME_BACK_MS = 3_600_000;
 const LABEL_MAX = 60;
 const NOTE_MAX = 2000;
@@ -13,7 +13,9 @@ function makeRecipients(input, taken) {
             rid = newRid();
         taken.add(rid);
         const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
-        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}) };
+        // The owner never carries a window: setCloses skips them and the page hides the closed state
+        // from them, so one stored here would offer Share on their link and then refuse it.
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}) };
     });
 }
 function revokeIn(rec, rids) {
@@ -29,6 +31,16 @@ function revokeIn(rec, rids) {
         rec.revokedAll = at;
     return hit;
 }
+function closeIn(rec, rids, closesAt) {
+    const hit = [];
+    for (const r of Object.values(rec.recipients)) {
+        if (r.owner || (rids !== '*' && !rids.includes(r.rid)))
+            continue;
+        r.closesAt = closesAt;
+        hit.push(r.rid);
+    }
+    return hit;
+}
 function addView(prev, v) {
     const doc = prev ? { ...prev, plays: { ...prev.plays } } : { artifactId: v.artifactId, rid: v.rid, session: v.session, device: v.device, firstAt: v.at, lastAt: v.at, activeSeconds: 0, plays: {} };
     doc.activeSeconds += Math.max(0, Math.min(60, v.addSeconds));
@@ -54,6 +66,7 @@ export function memoryRecipientsStore() {
             return structuredClone(out);
         },
         async revoke(id, rids) { const rec = recs.get(id); return rec ? revokeIn(rec, rids) : []; },
+        async setCloses(id, rids, closesAt) { const rec = recs.get(id); return rec ? closeIn(rec, rids, closesAt) : []; },
         async setExpiry(id, expireAt) {
             const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
             rec.expireAt = expireAt;
@@ -105,6 +118,18 @@ export function createRecipientsStore(db, base) {
             await recsCol().doc(id).set(patch, { merge: true });
             return hit;
         },
+        async setCloses(id, rids, closesAt) {
+            const rec = await read(id);
+            if (!rec)
+                return [];
+            const hit = closeIn(rec, rids, closesAt);
+            if (!hit.length)
+                return hit;
+            // A merge writes only this field on these readers: a revoke or an expiry that landed after the
+            // read above is left alone. `null` clears the window (read back as no window).
+            await recsCol().doc(id).set({ recipients: Object.fromEntries(hit.map((rid) => [rid, { closesAt }])) }, { merge: true });
+            return hit;
+        },
         async setExpiry(id, expireAt) {
             await recsCol().doc(id).set({ expireAt, keep: expireAt === null }, { merge: true });
         },
@@ -147,14 +172,14 @@ export function summarizeViews(rec, views, comments) {
         const mine = views.filter((v) => v.rid === r.rid).sort((a, b) => a.firstAt.localeCompare(b.firstAt));
         const firsts = mine.map((v) => Date.parse(v.firstAt));
         return {
-            rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt,
+            rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null,
             opened: mine.length > 0,
             firstOpenAt: mine[0]?.firstAt ?? null,
             cameBack: firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= CAME_BACK_MS,
             activeSeconds: mine.reduce((n, v) => n + v.activeSeconds, 0),
             plays: mine.reduce((n, v) => n + Object.values(v.plays).reduce((a, b) => a + b, 0), 0),
             devices: new Set(mine.map((v) => v.device)).size,
-            comments: comments.filter((c) => c.readerKey === `r:${r.rid}`).map((c) => ({ at: c.at, text: c.text })),
+            comments: comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ at: c.at, text: c.text })),
         };
     });
 }

package/lib/artifacts/recipients.d.ts

@@ -25,6 +25,15 @@ export declare function verifyRenderToken(secret: string, id: string, rid: strin
     why: string;
 };
 export declare function beatKey(secret: string, id: string, rid: string, session: string): string;
+/** One browser on a group link, as the 24 hex characters its reader key ends in (0.40.0). Derived
+ *  here from the page, the link's verified rid and the anonymous id this server handed that browser,
+ *  keyed by the recipient secret: a client cannot compute another browser's, and the stored key is
+ *  not the cookie, so reading a key (the publisher's exports carry it) never lets anyone write as
+ *  that reader. */
+export declare function browserIdFor(secret: string, id: string, rid: string, anon: string): string;
+/** The link a reader key was written through: `r:<rid>` (one link, one reader) or
+ *  `r:<rid>.<browser>` (one browser on a group link). Null for any other key. */
+export declare function ridOfReaderKey(key: string): string | null;
 /** Messaging apps' and search engines' preview fetchers. Apple's LinkPresentation presents as
  *  `facebookexternalhit/1.1 Facebot Twitterbot/1.0`. A request with no user agent is treated as one. */
 export declare const UNFURL_AGENTS: RegExp;

package/lib/artifacts/recipients.js

@@ -77,6 +77,22 @@ export function verifyRenderToken(secret, id, rid, token, now = Date.now()) {
 export function beatKey(secret, id, rid, session) {
     return mac(secret, `beat\n${id}\n${rid}\n${session}`);
 }
+/** One browser on a group link, as the 24 hex characters its reader key ends in (0.40.0). Derived
+ *  here from the page, the link's verified rid and the anonymous id this server handed that browser,
+ *  keyed by the recipient secret: a client cannot compute another browser's, and the stored key is
+ *  not the cookie, so reading a key (the publisher's exports carry it) never lets anyone write as
+ *  that reader. */
+export function browserIdFor(secret, id, rid, anon) {
+    if (!secret)
+        throw new Error('a signing secret is required');
+    return createHmac('sha256', secret).update(`browser\n${id}\n${rid}\n${anon}`).digest('hex').slice(0, 24);
+}
+const RECIPIENT_KEY = /^r:([a-z0-9]{12})(\.[0-9a-f]{24})?$/;
+/** The link a reader key was written through: `r:<rid>` (one link, one reader) or
+ *  `r:<rid>.<browser>` (one browser on a group link). Null for any other key. */
+export function ridOfReaderKey(key) {
+    return RECIPIENT_KEY.exec(key)?.[1] ?? null;
+}
 /** Messaging apps' and search engines' preview fetchers. Apple's LinkPresentation presents as
  *  `facebookexternalhit/1.1 Facebot Twitterbot/1.0`. A request with no user agent is treated as one. */
 export const UNFURL_AGENTS = /facebookexternalhit|facebot|twitterbot|slackbot|whatsapp|linkedinbot|discordbot|telegrambot|skypeuripreview|redditbot|applebot|googlebot|bingbot|embedly|iframely|pinterest|bitlybot|vkshare|mastodon|preview/i;

package/lib/artifacts/state-store.d.ts

@@ -82,6 +82,11 @@ export declare const readerKeyFor: {
     signedIn: (uid: string) => string;
     anonymous: (id: string) => string;
     recipient: (rid: string) => string;
+    /** One browser on a group link, on a page with `comment_name: required`: the link and the id
+     *  `browserIdFor` derives. `ridOfReaderKey` reads the link back out of either `r:` shape. */
+    groupBrowser: (rid: string, browser: string) => string;
+    /** The publisher's one reply in a thread, keyed by the thread's top comment. */
+    publisher: (entryId: string) => string;
 };
 export declare function createStateStore(db: Firestore, base: string): StateStore;
 /** The same contract in memory: for tests, and for hosts' own tests. */

package/lib/artifacts/state-store.js

@@ -18,6 +18,11 @@ export const readerKeyFor = {
     signedIn: (uid) => `u:${uid}`,
     anonymous: (id) => `a:${id}`,
     recipient: (rid) => `r:${rid}`,
+    /** One browser on a group link, on a page with `comment_name: required`: the link and the id
+     *  `browserIdFor` derives. `ridOfReaderKey` reads the link back out of either `r:` shape. */
+    groupBrowser: (rid, browser) => `r:${rid}.${browser}`,
+    /** The publisher's one reply in a thread, keyed by the thread's top comment. */
+    publisher: (entryId) => `p:${entryId}`,
 };
 const writerOf = (w) => ({
     ...(w.uid ? { uid: w.uid } : {}), ...(w.email ? { email: w.email } : {}), name: w.name, anonymous: w.anonymous,

package/lib/artifacts/store.d.ts

@@ -32,6 +32,7 @@ export type ArtifactRecord = {
     /** The brand pack the page asked for by name; see ArtifactMeta.pack. */
     pack?: string;
     toc?: boolean;
+    commentName?: 'required';
     definitions?: Definition[];
     /** Who may leave shared comments; absent is off. Personal notes need nothing. */
     comments?: CommentsMode;

package/lib/artifacts/store.js

@@ -163,6 +163,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.theme ? { theme: input.meta.theme } : {}),
         ...(input.meta.pack ? { pack: input.meta.pack } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
+        ...(input.meta.commentName ? { commentName: input.meta.commentName } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
     };
     if (input.id) {
@@ -215,6 +216,7 @@ async function saveArtifact(col, input) {
             ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
             ...(input.meta.pack ? {} : { pack: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
+            ...(input.meta.commentName ? {} : { commentName: 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/brand/pack.d.ts

@@ -84,6 +84,10 @@ export type CoverProps = {
     /** The version line and, for a signed-in reader, who they are signed in as. Unspoken. */
     meta: ReactNode;
     version: number;
+    /** Whether this reader may be shown the version number: true for whoever the host's `history`
+     *  lets see past versions (admins by default), false for everyone else. A Cover that draws
+     *  `version` itself draws it only when this is true; `meta` already follows it. */
+    showVersion: boolean;
     updatedAt: string;
     createdAt: string;
 };