@supersuit/artifacts 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 `@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

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.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({
@@ -329,7 +329,7 @@ export function createArtifactRoutes(config) {
                         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, 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 === 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,
+                    })() }), _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.27.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",