@supersuit/artifacts 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 `@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.8.0 (2026-09-27)
+
+**Pages play audio clips.** `![caption](clip.mp3)` renders a captioned player with native
+controls, the way `![alt](x.mp4)` already renders a video. An annotated conversation, a voice
+note, or a quote meant to be heard can now sit in the prose it belongs to, instead of on a
+second page or a download link. mp3 was already an accepted asset type; nothing rendered it.
+
+- `preload="none"`, never `autoplay`: a page of twenty clips fetches nothing until one is pressed.
+- The alt is the clip's caption, shown above the player and escaped as text.
+- DETECTOR: a page with an `.mp3` in image syntax that renders a broken image.
+- REMEDY: bump; republishing is not needed, the markdown is rendered on request.
+- Tests: `render.test.tsx` pins the audio element, its attributes, the caption and the escaping.
+
+## 0.7.1 (2026-09-27)
+
+**The narrator reads the subtitle.** `narrationText` built the spoken text from the title, the
+summary and the body, while the page renders a `subtitle:` between the title and the summary with
+no `data-nospeak`. So the audio skipped the page's first line under the title, and the highlighter
+expected words the narration never said.
+
+- `narrationText` takes an optional `subtitle` and reads it second; the narration-text route
+  passes it.
+- DETECTOR: a page with a `subtitle:` whose audio goes straight from the title to the summary.
+- REMEDY: bump, then republish the page so its narration is regenerated (the spoken text changed,
+  so the narration hash no longer matches and the publisher re-narrates).
+- Tests: `narration.test.ts` pins title, subtitle, summary, body order.
+
 ## 0.7.0 (2026-09-27)
 
 **A real version history: every page names its version, lists every version with its change note,

package/lib/artifacts/narration.d.ts

@@ -1,6 +1,7 @@
 export declare function narrationTextFromMarkdown(markdown: string): string;
 export declare function narrationText(input: {
     title: string;
+    subtitle?: string;
     summary: string;
     markdown: string;
 }): string;

package/lib/artifacts/narration.js

@@ -76,8 +76,12 @@ export function narrationTextFromMarkdown(markdown) {
     blocks(tree.children, out);
     return clean(out);
 }
+// The subtitle renders between the title and the summary with no data-nospeak, so the
+// highlighter expects it there; leaving it out made the narrator skip the page's first line.
 export function narrationText(input) {
-    return [input.title.trim(), input.summary.trim(), narrationTextFromMarkdown(input.markdown)].filter(Boolean).join('\n');
+    return [input.title.trim(), (input.subtitle ?? '').trim(), input.summary.trim(), narrationTextFromMarkdown(input.markdown)]
+        .filter(Boolean)
+        .join('\n');
 }
 /** Tokens the highlighter and the timings agree on: whitespace-split, lowercased, letters and digits only. */
 export function normalizeWord(w) {

package/lib/artifacts/render.js

@@ -52,6 +52,10 @@ export function isReachableHref(href) {
  *  is decoded frame by frame on the CPU and stuttered on an iPhone at 24fps (2026-09-27); video
  *  is decoded in hardware. */
 const VIDEO = /\.mp4(?:[?#].*)?$/i;
+/** `![caption](x.mp3)` is a clip the reader plays: an annotated conversation, a voice note, a
+ *  quote heard rather than read. Native controls, and `preload="none"` so a page of clips fetches
+ *  nothing until one is pressed. The alt is its caption, shown above the player. */
+const AUDIO = /\.mp3(?:[?#].*)?$/i;
 const VIDEO_IN_MD = /\]\([^)\s]+\.mp4(?:[?#][^)]*)?\)/i;
 const escapeAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 // Written as markup, not JSX: React renders `muted` as a property and leaves it out of server
@@ -62,6 +66,10 @@ function InlineVideo({ src, label }) {
     const html = `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-video muted loop playsinline preload="metadata" disablepictureinpicture class="block w-full"></video>`;
     return _jsx("span", { className: "my-6 block overflow-hidden rounded-lg border border-[color:var(--a-line)]", dangerouslySetInnerHTML: { __html: html } });
 }
+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 }),
@@ -70,7 +78,7 @@ const components = {
     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 ?? '' })) : (
+    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] })),

package/lib/routes/artifacts.js

@@ -391,7 +391,7 @@ export function createArtifactRoutes(config) {
         const a = await store.get(id);
         if (!a)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        return NextResponse.json({ id, text: narrationText({ title: a.title, summary: a.summary, markdown: a.markdown }) });
+        return NextResponse.json({ id, text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }) });
     }
     /** PUT /api/artifacts/<id>/assets/<name>: raw bytes in, public URL out. 16 MiB cap. */
     async function PUT_ASSET(request, { params }) {

package/package.json

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