@supersuit/artifacts 0.1.0

package/lib/artifacts/narration.js

@@ -0,0 +1,85 @@
+// The text a narrator reads for an artifact, derived from the markdown TREE with the
+// same skip rules the renderer marks in the markup (data-nospeak, link cards, code,
+// footnotes), so the words on screen are exactly the words spoken. The client-side
+// highlighter skips the same nodes, which is what keeps the two in step.
+//
+// Built from the tree rather than the rendered HTML because Next refuses
+// react-dom/server inside app code. Any block the renderer adds must be mirrored here.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+const CALLOUT = /^\[!(note|warning)\]\s*/i;
+function inline(nodes) {
+    let out = '';
+    for (const n of nodes) {
+        switch (n.type) {
+            case 'text':
+            case 'inlineCode':
+                out += n.value;
+                break;
+            case 'emphasis':
+            case 'strong':
+            case 'delete':
+            case 'link':
+            case 'linkReference':
+                out += inline(n.children);
+                break;
+            case 'break':
+                out += ' ';
+                break;
+            // footnoteReference, image, imageReference, html: not spoken
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function blocks(nodes, out) {
+    for (const n of nodes) {
+        switch (n.type) {
+            case 'heading':
+            case 'paragraph':
+                out.push(inline(n.children));
+                break;
+            case 'blockquote': {
+                const inner = [];
+                blocks(n.children, inner);
+                if (inner.length)
+                    inner[0] = inner[0].replace(CALLOUT, '');
+                out.push(...inner);
+                break;
+            }
+            case 'list':
+                for (const item of n.children)
+                    blocks(item.children, out);
+                break;
+            case 'table':
+                for (const row of n.children) {
+                    out.push(row.children.map((c) => inline(c.children)).join(', '));
+                }
+                break;
+            // code (including ```links), image, footnoteDefinition, thematicBreak, html: not spoken
+            default:
+                break;
+        }
+    }
+}
+function clean(lines) {
+    return lines
+        .map((l) => l.replace(/\s+/g, ' ').trim())
+        .filter(Boolean)
+        .join('\n');
+}
+export function narrationTextFromMarkdown(markdown) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(markdown);
+    const out = [];
+    blocks(tree.children, out);
+    return clean(out);
+}
+export function narrationText(input) {
+    return [input.title.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) {
+    return w.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+}

package/lib/artifacts/reader.d.ts

@@ -0,0 +1,54 @@
+export type Access = 'invite' | 'freedom';
+export declare const ACCESS_LEVELS: readonly Access[];
+/** The person a pass or a grant names. `member` is an active Freedom account at sign-in time. */
+export type Reader = {
+    uid: string;
+    email: string;
+    name: string | null;
+    member: boolean;
+};
+export declare const PASS_TTL_SECONDS = 300;
+/** A week, so a revoked Freedom account loses `freedom` pages within seven days. Allowlist
+ *  changes need no wait: the list is read on every request. */
+export declare const GRANT_TTL_SECONDS: number;
+export declare const GRANT_COOKIE = "artifact_reader";
+export declare function mintPass(secret: string, reader: Reader, exp: number): string;
+export declare function verifyPass(secret: string | undefined, pass: string | null | undefined, now?: number): Reader | null;
+export declare function mintGrant(secret: string, reader: Reader, now?: number): string;
+export declare function verifyGrant(secret: string | undefined, grant: string | null | undefined, now?: number): Reader | null;
+/** One person let in by name. Stored on the host, never in the published file. */
+export type AllowEntry = {
+    email: string;
+    name?: string;
+    reason?: string;
+    addedAt?: string;
+};
+export type Decision = {
+    open: true;
+    why: 'listed';
+    reason: string;
+} | {
+    open: true;
+    why: 'member';
+    reason: string;
+} | {
+    open: false;
+    why: 'signed-out';
+} | {
+    open: false;
+    why: 'not-allowed';
+    reader: Reader;
+};
+export declare const MEMBER_REASON = "you are a Freedom user";
+export declare const LISTED_REASON = "you were given access to it by name";
+/** Whether this reader may open a page with this access level. The allowlist opens both
+ *  levels; `freedom` also opens to any active Freedom account. A listed person's own reason
+ *  wins over the membership one, because it is the truer account of why they are reading. */
+export declare function decide(access: Access, reader: Reader | null, allow: AllowEntry[]): Decision;
+/** The name the banner addresses: the allowlist's name, then the account's, first word only. */
+export declare function firstName(reader: Reader, allow: AllowEntry[]): string | null;
+/** Where a reader goes to sign in, carrying the page they asked for. */
+export declare function signInUrl(signInOrigin: string, pageUrl: string): string;
+/** A path on this host that `enter` may send a reader to after it sets the grant: one page id,
+ *  nothing else, so the redirect cannot be pointed off the host. */
+export declare function safeReturnPath(to: string | null | undefined, prefix?: string): string | null;

package/lib/artifacts/reader.js

@@ -0,0 +1,109 @@
+// Who is reading a gated page, and whether they may.
+//
+// A page with `access:` in its front matter never renders its body to an anonymous request.
+// The reader signs in at the host's sign-in authority (`signInOrigin`, the service that knows
+// who holds a Freedom account), which bounces them back with a five-minute PASS naming them. The host swaps the pass for its
+// own GRANT, an HttpOnly cookie on this host, and from then on every gated page on the host
+// knows who is reading without asking again.
+//
+// THE PASS SHAPE IS A CONTRACT WITH THE SIGN-IN AUTHORITY, byte for byte (README, "The reader
+// pass"): `a1.<payload>.<sig>`, payload the base64url of a small JSON, sig the first 32 hex of
+// HMAC-SHA256(secret, `artifact-pass:a1.<payload>`). reader.test.ts pins the vector, so a
+// change here is named by a failing test before it can reach a deploy and break every sign-in.
+//
+// WHY A PERSON AND NOT A LINK. Nothing in the URL opens the page, so a forwarded link opens a
+// sign-in door and nothing else. When the person it was forwarded to signs in and is not on
+// the list, their refusal is recorded under their own address, which is how a forward shows up.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const ACCESS_LEVELS = ['invite', 'freedom'];
+export const PASS_TTL_SECONDS = 300;
+/** A week, so a revoked Freedom account loses `freedom` pages within seven days. Allowlist
+ *  changes need no wait: the list is read on every request. */
+export const GRANT_TTL_SECONDS = 7 * 24 * 60 * 60;
+export const GRANT_COOKIE = 'artifact_reader';
+const b64url = (s) => Buffer.from(s, 'utf8').toString('base64url');
+const unb64url = (s) => Buffer.from(s, 'base64url').toString('utf8');
+const sig = (secret, domain, body) => createHmac('sha256', secret).update(`${domain}:${body}`).digest('hex').slice(0, 32);
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+function encode(secret, domain, version, reader, exp) {
+    // Short keys: this rides in a URL and a cookie.
+    const payload = b64url(JSON.stringify({ u: reader.uid, e: reader.email, n: reader.name, m: reader.member, x: exp }));
+    const body = `${version}.${payload}`;
+    return `${body}.${sig(secret, domain, body)}`;
+}
+function decode(secret, domain, version, token, now) {
+    if (!secret || typeof token !== 'string')
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[0] !== version)
+        return null;
+    const body = `${parts[0]}.${parts[1]}`;
+    if (!/^[0-9a-f]{32}$/.test(parts[2]) || !safeEqual(parts[2], sig(secret, domain, body)))
+        return null;
+    let d;
+    try {
+        d = JSON.parse(unb64url(parts[1]));
+    }
+    catch {
+        return null;
+    }
+    if (typeof d.x !== 'number' || d.x * 1000 < now)
+        return null;
+    if (typeof d.u !== 'string' || !d.u || typeof d.e !== 'string' || !d.e.includes('@'))
+        return null;
+    return {
+        uid: d.u,
+        email: d.e.trim().toLowerCase(),
+        name: typeof d.n === 'string' && d.n.trim() ? d.n.trim() : null,
+        member: d.m === true,
+    };
+}
+export function mintPass(secret, reader, exp) {
+    return encode(secret, 'artifact-pass', 'a1', reader, exp);
+}
+export function verifyPass(secret, pass, now = Date.now()) {
+    return decode(secret, 'artifact-pass', 'a1', pass, now);
+}
+export function mintGrant(secret, reader, now = Date.now()) {
+    return encode(secret, 'artifact-grant', 'g1', reader, Math.floor(now / 1000) + GRANT_TTL_SECONDS);
+}
+export function verifyGrant(secret, grant, now = Date.now()) {
+    return decode(secret, 'artifact-grant', 'g1', grant, now);
+}
+export const MEMBER_REASON = 'you are a Freedom user';
+export const LISTED_REASON = 'you were given access to it by name';
+/** Whether this reader may open a page with this access level. The allowlist opens both
+ *  levels; `freedom` also opens to any active Freedom account. A listed person's own reason
+ *  wins over the membership one, because it is the truer account of why they are reading. */
+export function decide(access, reader, allow) {
+    if (!reader)
+        return { open: false, why: 'signed-out' };
+    const listed = allow.find((a) => a.email.trim().toLowerCase() === reader.email);
+    if (listed)
+        return { open: true, why: 'listed', reason: listed.reason?.trim() || LISTED_REASON };
+    if (access === 'freedom' && reader.member)
+        return { open: true, why: 'member', reason: MEMBER_REASON };
+    return { open: false, why: 'not-allowed', reader };
+}
+/** The name the banner addresses: the allowlist's name, then the account's, first word only. */
+export function firstName(reader, allow) {
+    const listed = allow.find((a) => a.email.trim().toLowerCase() === reader.email);
+    const full = listed?.name?.trim() || reader.name;
+    return full ? full.split(/\s+/)[0] : null;
+}
+/** Where a reader goes to sign in, carrying the page they asked for. */
+export function signInUrl(signInOrigin, pageUrl) {
+    return `${signInOrigin}/artifact/sign-in?to=${encodeURIComponent(pageUrl)}`;
+}
+/** A path on this host that `enter` may send a reader to after it sets the grant: one page id,
+ *  nothing else, so the redirect cannot be pointed off the host. */
+export function safeReturnPath(to, prefix = '/') {
+    if (typeof to !== 'string')
+        return null;
+    const m = new RegExp(`^${prefix.replace(/\//g, '\\/')}([abcdefghjkmnpqrstuvwxyz23456789]{8})$`).exec(to);
+    return m ? `${prefix}${m[1]}` : null;
+}

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

@@ -0,0 +1,90 @@
+import { type Firestore } from 'firebase-admin/firestore';
+import type { AllowEntry, Reader } from './reader.js';
+export declare const FLAG_KINDS: readonly ["save", "print", "copy", "image", "devtools", "refused"];
+export type FlagKind = (typeof FLAG_KINDS)[number];
+export type SessionDoc = {
+    artifactId: string;
+    session: string;
+    email: string;
+    name: string | null;
+    member: boolean;
+    startedAt: string;
+    lastAt: string;
+    activeSeconds: number;
+    maxScroll: number;
+    device?: string;
+    country?: string;
+};
+export type FlagDoc = {
+    artifactId: string;
+    email: string;
+    name: string | null;
+    kind: FlagKind;
+    detail?: string;
+    at: string;
+    country?: string;
+};
+export type AckDoc = {
+    artifactId: string;
+    email: string;
+    name: string | null;
+    text: string;
+    at: string;
+    country?: string;
+};
+export interface ReadersStore {
+    acknowledged(artifactId: string, email: string): Promise<boolean>;
+    acknowledge(input: {
+        artifactId: string;
+        reader: Reader;
+        text: string;
+        country?: string;
+    }): Promise<void>;
+    acks(artifactId: string): Promise<AckDoc[]>;
+    allowList(artifactId: string): Promise<AllowEntry[]>;
+    allow(artifactId: string, add: AllowEntry[], remove: string[]): Promise<AllowEntry[]>;
+    touchSession(input: {
+        artifactId: string;
+        session: string;
+        reader: Reader;
+        addSeconds: number;
+        scroll: number;
+        device?: string;
+        country?: string;
+    }): Promise<void>;
+    flag(input: {
+        artifactId: string;
+        reader: Reader;
+        kind: FlagKind;
+        detail?: string;
+        country?: string;
+    }): Promise<void>;
+    sessions(artifactId: string): Promise<SessionDoc[]>;
+    flags(artifactId: string): Promise<FlagDoc[]>;
+}
+export declare function createReadersStore(db: Firestore, base: string): ReadersStore;
+export type ReaderSummary = {
+    email: string;
+    name: string | null;
+    member: boolean;
+    sessions: number;
+    activeSeconds: number;
+    maxScroll: number;
+    firstSeen: string;
+    lastSeen: string;
+    flags: {
+        kind: FlagKind;
+        at: string;
+        detail?: string;
+    }[];
+};
+/** Per-reader totals for one page, most recently seen first, plus everyone refused at the door. */
+export declare function summarize(sessionDocs: SessionDoc[], flagDocs: FlagDoc[]): {
+    readers: ReaderSummary[];
+    refused: {
+        email: string;
+        name: string | null;
+        attempts: number;
+        lastAt: string;
+    }[];
+};

package/lib/artifacts/readers-store.js

@@ -0,0 +1,141 @@
+// The host-side record for gated pages: who may read each one, and what each reader did.
+//
+// Lives in Firestore beside the pages, never in a published file, because a person's email
+// never goes into file content, and so that changing who may read needs no republish.
+//
+//   <base>Access/<artifactId>     { readers: { <email>: AllowEntry } }
+//   <base>Sessions/<sessionId>    one visit: who, when, how long actively reading, how far
+//   <base>Flags/<auto>            one attempt to save, print, copy, or open a page refused
+//   <base>Acks/<page>__<email>    the reader's agreement to keep the page confidential, with the
+//                                 exact wording they agreed to, before the body was shown
+//
+// `base` is the artifacts collection path (`tenants/<id>/artifacts`), so each tenant's record
+// sits next to its own pages.
+import { FieldValue } from 'firebase-admin/firestore';
+export const FLAG_KINDS = ['save', 'print', 'copy', 'image', 'devtools', 'refused'];
+/** An email as a map key: lowercased, and with the dots Firestore reads as a path escaped. */
+const keyOf = (email) => email.trim().toLowerCase().replace(/\./g, ',');
+export function createReadersStore(db, base) {
+    const access = () => db.collection(`${base}Access`);
+    const sessions = () => db.collection(`${base}Sessions`);
+    const flags = () => db.collection(`${base}Flags`);
+    const acks = () => db.collection(`${base}Acks`);
+    const ackId = (artifactId, email) => `${artifactId}__${keyOf(email)}`;
+    const listOf = (data) => Object.values((data?.readers ?? {})).sort((a, b) => a.email.localeCompare(b.email));
+    return {
+        async acknowledged(artifactId, email) {
+            return (await acks().doc(ackId(artifactId, email)).get()).exists;
+        },
+        async acknowledge({ artifactId, reader, text, country }) {
+            const doc = { artifactId, email: reader.email, name: reader.name, text, at: new Date().toISOString(), ...(country ? { country } : {}) };
+            await acks().doc(ackId(artifactId, reader.email)).set(doc);
+        },
+        async acks(artifactId) {
+            const snap = await acks().where('artifactId', '==', artifactId).get();
+            return snap.docs.map((d) => d.data());
+        },
+        async allowList(artifactId) {
+            const snap = await access().doc(artifactId).get();
+            return snap.exists ? listOf(snap.data()) : [];
+        },
+        async allow(artifactId, add, remove) {
+            const now = new Date().toISOString();
+            const update = {};
+            for (const e of add) {
+                const email = e.email.trim().toLowerCase();
+                update[`readers.${keyOf(email)}`] = {
+                    email,
+                    ...(e.name?.trim() ? { name: e.name.trim() } : {}),
+                    ...(e.reason?.trim() ? { reason: e.reason.trim() } : {}),
+                    addedAt: now,
+                };
+            }
+            for (const email of remove)
+                update[`readers.${keyOf(email)}`] = FieldValue.delete();
+            const ref = access().doc(artifactId);
+            if (Object.keys(update).length) {
+                // Create the document only when it is missing. `set({ readers: {} }, { merge: true })`
+                // looks harmless and is not: Firestore writes an EMPTY map in a merge as a value, so it
+                // replaced the whole list and every `allow` erased everyone added before it. Seen live
+                // on 2026-09-24, when adding one reader to the lightpaper removed the one before.
+                if (!(await ref.get()).exists)
+                    await ref.set({ readers: {} });
+                await ref.update(update);
+            }
+            return listOf((await ref.get()).data());
+        },
+        async touchSession({ artifactId, session, reader, addSeconds, scroll, device, country }) {
+            const ref = sessions().doc(session);
+            const now = new Date().toISOString();
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                if (!snap.exists) {
+                    const doc = {
+                        artifactId, session, email: reader.email, name: reader.name, member: reader.member,
+                        startedAt: now, lastAt: now, activeSeconds: addSeconds, maxScroll: scroll,
+                        ...(device ? { device } : {}), ...(country ? { country } : {}),
+                    };
+                    tx.set(ref, doc);
+                    return;
+                }
+                const cur = snap.data();
+                // A session id is the browser's; it can never be moved onto another reader or page.
+                if (cur.email !== reader.email || cur.artifactId !== artifactId)
+                    return;
+                tx.update(ref, {
+                    lastAt: now,
+                    activeSeconds: FieldValue.increment(addSeconds),
+                    maxScroll: Math.max(cur.maxScroll ?? 0, scroll),
+                });
+            });
+        },
+        async flag({ artifactId, reader, kind, detail, country }) {
+            const doc = {
+                artifactId, email: reader.email, name: reader.name, kind, at: new Date().toISOString(),
+                ...(detail ? { detail } : {}), ...(country ? { country } : {}),
+            };
+            await flags().add(doc);
+        },
+        async sessions(artifactId) {
+            const snap = await sessions().where('artifactId', '==', artifactId).get();
+            return snap.docs.map((d) => d.data());
+        },
+        async flags(artifactId) {
+            const snap = await flags().where('artifactId', '==', artifactId).get();
+            return snap.docs.map((d) => d.data());
+        },
+    };
+}
+/** Per-reader totals for one page, most recently seen first, plus everyone refused at the door. */
+export function summarize(sessionDocs, flagDocs) {
+    const by = new Map();
+    for (const s of sessionDocs) {
+        const r = by.get(s.email) ?? {
+            email: s.email, name: s.name, member: s.member, sessions: 0, activeSeconds: 0, maxScroll: 0,
+            firstSeen: s.startedAt, lastSeen: s.lastAt, flags: [],
+        };
+        r.sessions += 1;
+        r.activeSeconds += s.activeSeconds ?? 0;
+        r.maxScroll = Math.max(r.maxScroll, s.maxScroll ?? 0);
+        if (s.startedAt < r.firstSeen)
+            r.firstSeen = s.startedAt;
+        if (s.lastAt > r.lastSeen)
+            r.lastSeen = s.lastAt;
+        by.set(s.email, r);
+    }
+    const refused = new Map();
+    for (const f of flagDocs.slice().sort((a, b) => a.at.localeCompare(b.at))) {
+        if (f.kind === 'refused') {
+            const r = refused.get(f.email) ?? { email: f.email, name: f.name, attempts: 0, lastAt: f.at };
+            r.attempts += 1;
+            r.lastAt = f.at;
+            refused.set(f.email, r);
+            continue;
+        }
+        by.get(f.email)?.flags.push({ kind: f.kind, at: f.at, ...(f.detail ? { detail: f.detail } : {}) });
+    }
+    return {
+        readers: [...by.values()].sort((a, b) => b.lastSeen.localeCompare(a.lastSeen)),
+        refused: [...refused.values()].sort((a, b) => b.lastAt.localeCompare(a.lastAt)),
+    };
+}

package/lib/artifacts/render.d.ts

@@ -0,0 +1,4 @@
+export declare function isReachableHref(href: unknown): href is string;
+export declare function ArtifactMarkdown({ markdown }: {
+    markdown: string;
+}): import("react").JSX.Element;

package/lib/artifacts/render.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+const GOLD = '#C2A15C';
+function hostOf(url) {
+    try {
+        return new URL(url).host.replace(/^www\./, '');
+    }
+    catch {
+        return '';
+    }
+}
+function textOf(node) {
+    if (node == null || typeof node === 'boolean')
+        return '';
+    if (typeof node === 'string' || typeof node === 'number')
+        return String(node);
+    if (Array.isArray(node))
+        return node.map(textOf).join('');
+    if (typeof node === 'object' && 'props' in node) {
+        return textOf(node.props.children);
+    }
+    return '';
+}
+function LinkCards({ source }) {
+    const rows = source
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [url, ...rest] = l.split('|');
+        return { url: url.trim(), note: rest.join('|').trim() };
+    });
+    return (_jsx("ul", { "data-artifact-links": true, className: "my-6 grid list-none gap-3 p-0", children: rows.map((r) => (_jsx("li", { className: "m-0 p-0", children: _jsxs("a", { href: r.url, target: "_blank", rel: "noopener noreferrer", className: "block rounded-lg border border-white/10 bg-white/[0.03] px-4 py-3 no-underline transition-colors hover:border-white/25", children: [_jsx("span", { className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: hostOf(r.url) }), _jsx("span", { className: "block text-zinc-100", children: r.note || r.url })] }) }, r.url))) }));
+}
+const CALLOUT = /^\[!(note|warning)\]\s*/i;
+// A link the reader can actually follow: absolute, a scheme like mailto:, a
+// root path on this host (uploaded assets), or an in-page fragment. Anything
+// else is a path on the author's disk (../meeting-transcripts/x.md), which the
+// publisher never uploads, so the anchor would 404. Those render as their text.
+const REACHABLE = /^(?:[a-z][a-z0-9+.-]*:|\/|#)/i;
+export function isReachableHref(href) {
+    return typeof href === 'string' && REACHABLE.test(href);
+}
+const components = {
+    h1: ({ children }) => _jsx("h1", { className: "mt-10 mb-4 font-serif text-3xl text-zinc-50", children: children }),
+    h2: ({ children }) => _jsx("h2", { className: "mt-10 mb-3 font-serif text-2xl text-zinc-50", children: children }),
+    h3: ({ children }) => _jsx("h3", { className: "mt-8 mb-2 text-lg font-semibold text-zinc-100", children: children }),
+    p: ({ children }) => _jsx("p", { className: "my-4 leading-relaxed", children: children }),
+    ul: ({ children }) => _jsx("ul", { className: "my-4 list-disc space-y-1 pl-6", children: children }),
+    ol: ({ children }) => _jsx("ol", { className: "my-4 list-decimal space-y-1 pl-6", children: children }),
+    hr: () => _jsx("hr", { className: "my-10 border-white/10" }),
+    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-white/20 px-3 py-2 text-left font-semibold text-zinc-100", children: children })),
+    td: ({ children }) => _jsx("td", { className: "border-b border-white/10 px-3 py-2 align-top", children: children }),
+    img: ({ src, 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-white/10" })),
+    a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, target: "_blank", rel: "noopener noreferrer", className: "text-zinc-50 underline decoration-white/30 underline-offset-4 hover:decoration-white", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-zinc-500", children: ["(", hostOf(href), ")"] })) : null] })),
+    code: ({ className, children }) => {
+        const lang = /language-(\w+)/.exec(className ?? '')?.[1];
+        if (lang === 'links')
+            return _jsx(LinkCards, { source: textOf(children) });
+        if (!className) {
+            return _jsx("code", { className: "rounded bg-white/10 px-1.5 py-0.5 text-[0.9em] text-zinc-100", children: children });
+        }
+        return _jsx("code", { className: className, children: children });
+    },
+    pre: ({ children }) => {
+        // A links fence renders its own block; do not wrap it in <pre>.
+        const inner = Array.isArray(children) ? children[0] : children;
+        const cls = inner?.props?.className ?? '';
+        if (/language-links/.test(cls))
+            return _jsx(_Fragment, { children: children });
+        return (_jsx("pre", { "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-white/10 bg-black/40 p-4 text-sm text-zinc-100", children: children }));
+    },
+    blockquote: ({ children }) => {
+        const t = textOf(children).trim();
+        const m = CALLOUT.exec(t);
+        if (!m) {
+            return (_jsx("blockquote", { className: "my-6 border-l-2 pl-4 italic text-zinc-300", style: { borderColor: GOLD }, children: children }));
+        }
+        const kind = m[1].toLowerCase();
+        const body = t.replace(CALLOUT, '');
+        return (_jsxs("aside", { "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'rgba(255,255,255,0.03)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-zinc-100", children: body })] }));
+    },
+};
+export function ArtifactMarkdown({ markdown }) {
+    return (_jsx("div", { className: "text-[17px] text-zinc-200", children: _jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: components, children: markdown }) }));
+}

package/lib/artifacts/store.d.ts

@@ -0,0 +1,52 @@
+import { type Firestore } from 'firebase-admin/firestore';
+import type { ArtifactMeta } from './front-matter.js';
+import type { Access } from './reader.js';
+export type ArtifactRecord = {
+    id: string;
+    title: string;
+    summary: string;
+    template: 'document';
+    subtitle?: string;
+    audience?: string;
+    cover?: string;
+    voice?: string;
+    narration?: string;
+    timings?: string;
+    narrationHash?: string;
+    password?: string;
+    access?: Access;
+    markdown: string;
+    createdAt: string;
+    updatedAt: string;
+    /** The current version number. Absent on pages saved before history moved out. */
+    version?: number;
+    /** LEGACY: history as an array on the document. Moved to the subcollection on next save. */
+    versions?: {
+        markdown: string;
+        at: string;
+    }[];
+    views: number;
+};
+export declare function newArtifactId(): string;
+export type SaveResult = {
+    id: string;
+    version: number;
+    created: boolean;
+} | {
+    notFound: true;
+};
+export interface ArtifactStore {
+    get(id: string): Promise<ArtifactRecord | null>;
+    save(input: {
+        id?: string;
+        meta: ArtifactMeta;
+        markdown: string;
+    }): Promise<SaveResult>;
+    delete(id: string): Promise<boolean>;
+    bumpViews(id: string): Promise<void>;
+    /** Set who may read a page without republishing it; 'public' opens it. False if no such page. */
+    setAccess?(id: string, access: Access | 'public'): Promise<boolean>;
+}
+/** The Firestore-backed store. The instance hands in its own Firestore, so the shell
+ *  never knows which project it is writing to; a hosted tenant passes a namespaced one. */
+export declare function createArtifactStore(db: Firestore, collection?: string): ArtifactStore;