@supersuit/artifacts 0.54.0 → 0.56.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 `@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.56.0 (2026-10-26)
+
+**A reader can pass a per-reader page on, and the link they make says who made it and from which
+link.** Superlinks step 3. Before this, Share on a per-reader page copied the page's bare address,
+which opens for nobody, so the only way to pass one on was the address bar, and every new reader
+counted as the first.
+
+- Front matter `forward: off | signed-in | open` (absent is off; needs `links: per-reader`; sticky).
+- `POST /api/artifacts/<id>/forward`: mints a forward reader with `parent`, `forwardedBy` and
+  `provenance`, and answers `{ link }`. 20 a day per reader per page. See Forward links.
+- A revoked link shuts every forward made from it (`perReaderGate` walks the parent chain).
+- Share on a per-reader page asks the route for a link (sending a signed-out reader to sign in on a
+  `signed-in` page), and is absent where forwarding is off. The owner and admins keep the address.
+- Acting through a group link on a page with `forward:` on, or through any forward link, needs
+  sign-in; the note is filed under the link with the signed-in name. Personal links are unchanged.
+- `GET /recipients` and `GET /views` carry `parent` and `forwardedBy` per reader.
+- DETECTOR: a per-reader page whose menu Share copies `https://<host>/<id>` with no `?r=`; or a
+  host whose `POST /api/artifacts/<id>/forward` answers 404 on a page with `forward: signed-in`
+  (no route file).
+- REMEDY: bump, and add the route file `app/api/artifacts/[id]/forward/route.ts` exporting
+  `POST = routes.FORWARD`. Pages without `forward:` behave as before, except that Share no longer
+  offers their dead address to a reader.
+- Tests: forward.test.tsx (each `forward:` value against signed in, signed out, revoked parent, no
+  link; the row's fields; the daily limit; the parent chain; the listing and views; Share present
+  exactly where forwarding is on; sign-in to act on thread and forward links, never on a personal one).
+
+## 0.55.0 (2026-10-26)
+
+**`GET /api/artifacts/<id>` now returns the page as written, not only its narration.** It answered
+`{ id, text }`, and `text` is the narration, which drops every list item, so an agent reading a
+prep sheet through the key got its headings ("Questions for him", "About him, first:") with the
+questions missing.
+
+- The response adds `title`, `subtitle` (when set), `summary`, `to` (when set), `markdown`,
+  `version` and `updatedAt`. `text` is unchanged, so existing callers keep working.
+- Never the password, the access list or reader data.
+- DETECTOR: `GET /api/artifacts/<id>` with the publish key answers no `markdown` field.
+- REMEDY: update the host.
+- Tests: `src/routes/artifacts.test.tsx` "GET returns the narration text and the markdown".
+
 ## 0.54.0 (2026-10-25)
 
 **A page no longer records under a reader left on the browser by another page.** posthog-js keeps

package/README.md

@@ -248,6 +248,12 @@ createArtifactRoutes({ ..., ownerEmail: 'owner@example.com', admins: ['editor@ex
 - `GET /api/artifacts/<id>/versions` lists the history; `POST` it `{ "version": 2, "note": "..." }`
   (or `"note": null`) to write a note onto a version after the fact.
 
+**Reading a page as its owner.** `GET /api/artifacts/<id>` with the publish key answers
+`{ id, title, subtitle?, summary, to?, markdown, version, updatedAt, text }`. `markdown` is the
+body as written, lists included, and is what an agent should read; `text` is the narration, which
+drops list items. Neither ever carries the page's password or anything about its readers. A page
+behind a sign-in door, a password or per-reader links is readable this way by whoever holds the key.
+
 ## Front matter
 
 ```markdown
@@ -277,6 +283,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `links` | `per-reader`: the page opens only through a link made for one reader (see Per-reader links). Sticky: a republish whose file leaves the line out changes nothing |
 | `media` | `private`: the page's body media is kept private and served through short-lived signed URLs. Needs `links: per-reader`. Sticky like `links` |
 | `comment_name` | `required`: on a per-reader page, a comment through a group link needs a typed first name, and each browser on a group link is its own reader (see Per-reader links). Needs `links: per-reader` |
+| `forward` | `off`, `signed-in` or `open`: whether a reader of a per-reader page may make a link to pass it on (see Forward links). Absent is `off`. Needs `links: per-reader`. Sticky like `links` |
 | `history` | `everyone` or `admins`: who sees this page's version number and past versions, overriding the host's `history` for this one page (see Version history). Absent, the host decides. Refused as `everyone` on a per-reader page |
 | `change` | One line saying what this version changed (see Version history) |
 | `template` | `document` (the default, the read-along reader) or `broadcast` (one message card sent to several people; see Broadcasts) |
@@ -1084,6 +1091,37 @@ stage, is refused (400) and nothing is added. It is kept on the reader's row and
 ignores the field, so a sender that needs it reads it back from `added` and treats `null` as an old
 host.
 
+### Forward links (0.56.0)
+
+A reader passes a per-reader page on through a link of its own, never the page's address, which
+opens for nobody. The page's `forward:` line decides who may:
+
+| `forward:` | Share in the page menu | Who can make a forward link |
+|---|---|---|
+| `off` (or absent) | absent | nobody; the route answers 404 |
+| `signed-in` | present, "Your name goes with this link." | a reader signed in through `signInOrigin` |
+| `open` | present | anyone holding a valid link; the forwarder is recorded as that link |
+
+`POST /api/artifacts/<id>/forward` is called by the page (same origin, the reader's link cookie).
+Body `{ to?: first name }`, up to 60 characters. It answers `{ link }`, a new reader row with
+`group: true`, `parent` (the rid it was made from), `forwardedBy` (`{ uid, email, name }` from the
+pass, or `{ rid, label }` on an `open` page) and `provenance` (`actor` "<name> (signed in as
+<email>)", `authority` "forwarded from <label>'s link"). Labelled "<to> (from <name>)", or "From
+<name>". Refusals: 404 for `forward: off`, no valid link, a revoked parent, or the owner; 401
+`{ signIn }` signed out on a `signed-in` page; 400 for a bad `to`; 429 past 20 forwards by one
+reader on one page in a day; 502 when the store fails, and the page says so rather than copying
+anything else. **A forward never outlives the link it came from**: revoking a link shuts every
+forward made from it, and their forwards. `GET /recipients` and `GET /views` carry `parent` and
+`forwardedBy` on every row (`null` on the publisher's own sends), so the page's travel is a tree.
+
+**Acting through a thread or forward link needs sign-in.** On a group link of a page whose
+`forward:` is on, and on any forward link, a comment asks the reader to sign in at the moment of
+commenting (401 `{ signIn }` from the state API; the comment card offers the sign-in). The note is
+stored under `r:<rid>.<24 hex>`, derived from the link and the signed-in uid, so it still counts for
+that link, and it carries the name they signed in with. A named (personal) link comments without
+sign-in, under its label, as before. A page without the line, and a page with
+`comment_name: required`, keep their old rules.
+
 ### Expiry
 
 `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.

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

@@ -68,7 +68,13 @@ export type ArtifactMeta = {
      *  follow from draft to draft; a page that reads as a message leaves the line out. Content, like
      *  `toc:`: a republish without the line goes back to the host's setting. */
     history?: PageHistory;
+    /** `forward: off | signed-in | open` (0.56.0): whether a reader of a per-reader page may make a
+     *  link to pass it on, and whether they must sign in first. Absent is off. A door like `links:`,
+     *  so sticky: a republish that leaves the line out changes nothing. */
+    forward?: ForwardMode;
 };
+export declare const FORWARD_MODES: readonly ["off", "signed-in", "open"];
+export type ForwardMode = (typeof FORWARD_MODES)[number];
 /** Who sees a page's version number and past versions. */
 export type PageHistory = 'admins' | 'everyone';
 export declare const PAGE_HISTORY: readonly PageHistory[];

package/lib/artifacts/front-matter.js

@@ -7,6 +7,7 @@ import { mergeChecklistState, mergeWidgetState, scanWidgets } from './widgets.js
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
+export const FORWARD_MODES = ['off', 'signed-in', 'open'];
 export const PAGE_HISTORY = ['admins', 'everyone'];
 export const ARTIFACT_KINDS = ['document', 'broadcast'];
 /** Any media in a body: an image, a video or an audio clip, written as markdown image syntax. */
@@ -20,7 +21,7 @@ const PRIVATE_REF_IN_BODY = /^private:/;
 export const PACK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export const MAX_TO_CHARS = 60;
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name', 'history']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name', 'history', 'forward']);
 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`. */
@@ -93,6 +94,11 @@ opts = {}) {
             return { ok: false, error: 'comment_name must be required' };
         meta.commentName = 'required';
     }
+    if (d.forward !== undefined && d.forward !== null) {
+        if (!FORWARD_MODES.includes(d.forward))
+            return { ok: false, error: 'forward must be off, signed-in or open' };
+        meta.forward = d.forward;
+    }
     if (d.theme !== undefined) {
         if (!THEME_MODES.includes(d.theme))
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
@@ -159,6 +165,9 @@ opts = {}) {
     // /<id>/v/<n> of a per-reader page is never served, so the history list would be dead links.
     if (meta.history === 'everyone' && meta.links === 'per-reader')
         return { ok: false, error: 'a per-reader page serves no past versions: drop history: everyone' };
+    // A page anyone can open is forwarded by its own address: forward links are for per-reader pages.
+    if (meta.forward && meta.links !== 'per-reader')
+        return { ok: false, error: 'forward needs links: per-reader' };
     if (meta.commentName && meta.links !== 'per-reader')
         return { ok: false, error: 'comment_name: required needs links: per-reader' };
     // Widgets declare their own slots, so a notes block (and a checklist with send) is merged into state: here, before the

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

@@ -12,6 +12,18 @@ export type Recipient = {
     closesAt?: string | null;
     sentAt?: string;
     provenance?: Provenance;
+    parent?: string;
+    forwardedBy?: ForwardedBy;
+};
+/** Who made a forward link (0.56.0): the signed-in reader, or on a `forward: open` page the link
+ *  they made it from. */
+export type ForwardedBy = {
+    uid: string;
+    email: string;
+    name: string | null;
+} | {
+    rid: string;
+    label: string;
 };
 /** Who minted a link, on whose authority, and when (a superlink, 0.53.0): `actor` is a person by
  *  hand or "<person>'s Pluma"; `authority` is the request, recurrent or approval it acted under, with
@@ -57,6 +69,8 @@ export type RecipientSummary = {
     closesAt: string | null;
     sentAt: string | null;
     provenance: Provenance | null;
+    parent: string | null;
+    forwardedBy: ForwardedBy | null;
     beforeSend: BeforeSend;
     opened: boolean;
     firstOpenAt: string | null;
@@ -78,6 +92,8 @@ type NewRecipient = {
     group?: boolean;
     closesAt?: string;
     provenance?: Provenance;
+    parent?: string;
+    forwardedBy?: ForwardedBy;
 };
 export interface RecipientsStore {
     get(artifactId: string): Promise<RecipientsRecord | null>;

package/lib/artifacts/recipients-store.js

@@ -15,7 +15,7 @@ function makeRecipients(input, taken) {
         const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
         // 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 } : {}), ...(i.provenance ? { provenance: { ...i.provenance } } : {}) };
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}), ...(i.provenance ? { provenance: { ...i.provenance } } : {}), ...(i.parent ? { parent: i.parent } : {}), ...(i.forwardedBy ? { forwardedBy: { ...i.forwardedBy } } : {}) };
     });
 }
 function revokeIn(rec, rids) {
@@ -213,6 +213,8 @@ export function summarizeViews(rec, views, comments) {
             rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null,
             sentAt: r.sentAt ?? null,
             provenance: r.provenance ?? null,
+            parent: r.parent ?? null,
+            forwardedBy: r.forwardedBy ?? null,
             beforeSend: Number.isFinite(sentMs) ? { sessions: early.length, devices: preDevices.size, activeSeconds: early.reduce((n, v) => n + v.activeSeconds, 0), firstAt: early[0]?.firstAt ?? null } : null,
             opened: mine.length > 0,
             firstOpenAt: mine[0]?.firstAt ?? null,

package/lib/artifacts/store.d.ts

@@ -1,5 +1,5 @@
 import { type Firestore } from 'firebase-admin/firestore';
-import type { ArtifactKind, ArtifactMeta } from './front-matter.js';
+import type { ArtifactKind, ArtifactMeta, ForwardMode } from './front-matter.js';
 import type { Access } from './reader.js';
 import type { StateConfig } from './state.js';
 import type { ThemeMode } from '../brand/theme.js';
@@ -33,6 +33,8 @@ export type ArtifactRecord = {
     pack?: string;
     toc?: boolean;
     commentName?: 'required';
+    /** Whether a reader may make a forward link (front-matter `forward:`); absent is off. */
+    forward?: ForwardMode;
     /** The page's own `history:` line; absent, the host's setting decides. */
     history?: 'admins' | 'everyone';
     definitions?: Definition[];

package/lib/artifacts/store.js

@@ -171,6 +171,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.pack ? { pack: input.meta.pack } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
         ...(input.meta.commentName ? { commentName: input.meta.commentName } : {}),
+        ...(input.meta.forward ? { forward: input.meta.forward } : {}),
         ...(input.meta.history ? { history: input.meta.history } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
     };

package/lib/reader/page-menu.d.ts

@@ -7,11 +7,14 @@ export type PageMenuProps = {
     name: string | null;
     /** The page is gated and this reader is not let in (they see its door). */
     shutOut?: boolean;
-    /** The link to share, or null when this reader cannot share this page. `note` sits under it. */
+    /** The link to share, or null when this reader cannot share this page. `note` sits under it.
+     *  `forward` (0.56.0): on a per-reader page, the route that makes a forward link for this reader;
+     *  Share asks it for the link (signing the reader in first when it says to) instead of `url`. */
     share: {
         url: string;
         title: string;
         note?: string;
+        forward?: string;
     } | null;
     /** Shared comments are on here, so the pins can be shown or hidden. */
     comments: boolean;

package/lib/reader/page-menu.js

@@ -142,10 +142,32 @@ export function PageMenu(props) {
     const onShare = async () => {
         if (!share)
             return;
+        let url = share.url;
+        if (share.forward) {
+            // A per-reader page is passed on through a link of its own, never its bare address, which
+            // opens for nobody. Signed out on a page that needs sign-in, the route says where to go.
+            try {
+                const res = await fetch(share.forward, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', credentials: 'same-origin' });
+                const body = (await res.json().catch(() => ({})));
+                if (res.status === 401 && body.signIn) {
+                    window.location.href = body.signIn;
+                    return;
+                }
+                if (!res.ok || !body.link) {
+                    setSaid(body.error ?? "Couldn't make a link. Try again.");
+                    return;
+                }
+                url = body.link;
+            }
+            catch {
+                setSaid("Couldn't make a link. Try again.");
+                return;
+            }
+        }
         // A phone hands the link to its own share sheet (Messages, Mail, AirDrop); a desk copies it.
         if (coarse() && typeof navigator.share === 'function') {
             try {
-                await navigator.share({ title: share.title, url: share.url });
+                await navigator.share({ title: share.title, url });
                 close();
                 return;
             }
@@ -156,7 +178,7 @@ export function PageMenu(props) {
                     return;
             }
         }
-        setSaid((await copyText(share.url)) ? 'Link copied' : 'Could not copy the link');
+        setSaid((await copyText(url)) ? 'Link copied' : 'Could not copy the link');
     };
     const onMarkdown = async () => {
         if (markdown === null)
@@ -199,5 +221,5 @@ export function PageMenu(props) {
                     border: '1px solid var(--a-line, rgba(127,127,127,0.3))', boxShadow: '0 1px 4px rgba(0,0,0,0.12)',
                     backdropFilter: 'blur(8px)', WebkitBackdropFilter: 'blur(8px)',
                 }, children: _jsxs("svg", { width: "18", height: "18", viewBox: "0 0 18 18", "aria-hidden": true, focusable: "false", children: [_jsx("circle", { cx: "3.5", cy: "9", r: "1.6", fill: "currentColor" }), _jsx("circle", { cx: "9", cy: "9", r: "1.6", fill: "currentColor" }), _jsx("circle", { cx: "14.5", cy: "9", r: "1.6", fill: "currentColor" })] }) }), open && phone ? _jsx("div", { "aria-hidden": true, "data-page-menu-scrim": true, style: { position: 'fixed', inset: 0, zIndex: 59, background: 'rgba(0,0,0,0.28)' } }) : null, open ? (_jsxs("div", { ref: menu, "data-page-menu": true, role: "menu", "aria-label": "Page menu", style: panelStyle, children: [_jsx("p", { "data-page-menu-role": true, style: { margin: 0, padding: phone ? '10px 12px 8px' : '8px 10px 6px', fontSize: 12, lineHeight: 1.35, opacity: 0.7, overflowWrap: 'anywhere' }, children: line }), items.length ? _jsx("div", { "aria-hidden": true, style: { height: 1, margin: '0 6px 4px', background: 'var(--a-line, rgba(127,127,127,0.3))' } }) : null, share ? (_jsxs("button", { type: "button", role: "menuitem", "data-page-menu-item": "share", onClick: () => void onShare(), style: itemStyle, children: [said === 'Link copied' || said === 'Could not copy the link' ? said : 'Share', share.note ? _jsx("span", { "data-page-menu-note": true, style: sub, children: share.note }) : null] })) : null, comments ? (_jsx("button", { type: "button", role: "menuitem", "data-page-menu-item": "comments", onClick: onPins, style: itemStyle, children: pins ? 'Hide comments' : 'Show comments' })) : null, settings ? (_jsx("button", { type: "button", role: "menuitem", "data-page-menu-item": "share-settings", "aria-haspopup": "dialog", onClick: () => onSheet('share'), style: itemStyle, children: "Share settings" })) : null, settings && settings.comments !== null ? (_jsx("button", { type: "button", role: "menuitem", "data-page-menu-item": "comment-settings", "aria-haspopup": "dialog", onClick: () => onSheet('comments'), style: itemStyle, children: "Comment settings" })) : null, history ? (_jsx("button", { type: "button", role: "menuitem", "data-page-menu-item": "history", "aria-haspopup": "dialog", onClick: onHistory, style: itemStyle, children: "Version history" })) : null, markdown !== null ? (_jsx("button", { type: "button", role: "menuitem", "data-page-menu-item": "markdown", onClick: () => void onMarkdown(), style: itemStyle, children: said === 'Markdown copied' || said === 'Could not copy the markdown' ? said : 'Copy the markdown' })) : null, viewAsReader ? (_jsx("a", { role: "menuitem", "data-page-menu-item": "view-as-reader", href: viewAsReader, style: itemStyle, children: "View as a reader" })) : null, signOut ? (_jsx("a", { role: "menuitem", "data-page-menu-item": "sign-out", href: signOut, style: itemStyle, children: "Sign out" })) : signIn ? (_jsx("a", { role: "menuitem", "data-page-menu-item": "sign-in", href: signIn, onClick: (e) => { e.currentTarget.href = signInBack(signIn); }, style: itemStyle, children: "Sign in" })) : null, _jsx("span", { role: "status", "aria-live": "polite", style: { position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)' }, children: said ?? '' })] })) : null, sheet && settings ? (_jsx(SettingsSheet, { kind: sheet.kind, settings: settings, saved: sheet.saved, phone: phone, vars: vars, onCopy: copyText, onClose: () => { setSheet(null); button.current?.focus(); } })) : null, historyOpen && history ? (_jsx(HistoryPanel, { items: history.items, base: history.base, viewing: history.viewing, anchor: button, onClose: () => { setHistoryOpen(false); button.current?.focus(); }, onOutside: () => setHistoryOpen(false) })) : null] })) : null;
-    return (_jsxs(_Fragment, { children: [_jsx("span", { ref: marker, hidden: true, "data-page-menu-for": role, "data-page-menu-items": items.join(' '), children: history ? _jsx(VersionList, { items: history.items, base: history.base, marker: true }) : null }), ui ? createPortal(ui, document.body) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx("span", { ref: marker, hidden: true, "data-page-menu-for": role, "data-page-menu-items": items.join(' '), "data-page-menu-forward": share?.forward ? share.note ?? '' : undefined, children: history ? _jsx(VersionList, { items: history.items, base: history.base, marker: true }) : null }), ui ? createPortal(ui, document.body) : null] }));
 }

package/lib/routes/artifacts.d.ts

@@ -176,6 +176,11 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
             id: string;
         }>;
     }) => Promise<NextResponse<unknown>>;
+    FORWARD: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
     sweepExpired: (now?: Date) => Promise<{
         pages: number;
         files: number;
@@ -251,8 +256,15 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     GET: (request: NextRequest, { params }: Params) => Promise<NextResponse<{
         error: string;
     }> | NextResponse<{
+        markdown: string;
+        version: number;
+        updatedAt: string;
+        to?: string | undefined;
+        summary: string;
+        subtitle?: string | undefined;
         id: string;
         text: string;
+        title: string;
     }>>;
     DELETE: (request: NextRequest, { params }: Params) => Promise<NextResponse<{
         error: string;

package/lib/routes/artifacts.js

@@ -22,7 +22,7 @@ import { CommentLayer } from '../reader/comment-layer.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
 import { UpdatedTime } from '../reader/updated-time.js';
 import { FeedbackWindow } from '../reader/feedback-window.js';
-import { perReaderGate, withPrivateUrls, NO_LINK, UNAVAILABLE } from './per-reader.js';
+import { perReaderGate, signInToAct, withPrivateUrls, NO_LINK, UNAVAILABLE } from './per-reader.js';
 import { ridCookieName, mintRenderToken, usableSecret, isUnfurlAgent, RID_COOKIE_MAX_AGE } from '../artifacts/recipients.js';
 import { PageMenu } from '../reader/page-menu.js';
 import { COMMENTS_MODES } from '../artifacts/comments.js';
@@ -139,7 +139,7 @@ export function createArtifactRoutes(config) {
     });
     const recipientsRoutes = createRecipientsRoutes({
         store, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
-        state: config.state, assets: config.assets, pageUrl, authed,
+        state: config.state, assets: config.assets, pageUrl, authed, readerSecret, signInOrigin, siteUrl,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({
@@ -246,15 +246,22 @@ export function createArtifactRoutes(config) {
      *    link, since only they hold it.
      *  - Version history: whoever `history` lets see past versions (admins by default).
      *  - Copy the markdown: the owner and admins. */
-    function Menu({ a, reader, shutOut, allow, comments, history, viewing, source, settings }) {
+    function Menu({ a, reader, shutOut, allow, comments, history, viewing, source, settings, perReader }) {
         const role = roleOf(reader);
         const admin = isAdmin(reader);
         const name = reader ? (firstName(reader, allow ?? []) ?? reader.email) : null;
-        const share = a.access
-            ? { url: pageUrl(a.id), title: a.title, ...(a.access === 'invite' ? { note: 'Only people on the list can open it.' } : {}) }
-            : a.password
-                ? (admin ? { url: `${pageUrl(a.id)}?key=${encodeURIComponent(a.password)}`, title: a.title, note: 'The link carries the password.' } : null)
-                : { url: pageUrl(a.id), title: a.title };
+        // A per-reader page opens only from a reader's own link, so its address is useless to pass on:
+        // a reader shares through a forward link, where the page allows one, and otherwise not at all.
+        const forwardNote = a.forward === 'open' ? 'This link says it came from yours.' : 'Your name goes with this link.';
+        const share = a.links === 'per-reader' && !admin
+            ? (perReader && !perReader.owner && (a.forward === 'signed-in' || a.forward === 'open')
+                ? { url: pageUrl(a.id), title: a.title, note: forwardNote, forward: `/api/artifacts/${a.id}/forward` }
+                : null)
+            : a.access
+                ? { url: pageUrl(a.id), title: a.title, ...(a.access === 'invite' ? { note: 'Only people on the list can open it.' } : {}) }
+                : a.password
+                    ? (admin ? { url: `${pageUrl(a.id)}?key=${encodeURIComponent(a.password)}`, title: a.title, note: 'The link carries the password.' } : null)
+                    : { url: pageUrl(a.id), title: a.title };
         return (_jsx(PageMenu, { role: role, name: name, shutOut: shutOut, share: share, comments: !!comments, signIn: !reader && signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, signOut: reader ? signOutUrl(a.id) : null, history: history && history.length > 1 && seesHistory(a, reader) && viewing ? { items: history, base: pagePath(a.id), viewing } : null, markdown: admin && source ? source : null, settings: admin ? settings ?? null : null, viewAsReader: admin && source ? `${pagePath(a.id)}?as=reader` : null }));
     }
     /** The kicker over every title: the pack's line, then who the page is for. Never spoken: the
@@ -352,7 +359,7 @@ export function createArtifactRoutes(config) {
             const remember = g.fromLink && !bot
                 ? [pagePath(id), `/api/artifacts/${id}`].map((p) => `document.cookie=${JSON.stringify(`${ridCookieName(id)}=${g.rid}.${g.sig}; Path=${p}; Max-Age=${RID_COOKIE_MAX_AGE}; SameSite=Lax; Secure`)}`).join(';')
                 : null;
-            const perReader = bot ? undefined : { rid: g.rid, sig: g.sig, label: g.label, note: g.note, owner: g.owner, group: g.group, closesAt: g.closesAt, token: mintRenderToken(secret, id, g.rid) };
+            const perReader = bot ? undefined : { rid: g.rid, sig: g.sig, label: g.label, note: g.note, owner: g.owner, group: g.group, forwarded: g.forwarded, closesAt: g.closesAt, token: mintRenderToken(secret, id, g.rid) };
             const markdown = await media(a.markdown);
             const body = broadcast
                 ? await BroadcastCard({ ...a, markdown }, { reader: null, perReader, bot })
@@ -491,7 +498,7 @@ export function createArtifactRoutes(config) {
         const cover = !bot && a.cover && !/!\[[^\]]*\]\(/.test(a.markdown) ? a.cover : null;
         return (_jsxs(_Fragment, { children: [admin ? (_jsx(PageMenu, { role: roleOf(reader), name: reader ? reader.name ?? reader.email : null, share: null, comments: mode !== 'off', signIn: null, signOut: signOutUrl(a.id), history: null, markdown: null, settings: null })) : null, _jsx("main", { "data-broadcast": true, className: "mx-auto max-w-lg px-4 pt-16 pb-20 sm:pt-24", children: _jsxs("article", { id: "broadcast-root", "data-broadcast-card": true, className: "rounded-2xl border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-5 py-6 sm:px-7 sm:py-8", children: [_jsx("p", { "data-nospeak": true, "data-broadcast-from": true, className: "text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: `From ${owner}` }), _jsx("h1", { className: "mt-3 text-2xl sm:text-3xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), cover ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone', signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked, bot })] }));
+                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || (effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone' && !(perReader && signInToAct(a, perReader))), signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked, bot })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader, perReader, untracked = false }) {
@@ -512,14 +519,14 @@ export function createArtifactRoutes(config) {
         const mode = config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
         const history = await historyOf(a.id);
         const current = a.version ?? (a.versions?.length ?? 0) + 1;
-        return (_jsxs(_Fragment, { children: [_jsx(Menu, { a: a, reader: reader, comments: mode !== 'off', history: history, viewing: current, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, a, a.markdown) : null }), toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
+        return (_jsxs(_Fragment, { children: [_jsx(Menu, { a: a, reader: reader, perReader: perReader, comments: mode !== 'off', history: history, viewing: current, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, a, a.markdown) : null }), toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt, numbered: seesHistory(a, reader) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, showVersion: seesHistory(a, reader), updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, embeds: embeds }) }));
-                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || (effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone' && !(perReader && signInToAct(a, perReader)))), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
     }
@@ -891,7 +898,15 @@ export function createArtifactRoutes(config) {
         const a = await kept.get(id);
         if (!a)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        return NextResponse.json({ id, text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }) });
+        // `text` is the narration (lists and headings without their items read badly aloud, so it
+        // drops them); `markdown` is the page as written, which is what an agent reading the page
+        // needs. Never the password or any reader data.
+        return NextResponse.json({
+            id,
+            text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }),
+            title: a.title, ...(a.subtitle ? { subtitle: a.subtitle } : {}), summary: a.summary, ...(a.to ? { to: a.to } : {}),
+            markdown: a.markdown, version: a.version ?? 1, updatedAt: a.updatedAt,
+        });
     }
     /** PUT /api/artifacts/<id>/assets/<name>: raw bytes in, public URL out. 16 MiB cap. */
     async function PUT_ASSET(request, { params }) {

package/lib/routes/per-reader.d.ts

@@ -9,11 +9,23 @@ export type PerReaderOpen = {
     group: boolean;
     closesAt: string | null;
     fromLink: boolean;
+    forwarded: boolean;
 };
 export type PerReaderShut = {
     state: 'shut';
     why: 'no-link' | 'revoked' | 'expired' | 'closed';
 };
+/** Superlinks (0.56.0): a link shared by several people, or passed on by a reader, says who nobody
+ *  is, so acting through it needs sign-in, at the moment of acting. Only on a forward link, or a
+ *  page that turned forwarding on: a page without the line keeps its old rule, and
+ *  `comment_name: required` keeps its typed name. One rule for the page and the state API. */
+export declare function signInToAct(page: {
+    forward?: string;
+    commentName?: string;
+}, link: {
+    group: boolean;
+    forwarded?: boolean;
+}): boolean;
 export declare const UNAVAILABLE = "This page is no longer available.";
 export declare const NO_LINK = "This page opens from the link it was sent with.";
 export declare function perReaderGate(o: {

package/lib/routes/per-reader.js

@@ -2,6 +2,13 @@
 // Every refusal is the same quiet page; a revoked or expired reader learns only that it is gone.
 import { parseRidParam, verifyRid } from '../artifacts/recipients.js';
 import { PRIVATE_REF } from '../artifacts/assets.js';
+/** Superlinks (0.56.0): a link shared by several people, or passed on by a reader, says who nobody
+ *  is, so acting through it needs sign-in, at the moment of acting. Only on a forward link, or a
+ *  page that turned forwarding on: a page without the line keeps its old rule, and
+ *  `comment_name: required` keeps its typed name. One rule for the page and the state API. */
+export function signInToAct(page, link) {
+    return link.group && page.commentName !== 'required' && (!!link.forwarded || (!!page.forward && page.forward !== 'off'));
+}
 export const UNAVAILABLE = 'This page is no longer available.';
 export const NO_LINK = 'This page opens from the link it was sent with.';
 export async function perReaderGate(o) {
@@ -18,12 +25,17 @@ export async function perReaderGate(o) {
     const r = rec?.recipients[pick.rid];
     if (!rec || !r)
         return { state: 'shut', why: 'no-link' };
-    if (r.revokedAt)
-        return { state: 'shut', why: 'revoked' };
+    // A forward never outlives the link it came from: any revoked link up its chain shuts it.
+    const seen = new Set();
+    for (let at = r; at; at = at.parent ? rec.recipients[at.parent] : undefined) {
+        if (at.revokedAt || seen.has(at.rid))
+            return { state: 'shut', why: 'revoked' };
+        seen.add(at.rid);
+    }
     // A malformed expireAt parses to NaN: treat it as expired, never as no expiry.
     if (rec.expireAt && !(Date.parse(rec.expireAt) > (o.now ?? Date.now())))
         return { state: 'shut', why: 'expired' };
-    return { state: 'open', rid: pick.rid, sig: pick.sig, label: r.label, note: r.note ?? null, owner: r.owner === true, group: r.group === true, closesAt: r.closesAt ?? null, fromLink: pick.fromLink };
+    return { state: 'open', rid: pick.rid, sig: pick.sig, label: r.label, note: r.note ?? null, owner: r.owner === true, group: r.group === true, closesAt: r.closesAt ?? null, fromLink: pick.fromLink, forwarded: !!r.parent };
 }
 const REF_IN_MD = /\]\((private:[A-Za-z0-9][A-Za-z0-9._-]{0,140})\)/g;
 export async function withPrivateUrls(markdown, id, privateUrl) {

package/lib/routes/recipients-routes.d.ts

@@ -19,7 +19,14 @@ export type RecipientsRoutesCtx = {
     authed: (r: Request) => boolean;
     /** Where the sweep reports a page it skipped or could not finish. Defaults to console.warn. */
     log?: (message: string) => void;
+    /** For FORWARD: who is signed in (the grant cookie's secret), where to send someone to sign in,
+     *  and this host's own address, the only origin a forward may be asked from. */
+    readerSecret?: () => string | undefined;
+    signInOrigin?: string;
+    siteUrl?: string;
 };
+/** How many forward links one reader may make on one page in a day. */
+export declare const FORWARDS_PER_DAY = 20;
 /** A reader's provenance as sent, checked: who minted the link, on whose authority, when (default
  *  now), and the funnel step it serves. -> the clean record, or the reason it is refused. */
 export declare function readProvenance(v: unknown, now?: Date): {
@@ -33,6 +40,7 @@ export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
     SEEN: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     RECIPIENTS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     VIEWS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    FORWARD: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     sweepExpired: (now?: Date) => Promise<{
         pages: number;
         files: number;

package/lib/routes/recipients-routes.js

@@ -1,9 +1,14 @@
 // The per-reader routes. SEEN is public (the page calls it); everything else needs the publish key.
 import { NextResponse } from 'next/server';
-import { RID_RE, usableSecret, beatKey, isUnfurlAgent, ridLink, verifyRenderToken, verifyRid } from '../artifacts/recipients.js';
+import { RID_RE, usableSecret, beatKey, isUnfurlAgent, ridLink, ridCookieName, verifyRenderToken, verifyRid } from '../artifacts/recipients.js';
+import { GRANT_COOKIE, signInUrl, verifyGrant } from '../artifacts/reader.js';
+import { perReaderGate } from './per-reader.js';
 import { summarizeViews } from '../artifacts/recipients-store.js';
 import { COMMENTS_SLOT } from '../artifacts/comments.js';
 import { ARTIFACT_ID_RE } from './ids.js';
+/** How many forward links one reader may make on one page in a day. */
+export const FORWARDS_PER_DAY = 20;
+const TO_MAX = 60;
 // Session and device ids become part of a stored view's id, so only a short plain shape is let in.
 const SESSION = /^[a-z0-9]{1,32}$/;
 const MEDIA = /^[A-Za-z0-9][A-Za-z0-9._-]{0,140}$/;
@@ -97,7 +102,7 @@ export function createRecipientsRoutes(given) {
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         return {
             id, expireAt: rec.expireAt, keep: rec.keep,
-            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, sentAt: r.sentAt ?? null, provenance: r.provenance ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
+            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, sentAt: r.sentAt ?? null, provenance: r.provenance ?? null, parent: r.parent ?? null, forwardedBy: r.forwardedBy ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
         };
     }
     /** GET and POST /api/artifacts/<id>/recipients: who a per-reader page was sent to (publish key). */
@@ -267,5 +272,52 @@ export function createRecipientsRoutes(given) {
         }
         return out;
     }
-    return { SEEN, RECIPIENTS, VIEWS, sweepExpired, forgetReaders };
+    /** POST /api/artifacts/<id>/forward (0.56.0): the page itself, for a reader passing it on.
+     *  Body `{ to?: first name }`. Mints a forward link that names who made it, from which link, and
+     *  when, and answers `{ link }`. Never mints from a page with `forward:` off, from a link that is
+     *  not valid, or (on `forward: signed-in`) for a reader who has not signed in. */
+    async function FORWARD(req, { params }) {
+        const { id } = await params;
+        const secret = ctx.recipientSecret?.();
+        if (!secret || !ctx.recipients || !ARTIFACT_ID_RE.test(id))
+            return json({ error: 'not found' }, 404);
+        const origin = req.headers.get('origin');
+        if (ctx.siteUrl && origin !== null && origin !== new URL(ctx.siteUrl).origin)
+            return json({ error: 'wrong origin' }, 403);
+        const a = await ctx.store.get(id);
+        if (!a || a.links !== 'per-reader' || !a.forward || a.forward === 'off')
+            return json({ error: 'not found' }, 404);
+        const g = await perReaderGate({ id, param: undefined, cookie: req.cookies.get(ridCookieName(id))?.value, secret, recipients: ctx.recipients });
+        if (g.state === 'shut' || g.owner)
+            return json({ error: 'not found' }, 404);
+        let by;
+        if (a.forward === 'signed-in') {
+            const reader = verifyGrant(ctx.readerSecret?.(), req.cookies.get(GRANT_COOKIE)?.value);
+            if (!reader)
+                return json({ error: 'sign in to share this page', signIn: ctx.signInOrigin ? signInUrl(ctx.signInOrigin, ctx.pageUrl(id)) : null }, 401);
+            by = { uid: reader.uid, email: reader.email, name: reader.name };
+        }
+        else
+            by = { rid: g.rid, label: g.label };
+        const body = (await req.json().catch(() => ({})));
+        if (body.to !== undefined && (typeof body.to !== 'string' || body.to.trim().length > TO_MAX || /[\r\n]/.test(body.to)))
+            return json({ error: `to must be a first name, up to ${TO_MAX} characters` }, 400);
+        const to = typeof body.to === 'string' ? body.to.trim() : '';
+        const rec = await ctx.recipients.get(id);
+        const dayAgo = new Date(Date.now() - 86_400_000).toISOString();
+        const same = (f) => !!f && ('uid' in by ? 'uid' in f && f.uid === by.uid : 'rid' in f && f.rid === by.rid);
+        const made = Object.values(rec?.recipients ?? {}).filter((r) => same(r.forwardedBy) && r.addedAt > dayAgo).length;
+        if (made >= FORWARDS_PER_DAY)
+            return json({ error: 'too many links today; try again tomorrow' }, 429);
+        const who = 'uid' in by ? by.name?.trim() || by.email : by.label;
+        const provenance = { actor: 'uid' in by ? `${who} (signed in as ${by.email})` : `${who}'s link`, authority: `forwarded from ${g.label}'s link`, at: new Date().toISOString() };
+        try {
+            const [row] = await ctx.recipients.add(id, [{ label: to ? `${to} (from ${who})` : `From ${who}`, group: true, parent: g.rid, forwardedBy: by, provenance }]);
+            return json({ link: ridLink(ctx.pageUrl(id), id, row.rid, secret) });
+        }
+        catch {
+            return json({ error: "Couldn't make a link. Try again." }, 502);
+        }
+    }
+    return { SEEN, RECIPIENTS, VIEWS, FORWARD, sweepExpired, forgetReaders };
 }

package/lib/routes/state-routes.js

@@ -24,7 +24,7 @@ import { ARTIFACT_ID_RE } from './ids.js';
 import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
 import { browserIdFor, ridCookieName, ridOfReaderKey, usableSecret } from '../artifacts/recipients.js';
-import { perReaderGate } from './per-reader.js';
+import { perReaderGate, signInToAct } from './per-reader.js';
 import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters, slotVisibility } from '../artifacts/state.js';
 import { COMMENTS_SLOT, FEEDBACK_CLOSED, MAX_COMMENT_CHARS, MAX_COMMENT_NAME_CHARS, NAME_NEEDED, cleanResolveNote, resolutionOf, validateComment } from '../artifacts/comments.js';
 import { MAX_QUOTE_CHARS } from '../artifacts/anchor.js';
@@ -102,7 +102,9 @@ export function createStateRoutes(ctx) {
             if (g.state === 'shut')
                 return { error: json({ error: 'this page is locked' }, 403) };
             // The gate opened, so the secret is usable: it is what the browser id below is derived with.
-            recipient = { rid: g.rid, label: g.label, group: g.group, closesAt: g.closesAt, perBrowser: g.group && a.commentName === 'required', secret: secret };
+            recipient = { rid: g.rid, label: g.label, group: g.group, closesAt: g.closesAt, perBrowser: g.group && a.commentName === 'required',
+                signInToAct: signInToAct(a, g),
+                secret: secret };
         }
         const rawAnon = req.cookies.get(ANON_COOKIE)?.value;
         const anonId = rawAnon && ANON_ID.test(rawAnon) ? rawAnon : null;
@@ -113,7 +115,8 @@ export function createStateRoutes(ctx) {
      *  the link's verified rid and an id derived from the anonymous cookie this server set. Null for
      *  such a browser before its first write, when it has no cookie and nothing is its own. The
      *  client never names the key and cannot work out another browser's. */
-    const recipientKey = (id, r, anonId) => !r.perBrowser ? readerKeyFor.recipient(r.rid) : anonId ? readerKeyFor.groupBrowser(r.rid, browserIdFor(r.secret, id, r.rid, anonId)) : null;
+    const recipientKey = (id, r, anonId, reader = null) => r.signInToAct ? (reader ? readerKeyFor.groupBrowser(r.rid, browserIdFor(r.secret, id, r.rid, `u.${reader.uid}`)) : null)
+        : !r.perBrowser ? readerKeyFor.recipient(r.rid) : anonId ? readerKeyFor.groupBrowser(r.rid, browserIdFor(r.secret, id, r.rid, anonId)) : null;
     const ownerEmail = ctx.ownerEmail?.trim().toLowerCase();
     const admins = new Set((ctx.admins ?? []).map((e) => e.trim().toLowerCase()));
     // The owner and the page's admins read every comment, with names.
@@ -204,7 +207,7 @@ export function createStateRoutes(ctx) {
             await ctx.state.moveReader(readerKeyFor.anonymous(anonId), writerFor(reader));
             clearAnon = true;
         }
-        const key = recipient ? recipientKey(id, recipient, anonId) : reader ? readerKeyFor.signedIn(reader.uid) : anonId ? readerKeyFor.anonymous(anonId) : null;
+        const key = recipient ? recipientKey(id, recipient, anonId, reader) : reader ? readerKeyFor.signedIn(reader.uid) : anonId ? readerKeyFor.anonymous(anonId) : null;
         const feedback = recipient?.closesAt ? { feedback: { closesAt: recipient.closesAt, closed: windowClosed(recipient) } } : {};
         const res = json({ ...(await viewBody(a, reader, key, !!recipient)), ...feedback, ...(reader || recipient ? {} : { signIn }) });
         if (clearAnon)
@@ -268,7 +271,18 @@ export function createStateRoutes(ctx) {
             return json({ error: FEEDBACK_CLOSED, closed: true }, 403);
         let setCookie = null;
         let writer;
-        if (recipient) {
+        if (recipient?.signInToAct) {
+            // Signed in, the note is the reader's own under the link: still counted for the link, and
+            // carrying the name they signed in with rather than one anybody could type.
+            const key = recipientKey(id, recipient, anonId, reader);
+            if (!key || !reader) {
+                if (op === 'remove')
+                    return isComments && entryId ? json({ error: 'no comment of yours with that id' }, 404) : json(await viewBody(a, reader, null, true));
+                return json({ error: 'sign in to comment', signIn }, 401);
+            }
+            writer = { ...writerFor(reader), key };
+        }
+        else if (recipient) {
             let key = recipientKey(id, recipient, anonId);
             if (!key) {
                 // A browser on a group link that has written nothing: there is nothing of its own to delete

package/package.json

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