@supersuit/artifacts 0.38.0 → 0.40.1

package/CHANGELOG.md

@@ -3,6 +3,123 @@
 `@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.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.**
+A ```` ```simulator ```` block drew its player in a frame of one fixed height (`height:`, 720px
+unless the block said). A session demo draws a different device for each viewer, a short laptop on
+a desktop and a tall phone on a phone, so one height suited neither: on a desktop a band of
+nothing, some 300px, sat between the laptop and the caption.
+
+- The frame now asks its embed page `fit=content` (the address gains `&fit=content`), and a page
+  that understands posts `{ type: 'embed:fit', height: <px> }` to its parent. The frame takes that
+  height (`EmbedFrame`, a client component; `fitFrom`, `FIT_MESSAGE`): only that message, only from
+  the frame's own window and the origin of the page it loaded, held between 240 and 2000px.
+- `height:` still means what it meant: the height the frame opens at, and so the room the player is
+  given. A page that posts nothing keeps it. No published page needs a change.
+- From 1024px a framed session demo is up to 64rem wide, centred on the column and clear of the
+  contents rail in the left margin from 1280px, with its caption centred under it. In a broadcast's
+  card, below 1024px, for the Messages phone, and for a caption with no player, the column is the
+  width, as before.
+
+DETECTOR: open a page with a ```` ```simulator ```` block on a desktop. Affected: the frame is the
+block's height whatever the device in it, with empty space under a laptop. Or
+`curl -s <page> | grep -o 'simulator/embed[^"]*'` shows no `fit=content`.
+
+REMEDY: take 0.39.0. A host whose embed page is not its own does nothing more: an unknown query key
+is ignored and the frame keeps the block's height. A host that serves its own embed page makes it
+answer `fit=content` in two steps, in this order: hold the player at the height the frame opened
+with (inside a frame the viewport IS the frame, so a player sized from it shrinks as the frame
+does and the two chase each other), then post its content's height as `embed:fit` whenever it
+changes. Centre the player in the frame as well, for hosts that never listen.
+
+Tests: `simulator.test.ts` (the address asks to fit and the Messages one does not; `fitFrom` takes
+the message from the right origin, refuses every other shape, and clamps), `embed-frame.test.tsx`
+(the frame opens at the block's height, takes a reported one, and ignores another window, origin
+and message), `render.test.tsx` (the opening height with and without `height:`; the wide rule is on
+a framed session demo only, never the Messages phone or a caption with no player). The wide rule
+itself is CSS and is not run by a test here: it was checked in a browser at 390, 1100 and 1440px.
+
 ## 0.38.0
 
 **Readers' voice memos live in the private bucket.** A memo left on a page (`comments/<memo>`, or a

package/README.md

@@ -253,6 +253,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 +749,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 +831,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 +894,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 +910,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 +985,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/embed-frame.d.ts

@@ -0,0 +1,5 @@
+export declare function EmbedFrame({ src, title, height }: {
+    src: string;
+    title: string;
+    height: string;
+}): import("react").JSX.Element;

package/lib/artifacts/embed-frame.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+// The frame an embed block plays in. It opens at the block's height and, when its embed page
+// reports how tall the player is (simulator.ts, "A frame that fits"), takes that height, so a
+// short device has no empty band under it and a tall one is not cut off.
+import { useEffect, useRef, useState } from 'react';
+import { fitFrom } from './simulator.js';
+export function EmbedFrame({ src, title, height }) {
+    const ref = useRef(null);
+    const [fit, setFit] = useState(null);
+    useEffect(() => {
+        const onMessage = (e) => {
+            if (!ref.current || e.source !== ref.current.contentWindow)
+                return;
+            const h = fitFrom(e.data, e.origin, src);
+            if (h != null)
+                setFit(h);
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }, [src]);
+    return (_jsx("iframe", { ref: ref, src: src, title: title, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: fit != null ? `${fit}px` : height, border: 0 } }));
+}

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

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
 export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
 export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS, type ResolveEvent, type DigestItem, type Burst, type Digest, type DigestStatus, type ResolveDigestStore, type DigestMessage, type DigestSender, type ResolveDigestOptions, type ComposeOptions, type FlushReport } from './resolve-digest.js';
@@ -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

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
 export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS } from './resolve-digest.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/render.js

@@ -17,6 +17,7 @@ import { blocksOf, checklistSyncs, checklistsOf, hasNotesWidget, headingsOf } fr
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { Checklist } from '../widgets/checklist.js';
 import { embedSrc, parseEmbedFence } from './simulator.js';
+import { EmbedFrame } from './embed-frame.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -110,6 +111,17 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio data-artifact-media="${escapeAttr(mediaName(src))}" controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
+// A session demo on a wide screen is wider than the reading column, so the device it draws (a
+// laptop, or a phone beside what was made) has room: up to 64rem, centred on the column, and clear
+// of the contents rail fixed in the left margin from 1280px (w-56 at left-6, w-64 at left-12).
+// Below 1024px, in a broadcast's card, for the Messages phone, and for a caption with no player
+// over it (a host that names no embed page), the column is the width.
+const WIDE = '[data-artifact-embed="simulator"][data-wide]';
+const WIDE_EMBED_CSS = `@media (min-width:1024px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 4rem)));margin-left:50%;transform:translateX(-50%)}` +
+    `${WIDE} figcaption{text-align:center}` +
+    `[data-broadcast] ${WIDE}{width:auto;margin-left:0;transform:none}[data-broadcast] ${WIDE} figcaption{text-align:inherit}}` +
+    `@media (min-width:1280px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 36rem)))}}` +
+    `@media (min-width:1536px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 40rem)))}}`;
 /** An embed block (```simulator, ```messages): the player in a frame when the host names one, its
  *  caption alone when it does not, and nothing when the block does not parse (a page published
  *  before validation existed). */
@@ -118,7 +130,8 @@ function EmbedFence({ kind, source, ctx }) {
     if (!r.ok)
         return null;
     const src = ctx ? embedSrc(kind, ctx.embed, r.block.value) : null;
-    return (_jsxs("figure", { "data-artifact-embed": kind, ...(kind === 'simulator' ? { 'data-artifact-simulator': '' } : {}), className: "my-8", children: [src ? (_jsx("iframe", { src: src, title: r.block.caption, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: r.block.height, border: 0 } })) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
+    const wide = kind === 'simulator' && src != null;
+    return (_jsxs("figure", { "data-artifact-embed": kind, ...(kind === 'simulator' ? { 'data-artifact-simulator': '' } : {}), ...(wide ? { 'data-wide': '' } : {}), className: "my-8", children: [wide ? _jsx("style", { children: WIDE_EMBED_CSS }) : null, src ? _jsx(EmbedFrame, { src: src, title: r.block.caption, height: r.block.height }) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
 }
 /** The one image a paragraph holds and nothing else (whitespace aside), or null. */
 function soleImage(node) {