@supersuit/artifacts 0.10.0 → 0.11.1

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.11.1 (2026-09-28)
+
+**The comment controls draw in the page's colours.** The comment overlay is portalled onto
+`document.body`, outside the wrapper that sets the `--a-*` theme variables, so on a dark page the
+Comment chip and the Comment button rendered black text on the dark ground. The overlay now
+carries the variables it finds around the page root (`themeVarsAround`), re-read when a `system`
+page changes scheme.
+
+- DETECTOR: on a dark page, the Comment button bottom right is hard to read.
+- REMEDY: bump.
+- Tests: `comment-layer.test.tsx` pins the variables on the portalled overlay (mutation-checked).
+
+## 0.11.0 (2026-09-28)
+
+**Comment on any part of a page.** Select text, or drag a box over anything that is not text
+(an image, a table, a heading), and a comment card opens pinned to that spot. Pins sit in the
+margin; a toggle hides them. Threads take one level of replies.
+
+- **Shared comments** are per page: `comments: anyone | signed-in | off` (default `off`) and
+  `comments_visible: owner | readers` (default `owner`). They ride the state core as a `many`
+  slot named `comments`, so caps, rate limits, CSRF, sign-in migration and the agreement gate on
+  confidential pages apply unchanged. A gated page forces `signed-in`. The owner, signed in with
+  `ownerEmail`, sees every comment with names on the page; `/responses` returns them.
+- **Personal notes** work on every page, for every reader. When a reader cannot share, the card
+  says before they type: "Only you will see this. <owner> has not opened this page to comments,
+  so this is a personal note. They won't see it." Signed-in readers' notes are stored in a new
+  store no publisher route reads; anonymous readers' notes never leave the device.
+- **Anchors survive a republish**: text by quote plus 32 characters of context, regions by a
+  content-hashed block id (`data-block` on every rendered block) and fractions of that block.
+  A comment whose spot is gone is listed under "Comments on earlier versions".
+- State API: `op: replace` edits your own entry (optional `StateStore.replace`; a store without
+  it answers 501); deleting someone else's comment answers 404. Slots gained an internal
+  per-slot `writers` so `comments: anyone` can sit beside signed-in-only answers.
+- DETECTOR: a host on 0.10.x.
+- REMEDY: bump; pass `personal: createPersonalStore(db, base)`, `ownerEmail`, and add
+  `app/api/artifacts/[id]/personal/route.ts` delegating to `PERSONAL_GET`, `PERSONAL_POST`,
+  `PERSONAL_DELETE`. Without `personal`, signed-in readers' notes stay on their device.
+- Tests: anchors (re-find after insertions, duplicates and deletions; block ids stable across
+  unrelated edits), comment validation, replies, owner view, `comments: off` refusing a write with
+  the UI bypassed, the comment layer and card (the warning line, the share switch, device notes,
+  pins, the earlier-versions list), and `personal-privacy.test.tsx`, which calls every handler the
+  factory returns as publisher, owner and nobody and fails if any of them returns a personal note.
+  The packed fixture posts a comment and reads it back through `/responses`.
+
 ## 0.10.0 (2026-09-28)
 
 **Every page can be read aloud.** A page with no recorded narration, or whose timings will not

package/README.md

@@ -384,6 +384,68 @@ visibility: shared   # optional: private | shared
   can leave or read notes; the banner, watermark and print refusal are unchanged. On a public
   page with `writers: signed-in`, the control offers sign-in through `signInOrigin`.
 
+## Comments and personal notes
+
+Every page takes comments pinned to any part of it. A reader selects text (a **Comment** chip
+appears) or holds and drags a box over anything that is not text (an image, a table, the gap
+between paragraphs; on a phone, long-press then drag). The card that opens says who will read it
+before anything is typed.
+
+```yaml
+comments: anyone          # anyone reading can leave SHARED comments
+comments: signed-in       # only signed-in readers (forced on a gated page)
+comments: off             # the default: personal notes only
+comments_visible: owner   # the default: shared comments go to the owner only
+comments_visible: readers # every reader who can comment sees the whole thread
+```
+
+- **Shared comments** are the `many` slot `comments` on the state API, declared by the
+  `comments:` line (a page needs no `state:` for it). Caps, rate limits, sign-in migration, CSRF
+  and the agreement gate all apply. `comments: off` declares no slot, so the API refuses a shared
+  comment as it refuses any undeclared slot. A comment is `{ anchor, body, version, parent? }`,
+  checked on the server; a reply names a top-level comment its writer can see (one level only). A
+  writer edits (`op: replace`) or deletes (`op: remove`) only their own. The publisher reads them
+  through `/responses` like every answer.
+- **The owner signed in** (`ownerEmail` in the config) sees every shared comment with its
+  writer's full name, whatever `comments_visible:` says.
+- **Personal notes** are for every reader on every page. Without comment access the card opens
+  with: *"Only you will see this. <owner> has not opened this page to comments, so this is a
+  personal note. They won't see it."* (`<owner>` is the config's `owner`, default the brand name.)
+  Signed in, the note is stored under the reader's id through `/personal`; signed out, it stays in
+  the browser (`localStorage`) and moves to the account on sign-in. **No publisher route reads
+  personal notes**: `src/routes/personal-privacy.test.tsx` calls every handler the factory returns
+  with the publish key and fails if one ever does.
+- **Anchors survive a republish.** A text comment stores its quote with 32 characters either side
+  and the heading it sat under; a region comment stores the block it was drawn on (every top-level
+  block carries a stable `data-block` id from its content) and the box as fractions of it. One
+  whose quote or block is gone is listed under "Comments on earlier versions", with its quote.
+
+Wiring, beside the state routes:
+
+```ts
+// lib/artifacts.ts
+export const artifacts = createArtifactRoutes({
+  store,
+  state: createStateStore(getFirestore(), 'artifacts'),
+  personal: createPersonalStore(getFirestore(), 'artifacts'), // <base>Personal/<page>__<uid>/notes/<id>
+  ownerEmail: 'owner@example.com',
+  // ...the rest of your config
+})
+```
+
+```ts
+// app/api/artifacts/[id]/personal/route.ts
+import type { NextRequest } from 'next/server'
+import { artifacts } from '@/lib/artifacts'
+type Ctx = { params: Promise<{ id: string }> }
+export function GET(request: NextRequest, ctx: Ctx) { return artifacts.PERSONAL_GET(request, ctx) }
+export function POST(request: NextRequest, ctx: Ctx) { return artifacts.PERSONAL_POST(request, ctx) }
+export function DELETE(request: NextRequest, ctx: Ctx) { return artifacts.PERSONAL_DELETE(request, ctx) }
+```
+
+Without `personal`, every reader's notes stay on their device. Without `state`, no page takes
+shared comments.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

package/lib/artifacts/anchor.d.ts

@@ -0,0 +1,33 @@
+export type TextAnchor = {
+    kind: 'text';
+    quote: string;
+    prefix: string;
+    suffix: string;
+    heading?: string;
+};
+export type RegionAnchor = {
+    kind: 'region';
+    block: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type Anchor = TextAnchor | RegionAnchor;
+export declare const CONTEXT_CHARS = 32;
+export declare const MAX_QUOTE_CHARS = 500;
+export declare const BLOCK_ID: RegExp;
+export declare function textAnchorFrom(fullText: string, start: number, end: number, heading?: string): TextAnchor;
+/** Where the quote is now: the exact quote, and when there are several copies, the one whose
+ *  surrounding text matches the stored context in the most characters (the first on a tie).
+ *  Null when the quote no longer appears at all. */
+export declare function findText(fullText: string, a: TextAnchor): {
+    start: number;
+    end: number;
+} | null;
+/** `b-<kind>-<8 hex of its content>`. `index` is how many identical blocks (same kind and
+ *  content) come before this one on the page, so it only ever breaks a tie. Images are keyed by
+ *  their asset name, so a re-uploaded image with the same name keeps its comments. */
+export declare function blockId(kind: string, index: number, content: string): string;
+/** The server's check on an anchor posted with a comment. */
+export declare function parseAnchor(raw: unknown): Anchor | null;

package/lib/artifacts/anchor.js

@@ -0,0 +1,93 @@
+export const CONTEXT_CHARS = 32;
+export const MAX_QUOTE_CHARS = 500;
+const MAX_HEADING_SLUG = 120;
+export const BLOCK_ID = /^b-[a-z]{1,8}-[0-9a-f]{8}(?:-[1-9]\d{0,3})?$/;
+export function textAnchorFrom(fullText, start, end, heading) {
+    return {
+        kind: 'text',
+        quote: fullText.slice(start, end),
+        prefix: fullText.slice(Math.max(0, start - CONTEXT_CHARS), start),
+        suffix: fullText.slice(end, end + CONTEXT_CHARS),
+        ...(heading ? { heading } : {}),
+    };
+}
+/** How many characters at the END of `a` match the end of `b`. */
+function sameEnding(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n])
+        n++;
+    return n;
+}
+/** How many characters at the START of `a` match the start of `b`. */
+function sameStart(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[n] === b[n])
+        n++;
+    return n;
+}
+/** Where the quote is now: the exact quote, and when there are several copies, the one whose
+ *  surrounding text matches the stored context in the most characters (the first on a tie).
+ *  Null when the quote no longer appears at all. */
+export function findText(fullText, a) {
+    if (!a.quote)
+        return null;
+    let best = null;
+    for (let i = fullText.indexOf(a.quote); i !== -1; i = fullText.indexOf(a.quote, i + 1)) {
+        const before = fullText.slice(Math.max(0, i - a.prefix.length), i);
+        const after = fullText.slice(i + a.quote.length, i + a.quote.length + a.suffix.length);
+        const score = sameEnding(before, a.prefix) + sameStart(after, a.suffix);
+        if (!best || score > best.score)
+            best = { start: i, score };
+    }
+    return best ? { start: best.start, end: best.start + a.quote.length } : null;
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/** `b-<kind>-<8 hex of its content>`. `index` is how many identical blocks (same kind and
+ *  content) come before this one on the page, so it only ever breaks a tie. Images are keyed by
+ *  their asset name, so a re-uploaded image with the same name keeps its comments. */
+export function blockId(kind, index, content) {
+    const id = `b-${kind}-${fnv1a(`${kind}\n${content}`)}`;
+    return index > 0 ? `${id}-${index}` : id;
+}
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const frac = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+/** The server's check on an anchor posted with a comment. */
+export function parseAnchor(raw) {
+    if (!isMap(raw))
+        return null;
+    if (raw.kind === 'text') {
+        if (Object.keys(raw).some((k) => !['kind', 'quote', 'prefix', 'suffix', 'heading'].includes(k)))
+            return null;
+        const { quote, prefix, suffix, heading } = raw;
+        if (typeof quote !== 'string' || !quote.trim() || quote.length > MAX_QUOTE_CHARS)
+            return null;
+        if (typeof prefix !== 'string' || prefix.length > CONTEXT_CHARS)
+            return null;
+        if (typeof suffix !== 'string' || suffix.length > CONTEXT_CHARS)
+            return null;
+        if (heading !== undefined && (typeof heading !== 'string' || !heading || heading.length > MAX_HEADING_SLUG))
+            return null;
+        return { kind: 'text', quote, prefix, suffix, ...(heading ? { heading: heading } : {}) };
+    }
+    if (raw.kind === 'region') {
+        if (Object.keys(raw).some((k) => !['kind', 'block', 'x', 'y', 'w', 'h'].includes(k)))
+            return null;
+        const { block, x, y, w, h } = raw;
+        if (typeof block !== 'string' || !BLOCK_ID.test(block))
+            return null;
+        if (!frac(x) || !frac(y) || !frac(w) || !frac(h) || w <= 0 || h <= 0)
+            return null;
+        // A small allowance for float rounding at the far edge; a box that leaves its block is refused.
+        if (x + w > 1.000001 || y + h > 1.000001)
+            return null;
+        return { kind: 'region', block, x, y, w, h };
+    }
+    return null;
+}

package/lib/artifacts/comments.d.ts

@@ -0,0 +1,38 @@
+import type { StateConfig, Writers } from './state.js';
+import { type Anchor } from './anchor.js';
+export declare const COMMENTS_SLOT = "comments";
+export type CommentsMode = 'off' | Writers;
+export type CommentsVisible = 'owner' | 'readers';
+export declare const COMMENTS_MODES: readonly CommentsMode[];
+/** The page's `comments:` line becomes the `comments` slot, beside whatever `state:` declares,
+ *  the way the notes block adds `notes`. Off (or absent) adds nothing, so the state API refuses a
+ *  shared-comment write as it refuses any slot the page did not declare. */
+export declare function mergeCommentsState(state: StateConfig | undefined, comments: CommentsMode | undefined, visible: CommentsVisible | undefined): {
+    ok: true;
+    state: StateConfig | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const MAX_COMMENT_CHARS = 4000;
+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. */
+export type CommentValue = {
+    anchor: Anchor;
+    body: string;
+    version: number;
+    parent?: string;
+    audio?: string;
+    transcript?: (typeof COMMENT_TRANSCRIPTS)[number];
+};
+/** The server's check on a comment, called by the state POST for the `comments` slot. `existing`
+ *  returns a comment THIS WRITER can see by its entry id, so a reply can only name a thread its
+ *  writer was shown. The browser checks too; this is the one that counts. */
+export declare function validateComment(v: unknown, existing: (id: string) => CommentValue | null): {
+    ok: true;
+    value: CommentValue;
+} | {
+    ok: false;
+    error: string;
+};

package/lib/artifacts/comments.js

@@ -0,0 +1,57 @@
+import { parseAnchor } from './anchor.js';
+export const COMMENTS_SLOT = 'comments';
+export const COMMENTS_MODES = ['off', 'anyone', 'signed-in'];
+/** The page's `comments:` line becomes the `comments` slot, beside whatever `state:` declares,
+ *  the way the notes block adds `notes`. Off (or absent) adds nothing, so the state API refuses a
+ *  shared-comment write as it refuses any slot the page did not declare. */
+export function mergeCommentsState(state, comments, visible) {
+    if (!comments || comments === 'off')
+        return { ok: true, state };
+    if (state && Object.hasOwn(state.slots, COMMENTS_SLOT))
+        return { ok: false, error: `comments: writes to slot "${COMMENTS_SLOT}", and state: declares a slot by that name; rename that slot` };
+    const base = state ?? { writers: 'signed-in', visibility: 'private', slots: {} };
+    const slot = { shape: 'many', visibility: visible === 'readers' ? 'shared' : 'private', writers: comments };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [COMMENTS_SLOT]: slot } } };
+}
+export const MAX_COMMENT_CHARS = 4000;
+export const COMMENT_TRANSCRIPTS = ['browser', 'host', 'typed'];
+const ENTRY_ID = /^[A-Za-z0-9_-]{1,128}$/;
+// An uploaded asset path under the page (comments/<id>.webm), never a URL and never `..`.
+const AUDIO_PATH = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9._/-]{0,299}$/;
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** The server's check on a comment, called by the state POST for the `comments` slot. `existing`
+ *  returns a comment THIS WRITER can see by its entry id, so a reply can only name a thread its
+ *  writer was shown. The browser checks too; this is the one that counts. */
+export function validateComment(v, existing) {
+    if (!isMap(v) || Object.keys(v).some((k) => !['anchor', 'body', 'version', 'parent', 'audio', 'transcript'].includes(k)))
+        return { ok: false, error: 'a comment is { anchor, body, version, parent? }' };
+    const anchor = parseAnchor(v.anchor);
+    if (!anchor)
+        return { ok: false, error: 'a comment needs the place on the page it is pinned to' };
+    if (v.audio !== undefined && (typeof v.audio !== 'string' || !AUDIO_PATH.test(v.audio)))
+        return { ok: false, error: 'a comment\'s audio is the path it was uploaded to' };
+    if (typeof v.body !== 'string' || (!v.body.trim() && v.audio === undefined))
+        return { ok: false, error: 'a comment needs some text' };
+    if (v.body.length > MAX_COMMENT_CHARS)
+        return { ok: false, error: `a comment is at most ${MAX_COMMENT_CHARS} characters` };
+    if (typeof v.version !== 'number' || !Number.isInteger(v.version) || v.version < 1 || v.version > 999999)
+        return { ok: false, error: 'a comment needs the version it was left on' };
+    if (v.transcript !== undefined && !COMMENT_TRANSCRIPTS.includes(v.transcript))
+        return { ok: false, error: `a comment's transcript is one of: ${COMMENT_TRANSCRIPTS.join(', ')}` };
+    const value = { anchor, body: v.body, version: v.version };
+    if (v.parent !== undefined) {
+        if (typeof v.parent !== 'string' || !ENTRY_ID.test(v.parent))
+            return { ok: false, error: 'a reply names the comment it answers' };
+        const parent = existing(v.parent);
+        if (!parent)
+            return { ok: false, error: 'there is no comment here to reply to' };
+        if (parent.parent)
+            return { ok: false, error: 'replies are one level deep: reply to the comment, not to a reply' };
+        value.parent = v.parent;
+    }
+    if (v.audio !== undefined)
+        value.audio = v.audio;
+    if (v.transcript !== undefined)
+        value.transcript = v.transcript;
+    return { ok: true, value };
+}

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

@@ -1,5 +1,6 @@
 import { type Access } from './reader.js';
 import { type StateConfig } from './state.js';
+import { type CommentsMode, type CommentsVisible } from './comments.js';
 import { type ThemeMode } from '../brand/theme.js';
 import { type Definition } from './definitions.js';
 export type ArtifactMeta = {
@@ -39,6 +40,12 @@ export type ArtifactMeta = {
     /** One line saying what changed in this version. Stored with the version it arrives on; a line
      *  left in the file from the previous publish is recognised and not repeated. */
     change?: string;
+    /** Who may leave SHARED comments: `off` (the default; readers still keep personal notes),
+     *  `anyone`, or `signed-in`. Forced to signed-in on a gated page. Not an access control, so a
+     *  republish without the line goes back to off. */
+    comments?: CommentsMode;
+    /** Who sees shared comments: `owner` (the default) or every reader (`readers`). */
+    commentsVisible?: CommentsVisible;
 };
 export declare function parseArtifactSource(text: string): {
     ok: true;

package/lib/artifacts/front-matter.js

@@ -4,9 +4,10 @@ import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
 import { parseStateConfig } from './state.js';
 import { mergeWidgetState, scanWidgets } from './widgets.js';
+import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -66,6 +67,18 @@ export function parseArtifactSource(text) {
             return { ok: false, error: s.error };
         meta.state = s.state;
     }
+    if (d.comments !== undefined && d.comments !== null) {
+        // A bare `off` is a string in YAML 1.2, but `false` is a boolean and means the same thing.
+        const c = d.comments === false ? 'off' : d.comments;
+        if (!COMMENTS_MODES.includes(c))
+            return { ok: false, error: `comments must be one of: ${COMMENTS_MODES.join(', ')}` };
+        meta.comments = c;
+    }
+    if (d.comments_visible !== undefined && d.comments_visible !== null) {
+        if (d.comments_visible !== 'owner' && d.comments_visible !== 'readers')
+            return { ok: false, error: 'comments_visible must be owner or readers' };
+        meta.commentsVisible = d.comments_visible;
+    }
     // Widgets declare their own slots, so a notes block 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.
@@ -76,7 +89,10 @@ export function parseArtifactSource(text) {
     const merged = mergeWidgetState(meta.state, w.notes);
     if (!merged.ok)
         return { ok: false, error: merged.error };
-    if (merged.state)
-        meta.state = merged.state;
+    const withComments = mergeCommentsState(merged.state, meta.comments, meta.commentsVisible);
+    if (!withComments.ok)
+        return { ok: false, error: withComments.error };
+    if (withComments.state)
+        meta.state = withComments.state;
     return { ok: true, meta, body: content };
 }

package/lib/artifacts/index.d.ts

@@ -10,4 +10,7 @@ export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type Flag
 export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT, type StateConfig, type SlotDef, type Shape, type Visibility, type Writers } from './state.js';
 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, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
+export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
+export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
+export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment, type CommentsMode, type CommentsVisible, type CommentValue } from './comments.js';
+export { createPersonalStore, createMemoryPersonalStore, validatePersonal, MAX_PERSONAL_PER_READER, type PersonalStore, type PersonalNote, type PersonalNoteValue } from './personal-store.js';

package/lib/artifacts/index.js

@@ -10,4 +10,7 @@ export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';
 export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT } from './state.js';
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
-export { slugify, headingsOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
+export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
+export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
+export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment } from './comments.js';
+export { createPersonalStore, createMemoryPersonalStore, validatePersonal, MAX_PERSONAL_PER_READER } from './personal-store.js';

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

@@ -0,0 +1,29 @@
+import type { Firestore } from 'firebase-admin/firestore';
+import { type CommentValue } from './comments.js';
+export type PersonalNoteValue = Omit<CommentValue, 'parent'>;
+export type PersonalNote = {
+    id: string;
+    value: PersonalNoteValue;
+    at: string;
+    updatedAt?: string;
+};
+export declare const MAX_PERSONAL_PER_READER = 500;
+export interface PersonalStore {
+    list(artifactId: string, readerUid: string): Promise<PersonalNote[]>;
+    add(artifactId: string, readerUid: string, value: PersonalNoteValue): Promise<PersonalNote | {
+        full: true;
+    }>;
+    replace(artifactId: string, readerUid: string, noteId: string, value: PersonalNoteValue): Promise<PersonalNote | null>;
+    remove(artifactId: string, readerUid: string, noteId: string): Promise<boolean>;
+}
+/** A personal note is a comment with no thread: nobody else can see it to reply. */
+export declare function validatePersonal(v: unknown): {
+    ok: true;
+    value: PersonalNoteValue;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function createPersonalStore(db: Firestore, base: string): PersonalStore;
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export declare function createMemoryPersonalStore(): PersonalStore;

package/lib/artifacts/personal-store.js

@@ -0,0 +1,100 @@
+// Personal notes: a comment only its writer will ever read. NOT the state core.
+//
+// The state core's `private` visibility hides an answer from other readers and still hands it to
+// the publisher through /responses. A personal note promises the page's owner never sees it, so
+// it lives in a store of its own that no publisher route reads. The route factory hands this store
+// to exactly one set of handlers, the reader's own (/personal, behind their grant cookie), and a
+// test (routes/personal-privacy.test.ts) calls every handler the factory returns with a publish key
+// and fails if the note appears in any answer. That test is what makes the warning line true.
+//
+//   <base>Personal/<page>__<readerUid>/notes/<noteId>
+//
+// `base` is the artifacts collection path (`tenants/<id>/artifacts`), the same base the readers
+// store uses, so each tenant's notes sit beside its own pages. A reader who is not signed in keeps
+// notes on their device instead (reader/device-notes.ts): those never reach any server at all.
+import { randomUUID } from 'node:crypto';
+import { validateComment } from './comments.js';
+export const MAX_PERSONAL_PER_READER = 500;
+/** A personal note is a comment with no thread: nobody else can see it to reply. */
+export function validatePersonal(v) {
+    if (v && typeof v === 'object' && 'parent' in v)
+        return { ok: false, error: 'a personal note is not a reply' };
+    const r = validateComment(v, () => null);
+    return r.ok ? { ok: true, value: r.value } : r;
+}
+const NOTE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+// A Firestore document id cannot hold a slash; a signed uid never should, but the path is built from it.
+const readerDoc = (artifactId, readerUid) => `${artifactId}__${readerUid.replace(/\//g, '_')}`;
+const byAt = (a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id);
+export function createPersonalStore(db, base) {
+    const notes = (artifactId, readerUid) => db.collection(`${base}Personal`).doc(readerDoc(artifactId, readerUid)).collection('notes');
+    const toNote = (id, d) => ({ id, value: JSON.parse(d.json), at: d.at, ...(d.updatedAt ? { updatedAt: d.updatedAt } : {}) });
+    return {
+        async list(artifactId, readerUid) {
+            const snap = await notes(artifactId, readerUid).get();
+            return snap.docs.map((d) => toNote(d.id, d.data())).sort(byAt);
+        },
+        async add(artifactId, readerUid, value) {
+            const col = notes(artifactId, readerUid);
+            if ((await col.count().get()).data().count >= MAX_PERSONAL_PER_READER)
+                return { full: true };
+            const ref = col.doc();
+            const at = new Date().toISOString();
+            // Stored as a JSON string, like the state core, because Firestore refuses nested arrays.
+            await ref.set({ json: JSON.stringify(value), at });
+            return { id: ref.id, value, at };
+        },
+        async replace(artifactId, readerUid, noteId, value) {
+            if (!NOTE_ID.test(noteId))
+                return null;
+            const ref = notes(artifactId, readerUid).doc(noteId);
+            const snap = await ref.get();
+            if (!snap.exists)
+                return null;
+            const updatedAt = new Date().toISOString();
+            await ref.update({ json: JSON.stringify(value), updatedAt });
+            return { ...toNote(noteId, snap.data()), value, updatedAt };
+        },
+        async remove(artifactId, readerUid, noteId) {
+            if (!NOTE_ID.test(noteId))
+                return false;
+            const ref = notes(artifactId, readerUid).doc(noteId);
+            if (!(await ref.get()).exists)
+                return false;
+            await ref.delete();
+            return true;
+        },
+    };
+}
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export function createMemoryPersonalStore() {
+    const docs = new Map();
+    const of = (artifactId, readerUid) => {
+        const k = readerDoc(artifactId, readerUid);
+        let m = docs.get(k);
+        if (!m)
+            docs.set(k, (m = new Map()));
+        return m;
+    };
+    return {
+        list: async (artifactId, readerUid) => [...of(artifactId, readerUid).values()].map((n) => structuredClone(n)).sort(byAt),
+        async add(artifactId, readerUid, value) {
+            const m = of(artifactId, readerUid);
+            if (m.size >= MAX_PERSONAL_PER_READER)
+                return { full: true };
+            const n = { id: randomUUID().replace(/-/g, ''), value: structuredClone(value), at: new Date().toISOString() };
+            m.set(n.id, n);
+            return structuredClone(n);
+        },
+        async replace(artifactId, readerUid, noteId, value) {
+            const m = of(artifactId, readerUid);
+            const n = m.get(noteId);
+            if (!n)
+                return null;
+            const next = { ...n, value: structuredClone(value), updatedAt: new Date().toISOString() };
+            m.set(noteId, next);
+            return structuredClone(next);
+        },
+        remove: async (artifactId, readerUid, noteId) => of(artifactId, readerUid).delete(noteId),
+    };
+}