@supersuit/artifacts 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 `@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.43.0
+
+**A comment's id per reader in `/views`, the comments feed for one page, and a limit on new browsers
+through a group link.** A consumer that keeps a local copy of a page's comments could not tell exactly
+which ones it lacked: `/views` listed each reader's comments as `{ at, text }` with no id, and
+`GET /api/comments` is the whole host's feed. Everything here is additive; a caller that ignores the
+new fields and the new parameter sees 0.42.0.
+
+- `GET /api/artifacts/<id>/views`: each comment gains `id` (the entry id the feed calls `entryId`) and
+  `parent` (the entry id it replies to, or null). Under `comment_name: required` every browser on a
+  group link is still listed under the link, each with its own id. Publisher replies stay out.
+- `GET /api/comments?artifact=<page id>`: only that page's rows, read from that page's entries rather
+  than a scan of the host. `since`, `open`, `cursor` and `more` work over that page's comments. A value
+  that is not a page id is a 400; a well-formed id with no page is an empty feed. Without the parameter
+  the feed is unchanged.
+- On a `comment_name: required` page, the first stored note of each new browser through one group
+  link (a reader key with no entry on the page yet, with or without an `artifact_anon` cookie) is
+  counted against the anonymous write limit, keyed by the link, and answers
+  `429 { error: "too many new readers through this link; try again in a minute" }` past 30 a minute.
+  Counted after validation, so a refused request spends nothing. A browser's later notes, a named link
+  and a page without the line are not counted.
+- `summarizeViews` (a public export) takes comments with `id` and `parent` OPTIONAL: a caller passing
+  `{ readerKey, at, text }` compiles and runs as before, and gets `id: null, parent: null` on each item.
+- README: the `id` and `parent` shapes, the `artifact` parameter, and the note that removing
+  `comment_name: required` later turns a group link back into one shared reader and hides every
+  per-browser note from its writer.
+
+DETECTOR: a consumer that reads `comments[]` from `/views` and rebuilds each item field by field, or
+that rejects unknown keys, meets two new ones: `rg -n "\.comments" <your consumer>`. A consumer that
+paged the host-wide feed to find one page's comments can ask for that page alone. A group link handed
+to a crowd that arrives all at once (more than 30 new browsers writing inside a minute) now sees 429 for
+the rest of that minute. A caller already sending a stray `artifact=` parameter on the feed, ignored
+until now, gets a filtered feed, or a 400 if it is not a page id.
+
+REMEDY: read `id` and `parent` where present and tolerate them where not; add `&artifact=<id>` to a
+per-page poll. Nothing is needed for the limit: the same people write again the next minute.
+
+Tests: `src/routes/comment-ids.test.tsx` (ids equal the feed's `entryId`; a reply's `parent`; two
+browsers on one group link under the link with distinct ids; no publisher reply; `artifact=` returns
+one page's rows and composes with `since` and `open=1`; paging 300 comments of one page among 450 in
+pages of 200 never returns another page's row; the unfiltered feed unchanged; a malformed id is 400
+and an unknown page is empty; the limit trips for cookieless writes through one link, not for a
+returning browser, a named link or a page without the line). Every test builds its own stores.
+
 ## 0.42.0
 
 **One page can say who sees its version number and past versions: `history: everyone | admins` in

package/README.md

@@ -851,6 +851,19 @@ Authorization: Bearer <publish key>
                                        quote, region, body, transcript, audioUrl, at, resolved, link } ] }
 ```
 
+**One page's feed (0.43.0).** `&artifact=<page id>` returns only that page's rows. `since`, `open`,
+`cursor` and `more` behave as above, over that page's comments alone, so a caller paging one page
+reaches its end without reading another page's rows. The feed is read from that page's own entries,
+not from a scan of the host. A value that is not a page id is a `400` ("artifact must be a page id,
+like abcd2345"); a well-formed id with no page, or no comments, answers an empty feed
+(`{ now, comments: [], cursor: null, more: false }`), as an empty host does. Without the parameter
+the feed is what it was.
+
+```
+GET /api/comments?since=2026-09-28T12:00:00Z&artifact=abcd2345&open=1
+Authorization: Bearer <publish key>
+```
+
 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; `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
@@ -911,7 +924,7 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 |---|---|---|
 | `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?, 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 |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). 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 |
 
 Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
@@ -978,6 +991,35 @@ the one shared reader (`r:<rid>`) and are shown to no browser afterwards. A name
 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.
 
+### Comment ids in `/views` (0.43.0)
+
+Each comment in a reader's `comments` array carries the entry id the comments feed calls
+`entryId`, and the id of the comment it replies to:
+
+```json
+{ "rid": "abcdefghijkl", "label": "Anyone with the link", "group": true, "comments": [
+  { "id": "kq3vN8xTz2LwPd5mRa", "parent": null, "at": "2026-10-11T10:01:00.000Z", "text": "Which river?" },
+  { "id": "Jm7cHy4bQe9sUf1xWk", "parent": "kq3vN8xTz2LwPd5mRa", "at": "2026-10-11T10:04:00.000Z", "text": "The north one." } ] }
+```
+
+`at` and `text` are as before. Under `comment_name: required` the notes of every browser on a
+group link are listed under that link's row, each with its own `id`. The publisher's replies are not
+listed. A caller that keeps a local copy of a page's comments compares these ids with
+`GET /api/comments?artifact=<id>` to see exactly which ones it lacks.
+
+**Limit on new browsers.** On a page with `comment_name: required`, the first stored note of each new
+browser through one group link is counted against that link, per minute, on the anonymous write limit
+(30). A browser is new when its reader key has no entry on the page yet, whether or not it arrived with
+an `artifact_anon` cookie. Past the limit the state route answers
+`429 { error: "too many new readers through this link; try again in a minute" }`. Only a stored note is
+counted: a request refused for a missing name, a closed window or a malformed body spends nothing. A
+browser's later notes, a named link and a page without the line are never counted. "Note" here means
+any stored entry in any slot, and a browser that removes its only entry and writes again is new again.
+
+**Removing the line later.** Taking `comment_name: required` off a page turns its group link back into
+one shared reader, and every note left per browser stops being shown to its writer: the notes stay with
+the publisher, under their per-browser keys.
+
 ## 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.

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

@@ -38,6 +38,8 @@ export type RecipientSummary = {
     plays: number;
     devices: number;
     comments: {
+        id: string | null;
+        parent: string | null;
         at: string;
         text: string;
     }[];
@@ -78,6 +80,8 @@ export declare function createRecipientsStore(db: Firestore, base: string): Reci
 /** One line per reader (never the owner), in the order they were added. */
 export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[], comments: {
     readerKey: string;
+    id?: string | null;
+    parent?: string | null;
     at: string;
     text: string;
 }[]): RecipientSummary[];

package/lib/artifacts/recipients-store.js

@@ -179,7 +179,7 @@ export function summarizeViews(rec, views, comments) {
             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) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ at: c.at, text: c.text })),
+            comments: comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ id: c.id ?? null, parent: c.parent ?? null, at: c.at, text: c.text })),
         };
     });
 }

package/lib/routes/recipients-routes.js

@@ -136,7 +136,7 @@ export function createRecipientsRoutes(given) {
         // A page nobody has been added to yet has no readers, which is an answer and not a missing page.
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         const entries = ctx.state ? await ctx.state.entries(id) : [];
-        const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, at: e.at, text: String(e.value?.body ?? '') }));
+        const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, id: e.id, parent: typeof e.value?.parent === 'string' ? e.value.parent : null, at: e.at, text: String(e.value?.body ?? '') }));
         return json({ id, expireAt: rec.expireAt, keep: rec.keep, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments) });
     }
     /** Reader text goes with the page: every comment and answer on it, whoever wrote it. */

package/lib/routes/state-routes.js

@@ -5,7 +5,8 @@
 //   GET  /api/artifacts/<id>/responses  publish key; every answer with who (?format=csv)
 //   DELETE /api/artifacts/<id>/responses?reader=<key>  publish key; one reader's answers
 //   GET  /api/comments?since=<ISO>      publish key; every shared comment on any page after a time
-//                                       (&open=1: leave out threads that are resolved)
+//                                       (&open=1: leave out threads that are resolved;
+//                                       &artifact=<id>: only that page's comments)
 //   POST /api/artifacts/<id>/resolve    publish key, or the owner or an admin signed in; resolve or
 //                                       reopen one comment thread { entry, resolved?, note?, by? }
 //
@@ -368,6 +369,16 @@ export function createStateRoutes(ctx) {
                 if (!replacing)
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }
+            // A group link under `comment_name: required` makes each browser its own reader, so one link
+            // could start any number of them. The FIRST STORED write of a reader key the page has not seen
+            // is counted against the link, whether it came with a cookie or not (any 24 characters pass as
+            // one), and only here, after validation, so a refused request spends nothing. A key that
+            // already has an entry is never counted again.
+            if (recipient?.perBrowser && !(await ctx.state.entries(id)).some((e) => e.readerKey === writer.key)) {
+                const n = await ctx.state.countAnonWrite(id, `gl.${recipient.rid}`, Math.floor(Date.now() / 60000));
+                if (n > ANON_WRITES_PER_MINUTE)
+                    return json({ error: 'too many new readers through this link; try again in a minute' }, 429);
+            }
             const r = op === 'set'
                 ? await ctx.state.set({ artifactId: id, slot, writer, value })
                 : await ctx.state.append({ artifactId: id, slot, writer, value });
@@ -424,10 +435,17 @@ export function createStateRoutes(ctx) {
         const openOnly = openParam === '1' || openParam === 'true';
         if (!ctx.state)
             return json({ error: 'this host keeps no answers' }, 501);
-        if (!ctx.state.slotSince)
+        // One page's feed (0.43.0): read that page's entries alone, so a caller paging a single page
+        // never reads, or is handed, another page's comments.
+        const only = req.nextUrl.searchParams.get('artifact');
+        if (only !== null && !ARTIFACT_ID_RE.test(only))
+            return json({ error: 'artifact must be a page id, like abcd2345' }, 400);
+        if (only === null && !ctx.state.slotSince)
             return json({ error: 'this host cannot list comments by time' }, 501);
         const now = new Date().toISOString();
-        const entries = await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
+        const entries = only !== null
+            ? (await ctx.state.entries(only)).filter((e) => e.slot === COMMENTS_SLOT && e.at > since).sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id)).slice(0, FEED_MAX)
+            : await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
         const pages = new Map();
         const pageOf = (id) => { if (!pages.has(id))
             pages.set(id, ctx.store.get(id)); return pages.get(id); };

package/package.json

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