@supersuit/artifacts 0.10.0 → 0.11.1

package/lib/artifacts/render.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
-import { hasNotesWidget, headingsOf } from './widgets.js';
+import { blocksOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -70,50 +70,52 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
-const components = {
-    p: ({ children }) => _jsx("p", { className: "my-4 leading-relaxed", children: children }),
-    ul: ({ children }) => _jsx("ul", { className: "my-4 list-disc space-y-1 pl-6", children: children }),
-    ol: ({ children }) => _jsx("ol", { className: "my-4 list-decimal space-y-1 pl-6", children: children }),
-    hr: () => _jsx("hr", { className: "my-10 border-[color:var(--a-line)]" }),
-    table: ({ children }) => (_jsx("div", { className: "my-6 overflow-x-auto", children: _jsx("table", { className: "w-full border-collapse text-sm", children: children }) })),
-    th: ({ children }) => (_jsx("th", { className: "border-b border-[color:var(--a-line-strong)] px-3 py-2 text-left font-semibold text-[color:var(--a-strong)]", children: children })),
-    td: ({ children }) => _jsx("td", { className: "border-b border-[color:var(--a-line)] px-3 py-2 align-top", children: children }),
-    img: ({ src, alt }) => typeof src === 'string' && VIDEO.test(src) ? (_jsx(InlineVideo, { src: src, label: alt ?? '' })) : typeof src === 'string' && AUDIO.test(src) ? (_jsx(InlineAudio, { src: src, label: alt ?? '' })) : (
-    // eslint-disable-next-line @next/next/no-img-element
-    _jsx("img", { src: typeof src === 'string' ? src : undefined, alt: alt ?? '', className: "my-6 w-full rounded-lg border border-[color:var(--a-line)]" })),
-    a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, target: "_blank", rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] })),
-    code: ({ className, children }) => {
-        const lang = /language-(\w+)/.exec(className ?? '')?.[1];
-        if (lang === 'links')
-            return _jsx(LinkCards, { source: textOf(children) });
-        // A notes fence is the widget's place on the page. Without notes enabled (the host keeps no
-        // answers) it draws nothing: its settings are not prose and never shown as code.
-        if (lang === 'notes')
-            return null;
-        if (!className) {
-            return _jsx("code", { className: "rounded bg-[color:var(--a-surface-strong)] px-1.5 py-0.5 text-[0.9em] text-[color:var(--a-strong)]", children: children });
-        }
-        return _jsx("code", { className: className, children: children });
-    },
-    pre: ({ children }) => {
-        // A links fence renders its own block; do not wrap it in <pre>.
-        const inner = Array.isArray(children) ? children[0] : children;
-        const cls = inner?.props?.className ?? '';
-        if (/language-(links|notes)/.test(cls))
-            return _jsx(_Fragment, { children: children });
-        return (_jsx("pre", { "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-code)] p-4 text-sm text-[color:var(--a-strong)]", children: children }));
-    },
-    blockquote: ({ children }) => {
-        const t = textOf(children).trim();
-        const m = CALLOUT.exec(t);
-        if (!m) {
-            return (_jsx("blockquote", { className: "my-6 border-l-2 pl-4 italic text-[color:var(--a-body)]", style: { borderColor: GOLD }, children: children }));
-        }
-        const kind = m[1].toLowerCase();
-        const body = t.replace(CALLOUT, '');
-        return (_jsxs("aside", { "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'var(--a-surface)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-[color:var(--a-strong)]", children: body })] }));
-    },
-};
+function baseComponents(block) {
+    return {
+        p: ({ node, children }) => _jsx("p", { ...block(node), className: "my-4 leading-relaxed", children: children }),
+        ul: ({ node, children }) => _jsx("ul", { ...block(node), className: "my-4 list-disc space-y-1 pl-6", children: children }),
+        ol: ({ node, children }) => _jsx("ol", { ...block(node), className: "my-4 list-decimal space-y-1 pl-6", children: children }),
+        hr: () => _jsx("hr", { className: "my-10 border-[color:var(--a-line)]" }),
+        table: ({ node, children }) => (_jsx("div", { ...block(node), className: "my-6 overflow-x-auto", children: _jsx("table", { className: "w-full border-collapse text-sm", children: children }) })),
+        th: ({ children }) => (_jsx("th", { className: "border-b border-[color:var(--a-line-strong)] px-3 py-2 text-left font-semibold text-[color:var(--a-strong)]", children: children })),
+        td: ({ children }) => _jsx("td", { className: "border-b border-[color:var(--a-line)] px-3 py-2 align-top", children: children }),
+        img: ({ src, alt }) => typeof src === 'string' && VIDEO.test(src) ? (_jsx(InlineVideo, { src: src, label: alt ?? '' })) : typeof src === 'string' && AUDIO.test(src) ? (_jsx(InlineAudio, { src: src, label: alt ?? '' })) : (
+        // eslint-disable-next-line @next/next/no-img-element
+        _jsx("img", { src: typeof src === 'string' ? src : undefined, alt: alt ?? '', className: "my-6 w-full rounded-lg border border-[color:var(--a-line)]" })),
+        a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, target: "_blank", rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] })),
+        code: ({ className, children }) => {
+            const lang = /language-(\w+)/.exec(className ?? '')?.[1];
+            if (lang === 'links')
+                return _jsx(LinkCards, { source: textOf(children) });
+            // A notes fence is the widget's place on the page. Without notes enabled (the host keeps no
+            // answers) it draws nothing: its settings are not prose and never shown as code.
+            if (lang === 'notes')
+                return null;
+            if (!className) {
+                return _jsx("code", { className: "rounded bg-[color:var(--a-surface-strong)] px-1.5 py-0.5 text-[0.9em] text-[color:var(--a-strong)]", children: children });
+            }
+            return _jsx("code", { className: className, children: children });
+        },
+        pre: ({ node, children }) => {
+            // A links fence renders its own block; do not wrap it in <pre>.
+            const inner = Array.isArray(children) ? children[0] : children;
+            const cls = inner?.props?.className ?? '';
+            if (/language-(links|notes)/.test(cls))
+                return _jsx(_Fragment, { children: children });
+            return (_jsx("pre", { ...block(node), "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-code)] p-4 text-sm text-[color:var(--a-strong)]", children: children }));
+        },
+        blockquote: ({ node, children }) => {
+            const t = textOf(children).trim();
+            const m = CALLOUT.exec(t);
+            if (!m) {
+                return (_jsx("blockquote", { ...block(node), className: "my-6 border-l-2 pl-4 italic text-[color:var(--a-body)]", style: { borderColor: GOLD }, children: children }));
+            }
+            const kind = m[1].toLowerCase();
+            const body = t.replace(CALLOUT, '');
+            return (_jsxs("aside", { ...block(node), "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'var(--a-surface)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-[color:var(--a-strong)]", children: body })] }));
+        },
+    };
+}
 // scroll-mt keeps a heading clear of the top of the screen when a contents link jumps to it.
 const HEADING_CLASS = {
     1: 'mt-10 mb-4 scroll-mt-24 font-serif text-3xl text-[color:var(--a-strong)]',
@@ -125,26 +127,27 @@ const HEADING_CLASS = {
 };
 /** Components for any page: every heading gets its slug as an id, the one headingsOf derived,
  *  so a contents link and a note both land on it. */
-function pageComponents(headings) {
+function pageComponents(headings, block) {
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function Heading({ node, children }) {
         const Tag = `h${depth}`;
         const h = byLine.get(node?.position?.start.line ?? -1);
-        return _jsx(Tag, { id: h?.slug, className: HEADING_CLASS[depth], children: children });
+        return _jsx(Tag, { id: h?.slug, ...block(node), className: HEADING_CLASS[depth], children: children });
     };
-    return { ...components, h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
 }
 /** Components for a page with a notes block: every heading gets its slug as an id, a note
  *  control, and its notes after it. The heading is found by its source line, so the slug is the
  *  one headingsOf derived, the same one a note stores. */
-function notesComponents(headings) {
+function notesComponents(headings, block) {
+    const components = baseComponents(block);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
         const h = byLine.get(node?.position?.start.line ?? -1);
         if (!h)
-            return _jsx(Tag, { className: HEADING_CLASS[depth], children: children });
-        return (_jsxs(_Fragment, { children: [_jsxs(Tag, { id: h.slug, className: HEADING_CLASS[depth], children: [children, _jsx(NoteToggle, { slug: h.slug })] }), _jsx(HeadingNotes, { slug: h.slug, text: h.text })] }));
+            return _jsx(Tag, { ...block(node), className: HEADING_CLASS[depth], children: children });
+        return (_jsxs(_Fragment, { children: [_jsxs(Tag, { id: h.slug, ...block(node), className: HEADING_CLASS[depth], children: [children, _jsx(NoteToggle, { slug: h.slug })] }), _jsx(HeadingNotes, { slug: h.slug, text: h.text })] }));
     };
     const Code = components.code;
     return {
@@ -170,8 +173,13 @@ const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;
 export function ArtifactMarkdown({ markdown, notes, definitions, }) {
     const on = !!notes && hasNotesWidget(markdown);
     const headings = headingsOf(markdown);
+    const blocks = blocksOf(markdown);
+    const block = (node) => {
+        const id = blocks.get(node?.position?.start.offset ?? -1);
+        return id ? { 'data-block': id } : {};
+    };
     const defined = definitions?.length ? definitions : null;
-    const body = (_jsx(ReactMarkdown, { remarkPlugins: defined ? [remarkGfm, remarkDefinitions(defined)] : [remarkGfm], components: on ? notesComponents(headings) : pageComponents(headings), children: markdown }));
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: defined ? [remarkGfm, remarkDefinitions(defined)] : [remarkGfm], components: on ? notesComponents(headings, block) : pageComponents(headings, block), children: markdown }));
     return (
     // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
     _jsxs("div", { className: "break-words text-[17px] text-[color:var(--a-body)]", children: [on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body, VIDEO_IN_MD.test(markdown) ? _jsx(VideoAutoplay, {}) : null, defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));

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

@@ -52,6 +52,16 @@ export interface StateStore {
     /** Does this reader already hold a `one` answer in this slot? One document read. Optional so a
      *  host's own store keeps working; without it the route falls back to loading the page. */
     hasOne?(artifactId: string, slot: string, readerKey: string): Promise<boolean>;
+    /** Replace the value of one of THIS reader's own `many` entries (editing a comment), keeping its
+     *  id and time. Null when no such entry is theirs. Optional so a host's own store keeps working;
+     *  without it an edit answers 501. */
+    replace?(input: {
+        artifactId: string;
+        slot: string;
+        readerKey: string;
+        entryId: string;
+        value: unknown;
+    }): Promise<StateEntry | null>;
 }
 export declare const readerKeyFor: {
     signedIn: (uid: string) => string;

package/lib/artifacts/state-store.js

@@ -90,6 +90,17 @@ export function createStateStore(db, base) {
             return (await col().where('artifactId', '==', artifactId).where('slot', '==', slot).count().get()).data().count;
         },
         hasOne: async (artifactId, slot, readerKey) => (await col().doc(oneId(artifactId, slot, readerKey)).get()).exists,
+        async replace({ artifactId, slot, readerKey, entryId, value }) {
+            const ref = col().doc(entryId);
+            const snap = await ref.get();
+            if (!snap.exists)
+                return null;
+            const e = toEntry(snap.id, snap.data());
+            if (e.artifactId !== artifactId || e.slot !== slot || e.readerKey !== readerKey || e.shape !== 'many')
+                return null;
+            await ref.update({ json: JSON.stringify(value) });
+            return { ...e, value };
+        },
     };
     return store;
 }
@@ -149,5 +160,13 @@ export function createMemoryStateStore() {
         },
         countSlot: async (artifactId, slot) => of(artifactId).filter((e) => e.slot === slot).length,
         hasOne: async (artifactId, slot, readerKey) => docs.has(oneId(artifactId, slot, readerKey)),
+        async replace({ artifactId, slot, readerKey, entryId, value }) {
+            const e = docs.get(entryId);
+            if (!e || e.artifactId !== artifactId || e.slot !== slot || e.readerKey !== readerKey || e.shape !== 'many')
+                return null;
+            const next = { ...e, value: structuredClone(value) };
+            docs.set(entryId, next);
+            return structuredClone(next);
+        },
     };
 }

package/lib/artifacts/state.d.ts

@@ -1,9 +1,13 @@
 export type Shape = 'one' | 'many';
 export type Visibility = 'private' | 'tally' | 'shared';
 export type Writers = 'signed-in' | 'anyone';
+/** `writers` on a slot is never written by an author (parseStateConfig refuses it); a widget that
+ *  declares its own slot sets it, as `comments:` does, so one page can take comments from anyone
+ *  and votes only from signed-in readers. Absent means the page's `writers`. */
 export type SlotDef = {
     shape: Shape;
     visibility?: Visibility;
+    writers?: Writers;
 };
 export type StateConfig = {
     writers: Writers;
@@ -27,8 +31,9 @@ export declare function parseStateConfig(raw: unknown): {
     ok: false;
     error: string;
 };
-/** A gated page's readers are always signed in, so its state is too, whatever the file says. */
-export declare function effectiveWriters(state: StateConfig, access?: string): Writers;
+/** A gated page's readers are always signed in, so its state is too, whatever the file says.
+ *  With a slot named, that slot's own writers (when it declares any) stand in for the page's. */
+export declare function effectiveWriters(state: StateConfig, access?: string, slot?: string): Writers;
 export declare function slotVisibility(state: StateConfig, slot: string): Visibility;
 export declare function checkValue(value: unknown): string | null;
 /** Answers are kept across a republish, so a slot may never change what shape its data is. */

package/lib/artifacts/state.js

@@ -42,9 +42,13 @@ export function parseStateConfig(raw) {
     }
     return { ok: true, state: { writers, visibility: visibility, slots } };
 }
-/** A gated page's readers are always signed in, so its state is too, whatever the file says. */
-export function effectiveWriters(state, access) {
-    return access ? 'signed-in' : state.writers;
+/** A gated page's readers are always signed in, so its state is too, whatever the file says.
+ *  With a slot named, that slot's own writers (when it declares any) stand in for the page's. */
+export function effectiveWriters(state, access, slot) {
+    if (access)
+        return 'signed-in';
+    const def = slot !== undefined && Object.hasOwn(state.slots, slot) ? state.slots[slot] : undefined;
+    return def?.writers ?? state.writers;
 }
 export function slotVisibility(state, slot) {
     return state.slots[slot]?.visibility ?? state.visibility;

package/lib/artifacts/store.d.ts

@@ -4,6 +4,7 @@ import type { Access } from './reader.js';
 import type { StateConfig } from './state.js';
 import type { ThemeMode } from '../brand/theme.js';
 import type { Definition } from './definitions.js';
+import type { CommentsMode, CommentsVisible } from './comments.js';
 export type ArtifactRecord = {
     id: string;
     title: string;
@@ -22,6 +23,9 @@ export type ArtifactRecord = {
     theme?: ThemeMode;
     toc?: boolean;
     definitions?: Definition[];
+    /** Who may leave shared comments; absent is off. Personal notes need nothing. */
+    comments?: CommentsMode;
+    commentsVisible?: CommentsVisible;
     markdown: string;
     createdAt: string;
     updatedAt: string;

package/lib/artifacts/store.js

@@ -135,6 +135,8 @@ async function saveArtifact(col, input) {
         ...(input.meta.theme ? { theme: input.meta.theme } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
+        ...(input.meta.comments ? { comments: input.meta.comments } : {}),
+        ...(input.meta.commentsVisible ? { commentsVisible: input.meta.commentsVisible } : {}),
     };
     if (input.id) {
         const existing = await getArtifact(col, input.id);
@@ -178,6 +180,10 @@ async function saveArtifact(col, input) {
             ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
             ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
+            // Comments are not an access control, so a line the file no longer carries goes back to
+            // off / owner. The comments already left are kept, like every answer.
+            ...(input.meta.comments ? {} : { comments: FieldValue.delete() }),
+            ...(input.meta.commentsVisible ? {} : { commentsVisible: FieldValue.delete() }),
         };
         await ref.update({
             ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, version: next,

package/lib/artifacts/widgets.d.ts

@@ -36,3 +36,7 @@ export declare function hasNotesWidget(markdown: string): boolean;
 /** The server's check on a note, on a page with a notes block. The browser checks too; this is
  *  the one that counts. */
 export declare function checkNoteValue(v: unknown): string | null;
+/** The stable id of every top-level block, by the offset it starts at in the markdown. The
+ *  renderer puts it on the block as `data-block`, and a region comment is pinned to it. Blocks
+ *  that draw no prose (a notes or links fence, a rule, raw html) get none. */
+export declare function blocksOf(markdown: string): Map<number, string>;

package/lib/artifacts/widgets.js

@@ -12,6 +12,7 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
+import { blockId } from './anchor.js';
 import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
 export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes } from './notes-place.js';
 /** Widgets the design names and this version does not draw yet. A fence using one is refused at
@@ -139,3 +140,72 @@ export function checkNoteValue(v) {
         return `a note is at most ${MAX_NOTE_CHARS} characters`;
     return null;
 }
+function plain(n) {
+    if ('value' in n && typeof n.value === 'string')
+        return n.value;
+    if (n.type === 'image')
+        return n.alt ?? '';
+    if ('children' in n)
+        return n.children.map(plain).join(n.type === 'list' || n.type === 'table' || n.type === 'tableRow' ? '\n' : '');
+    return '';
+}
+/** An image's asset name without the host's content digest (`chart.0a1b2c3d.png` is `chart.png`),
+ *  so replacing the file under the same name keeps the comments drawn on it. */
+function assetName(url) {
+    const base = url.split(/[?#]/)[0].split('/').pop() ?? url;
+    return base.replace(/\.[0-9a-f]{8}(\.[^.]+)$/, '$1');
+}
+/** The stable id of every top-level block, by the offset it starts at in the markdown. The
+ *  renderer puts it on the block as `data-block`, and a region comment is pinned to it. Blocks
+ *  that draw no prose (a notes or links fence, a rule, raw html) get none. */
+export function blocksOf(markdown) {
+    const out = new Map();
+    const seen = new Map();
+    for (const n of parse(markdown).children) {
+        const at = n.position?.start.offset;
+        if (at === undefined)
+            continue;
+        let kind;
+        let content;
+        if (n.type === 'paragraph') {
+            const only = n.children.filter((c) => !(c.type === 'text' && !c.value.trim()));
+            if (only.length === 1 && only[0].type === 'image') {
+                kind = 'img';
+                content = assetName(only[0].url);
+            }
+            else {
+                kind = 'p';
+                content = plain(n);
+            }
+        }
+        else if (n.type === 'heading') {
+            kind = 'h';
+            content = plain(n);
+        }
+        else if (n.type === 'list') {
+            kind = n.ordered ? 'ol' : 'ul';
+            content = plain(n);
+        }
+        else if (n.type === 'table') {
+            kind = 'table';
+            content = plain(n);
+        }
+        else if (n.type === 'blockquote') {
+            kind = 'quote';
+            content = plain(n);
+        }
+        else if (n.type === 'code') {
+            if (n.lang === 'links' || n.lang === NOTES_SLOT)
+                continue;
+            kind = 'code';
+            content = n.value;
+        }
+        else
+            continue;
+        const k = `${kind}\n${content}`;
+        const i = seen.get(k) ?? 0;
+        seen.set(k, i + 1);
+        out.set(at, blockId(kind, i, content));
+    }
+    return out;
+}

package/lib/reader/comment-card.d.ts

@@ -0,0 +1,18 @@
+import { type CommentsMode } from '../artifacts/comments.js';
+/** The warning, word for word. `They` is fixed copy: the card never guesses a pronoun. */
+export declare function warningLine(ownerName: string, mode: CommentsMode): string;
+export declare const DEVICE_LINE = "Saved on this device. Sign in to keep it everywhere.";
+export declare function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial, accent, signIn, onSave, onCancel, }: {
+    ownerName: string;
+    mode: CommentsMode;
+    canShare: boolean;
+    signedIn: boolean;
+    /** The quoted text the comment is pinned to, shown above the box. */
+    quote?: string;
+    initial?: string;
+    accent?: string;
+    signIn?: string | null;
+    /** Resolves to an error to show, or null when saved. */
+    onSave: (body: string, share: boolean) => Promise<string | null>;
+    onCancel: () => void;
+}): import("react").JSX.Element;

package/lib/reader/comment-card.js

@@ -0,0 +1,36 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The card a comment is written in. It says, before anything is typed, who will read it: when the
+// reader cannot share, the first line in the card is the warning that this is a personal note the
+// owner will never see, shown every time, because the moment it matters is the moment someone is
+// about to write something they meant for the owner. When they can share, a switch picks Share
+// (the default) or Just for me.
+import { useState } from 'react';
+import { MAX_COMMENT_CHARS } from '../artifacts/comments.js';
+/** The warning, word for word. `They` is fixed copy: the card never guesses a pronoun. */
+export function warningLine(ownerName, mode) {
+    const why = mode === 'off'
+        ? `${ownerName} has not opened this page to comments`
+        : `${ownerName} takes comments on this page from signed-in readers`;
+    return `Only you will see this. ${why}, so this is a personal note. They won't see it.`;
+}
+export const DEVICE_LINE = 'Saved on this device. Sign in to keep it everywhere.';
+export function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial = '', accent = 'currentColor', signIn, onSave, onCancel, }) {
+    const [text, setText] = useState(initial);
+    const [share, setShare] = useState(canShare);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const personal = !canShare || !share;
+    const submit = async (e) => {
+        e?.preventDefault();
+        const body = text.trim();
+        if (!body || busy)
+            return;
+        setBusy(true);
+        const err = await onSave(body, canShare && share);
+        setBusy(false);
+        setError(err);
+    };
+    return (_jsxs("form", { "data-comment-card": true, "data-comment-ui": true, "data-nospeak": true, onSubmit: submit, className: "w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-left font-sans text-sm text-[color:var(--a-strong)] shadow-xl", children: [!canShare ? (_jsx("p", { "data-comment-warning": true, role: "note", className: "mb-2 rounded-lg border px-3 py-2 text-[13px] leading-snug", style: { borderColor: accent }, children: warningLine(ownerName, mode) })) : null, quote ? _jsx("p", { className: "mb-2 line-clamp-3 border-l-2 pl-2 text-[13px] italic opacity-75", style: { borderColor: accent }, children: quote }) : null, _jsx("textarea", { value: text, autoFocus: true, onChange: (e) => setText(e.target.value), onKeyDown: (e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey))
+                    void submit(); }, maxLength: MAX_COMMENT_CHARS, rows: 3, "aria-label": personal ? 'A personal note' : `A comment for ${ownerName}`, placeholder: personal ? 'A note for yourself' : `A comment for ${ownerName}`, className: "w-full rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-ground,transparent)] p-2 text-[15px]" }), canShare ? (_jsxs("fieldset", { className: "mt-2 flex flex-wrap gap-x-4 gap-y-1 text-[13px]", children: [_jsx("legend", { className: "sr-only", children: "Who sees this" }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "share", checked: share, onChange: () => setShare(true) }), `Share with ${ownerName}`] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "mine", checked: !share, onChange: () => setShare(false) }), "Just for me"] })] })) : null, personal && !signedIn ? (_jsx("p", { "data-comment-device": true, className: "mt-2 text-xs opacity-70", children: signIn ? _jsxs(_Fragment, { children: ["Saved on this device. ", _jsx("a", { href: signIn, className: "underline", children: "Sign in to keep it everywhere." })] }) : DEVICE_LINE })) : null, error ? _jsx("p", { role: "alert", className: "mt-2 text-xs text-amber-500", children: error }) : null, _jsxs("div", { className: "mt-3 flex items-center gap-3", children: [_jsx("button", { type: "submit", "data-comment-save": true, disabled: busy || !text.trim(), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: accent, color: 'var(--a-on-accent, #111)' }, children: personal ? 'Save note' : 'Comment' }), _jsx("button", { type: "button", onClick: onCancel, className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
+}

package/lib/reader/comment-layer.d.ts

@@ -0,0 +1,17 @@
+import { type CommentsMode } from '../artifacts/comments.js';
+export declare function CommentLayer({ artifactId, rootId, ownerName, comments, canShare, signedIn, isOwner, version, accent, ground, signIn, }: {
+    artifactId: string;
+    /** The element holding the page's prose, the same root the read-aloud lights. */
+    rootId: string;
+    ownerName: string;
+    comments: CommentsMode;
+    /** This reader may leave shared comments here (comments: is on, and they are signed in where it asks). */
+    canShare: boolean;
+    signedIn: boolean;
+    isOwner: boolean;
+    /** The version being read, stored on every comment left on it. */
+    version: number;
+    accent: string;
+    ground: string;
+    signIn?: string | null;
+}): import("react").JSX.Element;