@supersuit/artifacts 0.4.6 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `@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.5.0 (2026-09-27)
+
+**Inline definitions: a page can define its jargon, and a reader sees it in line.**
+
+- New front matter key `definitions:`, a list of `Term | definition | optional link` (or a map).
+  The first occurrence of each term in the prose renders with a dotted underline; hover (desk) or
+  tap (phone) opens the definition, drawn by a new client component, `DefinitionLayer`, through a
+  portal on `document.body`, so nothing in the paragraph opens or closes and nothing reflows. The
+  store keeps the terms and a republish without the key removes them.
+- The read-along reader skips `<style>` and `<script>` text (it used to wrap any text node, which
+  would have turned an inline stylesheet into word spans) and a click on a defined term no longer
+  seeks. Its bar carries `data-artifact-player` so an overlay can sit above it.
+- Punctuation that continues a word across an element edge (`Edge` in a term, then `, which`;
+  `**bold**,`) is wrapped as a tail of that word rather than a word of its own, so the
+  highlighter's word sequence matches the narration's tokens. Found in WebKit, where a comma after
+  a defined term had become an extra, clickable word.
+- **DETECTOR:** a page with `definitions:` is refused as an unknown key before 0.5.0.
+- **REMEDY:** update the dependency; no host change. A publisher that filters keys must pass
+  `definitions` through.
+- **Tests:** parsing both shapes and refusals; first occurrence only, whole words, case rules and
+  every skipped context; the karaoke word spans are identical in number and order with and without
+  definitions and equal the narrated words; a tap on a defined word is not a seek; the definition
+  opens on `document.body` with the paragraph's markup unchanged, and closes on a second tap,
+  Escape or a tap elsewhere; the store round-trips and clears the key.
+
+## 0.4.7 (2026-09-27)
+
+**A page of videos opens as fast as a page of text.**
+
+- 0.4.6 marked every inline video `autoplay`, so all of them downloaded the moment the page opened
+  (21 diagrams, 6.8 MB, competing with the text and narration on a phone). The markup now carries
+  `preload="metadata"` and `data-artifact-video` instead, and a small client component,
+  `VideoAutoplay`, mounted only on pages that embed an `.mp4`, loads and plays each video as it
+  comes within a screen of view and pauses it when it leaves.
+- **DETECTOR:** a page with many inline videos is slow to become readable on cellular.
+- **REMEDY:** update the dependency; no host change.
+- **Tests:** the markup no longer autoplays and preloads only metadata; `VideoAutoplay` plays a
+  video only once it intersects, raises its preload, and pauses it when it leaves.
+
 ## 0.4.6 (2026-09-27)
 
 **Pages play video: `![alt](x.mp4)` is a silent, looping, autoplaying inline video.**

package/README.md

@@ -132,10 +132,32 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `access` | `freedom`, `invite` or `public`: a confidential page (below) |
 | `theme` | `light`, `dark` or `system` (follow the reader's device). Overrides the brand pack's mode for this page |
 | `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
+| `definitions` | Terms defined inline (below). A republish without it removes them |
 | `template` | `document`, the only one so far |
 
 An unknown key is refused, so a typo fails loudly instead of being ignored.
 
+## Inline definitions (`definitions:`)
+
+```yaml
+definitions:
+  - "Agentic Edge | The compounded context only you could have produced. | https://example.com/edge"
+  - "harness | The agent loop that reads, writes and runs on your behalf."
+```
+
+Each entry is `Term | definition | optional https link`; a map (`Term: definition`, or
+`Term: { text, href }`) is accepted too. The FIRST time each term appears in the prose it gets a
+dotted underline: hovering on a desk or tapping on a phone opens the definition, Escape or a tap
+elsewhere closes it. Matching is conservative: whole words, a capitalised term only as written, an
+all-lowercase term also at a sentence start, longest term first, and never inside a heading, a
+link, code, an image or a callout.
+
+The definition is drawn on `document.body`, outside the text, so opening it never reflows the
+page: a sheet at the bottom of a phone (above the narration bar), a box under the word on a desk.
+Screen readers get it as the term's accessible description. Read-aloud is unaffected: the spoken
+text comes from the markdown, the term's words stay ordinary words to the highlighter, and a tap
+on a defined word opens its definition instead of seeking.
+
 ## A page with a password
 
 `password: <string>` shuts the body behind a door. The title, summary and unfurl stay, so the

package/lib/artifacts/definitions.d.ts

@@ -0,0 +1,19 @@
+import type { Root } from 'mdast';
+export type Definition = {
+    term: string;
+    text: string;
+    href?: string;
+};
+/** `definitions:` as front matter carries it: a list of `Term | definition | optional link`
+ *  (the shape a Freedom workspace can write), or a map of term to definition, or to
+ *  `{ text, href }` (the shape any gray-matter publisher can write). */
+export declare function parseDefinitions(v: unknown): {
+    ok: true;
+    definitions: Definition[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function termId(term: string, i: number): string;
+/** The remark plugin: marks the first occurrence of each defined term. */
+export declare function remarkDefinitions(definitions: Definition[]): () => (tree: Root) => void;

package/lib/artifacts/definitions.js

@@ -0,0 +1,132 @@
+const LINK = /^https?:\/\//i;
+function entry(term, text, href) {
+    const t = typeof term === 'string' ? term.trim() : '';
+    const d = typeof text === 'string' ? text.trim() : '';
+    if (!t || !d)
+        return `definitions: "${t || String(term)}" needs "Term | definition"`;
+    const out = { term: t, text: d };
+    if (href !== undefined && href !== null && String(href).trim()) {
+        const h = String(href).trim();
+        if (!LINK.test(h))
+            return `definitions: the link for "${t}" must start with http:// or https://`;
+        out.href = h;
+    }
+    return out;
+}
+/** `definitions:` as front matter carries it: a list of `Term | definition | optional link`
+ *  (the shape a Freedom workspace can write), or a map of term to definition, or to
+ *  `{ text, href }` (the shape any gray-matter publisher can write). */
+export function parseDefinitions(v) {
+    const out = [];
+    const push = (e) => {
+        if (typeof e === 'string')
+            return e;
+        if (out.some((o) => o.term === e.term))
+            return `definitions: "${e.term}" is defined twice`;
+        out.push(e);
+        return null;
+    };
+    if (Array.isArray(v)) {
+        for (const item of v) {
+            if (typeof item !== 'string')
+                return { ok: false, error: 'definitions: each entry is a "Term | definition | optional link" string' };
+            const [term, text, href] = item.split('|');
+            const err = push(entry(term, text, href));
+            if (err)
+                return { ok: false, error: err };
+        }
+        return { ok: true, definitions: out };
+    }
+    if (v && typeof v === 'object') {
+        for (const [term, val] of Object.entries(v)) {
+            const e = val && typeof val === 'object' ? entry(term, val.text, val.href) : entry(term, val, undefined);
+            const err = push(e);
+            if (err)
+                return { ok: false, error: err };
+        }
+        return { ok: true, definitions: out };
+    }
+    return { ok: false, error: 'definitions: a list of "Term | definition | optional link" strings, or a map of term to definition' };
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** A term's matcher: whole word, case-aware. A term with any capital is a name and matches as
+ *  written; an all-lowercase term also matches with a capital first letter, at a sentence start. */
+function matcher(term) {
+    const body = escapeRe(term).replace(/\s+/g, '\\s+');
+    const lower = term === term.toLowerCase();
+    const first = term[0];
+    const head = lower && first.toUpperCase() !== first ? `[${escapeRe(first)}${escapeRe(first.toUpperCase())}]` + body.slice(escapeRe(first).length) : body;
+    return new RegExp(`(?<![\\p{L}\\p{N}])${head}(?![\\p{L}\\p{N}])`, 'u');
+}
+export function termId(term, i) {
+    return `artifact-def-${i}-${term.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-|-$/g, '')}`;
+}
+const SKIP = new Set(['heading', 'link', 'linkReference', 'inlineCode', 'code', 'image', 'imageReference', 'footnoteDefinition', 'html', 'definition']);
+const CALLOUT = /^\s*\[!(note|warning)\]/i;
+function firstText(n) {
+    if (n.type === 'text')
+        return n.value;
+    if ('children' in n && n.children.length)
+        return firstText(n.children[0]);
+    return '';
+}
+/** The remark plugin: marks the first occurrence of each defined term. */
+export function remarkDefinitions(definitions) {
+    return () => (tree) => {
+        const pending = definitions
+            .map((d, i) => ({ d, i, re: matcher(d.term) }))
+            .sort((a, b) => b.d.term.length - a.d.term.length);
+        const walk = (parent) => {
+            for (let k = 0; k < parent.children.length && pending.length; k++) {
+                const n = parent.children[k];
+                if (SKIP.has(n.type))
+                    continue;
+                if (n.type === 'blockquote' && CALLOUT.test(firstText(n)))
+                    continue;
+                if (n.type === 'text') {
+                    const hit = earliest(n.value);
+                    if (!hit)
+                        continue;
+                    const { at, len, p } = hit;
+                    pending.splice(pending.indexOf(p), 1);
+                    const id = termId(p.d.term, p.i);
+                    const before = { type: 'text', value: n.value.slice(0, at) };
+                    const after = { type: 'text', value: n.value.slice(at + len) };
+                    const mark = {
+                        type: 'definedTerm',
+                        data: {
+                            hName: 'span',
+                            hProperties: { dataDefinedTerm: p.d.term, role: 'button', tabIndex: 0, ariaDescribedBy: id, ariaExpanded: 'false', className: ['artifact-defined-term'] },
+                        },
+                        children: [{ type: 'text', value: n.value.slice(at, at + len) }],
+                    };
+                    const note = {
+                        type: 'definedTermNote',
+                        data: {
+                            hName: 'span',
+                            hProperties: { id, dataNospeak: '', dataDefinition: p.d.text, ...(p.d.href ? { dataHref: p.d.href } : {}), className: ['artifact-defined-note'] },
+                        },
+                        children: [{ type: 'text', value: p.d.text }],
+                    };
+                    const parts = [before, mark, note, after].filter((x) => x.type !== 'text' || x.value);
+                    parent.children.splice(k, 1, ...parts);
+                    // Continue AFTER the note, on the remaining text: another term may follow in it.
+                    k += parts.indexOf(note);
+                    continue;
+                }
+                if ('children' in n)
+                    walk(n);
+            }
+        };
+        const earliest = (s) => {
+            let best = null;
+            for (const p of pending) {
+                const m = p.re.exec(s);
+                if (m && (!best || m.index < best.at))
+                    best = { at: m.index, len: m[0].length, p };
+            }
+            return best;
+        };
+        walk(tree);
+    };
+}

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

@@ -1,6 +1,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';
 export type ArtifactMeta = {
     title: string;
     summary: string;
@@ -32,6 +33,9 @@ export type ArtifactMeta = {
     theme?: ThemeMode;
     /** The table of contents: absent draws it once the page has four sections, false never. */
     toc?: boolean;
+    /** Terms this page defines inline: the first occurrence of each is underlined and opens its
+     *  definition. Content, like the body: a republish without it removes them. */
+    definitions?: Definition[];
 };
 export declare function parseArtifactSource(text: string): {
     ok: true;

package/lib/artifacts/front-matter.js

@@ -5,7 +5,8 @@ import { ACCESS_LEVELS } from './reader.js';
 import { parseStateConfig } from './state.js';
 import { mergeWidgetState, scanWidgets } from './widgets.js';
 import { THEME_MODES } from '../brand/theme.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc']);
+import { parseDefinitions } from './definitions.js';
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -46,6 +47,13 @@ export function parseArtifactSource(text) {
             return { ok: false, error: 'toc must be true or false' };
         meta.toc = d.toc;
     }
+    if (d.definitions !== undefined) {
+        const r = parseDefinitions(d.definitions);
+        if (!r.ok)
+            return { ok: false, error: r.error };
+        if (r.definitions.length)
+            meta.definitions = r.definitions;
+    }
     if (d.state !== undefined) {
         const s = parseStateConfig(d.state);
         if (!s.ok)

package/lib/artifacts/render.d.ts

@@ -1,10 +1,13 @@
+import { type Definition } from './definitions.js';
 export declare function isReachableHref(href: unknown): href is string;
 /** `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 }: {
+export declare function ArtifactMarkdown({ markdown, notes, definitions, }: {
     markdown: string;
     notes?: {
         artifactId: string;
         accent?: string;
     };
+    /** Terms to define inline (front matter `definitions:`): the first occurrence of each is underlined. */
+    definitions?: Definition[];
 }): import("react").JSX.Element;

package/lib/artifacts/render.js

@@ -3,6 +3,9 @@ import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { 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';
+import { remarkDefinitions } from './definitions.js';
 // Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
 const GOLD = 'var(--a-accent)';
 function hostOf(url) {
@@ -49,12 +52,14 @@ 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;
+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
-// HTML, and iOS refuses to autoplay a video whose markup is not muted. `playsinline` keeps
-// iPhone from going full screen.
+// HTML, and iOS refuses to play a video unprompted whose markup is not muted. `playsinline` keeps
+// iPhone from going full screen. No `autoplay`: VideoAutoplay starts each one as it nears the
+// screen, so a page of videos does not download them all on open.
 function InlineVideo({ src, label }) {
-    const html = `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" autoplay muted loop playsinline preload="auto" disablepictureinpicture class="block w-full"></video>`;
+    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 } });
 }
 const components = {
@@ -140,13 +145,26 @@ function notesComponents(headings) {
         code: (props) => (/language-notes/.test(props.className ?? '') ? _jsx(NotesEarlier, {}) : _jsx(Code, { ...props })),
     };
 }
+// The term is text with a dotted underline; the description copy is visually hidden and out of
+// flow (absolute), so it takes no room in the line. Neither ever changes size: the definition
+// that opens is drawn by DefinitionLayer on document.body.
+const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;text-decoration-style:dotted;' +
+    'text-decoration-color:color-mix(in srgb,currentColor 55%,transparent);text-decoration-thickness:0.08em;' +
+    'text-underline-offset:0.2em;text-decoration-skip-ink:none;cursor:help;-webkit-tap-highlight-color:transparent}' +
+    '.artifact-defined-term:hover,.artifact-defined-term[aria-expanded="true"]{text-decoration-color:currentColor}' +
+    '.artifact-defined-term:focus-visible{outline:2px solid var(--a-accent);outline-offset:2px;border-radius:2px}' +
+    '.artifact-defined-term .artifact-word{cursor:inherit}' +
+    '@media (hover:none){.artifact-defined-term{cursor:pointer}}' +
+    '.artifact-defined-note{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;' +
+    '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 }) {
+export function ArtifactMarkdown({ markdown, notes, definitions, }) {
     const on = !!notes && hasNotesWidget(markdown);
     const headings = headingsOf(markdown);
-    const body = (_jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: on ? notesComponents(headings) : pageComponents(headings), children: markdown }));
+    const defined = definitions?.length ? definitions : null;
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: defined ? [remarkGfm, remarkDefinitions(defined)] : [remarkGfm], components: on ? notesComponents(headings) : pageComponents(headings), children: markdown }));
     return (
     // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
-    _jsx("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 }));
+    _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/store.d.ts

@@ -3,6 +3,7 @@ import type { ArtifactMeta } from './front-matter.js';
 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';
 export type ArtifactRecord = {
     id: string;
     title: string;
@@ -20,6 +21,7 @@ export type ArtifactRecord = {
     state?: StateConfig;
     theme?: ThemeMode;
     toc?: boolean;
+    definitions?: Definition[];
     markdown: string;
     createdAt: string;
     updatedAt: string;

package/lib/artifacts/store.js

@@ -59,6 +59,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.state ? { state: input.meta.state } : {}),
         ...(input.meta.theme ? { theme: input.meta.theme } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
+        ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
     };
     if (input.id) {
         const existing = await getArtifact(col, input.id);
@@ -88,6 +89,7 @@ async function saveArtifact(col, input) {
         const look = {
             ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
+            ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
         };
         await ref.update({
             ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, updatedAt: now, version: next,

package/lib/reader/artifact-reader.d.ts

@@ -3,6 +3,11 @@ export type WordTiming = {
     s: number;
     e: number;
 };
+/** Wrap every word inside `root` (except skipped subtrees) in a span; return them in order. */
+export declare function wrapWords(root: HTMLElement): HTMLSpanElement[];
+/** The karaoke word a click lands on, or null. A defined term is a control that opens its
+ *  definition, so a tap on it must never seek or start the narration. */
+export declare function seekableWord(target: Element | null): HTMLSpanElement | null;
 /** The word to light at `now`, or -1. Nothing lights until narration has started: the first
  *  word begins at 0, so an untouched page would otherwise sit with its first word highlighted. */
 export declare function litWordIndex(words: WordTiming[], now: number, started: boolean): number;

package/lib/reader/artifact-reader.js

@@ -6,12 +6,13 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // sequence to the word timings by normalized token, resyncing within a short window
 // when the two disagree. Click a word to seek; the bar at the bottom plays and paces.
 import { useEffect, useRef, useState } from 'react';
-const SKIP = '[data-nospeak], [data-artifact-links], pre, [data-footnotes], sup, img';
+const SKIP = '[data-nospeak], [data-artifact-links], pre, [data-footnotes], sup, img, style, script';
+const BLOCK = 'p, li, td, th, h1, h2, h3, h4, h5, h6, blockquote, aside, dt, dd, figcaption, div';
 function normalize(w) {
     return w.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
 }
 /** Wrap every word inside `root` (except skipped subtrees) in a span; return them in order. */
-function wrapWords(root) {
+export function wrapWords(root) {
     const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
         acceptNode: (n) => {
             const el = n.parentElement;
@@ -24,12 +25,29 @@ function wrapWords(root) {
     for (let n = walker.nextNode(); n; n = walker.nextNode())
         nodes.push(n);
     const spans = [];
+    let prev = null;
     for (const node of nodes) {
         const parts = node.nodeValue.split(/(\s+)/);
         const frag = document.createDocumentFragment();
+        const block = node.parentElement.closest(BLOCK);
+        // Punctuation that continues the previous word across an element edge ("Edge" in a defined
+        // term, then ", which"; "**bold**,") is one spoken token with it. It is wrapped as a tail,
+        // not a word, so the word sequence matches the narration's whitespace tokens.
+        const glued = !!prev && prev.block === block && /\S$/.test(prev.text) && /^\S/.test(node.nodeValue);
+        prev = { text: node.nodeValue, block };
+        let first = true;
         for (const part of parts) {
             if (!part)
                 continue;
+            const lead = first;
+            first = false;
+            if (lead && glued && !normalize(part)) {
+                const tail = document.createElement('span');
+                tail.textContent = part;
+                tail.className = 'artifact-word-tail';
+                frag.appendChild(tail);
+                continue;
+            }
             if (/^\s+$/.test(part)) {
                 frag.appendChild(document.createTextNode(part));
                 continue;
@@ -44,6 +62,13 @@ function wrapWords(root) {
     }
     return spans;
 }
+/** The karaoke word a click lands on, or null. A defined term is a control that opens its
+ *  definition, so a tap on it must never seek or start the narration. */
+export function seekableWord(target) {
+    if (!target || target.closest('[data-defined-term]'))
+        return null;
+    return target.closest('.artifact-word');
+}
 /** Map each timing index to a DOM span index, tolerating small mismatches. */
 function align(spans, words) {
     const out = [];
@@ -112,7 +137,7 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
         const spans = wrapWords(root);
         mapRef.current = align(spans, words);
         const onClick = (e) => {
-            const el = e.target.closest('.artifact-word');
+            const el = seekableWord(e.target);
             if (!el)
                 return;
             const idx = mapRef.current.indexOf(el);
@@ -168,7 +193,7 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
                     setPlaying(true);
                 }, onSeeking: () => {
                     startedRef.current = true;
-                }, onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
+                }, onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { "data-artifact-player": true, className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
                                         if (audioRef.current)
                                             audioRef.current.currentTime = Number(e.target.value);
                                     }, "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsxs("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: [fmt(t), " / ", fmt(dur)] }), _jsxs("button", { type: "button", onClick: () => {

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

@@ -0,0 +1 @@
+export declare function DefinitionLayer(): import("react").ReactPortal | null;

package/lib/reader/definition-layer.js

@@ -0,0 +1,153 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Opens a defined term's definition. ONE controller per page, listening on the document, so the
+// terms themselves stay plain server-rendered spans: nothing in a paragraph is a React island that
+// could re-render under the read-along's word spans, and nothing in a paragraph opens or closes.
+//
+// The definition renders through a portal on document.body, OUTSIDE the text flow, so opening it
+// cannot reflow the page (earned 2026-09-27 on a sibling site: a definition toggled as
+// a child of the word re-ran the paragraph's line breaking). On a phone it is a sheet pinned to
+// the bottom, above the narration bar; on a desk it sits under the word, clamped in the window.
+// Mouse hover shows it; a click, a tap, Enter or Space pins it; Escape or a tap elsewhere closes.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+const WIDTH = 320;
+const GAP = 10;
+const MARGIN = 16;
+const PHONE = '(max-width: 639px)';
+// The theme lives on a wrapper, not on body, so the portal carries the values it needs.
+const VARS = ['--a-ground', '--a-ink', '--a-accent'];
+function openFor(el, pinned) {
+    const note = document.getElementById(el.getAttribute('aria-describedby') ?? '');
+    const text = note?.dataset.definition;
+    if (!text)
+        return null;
+    return { el, term: el.dataset.definedTerm ?? el.textContent ?? '', text, href: note?.dataset.href, pinned };
+}
+export function DefinitionLayer() {
+    const [open, setOpen] = useState(null);
+    const [place, setPlace] = useState(null);
+    const [vars, setVars] = useState({});
+    const sheet = useRef(null);
+    const openRef = useRef(null);
+    openRef.current = open;
+    const show = useCallback((next) => {
+        const prev = openRef.current;
+        if (prev && prev.el !== next?.el)
+            prev.el.setAttribute('aria-expanded', 'false');
+        if (next)
+            next.el.setAttribute('aria-expanded', next.pinned ? 'true' : 'false');
+        openRef.current = next;
+        setOpen(next);
+    }, []);
+    const measure = useCallback(() => {
+        const o = openRef.current;
+        if (!o)
+            return setPlace(null);
+        const cs = getComputedStyle(o.el);
+        // The body font is not always the page's: the brand sets it on a wrapper, so carry it too.
+        setVars({ ...Object.fromEntries(VARS.map((v) => [v, cs.getPropertyValue(v).trim()]).filter(([, x]) => x)), fontFamily: cs.fontFamily });
+        if (window.matchMedia ? window.matchMedia(PHONE).matches : window.innerWidth < 640) {
+            const bar = document.querySelector('[data-artifact-player]')?.getBoundingClientRect();
+            const clear = bar && bar.top < window.innerHeight ? window.innerHeight - bar.top : 0;
+            return setPlace({ phone: true, bottom: clear + MARGIN });
+        }
+        const rects = o.el.getClientRects();
+        const r = rects.length ? rects[rects.length - 1] : o.el.getBoundingClientRect();
+        const width = Math.min(WIDTH, window.innerWidth - 2 * MARGIN);
+        const left = Math.min(Math.max(r.left + r.width / 2 - width / 2, MARGIN), window.innerWidth - width - MARGIN);
+        setPlace({ phone: false, top: r.bottom + window.scrollY + GAP, left: left + window.scrollX, width });
+    }, []);
+    useEffect(() => {
+        const termOf = (t) => (t instanceof Element ? t.closest('[data-defined-term]') : null);
+        const toggle = (el) => {
+            const cur = openRef.current;
+            show(cur && cur.el === el && cur.pinned ? null : openFor(el, true));
+        };
+        const onClick = (e) => {
+            const el = termOf(e.target);
+            if (el)
+                toggle(el);
+        };
+        const onDown = (e) => {
+            const cur = openRef.current;
+            if (!cur?.pinned)
+                return;
+            const t = e.target;
+            if (termOf(t) === cur.el || sheet.current?.contains(t))
+                return;
+            show(null);
+        };
+        const onOver = (e) => {
+            if (e.pointerType !== 'mouse' || openRef.current?.pinned)
+                return;
+            const el = termOf(e.target);
+            if (el && openRef.current?.el !== el)
+                show(openFor(el, false));
+        };
+        const onOut = (e) => {
+            const cur = openRef.current;
+            if (e.pointerType !== 'mouse' || !cur || cur.pinned)
+                return;
+            if (termOf(e.target) === cur.el && termOf(e.relatedTarget) !== cur.el)
+                show(null);
+        };
+        const onKey = (e) => {
+            if (e.key === 'Escape' && openRef.current) {
+                const el = openRef.current.el;
+                show(null);
+                el.focus?.();
+                return;
+            }
+            if (e.key !== 'Enter' && e.key !== ' ')
+                return;
+            const el = termOf(e.target);
+            if (!el)
+                return;
+            e.preventDefault();
+            toggle(el);
+        };
+        document.addEventListener('click', onClick);
+        document.addEventListener('pointerdown', onDown);
+        document.addEventListener('pointerover', onOver);
+        document.addEventListener('pointerout', onOut);
+        document.addEventListener('keydown', onKey);
+        return () => {
+            document.removeEventListener('click', onClick);
+            document.removeEventListener('pointerdown', onDown);
+            document.removeEventListener('pointerover', onOver);
+            document.removeEventListener('pointerout', onOut);
+            document.removeEventListener('keydown', onKey);
+        };
+    }, [show]);
+    useEffect(() => {
+        measure();
+        if (!open)
+            return;
+        window.addEventListener('resize', measure);
+        return () => window.removeEventListener('resize', measure);
+    }, [open, measure]);
+    if (!open || !place)
+        return null;
+    const style = {
+        ...vars,
+        zIndex: 60,
+        boxSizing: 'border-box',
+        borderRadius: 10,
+        padding: '12px 16px',
+        background: 'var(--a-ink, #111)',
+        color: 'var(--a-ground, #fff)',
+        fontSize: 15,
+        lineHeight: 1.45,
+        fontStyle: 'normal',
+        fontWeight: 400,
+        letterSpacing: 'normal',
+        textAlign: 'left',
+        boxShadow: '0 10px 30px rgba(0,0,0,0.25)',
+        pointerEvents: open.pinned ? 'auto' : 'none',
+        ...(place.phone
+            ? { position: 'fixed', left: MARGIN, right: MARGIN, bottom: `calc(${place.bottom}px + env(safe-area-inset-bottom, 0px))` }
+            : { position: 'absolute', top: place.top, left: place.left, width: place.width }),
+    };
+    return createPortal(_jsxs("div", { ref: sheet, "data-definition-sheet": true, role: "note", "aria-hidden": open.href ? undefined : true, style: style, children: [_jsx("span", { style: { display: 'block', marginBottom: 4, fontSize: 11, fontWeight: 500, letterSpacing: '0.18em', textTransform: 'uppercase', opacity: 0.6 }, children: open.term }), open.text, open.href ? (_jsx("a", { href: open.href, target: "_blank", rel: "noopener noreferrer", style: { display: 'block', marginTop: 8, fontSize: 13, color: 'inherit', textDecoration: 'underline', textUnderlineOffset: '0.2em', opacity: 0.85 }, children: "Read more" })) : null] }), document.body);
+}

package/lib/reader/video-autoplay.d.ts

@@ -0,0 +1 @@
+export declare function VideoAutoplay(): null;

package/lib/reader/video-autoplay.js

@@ -0,0 +1,31 @@
+'use client';
+// Plays each inline video only while it is near the screen. With `autoplay` in the markup every
+// video on the page downloads the moment it opens (the Freedom whitepaper: 21 diagrams, 6.8 MB,
+// competing with the text and the narration on a phone). Here a video loads and plays as it
+// comes within a screen of view and pauses when it leaves, so opening the page costs the text.
+import { useEffect } from 'react';
+export function VideoAutoplay() {
+    useEffect(() => {
+        const videos = Array.from(document.querySelectorAll('video[data-artifact-video]'));
+        if (!videos.length || typeof IntersectionObserver === 'undefined') {
+            for (const v of videos)
+                void v.play?.().catch(() => { });
+            return;
+        }
+        const io = new IntersectionObserver((entries) => {
+            for (const e of entries) {
+                const v = e.target;
+                if (e.isIntersecting) {
+                    v.preload = 'auto';
+                    void v.play().catch(() => { });
+                }
+                else
+                    v.pause();
+            }
+        }, { rootMargin: '100% 0px' });
+        for (const v of videos)
+            io.observe(v);
+        return () => io.disconnect();
+    }, []);
+    return null;
+}

package/lib/routes/artifacts.js

@@ -147,7 +147,7 @@ export function createArtifactRoutes(config) {
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
         const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), 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] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), 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] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in

package/package.json

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