@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/section-identity.js

@@ -0,0 +1,137 @@
+export const validSectionId = (value) => typeof value === 'string' && /^[a-z0-9][a-z0-9-]{0,511}$/.test(value);
+const textOf = (node) => typeof node.value === 'string' ? node.value : (node.children ?? []).map(textOf).join('');
+const marker = (node) => ['mdxJsxTextElement', 'mdxJsxFlowElement'].includes(node.type) && node.name === 'Anchor';
+/** Consume only a direct trailing marker on an authored root H2. Code stays inert. */
+export function lowerSectionMarkers(tree, label = 'document') {
+    const allowed = new Set();
+    const children = (tree.children ?? []).map((node) => {
+        if (node.type !== 'heading' || node.depth !== 2)
+            return node;
+        const parts = [...(node.children ?? [])];
+        while (parts.at(-1)?.type === 'text' && !parts.at(-1).value.trim())
+            parts.pop();
+        const last = parts.at(-1);
+        if (!last || !marker(last))
+            return node;
+        const attributes = last.attributes ?? [];
+        if (last.type !== 'mdxJsxTextElement' || last.children?.length || attributes.length !== 1 || attributes[0].type !== 'mdxJsxAttribute' || attributes[0].name !== 'id' || !validSectionId(attributes[0].value)) {
+            throw new Error(`${label}: <Anchor> needs only a literal id of 1–512 lowercase letters, numbers, or dashes and no children`);
+        }
+        allowed.add(last);
+        parts.pop();
+        if (parts.at(-1)?.type === 'text')
+            parts[parts.length - 1] = { ...parts.at(-1), value: parts.at(-1).value.trimEnd() };
+        if (!parts.map(textOf).join('').trim())
+            throw new Error(`${label}: an anchored heading needs a title`);
+        const id = attributes[0].value;
+        return { ...node, children: parts, data: { ...node.data, sectionId: id, hProperties: { ...node.data?.hProperties, 'data-shoalrun-section-id': id } } };
+    });
+    const check = (node) => {
+        if (marker(node) && !allowed.has(node))
+            throw new Error(`${label}: <Anchor> must be the single trailing marker of a root level-two heading`);
+        node.children?.forEach(check);
+    };
+    check(tree);
+    return { ...tree, children };
+}
+export function sectionIdentities(tree, label = 'document') {
+    const children = tree.children ?? [];
+    const starts = children.flatMap((node, index) => node.type === 'heading' && node.depth === 2 ? [index] : []);
+    const used = new Set();
+    const sections = starts.map(start => {
+        const node = children[start];
+        const title = textOf(node).trim();
+        const stem = title.normalize('NFKD').toLowerCase().replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'section';
+        let generated = stem;
+        for (let suffix = 2; used.has(generated); suffix++)
+            generated = `${stem}-${suffix}`;
+        used.add(generated);
+        const explicit = node.data?.sectionId !== undefined;
+        if (explicit && !validSectionId(node.data.sectionId))
+            throw new Error(`${label}: invalid explicit section ID`);
+        const end = children.findIndex((child, index) => index > start && child.type === 'heading' && child.depth <= 2);
+        return { id: explicit ? node.data.sectionId : generated, title, depth: 2, start, end: end < 0 ? children.length : end, explicit, generated };
+    });
+    const owners = new Map();
+    for (const item of sections) {
+        if (owners.has(item.id))
+            throw new Error(`${label}: duplicate section ID ${item.id}`);
+        owners.set(item.id, item.start);
+        if (item.explicit && sections.some(other => other.start !== item.start && other.generated === item.id))
+            throw new Error(`${label}: explicit section ID ${item.id} conflicts with another heading's derived ID`);
+    }
+    return sections.map(({ generated, ...section }) => section);
+}
+export function validateStandaloneSectionDeclarations(value, label = 'document') {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        throw new Error(`${label}: standaloneSections must be an array`);
+    const seen = new Set();
+    for (const item of value) {
+        const legacy = typeof item === 'string';
+        if (legacy ? !item.trim() || item !== item.trim() : !item || typeof item !== 'object' || Array.isArray(item) || Object.keys(item).sort().join(',') !== 'context,id' || item.context !== 'section' || !validSectionId(item.id)) {
+            throw new Error(`${label}: standaloneSections needs trimmed heading titles or { id, context: section } declarations`);
+        }
+        const key = legacy ? `title:${item}` : `id:${item.id}`;
+        if (seen.has(key))
+            throw new Error(`${label}: standaloneSections declarations must be unique`);
+        seen.add(key);
+    }
+}
+export function validateStandaloneSections(tree, declarations = [], label = 'document') {
+    validateStandaloneSectionDeclarations(declarations, label);
+    const sections = sectionIdentities(tree, label);
+    const seen = new Set();
+    for (const declaration of declarations) {
+        const matches = sections.filter(section => typeof declaration === 'string' ? section.title === declaration : section.id === declaration.id);
+        if (matches.length !== 1)
+            throw new Error(`${label}: standaloneSections ${typeof declaration === 'string' ? `title "${declaration}"` : `ID "${declaration.id}"`} must match exactly one top-level level-two heading`);
+        if (seen.has(matches[0].start))
+            throw new Error(`${label}: standaloneSections declares the same heading more than once`);
+        seen.add(matches[0].start);
+    }
+    return sections;
+}
+/** Slice-only delivery is a distinct author approval from contextual discovery. */
+export function selectSection(tree, id, declarations = [], label = 'document') {
+    const section = validateStandaloneSections(tree, declarations, label).find(item => item.id === id);
+    if (!section)
+        throw new Error(`${label}: unknown section ${id}`);
+    if (!declarations.some(item => typeof item !== 'string' && item.id === id && item.context === 'section'))
+        throw new Error(`${label}: section ${id} needs standaloneSections: [{ id: ${id}, context: section }] approval`);
+    const definitions = new Map();
+    const key = (node) => `${node.type === 'footnoteDefinition' || node.type === 'footnoteReference' ? 'footnote' : 'link'}:${node.identifier}`;
+    const comparable = (value) => Array.isArray(value) ? value.map(comparable) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).filter(([name]) => name !== 'position' && name !== 'exportSourceKey').map(([name, item]) => [name, comparable(item)])) : value;
+    const collect = (node) => {
+        if (['definition', 'footnoteDefinition'].includes(node.type)) {
+            const previous = definitions.get(key(node));
+            if (previous && JSON.stringify(comparable(previous)) !== JSON.stringify(comparable(node)))
+                throw new Error(`${label}: ambiguous definition ${node.identifier} for section ${id}`);
+            if (!previous)
+                definitions.set(key(node), node);
+        }
+        node.children?.forEach(collect);
+    };
+    collect(tree);
+    const strip = (node) => ['definition', 'footnoteDefinition'].includes(node.type) ? [] : [{ ...node, ...(node.children ? { children: node.children.flatMap(strip) } : {}) }];
+    const nodes = tree.children.slice(section.start, section.end).flatMap(strip);
+    const included = new Set();
+    const closure = [];
+    const visit = (node) => {
+        if (['linkReference', 'imageReference', 'footnoteReference'].includes(node.type)) {
+            const identity = key(node);
+            if (!included.has(identity)) {
+                included.add(identity);
+                const definition = definitions.get(identity);
+                if (!definition)
+                    throw new Error(`${label}: section ${id} has an unresolved reference ${node.identifier}`);
+                closure.push(definition);
+                visit(definition);
+            }
+        }
+        node.children?.forEach(visit);
+    };
+    nodes.forEach(visit);
+    return { section, tree: { type: 'root', children: [...nodes, ...closure] } };
+}

package/examples/content-delivery/README.md

@@ -0,0 +1,87 @@
+# Use pages, sections, and snippets in an application
+
+This example uses the public `@shoalrun/cli/content` client to show a whole
+billing guide, its independently approved refund section, and two simultaneous
+copies of one reusable policy snippet. The app owns the drawer, buttons, focus,
+and styling. Shoalrun supplies passive content and typed resource references.
+
+Copy this directory into a project with Shoalrun installed. From the copied
+example directory, run:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help/releases/demo
+node preview.mjs
+```
+
+Open `http://127.0.0.1:8775/settings/billing`. Choose **Billing guide** to read the
+page or **How to request a refund** to read only its named section. Follow the
+section's billing-overview link. Both cards display the same snippet, with
+independent footnote anchors. Escape closes the drawer and restores focus.
+
+The preview resolves the installed package's public `@shoalrun/cli/content`
+entrypoint and serves only its browser-safe modules. It does not serve arbitrary
+package or project files. In a real app, import that entrypoint through your
+existing browser bundler.
+
+## Author the resources
+
+The page gives its root heading a stable ID with
+`## Request a refund <Anchor id="refunds" />`. Its page metadata separately
+declares `{ id: refunds, context: section }` in `standaloneSections`, approving
+that section as useful without the page introduction.
+
+The export target selects a page reference, a section reference, and a named
+snippet instance with a fixed `days` value. `snippets/refund-window.mdx` is also
+included in the page, so the reusable wording stays in one source. Snippet
+content is block content; this example does not insert it inside a button or
+promise that arbitrary snippets are suitable for inline tooltips.
+
+## Keep serving independent from presentation
+
+`app.js` opens a snapshot with `openManifestContentSource`, reads resources by
+typed reference, and uses `mountContent` for the HTML. Each mount receives fresh
+DOM IDs and remapped anchors. The drawer aborts superseded requests and ignores
+late results after closing. These are application behaviors, not server duties.
+
+The preview also serves the read-only REST API at `/content/v1`. Open
+`http://127.0.0.1:8775/settings/billing?delivery=rest` to use
+`openRestContentSource` through the same snapshot interface. Both modes deliver
+identical content and use the same application rendering code.
+
+The server uses `createContentRestHandler` from `@shoalrun/cli/content/server`.
+It pins one approved snapshot per publication at startup and retains no revision
+history. All requests select `channel`, `version`, and `language`. List resources
+first, then use the returned key and revision for subsequent reads:
+
+```sh
+curl 'http://127.0.0.1:8775/content/v1/resources?channel=production&version=current&language=en'
+```
+
+`GET /resources/{key}` returns metadata; `GET
+/resources/{key}/representations/{format}` returns HTML or Markdown. Append the
+same publication parameters and `revision` returned by the list. HEAD and
+conditional requests with `If-None-Match` are supported. The complete
+[OpenAPI contract](../../schemas/content-rest.openapi.json) describes responses,
+errors, and caching. The HTTP contract's `v1` is separate from package versions.
+
+Keep `/help/releases/demo/` served alongside the API: the REST adapter preserves
+exported bytes, including static links and asset URLs. Browser clients require
+the application origin and HTTPS or localhost. This local example does not add
+authentication, search, editing, or a production hosting service.
+
+## Publish complete revisions
+
+The example uses `/help/releases/demo/` as a fixed demonstration revision.
+Production should use a new directory and matching `publicBase` for each release,
+upload the complete export, and only then update the app's manifest URL or
+release pointer. Retain revisions still used by open clients. Do not overwrite
+files underneath an existing snapshot.
+
+Use `--previous-manifest PATH --fail-on-removed` to detect removed public resource
+references before replacing output. Without a baseline, the export reports that
+removal coverage was unavailable. API review candidates are not approved content:
+the client refuses a manifest whose review status is `required`.
+
+The content comes from this project's trusted build. The client checks the
+manifest and content digests; these establish consistency with that manifest,
+not trust in an arbitrary third-party publisher. Preserve the export's notices.

package/examples/content-delivery/app.js

@@ -0,0 +1,91 @@
+import { openManifestContentSource, openRestContentSource, mountContent } from '/shoalrun/content-delivery.js';
+
+// The app owns interaction. A future server-backed source can supply this same
+// snapshot interface; the drawer does not depend on manifest layout or filenames.
+const lifetime = new AbortController();
+const source = new URLSearchParams(location.search).get('delivery') === 'rest'
+  ? openRestContentSource({ baseUrl: '/content/v1', publication: { channel: 'production', version: 'current', language: 'en' }, signal: lifetime.signal })
+  : openManifestContentSource({ manifestUrl: '/help/releases/demo/manifest.json', signal: lifetime.signal });
+const drawer = document.querySelector('#drawer');
+const container = document.querySelector('#help-content');
+let generation = 0;
+let pending;
+let mounted;
+let opener;
+let snapshot;
+let disposed = false;
+const notes = [];
+
+async function openHelp(ref, fragment) {
+  if (disposed) return;
+  const ticket = ++generation;
+  pending?.abort();
+  const controller = new AbortController();
+  pending = controller;
+  try {
+    const content = await source;
+    if (ticket !== generation) return;
+    const result = await content.get(ref, { format: 'html', signal: controller.signal });
+    if (ticket !== generation) return;
+    mounted?.unmount();
+    mounted = mountContent(container, result);
+    drawer.hidden = false;
+    const anchor = fragment && mounted.anchors.find(item => item.id === fragment || item.exportedId === fragment);
+    const target = anchor ? container.querySelector(`#${CSS.escape(anchor.exportedId)}`) : container.querySelector('h1,h2,h3') ?? container;
+    // Stable aliases precede the visible heading. Focus the heading rather than
+    // an empty aria-hidden alias so keyboard and screen-reader users get context.
+    const focus = target?.getAttribute('aria-hidden') === 'true' && target.nextElementSibling?.matches('h1,h2,h3,h4,h5,h6')
+      ? target.nextElementSibling : target;
+    if (focus) { focus.tabIndex = -1; focus.focus({ preventScroll: true }); }
+    if (anchor) focus?.scrollIntoView();
+    else drawer.scrollTop = 0;
+  } catch (error) {
+    if (ticket !== generation || controller.signal.aborted) return;
+    mounted?.unmount();
+    mounted = undefined;
+    container.textContent = `Help could not be loaded: ${error.message}`;
+    drawer.hidden = false;
+    document.querySelector('#close').focus();
+  }
+}
+function closeHelp() {
+  ++generation;
+  pending?.abort();
+  mounted?.unmount();
+  mounted = undefined;
+  drawer.hidden = true;
+  opener?.focus();
+}
+for (const [id, ref] of [
+  ['page-help', { kind: 'page', documentId: 'guide.billing' }],
+  ['section-help', { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' }],
+]) document.getElementById(id).addEventListener('click', event => { opener = event.currentTarget; openHelp(ref); });
+container.addEventListener('click', event => {
+  const anchor = event.target.closest('a[data-export-link]');
+  const link = anchor && mounted?.links.find(item => item.key === anchor.dataset.exportLink);
+  if (link?.kind !== 'resource') return;
+  event.preventDefault();
+  openHelp(link.ref, link.fragment);
+});
+document.querySelector('#close').addEventListener('click', closeHelp);
+drawer.addEventListener('keydown', event => { if (event.key === 'Escape') { event.preventDefault(); closeHelp(); } });
+
+source.then(async content => {
+  if (disposed) { content.dispose(); return; }
+  snapshot = content;
+  const result = await content.get({ kind: 'snippet', id: 'billing.refund-window' }, { format: 'html', signal: lifetime.signal });
+  if (disposed) return;
+  for (const id of ['plan-note', 'invoice-note']) notes.push(mountContent(document.getElementById(id), result));
+}).catch(error => { if (!disposed) document.querySelector('#status').textContent = `Help could not be loaded: ${error.message}`; });
+window.addEventListener('pagehide', event => {
+  // A back/forward-cache entry resumes this same module and snapshot. Preserve
+  // its state while the browser freezes it; only tear down a discarded page.
+  if (event.persisted) return;
+  disposed = true;
+  ++generation;
+  lifetime.abort();
+  pending?.abort();
+  mounted?.unmount();
+  notes.forEach(note => note.unmount());
+  snapshot?.dispose();
+});

package/examples/content-delivery/content/billing.mdx

@@ -0,0 +1,22 @@
+---
+id: guide.billing
+title: Billing help
+summary: Find invoices and request a refund for your workspace.
+slug: /billing
+standaloneSections:
+  - { id: refunds, context: section }
+---
+
+Use this guide to manage payments for your workspace.
+
+## Find an invoice
+
+Open **Settings → Billing → Invoices** and choose the payment date.
+
+## Request a refund <Anchor id="refunds" />
+
+<Snippet id="shared.refund-window" />
+
+The workspace owner can open **Settings → Billing → Contact support** and provide the invoice number. Support confirms eligibility before issuing a refund.
+
+[Read the billing overview](doc:guide.billing).

package/examples/content-delivery/docs.config.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+site:
+  title: Acme billing help
+  origin: https://docs.example.com
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+snippets:
+  shared.refund-window:
+    file: ./snippets/refund-window.mdx
+    variables:
+      days: { type: number, default: 30 }
+exports:
+  app-help:
+    formats: [html, markdown]
+    publicBase: /help/releases/demo/
+    resources:
+      - { kind: page, documentId: guide.billing }
+      - { kind: section, documentId: guide.billing, sectionId: refunds }
+      - kind: snippet
+        id: billing.refund-window
+        snippetId: shared.refund-window
+        title: Refund window
+        summary: When a workspace can request a refund.
+        values: { days: 30 }

package/examples/content-delivery/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Acme billing · Content delivery example</title>
+<style>
+  *{box-sizing:border-box}body{font:16px/1.6 system-ui,sans-serif;color:#193b2c;background:#f4f7f4;margin:0}main{max-width:60rem;margin:3rem auto;padding:0 1.5rem}h1{line-height:1.2}button,a{color:#205b3b}button{font:inherit;cursor:pointer;padding:.5rem .8rem;border:1px solid #aac5b2;border-radius:.4rem;background:white}button:focus-visible,a:focus-visible{outline:3px solid #47926b;outline-offset:3px}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(16rem,1fr));gap:1rem}.card{padding:1.5rem;border:1px solid #d6e3d9;border-radius:.75rem;background:white}.card h2{margin-top:0}.help-content{font-size:.95rem}.help-content h2{font-size:1.3rem}.help-content a{overflow-wrap:anywhere}#drawer{position:fixed;inset:0 0 0 auto;width:min(36rem,95vw);padding:1.5rem;background:white;overflow:auto;box-shadow:-1rem 0 3rem #193b2c22}#drawer[hidden]{display:none}.drawer-header{display:flex;align-items:center;justify-content:space-between;gap:1rem;border-bottom:1px solid #d6e3d9;padding-bottom:1rem}.muted{color:#526f5d}#status{min-height:1.5em}
+</style>
+<main>
+  <p class="muted">Acme workspace</p>
+  <h1>Billing</h1>
+  <p>Manage your plan and recent payments.</p>
+  <p><button id="page-help">Billing guide</button> <button id="section-help">How to request a refund</button></p>
+  <div class="cards">
+    <section class="card" aria-labelledby="plan-title"><h2 id="plan-title">Current plan</h2><p>Team · $24 per month</p><div id="plan-note" class="help-content" aria-label="Plan refund policy"></div></section>
+    <section class="card" aria-labelledby="invoice-title"><h2 id="invoice-title">Recent payment</h2><p>Invoice INV-1042 · $24</p><div id="invoice-note" class="help-content" aria-label="Invoice refund policy"></div></section>
+  </div>
+  <p id="status" role="status" class="muted"></p>
+</main>
+<aside id="drawer" aria-label="Billing help" hidden>
+  <div class="drawer-header"><strong>Billing help</strong><button id="close">Close help</button></div>
+  <div id="help-content" class="help-content" aria-live="polite"></div>
+</aside>
+<script type="module" src="/app.js"></script>
+</html>

package/examples/content-delivery/preview.mjs

@@ -0,0 +1,86 @@
+import { createServer } from 'node:http';
+import { readFile, realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { openManifestContentSource } from '@shoalrun/cli/content';
+import { createContentRestHandler } from '@shoalrun/cli/content/server';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+let port = 8775;
+let directory = path.join(root, 'public/help/releases/demo');
+const args = process.argv.slice(2);
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === '--help') { console.log('Usage: node preview.mjs [--port PORT] [--help-directory DIRECTORY]'); process.exit(0); }
+  if (args[index] === '--port') port = Number(args[++index]);
+  else if (args[index] === '--help-directory' && args[index + 1]) directory = path.resolve(args[++index]);
+  else throw new Error('Unknown preview option');
+}
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port');
+const help = await realpath(directory);
+const clientEntry = fileURLToPath(import.meta.resolve('@shoalrun/cli/content'));
+const clientDirectory = path.dirname(clientEntry);
+// Serve only the public browser entry and its browser-safe dependencies.
+// This is deliberately not a generic node_modules or repository file server.
+const clientFiles = new Map([
+  ['/shoalrun/content-delivery.js', clientEntry],
+  ['/shoalrun/content-delivery-contract.js', path.join(clientDirectory, 'content-delivery-contract.js')],
+  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
+]);
+const mount = '/help/releases/demo/';
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.md': 'text/markdown; charset=utf-8', '.png': 'image/png' };
+// Pin one approved bundle at startup. The injected transport reads only this
+// bundle; realpath containment applies even to symlinks. It does not fetch URLs.
+const source = await openManifestContentSource({
+  manifestUrl: `http://content.local${mount}manifest.json`,
+  fetch: async (input, options) => {
+    options?.signal?.throwIfAborted();
+    const url = new URL(String(input));
+    if (url.origin !== 'http://content.local' || !url.pathname.startsWith(mount)) throw new Error('Outside bundle');
+    try {
+      const file = await realpath(path.join(help, url.pathname.slice(mount.length)));
+      if (!file.startsWith(help + path.sep)) throw new Error('Outside bundle');
+      const body = await readFile(file, { signal: options?.signal ?? undefined });
+      return new Response(body, { headers: { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream' } });
+    } catch (error) {
+      options?.signal?.throwIfAborted();
+      return new Response(null, { status: 404 });
+    }
+  },
+});
+const rest = createContentRestHandler({ sources: [source] });
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url, 'http://127.0.0.1');
+  if (url.pathname === '/content/v1' || url.pathname.startsWith('/content/v1/')) {
+    const controller = new AbortController();
+    request.once('aborted', () => controller.abort());
+    response.once('close', () => { if (!response.writableEnded) controller.abort(); });
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(request.headers)) if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+      const result = await rest(new Request(url, { method: request.method, headers, signal: controller.signal }));
+      response.writeHead(result.status, Object.fromEntries(result.headers));
+      response.end(Buffer.from(await result.arrayBuffer()));
+    } catch {
+      if (!response.destroyed) { response.writeHead(500, { 'Cache-Control': 'no-store' }); response.end(); }
+    }
+    return;
+  }
+  if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405, { Allow: 'GET, HEAD' }); response.end(); return; }
+  try {
+    const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname);
+    let file = clientFiles.get(pathname);
+    if (!file && pathname.startsWith(mount)) {
+      file = await realpath(path.join(help, pathname.slice(mount.length)));
+      if (!file.startsWith(help + path.sep)) throw new Error('Invalid path');
+    }
+    if (!file && pathname === '/app.js') file = path.join(root, 'app.js');
+    if (!file && (pathname === '/' || pathname === '/settings/billing')) file = path.join(root, 'index.html');
+    if (!file) throw new Error('Not found');
+    const body = await readFile(file);
+    response.writeHead(200, { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream', 'X-Content-Type-Options': 'nosniff' });
+    response.end(request.method === 'HEAD' ? undefined : body);
+  } catch { response.writeHead(404); response.end('Not found'); }
+});
+server.listen(port, '127.0.0.1', () => console.log(`Content delivery demo: http://127.0.0.1:${server.address().port}/settings/billing`));
+process.on('SIGINT', () => server.close(() => { source.dispose(); process.exit(0); }));
+process.on('SIGTERM', () => server.close(() => { source.dispose(); process.exit(0); }));

package/examples/content-delivery/snippets/refund-window.mdx

@@ -0,0 +1,3 @@
+You can request a refund within <Var name="days" /> days of payment.[^terms]
+
+[^terms]: Refund eligibility depends on the workspace agreement.

package/examples/help-drawer/README.md

@@ -18,10 +18,10 @@ billing help buttons; follow the in-drawer links and inspect the images.
 The full account guide is omitted from the export and links to the configured
 example documentation host; replace that origin for your own project.
 
-`manifest.json` maps stable document IDs to representation files. `app.js`
+`manifest.json` maps typed page references to representation files in its `resources` array. `app.js`
 fetches the HTML, inserts it into one content container, and intercepts anchors
 marked `data-export-link`. The corresponding manifest link supplies the target
-document ID and original fragment. Other links use their ordinary destinations.
+page reference and original fragment. Other links use their ordinary destinations.
 
 `/help/` is an example path, not a required Shoalrun directory. You can choose
 another root-relative path, such as `/resources/`. Set `publicBase` to that path,

package/examples/help-drawer/app.js

@@ -14,7 +14,7 @@ let current;
 let request = 0;
 let opener;
 async function openHelp(id, fragment) {
-  const document = manifest.documents.find(document => document.id === id);
+  const document = manifest.resources.find(resource => resource.ref.kind === 'page' && resource.ref.documentId === id);
   if (!document?.representations.html) throw new Error(`No HTML help for ${id}`);
   const ticket = ++request;
   const response = await fetch(manifest.publicBase + document.representations.html.path);
@@ -43,9 +43,9 @@ content.addEventListener('click', event => {
   const anchor = event.target.closest('a[data-export-link]');
   if (!anchor) return;
   const link = current?.representations.html.links.find(link => link.key === anchor.dataset.exportLink);
-  if (link?.kind !== 'document') return; // Canonical fallbacks open as ordinary links.
+  if (link?.kind !== 'resource' || link.ref?.kind !== 'page') return; // Canonical fallbacks open as ordinary links.
   event.preventDefault();
-  openHelp(link.documentId, link.fragment).catch(showError);
+  openHelp(link.ref.documentId, link.fragment).catch(showError);
 });
 function closeHelp() { request++; drawer.hidden = true; opener?.focus(); }
 document.querySelector('#close').addEventListener('click', closeHelp);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -11,9 +11,11 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
+    "./content": "./dist/content-delivery.js",
     "./authoring": "./dist/authoring-api.js",
     "./*": "./*",
-    "./components": "./dist/components.js"
+    "./components": "./dist/components.js",
+    "./content/server": "./dist/content-rest-server.js"
   },
   "files": [
     "dist",
@@ -23,7 +25,7 @@
     "styles",
     "templates",
     "examples",
-    "!examples/help-drawer/public/**",
+    "!examples/**/public/**",
     "!examples/**/node_modules/**",
     "example-configs",
     "!example-configs/**/.shoalrun/**",
@@ -32,6 +34,7 @@
     "README.md",
     "AUTHORING.md",
     "schemas/content-export.schema.json",
+    "schemas/content-rest.openapi.json",
     "CHANGELOG.md",
     "!**/*.local.md",
     "!**/*.override.md",