@shoalrun/cli 0.1.0-alpha.19 → 0.1.0-beta.1

package/agent-docs/start.md

@@ -16,11 +16,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Prerequisites
 
@@ -30,13 +30,13 @@ The public npm package needs no account or token.
 
 ## Start your own project
 
-Install an exact version of the alpha and initialize the minimal starter:
+Install an exact version of the beta and initialize the minimal starter:
 
 ```sh
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/start.sections/add-the-page-to-navigation.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Add the page to navigation
 

package/agent-docs/start.sections/build-and-check-both-outputs.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Build and check both outputs
 

package/agent-docs/start.sections/build-this-site.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Build this site
 

package/agent-docs/start.sections/check-writing-style.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Check writing style
 

package/agent-docs/start.sections/create-a-page.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Create a page
 

package/agent-docs/start.sections/make-it-yours.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Make it yours
 

package/agent-docs/start.sections/migrating-from-github-packages.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Migrating from GitHub Packages
 

package/agent-docs/start.sections/prerequisites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Prerequisites
 

package/agent-docs/start.sections/related-reading.md

@@ -16,13 +16,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Related reading
 

package/agent-docs/start.sections/start-your-own-project.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,17 +28,17 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
 
 ## Start your own project
 
-Install an exact version of the alpha and initialize the minimal starter:
+Install an exact version of the beta and initialize the minimal starter:
 
 ```sh
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/status.md

@@ -16,11 +16,11 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Project > Project status
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
-Shoalrun is an alpha for publishing documentation for people and agents from the same source. This site is built with it. Install the public `@shoalrun/cli` npm package through [Getting started](https://www.shoalrun.com/start.md). No account or package token is needed.
+Shoalrun is in beta for publishing documentation for people and agents from the same source. This site is built with it. Install the public `@shoalrun/cli` npm package through [Getting started](https://www.shoalrun.com/start.md). No account or package token is needed.
 
-The [features overview](https://www.shoalrun.com/features.md) summarizes the platform on one page. The capabilities below include `0.1.0-alpha.18`.
+The [features overview](https://www.shoalrun.com/features.md) summarizes the platform on one page. The capabilities below include `0.1.0-beta.1`.
 
 ## What works today
 
@@ -30,6 +30,8 @@ The [features overview](https://www.shoalrun.com/features.md) summarizes the pla
 
 - **Rich documentation pages.** Built-in [components](https://www.shoalrun.com/author/components.md) include tabs, callouts, tables, code walkthroughs, steps, timelines, and API embeds, with defined Markdown output. [Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render D2 and Mermaid syntax as SVG during the build; Pele renders the Mermaid diagrams. Markdown retains the diagram source and explanation.
 
+- **Code highlighting and PDFs.** Register [custom code languages](https://www.shoalrun.com/author/components/code-blocks.md) and offer [styled page printing or PDF exports](https://www.shoalrun.com/publish/pdf.md), including optional publication manuals and the `shoalrun-pdf` agent skill.
+
 - **Reader controls.** [File trees](https://www.shoalrun.com/author/components/file-tree.md) have expandable folders and keyboard navigation. [Collapsible groups](https://www.shoalrun.com/author/components/collapsible.md) join related disclosures without gaps. Authors can synchronize related [tabs](https://www.shoalrun.com/author/components/tabs.md) and add captions or expanded viewing to [images](https://www.shoalrun.com/author/components/images.md).
 
 - **Configurable sites.** Themes, palettes, layouts, headers, and footers shape the presentation. [Navigation tabs](https://www.shoalrun.com/author/navigation.md) organize larger sites into sections. Explicit [versions and languages](https://www.shoalrun.com/publish/publications.md) publish separate page variants, while reader views tailor navigation and marked content to different audiences.
@@ -60,7 +62,7 @@ These are intended additions, without a promised release date.
 
 ## Current limits
 
-- **Alpha stability.** Configuration, extension points, and output formats can still change. There is no stable release or compatibility promise yet.
+- **Beta stability.** Configuration, extension points, and output formats can still change. There is no stable release or compatibility promise yet.
 - **Component extensibility.** [Trusted custom components](https://www.shoalrun.com/author/components/custom.md) lower into shared content, with a portable authoring skill. Arbitrary executable MDX remains unsupported. Project CSS, browser modules, and configured build extensions are trusted project code.
 - **API coverage.** OpenAPI and JSON Schema support is partial; check the [support reference](https://www.shoalrun.com/api-docs/support.md) against your source. Request examples are copyable, but Shoalrun doesn't provide a live API explorer that sends requests.
 - **Private content.** Reader views don't restrict access to published files. Shoalrun has no built-in reader authentication, and its HTTP MCP endpoint currently serves one selected public publication. Host-level authorization is a separate responsibility.
@@ -82,4 +84,4 @@ Automatic skill generation and general agent orchestration are [deliberate non-g
 
 - [Changelog](https://www.shoalrun.com/changelog.md) — Check implemented capabilities and the remaining release work.
 
-- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — Check the alpha's capabilities and current limits.
+- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — Check the current capabilities and limits.

package/agent-docs/what-is-shoalrun.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > What is Shoalrun?
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Shoalrun is a documentation compiler for product and API docs. It reads project configuration, Markdown and supported MDX pages, and optional local OpenAPI files. From those sources, it builds a site for people and readable Markdown pages for agents. The normal build is deterministic: it makes no model calls or network requests.
 
@@ -43,7 +43,7 @@ Optional ingredients, recipes, and cookbooks extend the same idea to tasks. An i
 
 ## Where it stands
 
-The public documentation site shows output built by Shoalrun. Install the alpha CLI from npm using [Getting started](https://www.shoalrun.com/start.md). The [project status](https://www.shoalrun.com/status.md) lists implemented capabilities and current limits.
+The public documentation site shows output built by Shoalrun. Install the beta CLI from npm using [Getting started](https://www.shoalrun.com/start.md). The [project status](https://www.shoalrun.com/status.md) lists implemented capabilities and current limits.
 
 ## Related reading
 

package/assets/copy-markdown.js

@@ -1,6 +1,6 @@
 const button = document.querySelector('[data-copy-markdown]');
 const status = document.querySelector('[data-copy-markdown-status]');
-const link = document.querySelector('.page-formats a');
+const link = document.querySelector('[data-markdown-link]');
 if (button && status && link) {
   button.hidden = false;
   button.addEventListener('click', async () => {

package/assets/print-view.js

@@ -0,0 +1,165 @@
+const htmlTags = new Set('a abbr article b blockquote br caption code col colgroup dd del div dl dt em figcaption figure header footer h1 h2 h3 h4 h5 h6 hr i img kbd li ol p pre progress s section small span strong sub sup table tbody td th thead time tr ul'.split(' '));
+const mathTags = new Set('math semantics annotation mrow mi mn mo mtext mspace ms mfrac msqrt mroot mstyle merror mpadded mphantom mfenced menclose msub msup msubsup munder mover munderover mmultiscripts mprescripts none mtable mtr mtd mlabeledtr'.split(' '));
+const svgTags = new Set('svg g defs marker path rect circle ellipse line polyline polygon text tspan title desc linearGradient radialGradient stop clipPath pattern symbol use'.toLowerCase().split(' '));
+const attributes = new Set('id class alt title colspan rowspan start reversed value max datetime scope align role aria-label aria-labelledby aria-describedby aria-hidden data-document-type'.split(' '));
+const mathAttributes = new Set('xmlns display mathvariant encoding stretchy fence separator accent accentunder form lspace rspace minsize maxsize symmetric largeop movablelimits scriptlevel displaystyle linethickness notation columnalign columnspacing rowalign rowspacing columnspan rowspan width height depth voffset'.split(' '));
+const svgAttributes = new Set('viewbox width height x y x1 y1 x2 y2 cx cy r rx ry d points fill stroke stroke-width stroke-linecap stroke-linejoin opacity fill-opacity stroke-opacity transform preserveaspectratio marker-start marker-mid marker-end offset stop-color stop-opacity clip-path fill-rule clip-rule'.split(' '));
+const blocked = new Set('script style iframe object embed link base meta form select textarea audio video canvas noscript'.split(' '));
+const browserOnly = new Set('doc-tablist reader-filter-slot reader-filter-controls reader-outside-view heading-anchor code-copy copy-status file-tree-controls doc-image-expand hero-actions example-picker api-view-control code-samples-bar'.split(' '));
+const referrerPolicies = new Set('no-referrer no-referrer-when-downgrade origin origin-when-cross-origin same-origin strict-origin strict-origin-when-cross-origin unsafe-url'.split(' '));
+
+export function printUrl(value, base, image = false) {
+  try {
+    const url = new URL(value, base);
+    if (url.username || url.password || !['http:', 'https:', ...(image ? [] : ['mailto:', 'tel:'])].includes(url.protocol)) return undefined;
+    const current = new URL(base);
+    if (!image && url.origin === current.origin && url.pathname.replace(/\/$/, '') === current.pathname.replace(/\/$/, '') && url.hash) return url.hash;
+    return url.href;
+  } catch { return undefined; }
+}
+
+export function printPolicy(base) {
+  const url = new URL(base);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('Print view requires a website origin');
+  // about:blank inherits access to its creator, but Firefox can resolve CSP 'self'
+  // against the blank document. Grant assets only to the explicit website origin.
+  return `default-src 'none'; img-src ${url.origin} https:; font-src ${url.origin}; style-src ${url.origin} 'unsafe-inline'; script-src 'none'; base-uri 'none'; form-action 'none'`;
+}
+
+/** Copy semantic content, not the website's controls or executable DOM. */
+export function printNodes(node, base) {
+  if (node.nodeType === 3) return [{ text: node.textContent ?? '' }];
+  if (node.nodeType !== 1) return [];
+  const tag = node.localName.toLowerCase();
+  const classes = (node.getAttribute('class') ?? '').split(/\s+/);
+  if (blocked.has(tag) || classes.some(name => browserOnly.has(name))) return [];
+  if (tag === 'button') return [];
+  if (tag === 'input') return node.getAttribute('type') === 'checkbox' ? [{ tag: 'span', attrs: {}, children: [{ text: node.hasAttribute('checked') ? '☑ ' : '☐ ' }] }] : [];
+  const namespace = node.namespaceURI;
+  const math = namespace === 'http://www.w3.org/1998/Math/MathML';
+  const svg = namespace === 'http://www.w3.org/2000/svg';
+  let children = [...node.childNodes].flatMap(child => printNodes(child, base));
+  if (tag === 'details' || tag === 'summary') return [{ tag: tag === 'details' ? 'section' : 'h3', attrs: {}, children }];
+  if (!(math ? mathTags : svg ? svgTags : htmlTags).has(tag)) return children;
+  const attrs = {};
+  for (const attribute of [...node.attributes]) {
+    const name = attribute.name.toLowerCase(), value = attribute.value;
+    if (/^on/.test(name) || ['hidden', 'aria-hidden', 'srcset', 'tabindex', 'contenteditable'].includes(name)) continue;
+    if (name === 'href' || name === 'xlink:href') {
+      if (svg) { if (/^#[A-Za-z0-9_.:-]+$/.test(value)) attrs.href = value; }
+      else { const url = printUrl(value, base); if (url) attrs.href = url; }
+    } else if (name === 'src' && tag === 'img') {
+      const url = printUrl(node.currentSrc || value, base, true);
+      if (url) attrs.src = url;
+    } else if (name === 'crossorigin' && tag === 'img') {
+      // Empty and invalid CORS attribute values both mean anonymous in HTML.
+      attrs.crossorigin = value.toLowerCase() === 'use-credentials' ? 'use-credentials' : 'anonymous';
+    } else if (name === 'referrerpolicy' && tag === 'img') {
+      const policy = value.toLowerCase();
+      if (referrerPolicies.has(policy)) attrs.referrerpolicy = policy;
+    } else if (name === 'style') {
+      // Site-theme code tokens remain readable through the print theme's variables.
+      if (/^(?:color\s*:\s*(?:#[0-9a-f]{3,8}|var\(--code-(?:foreground|token-[a-z-]+)\));?\s*)+$/i.test(value)) attrs.style = value;
+    } else if (attributes.has(name) || math && mathAttributes.has(name)) attrs[name] = value;
+    // CSS escapes can hide url() and its protocol; retain only literal SVG values.
+    else if (svg && svgAttributes.has(name) && !/[\\\u0000-\u001f]|javascript:|https?:|data:|url\((?!\s*#)/i.test(value)) attrs[attribute.name] = value;
+  }
+  if (tag === 'img') {
+    if (!attrs.src) return [{ tag: 'p', attrs: {}, children: [{ text: attrs.alt ? `Image: ${attrs.alt}` : 'Image unavailable for printing.' }] }];
+    attrs.loading = 'eager';
+  }
+  if (tag === 'a' && attrs.href && !attrs.href.startsWith('#')) { attrs.target = '_blank'; attrs.rel = 'noopener noreferrer'; }
+  const label = node.getAttribute('data-reader-print-label');
+  if (label) children = [{ tag: 'p', attrs: { class: 'pdf-reader-label' }, children: [{ text: label }] }, ...children];
+  return [{ tag: node.localName, ...(math || svg ? { namespace } : {}), attrs, children }];
+}
+
+export function materialize(doc, node) {
+  if (node.text !== undefined) return doc.createTextNode(node.text);
+  const result = node.namespace ? doc.createElementNS(node.namespace, node.tag) : doc.createElement(node.tag);
+  // Setting src can start a request immediately, even on a detached image.
+  for (const [name, value] of Object.entries(node.attrs)) if (name !== 'src') result.setAttribute(name, value);
+  if (node.attrs.src !== undefined) result.setAttribute('src', node.attrs.src);
+  for (const child of node.children) result.append(materialize(doc, child));
+  return result;
+}
+function element(doc, tag, text, className) {
+  const result = doc.createElement(tag);
+  if (text !== undefined) result.textContent = text;
+  if (className) result.className = className;
+  return result;
+}
+function marginContent(value, title) {
+  return value.split(/(\{title\}|\{page\}|\{pages\})/).filter(Boolean).map(part => part === '{page}' ? 'counter(page)' : part === '{pages}' ? 'counter(pages)' : JSON.stringify(part === '{title}' ? title : part)).join(' ');
+}
+
+export async function populatePrintView(view, source, metadata, settings, signal) {
+  if (view.closed || signal?.aborted) throw new Error('Print view was closed or cancelled');
+  const doc = view.document;
+  view.opener = null;
+  doc.documentElement.lang = metadata.publication?.language ?? source.documentElement.lang ?? 'en';
+  doc.head.replaceChildren();
+  doc.title = metadata.title;
+  const charset = element(doc, 'meta'); charset.setAttribute('charset', 'utf-8'); doc.head.append(charset);
+  const policy = element(doc, 'meta'); policy.setAttribute('http-equiv', 'Content-Security-Policy');
+  policy.setAttribute('content', printPolicy(source.location.href));
+  doc.head.append(policy);
+  const stylesheet = element(doc, 'link'); stylesheet.rel = 'stylesheet'; stylesheet.href = new URL(settings.stylesheet, source.location.href).href;
+  if (new URL(stylesheet.href).origin !== source.location.origin) throw new Error('Print theme must be local');
+  const styleReady = new Promise((resolve, reject) => { stylesheet.onload = resolve; stylesheet.onerror = () => reject(new Error('Print theme could not load')); });
+  doc.head.append(stylesheet);
+  const margins = element(doc, 'style');
+  margins.textContent = `@page{${settings.header ? `@top-center{content:${marginContent(settings.header, metadata.title)};font:9px Arial,sans-serif;color:#555}` : ''}${settings.footer ? `@bottom-center{content:${marginContent(settings.footer, metadata.title)};font:9px Arial,sans-serif;color:#555}` : ''}}`;
+  doc.head.append(margins);
+  const tools = element(doc, 'nav', undefined, 'pdf-print-tools'); tools.setAttribute('aria-label', 'Print controls');
+  const print = element(doc, 'button', 'Print PDF'); print.type = 'button'; print.disabled = true;
+  const close = element(doc, 'button', 'Close'); close.type = 'button'; close.addEventListener('click', () => view.close());
+  const note = element(doc, 'span', 'Preparing document…', 'pdf-print-note'); note.setAttribute('role', 'status');
+  tools.append(print, close, note);
+  doc.body.replaceChildren(tools);
+  const publication = Object.entries(metadata.publication ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => `${key}: ${value}`).join(' · ');
+  if (settings.cover) {
+    const cover = element(doc, 'section', undefined, 'pdf-cover');
+    if (settings.logo) { const logo = element(doc, 'img', undefined, 'pdf-logo'); logo.src = new URL(settings.logo, source.location.href).href; logo.alt = ''; cover.append(logo); }
+    cover.append(element(doc, 'h1', metadata.title));
+    if (settings.subtitle) cover.append(element(doc, 'p', settings.subtitle, 'pdf-subtitle'));
+    if (publication) cover.append(element(doc, 'p', publication, 'pdf-publication'));
+    doc.body.append(cover);
+  }
+  const chapter = element(doc, 'article', undefined, 'pdf-chapter');
+  const header = source.querySelector('main.content > .page-head');
+  if (header) for (const node of printNodes(header, source.location.href)) chapter.append(materialize(doc, node));
+  else chapter.append(element(doc, 'h1', metadata.title));
+  if (publication && !settings.cover) (chapter.querySelector('.page-head') ?? chapter).append(element(doc, 'p', publication, 'pdf-page-meta'));
+  const article = source.querySelector('main.content > article');
+  if (!article) throw new Error('Page content is unavailable');
+  for (const node of [...article.childNodes].flatMap(child => printNodes(child, source.location.href))) chapter.append(materialize(doc, node));
+  for (const examples of source.querySelectorAll('.examples')) for (const node of printNodes(examples, source.location.href)) chapter.append(materialize(doc, node));
+  if (settings.toc) {
+    const toc = element(doc, 'nav', undefined, 'pdf-toc'); toc.setAttribute('aria-label', 'Contents'); toc.append(element(doc, 'h1', 'Contents'));
+    const list = element(doc, 'ol');
+    let index = 0;
+    const usedIds = new Set([...chapter.querySelectorAll('[id]')].map(node => node.id));
+    for (const heading of chapter.querySelectorAll('h2,h3')) {
+      if (!heading.id) {
+        let id; do { id = `pdf-section-${++index}`; } while (usedIds.has(id));
+        heading.id = id; usedIds.add(id);
+      }
+      const item = element(doc, 'li'), link = element(doc, 'a', heading.textContent); link.setAttribute('href', `#${heading.id}`); item.append(link); list.append(item);
+    }
+    toc.append(list); doc.body.append(toc);
+  }
+  doc.body.append(chapter);
+  await styleReady;
+  await doc.fonts.ready;
+  for (const font of settings.fonts ?? []) {
+    const loaded = await doc.fonts.load(`${font.style ?? 'normal'} ${font.weight ?? 'normal'} 12px ${JSON.stringify(font.family)}`);
+    if (!loaded.length) throw new Error('A print font could not load');
+  }
+  await Promise.all([...doc.images].map(image => image.complete ? (image.naturalWidth ? Promise.resolve() : Promise.reject(new Error('A print image could not load'))) : new Promise((resolve, reject) => { image.onload = resolve; image.onerror = () => reject(new Error('A print image could not load')); })));
+  if (view.closed || signal?.aborted) throw new Error('Print view was closed or cancelled');
+  print.disabled = false; note.textContent = 'Choose Save as PDF in the print dialog.';
+  const trigger = () => { if (!view.closed) { view.focus(); view.print(); } };
+  print.addEventListener('click', trigger);
+  return trigger;
+}

package/assets/print.js

@@ -0,0 +1,63 @@
+import { populatePrintView } from './print-view.js';
+
+const buttons = document.querySelectorAll('[data-print-page]');
+const status = document.querySelector('[data-print-status]');
+let opened = [];
+let printing = false;
+
+const prepare = () => {
+  if (printing) return;
+  printing = true;
+  opened = [...document.querySelectorAll('main details:not([open]), .examples details:not([open])')];
+  for (const details of opened) details.open = true;
+};
+const restore = () => {
+  for (const details of opened) details.open = false;
+  opened = [];
+  printing = false;
+};
+window.addEventListener('beforeprint', prepare);
+window.addEventListener('afterprint', restore);
+for (const button of buttons) {
+  button.hidden = false;
+  button.addEventListener('click', async () => {
+    if (button.disabled) return;
+    button.disabled = true;
+    if (status) status.textContent = '';
+    let view;
+    try { view = window.open('', '_blank'); } catch { /* Browser policy may refuse the new view. */ }
+    if (!view) {
+      button.disabled = false;
+      if (status) status.textContent = 'Allow the print view to open, or use your browser’s Print command.';
+      return;
+    }
+    const controller = new AbortController();
+    let timer;
+    try {
+      view.document.title = 'Print preview';
+      view.document.body.textContent = 'Preparing document…';
+      const settingsUrl = new URL(button.dataset.printSettings, document.location.href);
+      if (settingsUrl.origin !== document.location.origin) throw new Error('Print settings must be local');
+      const work = async () => {
+        const response = await fetch(settingsUrl.href, { credentials: 'same-origin', signal: controller.signal });
+        if (!response.ok) throw new Error('Print theme could not load');
+        const text = await response.text();
+        if (text.length > 65536) throw new Error('Print settings are too large');
+        const settings = JSON.parse(text);
+        if (settings.schemaVersion !== 1 || typeof settings.stylesheet !== 'string') throw new Error('Invalid print settings');
+        const metadata = JSON.parse(document.querySelector('[data-print-page-meta]').textContent);
+        return populatePrintView(view, document, metadata, settings, controller.signal);
+      };
+      const print = await Promise.race([work(), new Promise((_, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(new Error('Print preparation timed out')); }, 20000);
+      })]);
+      clearTimeout(timer); timer = undefined;
+      print();
+    } catch {
+      restore();
+      const message = 'Could not prepare the print view. Use your browser’s Print command, or try again.';
+      if (status) status.textContent = message;
+      try { if (!view.closed) view.document.body.append(view.document.createTextNode(message)); } catch { /* The reader may have navigated away. */ }
+    } finally { clearTimeout(timer); button.disabled = false; }
+  });
+}

package/dist/artifact-bundle.d.ts

@@ -13,6 +13,7 @@ export type ArtifactPage = {
     sections?: import('./markdown-sections.js').MarkdownSection[];
 };
 export type ArtifactAssemblyInput = {
+    extraArtifacts?: Map<string, string | Buffer>;
     base: string;
     basePath: string;
     publicPath: (route: string) => string;

package/dist/artifact-bundle.js

@@ -38,6 +38,8 @@ export async function assembleArtifacts(input) {
             artifactDirectories.add(parent);
         artifacts.set(normalized, data);
     };
+    for (const [route, bytes] of input.extraArtifacts ?? [])
+        addArtifact(route, bytes);
     const addPublicArtifact = (route, data) => addArtifact(publicPath(route), data);
     const addMetadataArtifact = (route, data) => {
         for (const url of new Set([route, publicPath(route)]))

package/dist/authoring-snapshot.js

@@ -193,7 +193,7 @@ export async function captureSnapshotInputs(configFile, options = {}) {
                 for (const key of Object.keys(value))
                     await visit(value[key], [...segments, key]);
             }
-            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon', 'logo'].includes(segments.at(-1)) || segments.at(-2) === 'files') && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
+            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon', 'logo'].includes(segments.at(-1)) || segments.at(-2) === 'files' || (segments[0] === 'outputs' && segments[1] === 'html' && segments[2] === 'highlighting' && segments.at(-1) === 'grammar') || (segments.includes('pdf') && (segments.at(-1) === 'stylesheet' || segments.includes('fonts') && segments.at(-1) === 'source'))) && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
                 if (path.isAbsolute(value))
                     throw new SnapshotError('unsupported_dependency', `Absolute dependency at ${segments.join('.')} cannot be isolated; use a relative path.`);
                 if (segments[0] === 'components' && segments.at(-1) === 'module' && !value.startsWith('.'))

package/dist/browser-print-assets.d.ts

@@ -0,0 +1,9 @@
+/** One shared print theme for the entire build; no page content is materialized. */
+export declare function browserPrintAssets(configFile: string, options: {
+    basePath: string;
+    profile?: string;
+    style?: string;
+}): Promise<{
+    artifacts: Map<string, string | Buffer<ArrayBufferLike>>;
+    dependencies: Set<string>;
+}>;

package/dist/browser-print-assets.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { parse } from 'parse5';
+import { loadConfig } from './config.js';
+import { projectPdfSettings } from './pdf-project.js';
+import { preparePdfDocument } from './pdf-renderer.js';
+import { sitePath } from './site-path.js';
+/** One shared print theme for the entire build; no page content is materialized. */
+export async function browserPrintAssets(configFile, options) {
+    const loaded = await loadConfig(configFile, { profile: options.profile });
+    const { config, files } = projectPdfSettings(loaded, configFile, options.style);
+    const prepared = await preparePdfDocument({
+        documents: [{ id: 'print-theme', title: '', html: '' }], title: '', assets: new Map(), publicBase: '/',
+        config: { ...config, cover: false, toc: false }, configFile,
+        assetRoots: files.map(file => path.dirname(file))
+    });
+    let css = '';
+    const findStyle = (node) => { if (node.tagName === 'style')
+        css += (node.childNodes ?? []).map((child) => child.value ?? '').join(''); for (const child of node.childNodes ?? [])
+        findStyle(child); };
+    findStyle(parse(prepared.html));
+    const artifacts = new Map();
+    let logo;
+    for (const [original, asset] of prepared.assets) {
+        const route = sitePath(options.basePath, `/assets/print/${path.posix.basename(original)}`);
+        artifacts.set(route, asset.bytes);
+        css = css.replaceAll(original, route);
+        if (original.startsWith('/__pdf_logo/'))
+            logo = route;
+    }
+    const margins = { top: '18mm', right: '18mm', bottom: '18mm', left: '18mm', ...config.margins };
+    css = `@page{size:${config.size ?? 'A4'};margin:${margins.top} ${margins.right} ${margins.bottom} ${margins.left}}\n` + css;
+    css += '\n.pdf-print-tools{display:flex;gap:10px;align-items:center;padding:12px 0;margin-bottom:24px;font:14px Arial,sans-serif}.pdf-print-tools button{font:inherit;padding:8px 12px;border:1px solid #89998e;border-radius:4px;cursor:pointer}.pdf-print-tools .pdf-print-note{margin-left:auto;color:#53665e;font-size:12px}.pdf-chapter .page-head h1{margin-bottom:8pt}.pdf-chapter .page-head .summary{font-size:10pt;line-height:1.5;margin:0 0 8pt}.pdf-chapter .page-head .pdf-page-meta{font-size:8pt;margin:5pt 0 12pt}.pdf-page-meta{color:var(--pdf-muted);font-size:9pt;margin-bottom:14pt}.pdf-chapter .eyebrow{color:var(--pdf-muted);font-size:9pt}.pdf-chapter .page-dates{display:flex;flex-wrap:wrap;gap:4pt 10pt;font-size:9pt;color:var(--pdf-muted)}.pdf-chapter .doc-callout{border-left:3pt solid var(--pdf-accent);padding:10pt 14pt;background:#f1f4ee;margin:14pt 0}.pdf-chapter details{display:block}.pdf-reader-label{font-weight:bold;margin-top:14pt}@media screen{html{background:#dfe5de}body{max-width:210mm;margin:24px auto;padding:18mm;background:white;box-shadow:0 8px 40px #173c3520}}@media print{.pdf-print-tools{display:none!important}}';
+    // A manual theme may start every chapter on a new page. When no cover or
+    // contents precede this chapter, that break can produce a blank first sheet.
+    css += '\n.pdf-print-tools + .pdf-chapter{break-before:auto}';
+    const stylesheet = sitePath(options.basePath, '/assets/print/theme.css');
+    artifacts.set(stylesheet, css);
+    const settings = {
+        schemaVersion: 1, stylesheet, ...(logo ? { logo } : {}), cover: config.cover ?? false,
+        toc: config.toc ?? false, subtitle: config.subtitle ?? '', header: config.header ?? '', footer: config.footer ?? '',
+        fonts: (config.fonts ?? []).map(({ family, weight, style }) => ({ family, weight, style }))
+    };
+    artifacts.set(sitePath(options.basePath, '/assets/print/settings.json'), JSON.stringify(settings));
+    return { artifacts, dependencies: new Set([...loaded.dependencies, ...files]) };
+}