@supersuit/artifacts 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 `@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.28.0
+
+**A link to a comment opens for the page's admins, and says so when it cannot.** On an owner-only
+page (`comments_visible: owner`, the default) the state API showed every comment to exactly one
+person, `ownerEmail`. An admin opening a comment's link (the link in every comment notification)
+got the page with nothing to scroll to, and nothing said why.
+
+- `StateRoutesContext.admins` (passed from `ArtifactRoutesConfig.admins`, which version history
+  already used): admins, like the owner, read every comment with names and see the owner panel.
+- The owner's view names an anonymous commenter by the name they declared (0.24.0's `by`),
+  where it said "a reader".
+- A `#comment-<id>` link to a comment this reader cannot see now shows a closable line: "That
+  comment can't be shown to you. Comments on this page are visible to its owner and admins", with
+  "sign in if that is you" when signed out. It used to do nothing.
+- DETECTOR: as an admin who is not `ownerEmail`, open a comment notification's link on an
+  owner-only page. No pin and no thread means 0.27.0 or earlier.
+- REMEDY: update the dependency; a host that sets `admins` needs no other change.
+- Tests: `comments.test.tsx` (an admin sees every comment with names; the owner sees a declared
+  name), `comment-layer.test.tsx` (an unseeable link says so). `test:packed` green.
+
+## 0.27.0
+
+**A page can play a Messages-app phone of real threads inline: the ```messages block.** The
+second embedded player after ```simulator, so both now run through one embed mechanism.
+
+```messages
+chat: fritz            # optional: open on one chat; without it the chat list
+caption: Fritz, in his own words.
+height: 760px          # optional, default 760px
+```
+
+- The HOST names the player: new `ArtifactRoutesConfig.messagesEmbed` (an https embed page). The
+  block draws as a lazy frame on `<embed>?chat=<id>`, with the caption under it; a host without it
+  draws the caption alone, never the block as code. Malformed blocks are refused at publish.
+- `simulator` and `messages` share `parseEmbedFence` and `embedSrc` (new exports, with
+  `EMBED_KINDS`, `EmbedBlock`, `EmbedKind`); `parseSimulatorFence` and `simulatorSrc` keep working.
+  `ArtifactMarkdown` takes `messages?: { embed }`.
+- DETECTOR: a page with a ```messages block showing `chat:` as code means 0.26.0 or earlier, or no
+  `messagesEmbed`.
+- REMEDY: update the dependency and set `messagesEmbed`.
+- Tests: `simulator.test.ts` (messages parse, optional chat, refusals, src with and without a chat),
+  `render.test.tsx`, `widgets.test.ts`. `test:packed` green.
+
 ## 0.26.0
 
 **Read-along that leaves the reader in charge.** A tap on any word started the audio, and while it

package/lib/artifacts/index.d.ts

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
 export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc, type SimulatorBlock } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment, type CommentsMode, type CommentsVisible, type CommentValue } from './comments.js';

package/lib/artifacts/index.js

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment } from './comments.js';

package/lib/artifacts/render.d.ts

@@ -14,7 +14,7 @@ export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps>
 export declare function sectionOutline(markdown: string, headings?: Heading[]): SectionOutline[];
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, }: {
+export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, messages, }: {
     markdown: string;
     /** The page a ```checklist keeps its ticks under, and whether its Send can reach the owner
      *  (a host that keeps answers, on a page that declares the slot). On a page whose checklists
@@ -38,5 +38,7 @@ export declare function ArtifactMarkdown({ markdown, notes, checklist, definitio
     definitions?: Definition[];
     /** The host's Supersuit Session demo, for ```simulator blocks. Without it a block shows its caption only. */
     simulator?: SimulatorCtx;
+    /** The host's Messages phone, for ```messages blocks. Without it a block shows its caption only. */
+    messages?: SimulatorCtx;
 }): import("react").JSX.Element;
 export {};

package/lib/artifacts/render.js

@@ -16,7 +16,7 @@ import { unified } from 'unified';
 import { blocksOf, checklistSyncs, checklistsOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { Checklist } from '../widgets/checklist.js';
-import { parseSimulatorFence, simulatorSrc } from './simulator.js';
+import { embedSrc, parseEmbedFence } from './simulator.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -95,14 +95,15 @@ 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 } })] }));
 }
-/** A ```simulator block: the demo in a frame when the host has one, its caption alone when it does
- *  not, and nothing when the block does not parse (a page published before validation existed). */
-function SimulatorFence({ source, ctx }) {
-    const r = parseSimulatorFence(source.replace(/\n$/, ''), 0);
+/** An embed block (```simulator, ```messages): the player in a frame when the host names one, its
+ *  caption alone when it does not, and nothing when the block does not parse (a page published
+ *  before validation existed). */
+function EmbedFence({ kind, source, ctx }) {
+    const r = parseEmbedFence(kind, source.replace(/\n$/, ''), 0);
     if (!r.ok)
         return null;
-    const src = ctx ? simulatorSrc(ctx.embed, r.block.scenario) : null;
-    return (_jsxs("figure", { "data-artifact-simulator": true, className: "my-8", children: [src ? (_jsx("iframe", { src: src, title: r.block.caption, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: r.block.height, border: 0 } })) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
+    const src = ctx ? embedSrc(kind, ctx.embed, r.block.value) : null;
+    return (_jsxs("figure", { "data-artifact-embed": kind, ...(kind === 'simulator' ? { 'data-artifact-simulator': '' } : {}), className: "my-8", children: [src ? (_jsx("iframe", { src: src, title: r.block.caption, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: r.block.height, border: 0 } })) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
 }
 /** The one image a paragraph holds and nothing else (whitespace aside), or null. */
 function soleImage(node) {
@@ -132,7 +133,7 @@ function ChecklistFence({ line, ctx }) {
         return null;
     return (_jsx(Checklist, { items: c.items.map((it) => ({ id: it.id, title: checklistMarkdown(it.text, true), description: it.description ? checklistMarkdown(it.description, false) : null })), artifactId: ctx.artifactId, send: ctx.send && ctx.artifactId && !ctx.sync ? c.send : undefined, sync: ctx.sync && !!ctx.artifactId, owner: ctx.owner, accent: ctx.accent }));
 }
-function baseComponents(block, figure, checklists, simulator) {
+function baseComponents(block, figure, checklists, embeds) {
     return {
         p: ({ node, children }) => {
             // An image alone in its paragraph that the pack draws itself replaces the paragraph, so the
@@ -172,8 +173,8 @@ function baseComponents(block, figure, checklists, simulator) {
             // answers) it draws nothing: its settings are not prose and never shown as code.
             if (lang === 'notes')
                 return null;
-            if (lang === 'simulator')
-                return _jsx(SimulatorFence, { source: textOf(children), ctx: simulator });
+            if (lang === 'simulator' || lang === 'messages')
+                return _jsx(EmbedFence, { kind: lang, source: textOf(children), ctx: embeds?.[lang] });
             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 });
             }
@@ -183,7 +184,7 @@ function baseComponents(block, figure, checklists, simulator) {
             // 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|checklist|simulator)/.test(cls))
+            if (/language-(links|notes|checklist|simulator|messages)/.test(cls))
                 return _jsx(_Fragment, { children: children });
             return (_jsx("pre", { ...block(node), "data-artifact-code": true, 
                 // whitespace-pre-wrap, because a fence here usually holds PROSE meant to be pasted
@@ -216,20 +217,20 @@ 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, block, figure, checklists, simulator) {
+function pageComponents(headings, block, figure, checklists, embeds) {
     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, ...block(node), className: HEADING_CLASS[depth], children: children });
     };
-    return { ...baseComponents(block, figure, checklists, simulator), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block, figure, checklists, embeds), 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, block, figure, checklists, simulator) {
-    const components = baseComponents(block, figure, checklists, simulator);
+function notesComponents(headings, block, figure, checklists, embeds) {
+    const components = baseComponents(block, figure, checklists, embeds);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
@@ -308,8 +309,9 @@ const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;
     'clip:rect(0,0,0,0);white-space:nowrap;border:0}';
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, }) {
+export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, messages, }) {
     const on = !!notes && hasNotesWidget(markdown);
+    const embeds = { simulator, messages };
     const headings = headingsOf(markdown);
     const blocks = blocksOf(markdown);
     const block = (node) => {
@@ -325,7 +327,7 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
         // page whose checklists sync, that same slot is the shared set, so it turns sync on instead.
         ? { byLine: lists, artifactId: checklist?.artifactId, send: !!checklist?.send, sync: !!checklist?.send && checklistSyncs(lists.values()), owner: checklist?.owner, accent: checklist?.accent }
         : undefined;
-    const components = on ? notesComponents(headings, block, figure, checklists, simulator) : pageComponents(headings, block, figure, checklists, simulator);
+    const components = on ? notesComponents(headings, block, figure, checklists, embeds) : pageComponents(headings, block, figure, checklists, embeds);
     if (outline.length)
         components.section = sectionComponent(Section, outline, block);
     const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, urlTransform: artifactUrlTransform, children: markdown }));

package/lib/artifacts/simulator.d.ts

@@ -1,10 +1,29 @@
+export type EmbedKind = 'simulator' | 'messages';
+export declare const EMBED_KINDS: EmbedKind[];
+export declare const isEmbedKind: (k: unknown) => k is EmbedKind;
+export type EmbedBlock = {
+    value: string | null;
+    caption: string;
+    height: string;
+};
 export type SimulatorBlock = {
     scenario: string;
     caption: string;
     height: string;
 };
-/** Parses a simulator fence's body. `line` is the line the fence opens on, so every error names
- *  the line the author sees. */
+/** Parses an embed fence's body. `line` is the line the fence opens on, so every error names the
+ *  line the author sees. */
+export declare function parseEmbedFence(kind: EmbedKind, value: string, line: number): {
+    ok: true;
+    block: EmbedBlock;
+} | {
+    ok: false;
+    error: string;
+};
+/** The address a player loads: the host's embed page, what to open, any fixed switches. Null for an
+ *  embed address that is not https, so a misconfigured host frames nothing. */
+export declare function embedSrc(kind: EmbedKind, embed: string, value: string | null): string | null;
+/** The ```simulator block (kept for callers of 0.25.0). */
 export declare function parseSimulatorFence(value: string, line: number): {
     ok: true;
     block: SimulatorBlock;
@@ -12,6 +31,4 @@ export declare function parseSimulatorFence(value: string, line: number): {
     ok: false;
     error: string;
 };
-/** The address the player loads: the host's embed page, the scenario, the timeline off. Null for
- *  an embed address that is not https, so a misconfigured host frames nothing. */
-export declare function simulatorSrc(embed: string, scenario: string): string | null;
+export declare const simulatorSrc: (embed: string, scenario: string) => string | null;

package/lib/artifacts/simulator.js

@@ -1,21 +1,29 @@
-// The ```simulator fence: a Supersuit Session demo played inline on the page. The block names a
-// scenario and a caption; the HOST names the demo's embed page (ArtifactRoutesConfig.simulatorEmbed),
-// so this public package points at nobody's service by default, and a host without a demo draws
-// the caption alone rather than the block's source as code.
+// Embedded players: fenced blocks that play a host-named page inline, in a frame.
 //
-//   ```simulator
-//   scenario: diane-meeting-prep
-//   caption: Step into the hour before Diane's first meeting. Press Start.
-//   height: 760px            # optional, default 720px
-//   ```
+//   ```simulator                       ```messages
+//   scenario: diane-meeting-prep       chat: fritz          # optional: open on one chat
+//   caption: Step into the hour ...    caption: Fritz, in his own words.
+//   height: 760px      # optional      height: 760px        # optional, default 760px (simulator 720px)
+//   ```                                ```
 //
-// The same syntax the Superskills book's reader takes, so one block works in both.
-const SCENARIO = /^[a-z0-9-]+$/;
+// `simulator` is a Supersuit Session demo; `messages` is a Messages-app phone of real threads. The
+// block names what to open and a caption; the HOST names each player's embed page
+// (ArtifactRoutesConfig.simulatorEmbed / messagesEmbed), so this public package points at nobody's
+// service by default, and a host without the player draws the caption alone rather than the block's
+// source as code. `simulator` keeps the syntax the Superskills book's reader takes.
+const KINDS = {
+    simulator: { key: 'scenario', required: true, fixed: { timeline: 'off' }, height: '720px' },
+    messages: { key: 'chat', required: false, fixed: {}, height: '760px' },
+};
+export const EMBED_KINDS = Object.keys(KINDS);
+export const isEmbedKind = (k) => typeof k === 'string' && Object.hasOwn(KINDS, k);
+const ID = /^[a-z0-9-]+$/;
 const HEIGHT = /^\d{3,4}px$/;
-const KEYS = ['scenario', 'caption', 'height'];
-/** Parses a simulator fence's body. `line` is the line the fence opens on, so every error names
- *  the line the author sees. */
-export function parseSimulatorFence(value, line) {
+/** Parses an embed fence's body. `line` is the line the fence opens on, so every error names the
+ *  line the author sees. */
+export function parseEmbedFence(kind, value, line) {
+    const spec = KINDS[kind];
+    const keys = [spec.key, 'caption', 'height'];
     const got = {};
     const rows = value ? value.split('\n') : [];
     for (let i = 0; i < rows.length; i++) {
@@ -25,25 +33,25 @@ export function parseSimulatorFence(value, line) {
         const at = line + 1 + i;
         const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(raw);
         if (!m)
-            return { ok: false, error: `line ${at}: the simulator block takes lines like "scenario: <id>"` };
-        const key = m[1];
-        if (!KEYS.includes(key))
-            return { ok: false, error: `line ${at}: the simulator block has an unknown key: ${m[1]}` };
-        got[key] = { v: m[2].replace(/\s+#.*$/, '').trim(), at };
+            return { ok: false, error: `line ${at}: the ${kind} block takes lines like "${spec.key}: <id>"` };
+        if (!keys.includes(m[1]))
+            return { ok: false, error: `line ${at}: the ${kind} block has an unknown key: ${m[1]}` };
+        got[m[1]] = { v: m[2].replace(/\s+#.*$/, '').trim(), at };
     }
-    if (!got.scenario)
-        return { ok: false, error: `line ${line}: the simulator block needs a scenario` };
-    if (!SCENARIO.test(got.scenario.v))
-        return { ok: false, error: `line ${got.scenario.at}: a simulator scenario is lowercase letters, digits and dashes` };
+    const id = got[spec.key];
+    if (!id && spec.required)
+        return { ok: false, error: `line ${line}: the ${kind} block needs a ${spec.key}` };
+    if (id && !ID.test(id.v))
+        return { ok: false, error: `line ${id.at}: a ${kind} ${spec.key} is lowercase letters, digits and dashes` };
     if (!got.caption?.v)
-        return { ok: false, error: `line ${line}: the simulator block needs a caption, the line a reader sees under the demo` };
+        return { ok: false, error: `line ${line}: the ${kind} block needs a caption, the line a reader sees under it` };
     if (got.height && !HEIGHT.test(got.height.v))
-        return { ok: false, error: `line ${got.height.at}: a simulator height is a number of pixels, like 760px` };
-    return { ok: true, block: { scenario: got.scenario.v, caption: got.caption.v, height: got.height?.v ?? '720px' } };
+        return { ok: false, error: `line ${got.height.at}: a ${kind} height is a number of pixels, like 760px` };
+    return { ok: true, block: { value: id?.v ?? null, caption: got.caption.v, height: got.height?.v ?? spec.height } };
 }
-/** The address the player loads: the host's embed page, the scenario, the timeline off. Null for
- *  an embed address that is not https, so a misconfigured host frames nothing. */
-export function simulatorSrc(embed, scenario) {
+/** The address a player loads: the host's embed page, what to open, any fixed switches. Null for an
+ *  embed address that is not https, so a misconfigured host frames nothing. */
+export function embedSrc(kind, embed, value) {
     let u;
     try {
         u = new URL(embed);
@@ -53,7 +61,16 @@ export function simulatorSrc(embed, scenario) {
     }
     if (u.protocol !== 'https:')
         return null;
-    u.searchParams.set('scenario', scenario);
-    u.searchParams.set('timeline', 'off');
+    const spec = KINDS[kind];
+    if (value)
+        u.searchParams.set(spec.key, value);
+    for (const [k, v] of Object.entries(spec.fixed))
+        u.searchParams.set(k, v);
     return u.toString();
 }
+/** The ```simulator block (kept for callers of 0.25.0). */
+export function parseSimulatorFence(value, line) {
+    const r = parseEmbedFence('simulator', value, line);
+    return r.ok ? { ok: true, block: { scenario: r.block.value, caption: r.block.caption, height: r.block.height } } : r;
+}
+export const simulatorSrc = (embed, scenario) => embedSrc('simulator', embed, scenario);

package/lib/artifacts/widgets.js

@@ -16,7 +16,7 @@ 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';
-import { parseSimulatorFence } from './simulator.js';
+import { isEmbedKind, parseEmbedFence } from './simulator.js';
 import { CHECKLIST_SLOT, assignChecklistIds, parseChecklistFence } from './checklist.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
@@ -102,9 +102,9 @@ export function scanWidgets(body, offset) {
         notes = w;
     }
     for (const f of fences) {
-        if (f.lang !== 'simulator')
+        if (!isEmbedKind(f.lang))
             continue;
-        const r = parseSimulatorFence(f.value, (f.position?.start.line ?? 1) + offset);
+        const r = parseEmbedFence(f.lang, f.value, (f.position?.start.line ?? 1) + offset);
         if (!r.ok)
             return r;
     }

package/lib/reader/comment-layer.js

@@ -1,5 +1,5 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 // Comments on any part of a page, Figma style. Select text and a "Comment" chip appears; hold and
 // drag over anything that is not text (an image, a table, the gap between paragraphs) and a box
 // draws. Either opens the card (comment-card.tsx), which says before anything is typed whether
@@ -85,6 +85,9 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const personalUrl = `/api/artifacts/${artifactId}/personal`;
     const [mounted, setMounted] = useState(false);
     const [shared, setShared] = useState([]);
+    // Whether the shared comments have arrived, so a link to one this reader cannot see can say so.
+    const [loaded, setLoaded] = useState(false);
+    const [missing, setMissing] = useState(false);
     const [serverNotes, setServerNotes] = useState([]);
     const [device, setDevice] = useState([]);
     const [onServer, setOnServer] = useState(signedIn);
@@ -124,9 +127,12 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
         refreshDevice();
         let live = true;
         if (comments !== 'off') {
-            void call(stateUrl).then((r) => { if (live && r.status === 200)
-                setShared(sharedFrom(r.body)); });
+            void call(stateUrl).then((r) => { if (!live)
+                return; if (r.status === 200)
+                setShared(sharedFrom(r.body)); setLoaded(true); });
         }
+        else
+            setLoaded(true);
         if (signedIn) {
             void (async () => {
                 const r = await call(personalUrl);
@@ -343,14 +349,20 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
         // `tick` re-measures after a resize.
     }, [mounted, rootId, tops, tick]); // eslint-disable-line react-hooks/exhaustive-deps
     // Show the comment the address names once it has loaded: a reply is shown in its parent's thread.
-    // Held until the comments arrive; an id that never arrives (deleted, or not this reader's to see)
-    // simply does nothing.
+    // Held until the comments arrive; an id that is not among them (deleted, or not this reader's to
+    // see) says so in a line, rather than leaving the reader wondering why nothing happened.
     useEffect(() => {
         if (!target || !mounted)
             return;
         const item = items.find((i) => i.id === target);
-        if (!item)
+        if (!item) {
+            if (loaded) {
+                setMissing(true);
+                setTarget(null);
+            }
             return;
+        }
+        setMissing(false);
         const parent = item.value.parent ? items.find((i) => i.id === item.value.parent) : undefined;
         const id = (parent ?? item).id;
         setTarget(null);
@@ -365,7 +377,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
             setHighlight(id);
             setScrollTo(`[data-comment-earlier-id="${id}"]`);
         }
-    }, [target, mounted, items, layout]);
+    }, [target, mounted, items, layout, loaded]);
     // Effects run after the DOM is committed, so the pin or list item drawn for the target is there.
     useEffect(() => {
         if (!scrollTo)
@@ -468,7 +480,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const open = layout.placed.find((p) => p.item.id === thread);
     const openItem = open?.item ?? layout.earlier.find((i) => i.id === thread);
     const count = tops.length;
-    const overlay = mounted ? (_jsxs("div", { "data-comment-ui": true, "data-nospeak": true, className: "font-sans", style: theme, children: [showPins ? layout.placed.map(({ item, left, top, box }) => (_jsxs("div", { children: [box ? (_jsx("div", { "data-comment-box": item.id, "aria-hidden": true, className: "pointer-events-none absolute z-30 rounded-md border-2", style: { left: box.left, top: box.top, width: box.width, height: box.height, borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid', opacity: thread === item.id ? 1 : 0.55 } })) : null, _jsx(Pin, { item: item, left: left, top: top, accent: accent, ground: ground, onOpen: () => setThread(thread === item.id ? null : item.id) })] }, item.id))) : null, chip && !draft ? (
+    const overlay = mounted ? (_jsxs("div", { "data-comment-ui": true, "data-nospeak": true, className: "font-sans", style: theme, children: [missing ? (_jsxs("div", { "data-comment-missing": true, role: "status", className: "fixed left-1/2 top-4 z-50 flex -translate-x-1/2 items-center gap-2 rounded-full border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] px-4 py-2 text-sm text-[color:var(--a-strong)] shadow-lg", children: [_jsxs("span", { children: ["That comment can't be shown to you. Comments on this page are visible to its owner and admins", signedIn ? '' : '; sign in if that is you', "."] }), _jsx("button", { type: "button", "aria-label": "Close", onClick: () => setMissing(false), className: "opacity-70", children: "\u00D7" })] })) : null, showPins ? layout.placed.map(({ item, left, top, box }) => (_jsxs("div", { children: [box ? (_jsx("div", { "data-comment-box": item.id, "aria-hidden": true, className: "pointer-events-none absolute z-30 rounded-md border-2", style: { left: box.left, top: box.top, width: box.width, height: box.height, borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid', opacity: thread === item.id ? 1 : 0.55 } })) : null, _jsx(Pin, { item: item, left: left, top: top, accent: accent, ground: ground, onOpen: () => setThread(thread === item.id ? null : item.id) })] }, item.id))) : null, chip && !draft ? (
             // On a phone the button sits at the TOP of the screen, never beside the selection: that is
             // where iOS draws its own Copy / Look Up menu, and the two fought for the same tap (Gary,
             // 2026-09-29: "I keep trying to fight with the Apple pop-up"). A mouse keeps it by the text.

package/lib/routes/artifacts.d.ts

@@ -31,6 +31,9 @@ export type ArtifactRoutesConfig = {
      *  https://example.com/simulator/embed), for ```simulator blocks. Without it a block shows its
      *  caption only. No default: this package points at nobody's service. */
     simulatorEmbed?: string;
+    /** The embed page of this host's Messages phone (an https URL), for ```messages blocks: a
+     *  `chat=<id>` opens one thread. Without it a block shows its caption only. No default. */
+    messagesEmbed?: string;
     /** Read at request time, so a rotated key needs no rebuild. */
     publishKey: () => string | undefined;
     /** Verifies publisher passes (`p1`, see artifacts/publisher.ts): a signed, hour-long stand-in

package/lib/routes/artifacts.js

@@ -78,7 +78,7 @@ export function createArtifactRoutes(config) {
     const stateRoutes = createStateRoutes({
         store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey,
         publisherSecret: config.publisherSecret, publisherHost: config.publisherHost, pageUrl, signInOrigin, siteUrl,
-        clientIp: config.clientIp, ownerEmail: config.ownerEmail, audioUrl,
+        clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({
@@ -303,7 +303,7 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader }) {
@@ -328,8 +328,8 @@ export function createArtifactRoutes(config) {
                         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, 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: [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, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined }) }));
-                    })() }), _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: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                                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, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));
+                    })() }), _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: !!reader && ((!!ownerEmail && reader.email.trim().toLowerCase() === ownerEmail.trim().toLowerCase()) || (config.admins ?? []).some((e) => e.trim().toLowerCase() === reader.email.trim().toLowerCase())), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), 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. */] }));
     }

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

@@ -33,6 +33,9 @@ export type StateRoutesContext = {
     /** The page owner's sign-in email. Signed in as them, a page's comments show every entry with
      *  full names, whatever `comments_visible:` says. */
     ownerEmail?: string;
+    /** The page's admins' sign-in emails. Like the owner they read every comment with names, so a
+     *  link to any comment opens for them. */
+    admins?: readonly string[];
     /** A signed URL to play a comment's recording. Called only for `comments/` paths, and only for
      *  comments the asker is already being shown. Without it a recording has no play control. */
     audioUrl?: (id: string, path: string) => Promise<string>;

package/lib/routes/state-routes.js

@@ -84,7 +84,10 @@ export function createStateRoutes(ctx) {
         return { a, reader, anonId, signIn };
     }
     const ownerEmail = ctx.ownerEmail?.trim().toLowerCase();
-    const isOwner = (r) => !!r && !!ownerEmail && r.email === ownerEmail;
+    const admins = new Set((ctx.admins ?? []).map((e) => e.trim().toLowerCase()));
+    // The owner and the page's admins read every comment, with names.
+    const isOwner = (r) => !!r && ((!!ownerEmail && r.email.trim().toLowerCase() === ownerEmail) || admins.has(r.email.trim().toLowerCase()));
+    const declared = (v) => { const by = v?.by; return typeof by === 'string' && by.trim() ? by.trim() : null; };
     /** Comments are on for this page: the slot exists because `comments:` put it there. */
     const commentsOn = (a) => !!a.comments && a.comments !== 'off' && Object.hasOwn(a.state.slots, COMMENTS_SLOT);
     const writerFor = (r) => ({ key: readerKeyFor.signedIn(r.uid), uid: r.uid, email: r.email, name: r.name, anonymous: false });
@@ -109,7 +112,7 @@ export function createStateRoutes(ctx) {
         if (owner && commentsOn(a)) {
             slots[COMMENTS_SLOT].shared = entries.filter((e) => e.slot === COMMENTS_SLOT)
                 .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id))
-                .map((e) => ({ id: e.id, name: e.writer.name?.trim() || 'a reader', value: e.value, at: e.at, mine: e.readerKey === readerKey }));
+                .map((e) => ({ id: e.id, name: e.writer.name?.trim() || declared(e.value) || 'a reader', value: e.value, at: e.at, mine: e.readerKey === readerKey }));
         }
         if (commentsOn(a) && slots[COMMENTS_SLOT]) {
             const v = slots[COMMENTS_SLOT];

package/package.json

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