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

package/examples/pdf/content/operations.mdx

@@ -0,0 +1,26 @@
+---
+id: guide.operations
+title: Run daily operations
+summary: Review workspace activity and record an outcome.
+slug: /operations
+---
+
+Start each review by checking the [workspace setup](doc:guide.start). Record the review date and result with your operating notes.
+
+## Review activity
+
+Use these example thresholds to decide whether activity needs investigation:
+
+| Signal | Expected value | Follow-up |
+| --- | --- | --- |
+| Queued work | Below 100 items | Check worker capacity. |
+| Oldest item | Below 10 minutes | Inspect the processing log. |
+| Failed items | Zero | Review the reported failure. |
+
+For a completed-work count of 90 out of 100, the completion ratio is:
+
+<Math display expression="r = \frac{90}{100} = 0.9" />
+
+## Record the outcome
+
+Save a brief report with the observed counts and any follow-up action. Link to [the review section](#review-activity) so the next operator can repeat the checks.

package/examples/pdf/content/start.mdx

@@ -0,0 +1,28 @@
+---
+id: guide.start
+title: Start your workspace
+summary: Configure a workspace and confirm its status.
+slug: /start
+---
+
+Create a workspace before running daily operations. Keep its configuration in your project so another operator can reproduce the setup.
+
+## Configure the workspace
+
+Save the following example configuration:
+
+```yaml
+workspace:
+  name: training
+  retentionDays: 30
+```
+
+## Verify the result
+
+Confirm that the workspace name is `training` and that retention is 30 days. Continue with [daily operations](doc:guide.operations).
+
+<Collapsible title="Configuration checklist">
+
+Record the workspace owner, retention period, and expected data source before adding live data.
+
+</Collapsible>

package/examples/pdf/docs.config.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+site:
+  title: Operations documentation
+  origin: https://docs.example.com
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels: { production: {} }
+  versions: { current: {} }
+  enabled: [{ channel: production, version: current }]
+navigation:
+  - { id: start, doc: guide.start }
+  - { id: operations, doc: guide.operations }
+outputs:
+  pdf:
+    stylesheet: ./print.css
+    size: A4
+    footer: "{title} | {page} / {pages}"
+    subtitle: Setup and daily operations
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after

package/examples/pdf/print.css

@@ -0,0 +1,9 @@
+:root {
+  --pdf-accent: #28584b;
+  --pdf-text: #172722;
+  --pdf-muted: #53665e;
+  --pdf-font: Arial, sans-serif;
+}
+.pdf-cover { border-top: 6pt solid var(--pdf-accent); }
+.pdf-cover h1 { max-width: 15ch; }
+th { background: #e5eee9; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-beta.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -15,7 +15,8 @@
     "./authoring": "./dist/authoring-api.js",
     "./*": "./*",
     "./components": "./dist/components.js",
-    "./content/server": "./dist/content-rest-server.js"
+    "./content/server": "./dist/content-rest-server.js",
+    "./pdf/server": "./dist/pdf-http.js"
   },
   "files": [
     "dist",
@@ -70,6 +71,7 @@
     "lucide": "1.47.0",
     "parse5": "8.0.1",
     "pele": "1.6.0",
+    "puppeteer-core": "25.16.0",
     "rehype-stringify": "10.0.1",
     "remark-gfm": "4.0.1",
     "remark-mdx": "3.1.1",

package/skills/shoalrun-author/SKILL.md

@@ -31,6 +31,8 @@ For SKU-selected or white-label documentation, read [references/customer-edition
 
 ## Record scope and edit
 
+For PDF export or page print/download actions, read [references/pdf-export.md](references/pdf-export.md). Keep PDF selection distinct from reader-view controls. Use browser printing on static sites, optional CLI manual downloads, and explicit Node-hosted generation when needed.
+
 Before editing, capture the current state with `docs baseline --out <new-baseline> --config <config>`. Put baselines inside the project's excluded `.shoalrun` directory or outside the project. This includes earlier dirty/untracked files rather than comparing with Git HEAD. Retain the corresponding before-content/task diff with your harness; a baseline stores digests, not earlier text. For an existing rendering failure, reproduce its located finding before repairing it.
 
 Edit ordinary source files and required companions. Choose a page type and reviewed example for the reader's goal. Preserve stable IDs, routes, original `date` and access policy; set `updated` to the actual edit date. For a new page, use `shoalrun scaffold <template> -n <target> --config <config>` and resolve its prompts. Keep it draft until reviewed; snapshot validation renders affected drafts without changing their publication metadata. API materialization and recipe tasks have focused references/skills when needed.

package/skills/shoalrun-author/references/pdf-export.md

@@ -0,0 +1,15 @@
+# PDF export
+
+For print design, brand styling, and visual verification, read the [PDF skill](../../shoalrun-pdf/SKILL.md). Its print reference and stylesheet starter accompany the instructions; keep the complete skill folder when installing it.
+
+Check the installed CLI's `export --help` and supported output settings before configuring PDFs. Use `export --format pdf --document ID --out DIRECTORY` for one page; omit the document selector for a complete publication. Select exact product/channel/version/language coordinates when more than one publication is enabled. Pass the same customer profile as the site. PDF selection uses the target's contentFilter, otherwise the site's filter; ordinary HTML/Markdown application exports retain their independent filter behavior.
+
+Set shared print settings under outputs.pdf and per-target overrides under exports.<target>.pdf. Local stylesheet/font/logo paths resolve relative to their declaring configuration. Register licensed local fonts explicitly; custom CSS cannot import files or load URLs. Body CSS doesn't style Chromium's separate header/footer templates. Their escaped text supports {title}, {page}, and {pages}. The TOC is linked without printed page numbers. Bookmarks/tagging need actual PDF inspection; don't infer accessibility certification.
+
+The page action is disabled by default. An enabled outputs.html.pdf mapping defaults to mode:print for static sites: the browser creates a separate branded view and opens its print dialog, with no generated page PDFs or extra print documents. Configure its label, placement before/after Markdown actions, include/exclude IDs, and optional named style target. Shared outputs.pdf styling and assets serve all print views; only a target's PDF settings apply, never its content selection. Page frontmatter pdf:false suppresses the action. Native browser printing remains a fallback using website print CSS. Keep full-manual CLI export and its published download optional.
+
+Explicit mode:endpoint prepares private inputs for on-demand generation through a Node host with Chromium. Optional style names an export target's pdf mapping; only its styling applies, never its page/publication/filter selection. Vercel supports browser printing and rejects endpoint mode. Never publish pdf-runtime.json or __shoalrun/pdf-data through a generic static server. A custom handler must use the same authentication boundary as the site. Audience/profile selection isn't visitor authorization.
+
+Generation requires an installed Chrome/Chromium executable through SHOALRUN_PDF_BROWSER or outputs.pdf.executablePath. It runs offline with JavaScript disabled and the browser sandbox retained. Missing assets, remote images, missing browser, or rendering failures must be reported; don't substitute a print dialog for a promised PDF download. Preserve existing exports on failure.
+
+Verify a page and full publication, their selection/order, excluded content, links, fonts, bookmarks, page breaks, long code/tables, and static component fallbacks. Inspect rendered PDF pages as well as extracted text. Keep PDF manifests separate from content REST representation manifests. Enabling an action doesn't authorize deploying internal/customer PDFs publicly.

package/skills/shoalrun-brand/SKILL.md

@@ -45,6 +45,8 @@ Check every requested color mode. Normal text needs at least 4.5:1 contrast; lar
 
 ## Validate and preview
 
+For branded PDF output, read the [PDF skill](../shoalrun-pdf/SKILL.md). Configure print styling separately from website styling, retain the intended publication/profile selection, and inspect actual rendered PDF pages. A passing HTML build doesn't verify PDF appearance.
+
 Validate against the baseline with `shoalrun docs validate --baseline .shoalrun/brand-before.json --config docs.config.yaml`, including the selected profile when applicable. Read the report's findings and coverage. Reuse its captured output with `shoalrun docs preview REPORT --port 0`, or follow the project's required build workflow and serve that output. Rebuild when styles, configuration, or assets change.
 
 Inspect a landing page and a representative article at desktop and mobile widths. Check font and image loading, overflow, keyboard navigation, dropdown destinations, and search interactions. Confirm HTML navigation and Markdown twins retain the documentation's meaning. A successful build doesn't establish visual correctness; state any browser checks that couldn't run.

package/skills/shoalrun-pdf/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: shoalrun-pdf
+description: Style and export Shoalrun pages or publications as PDFs, including brand typography, covers, print layouts, optional download actions, and visual verification. Use for documentation PDFs rather than ordinary website styling or unrelated PDF editing.
+---
+
+# Style and export documentation PDFs
+
+Inspect the documentation project's instructions, installed CLI, content selection, and existing print assets. Check `shoalrun export --help` before using PDF options; a skill folder alone doesn't establish installed-version support. Use the project's installed CLI and package references without requiring a framework checkout. Preserve existing source, routes, IDs, and unrelated edits.
+
+## Choose the publication and output
+
+Confirm whether the request covers a page, a selected collection, or a complete publication. Keep product, channel, version, language, audience, and customer profile consistent with the intended site. Pass the same profile to build, export, and preview. PDF selection uses the export target's `contentFilter`, otherwise the site's filter. Reader sections remain complete labeled content; reader views aren't exclusion or authorization controls.
+
+For an existing project, capture the required baseline before editing. Keep a separate demo's source and output isolated. Use genuine project facts in customer documentation; label sample content and don't invent product capabilities to fill a design.
+
+## Translate the brand into print
+
+Read [the print design reference](references/print-design.md) when choosing configuration, selectors, typography, or page behavior. Use supplied brand evidence and suitable local fonts/logo assets; keep customer-specific values in the project and preserve asset notices. Website theme settings aren't automatically a PDF theme.
+
+Use `outputs.pdf` for shared print settings and `exports.<target>.pdf` for overrides. Copy [the manual stylesheet starter](assets/print.css) into the project when useful, then adapt its tokens and typography. It supplies a restrained cover, contents, chapter hierarchy, tables, code, and print breaks; it isn't a required visual style. Browser print views reuse these print settings and shared assets. The ordinary browser Print fallback uses website print CSS through `site.customCss` and `@media print`.
+
+Design the cover, contents, article pages, tables, and code as one publication. Use physical dimensions for page geometry and keep text/background contrast readable in print. Give headings room without isolating them from their content. Avoid blanket `break-inside: avoid` on chapters, long code, or large tables; it can create blank space or overflow. Don't reduce body type to hide a pagination problem.
+
+Register local font files explicitly with accurate families, weights, and styles. Use existing licensed assets rather than copying system fonts into a distributable template. The stylesheet can't import files or load URLs; images must be staged local assets. Keep source paths relative to the configuration that declares them.
+
+## Export and offer downloads
+
+Use an output directory separate from source. Commands below assume the project directory and its installed CLI:
+
+```sh
+shoalrun export docs.config.yaml --format pdf --document guide.start --out pdf/page
+shoalrun export docs.config.yaml --format pdf --out pdf/manual
+```
+
+Select a named target or explicit publication coordinates when needed. One export contains one publication. Full-publication order follows navigation, with eligible unlisted pages appended and reported; an explicit target document list supplies an order. PDF bundles and manifests are separate from HTML/Markdown application exports and Content REST representations.
+
+Enable the optional page action only when requested. Static sites use `mode: print`, which opens the visitor's print dialog without generating page PDFs or extra print documents during builds. Keep whole-manual PDF generation optional through the CLI and publish that download only when requested. Never turn on per-page PDF generation as a static-hosting default.
+
+Endpoint generation is an explicit option for a Node host with an installed browser. Label, placement, page inclusion/exclusion, and suppression are configurable. A style target supplies only its PDF settings to a browser print view or endpoint download; it mustn't change the current page's selection. Browser print views have no generation endpoint and use shared CSS/fonts/settings rather than per-page output files. See the reference for configuration and hosting boundaries.
+
+## Verify the PDF itself
+
+Generate a representative page and full publication when the request affects both. Reuse each artifact until its source, styling, or assets change. Inspect all pages as rendered images or in a PDF viewer, then check extracted text, internal destinations, fonts, and any requested bookmarks. Check cover crop, chapter starts, heading orphans, footer clearance, contrast, long URLs/code, table continuation, and mathematical content. Verify excluded edition content is absent.
+
+Check an enabled action against the selected page and publication. For browser printing, verify that it opens the native print dialog with the current page's printable content and creates no build-time PDFs. For a CLI or endpoint download, verify the actual PDF. An HTML preview, successful build, or browser-free test isn't evidence that PDF generation works. Chromium outline/tagging support is experimental; inspect actual output and don't claim PDF/UA compliance from a setting.
+
+If rendering is blocked, report the exact failed stage and preserve the prepared content and runnable export command. Don't disable browser sandboxing to make a preview work. A native print-interface fallback can demonstrate styling when appropriate, but identify its renderer/settings and don't report it as a passing automated CLI export. A print dialog isn't an on-demand PDF download endpoint.
+
+Deliver the PDF or working preview link with a brief description of the design, checks completed, and remaining limitations. Follow the user's existing authorization for commits, deployment, and publication.

package/skills/shoalrun-pdf/assets/print.css

@@ -0,0 +1,49 @@
+/* Copy into the documentation project and adapt to its brand and local fonts. */
+:root {
+  --pdf-accent: #234c44;
+  --pdf-text: #263e3a;
+  --pdf-muted: #62766c;
+  --pdf-font: Arial, sans-serif;
+  --pdf-code-font: monospace;
+}
+body { font-size: 10.5pt; line-height: 1.6; }
+h1, h2, h3 { break-after: avoid; }
+h1 { font-family: Georgia, serif; font-weight: 400; }
+.pdf-cover {
+  position: relative;
+  min-height: 220mm;
+  padding: 16mm 12mm 26mm;
+  color: #f4f1e8;
+  background: #234c44;
+  border-top: 5pt solid #bbd58a;
+}
+.pdf-cover h1 {
+  color: inherit;
+  font-size: 38pt;
+  line-height: 1.12;
+  max-width: 15ch;
+  margin: 12mm 0 8mm;
+}
+.pdf-cover .pdf-subtitle { max-width: 30ch; font-size: 13pt; }
+.pdf-cover .pdf-publication {
+  color: #e0e9d8;
+  font-size: 8pt;
+  margin-top: 14mm;
+}
+.pdf-logo { max-width: 40mm; max-height: 20mm; object-fit: contain; }
+.pdf-toc { padding-top: 10mm; }
+.pdf-toc h1 { font-size: 30pt; margin-bottom: 12mm; }
+.pdf-toc ol { padding-left: 7mm; }
+.pdf-toc li { padding: 4mm 0; border-top: .5pt solid #d2ddd2; }
+.pdf-toc a { text-decoration: none; font-size: 13pt; }
+.pdf-chapter { break-before: page; padding-top: 4mm; }
+.pdf-chapter h1 { font-size: 29pt; line-height: 1.15; margin-bottom: 8mm; }
+.pdf-chapter h2 { font-size: 13pt; margin: 8mm 0 3mm; }
+.pdf-chapter > p:first-of-type { color: var(--pdf-muted); font-size: 11.5pt; }
+blockquote { padding: 4mm 5mm; background: #f0f4ea; border-left: 3pt solid #bbd58a; }
+table { font-size: 9pt; margin: 5mm 0; }
+th { padding: 3mm; color: #fff; background: #234c44; }
+td { padding: 3mm; border-color: #d2ddd2; }
+tbody tr:nth-child(even) { background: #f4f6f0; }
+pre { padding: 5mm; font-size: 8.5pt; background: #f0f4ed; border: 0; border-left: 3pt solid #bbd58a; }
+a { text-underline-offset: 2pt; }

package/skills/shoalrun-pdf/references/print-design.md

@@ -0,0 +1,75 @@
+# Print design and configuration
+
+Use the installed configuration reference as the contract. These examples show PDF settings; retain the rest of the project's configuration.
+
+## Shared settings and target overrides
+
+```yaml
+outputs:
+  pdf:
+    stylesheet: ./styles/print.css
+    size: A4
+    margins: { top: 18mm, right: 18mm, bottom: 20mm, left: 18mm }
+    footer: "{title} | {page} / {pages}"
+    cover: true
+    toc: true
+    bookmarks: true
+exports:
+  manual:
+    formats: [pdf]
+    pdf:
+      subtitle: Configuration and operations
+      size: Letter
+```
+
+Export the target with `shoalrun export docs.config.yaml --target manual --out pdf/manual`. Use explicit product/channel/version/language coordinates or a target publication when multiple publications are enabled. Add `--profile FILE` for the intended customer edition. Keep internal/customer exports out of public output unless that delivery is intended and authorized.
+
+Paper sizes are A4, Letter, Legal, A3, and A5. Margins accept nonnegative mm, cm, in, or px dimensions. `timeout` accepts 1,000–120,000 milliseconds. Browser selection uses `SHOALRUN_PDF_BROWSER`, `PUPPETEER_EXECUTABLE_PATH`, or `executablePath`; configured paths take precedence. Normal installation doesn't download a browser.
+
+## Typography and assets
+
+Register existing local licensed font files under `outputs.pdf.fonts` with `family`, `source`, and optional `weight`/`style`. Sources support woff, woff2, ttf, and otf. Declare static weights as strings such as `"400"` and `"700"`; don't pretend a regular face is bold. Add `logo` for a local cover image and `subtitle` for cover text.
+
+Set the stylesheet's `--pdf-font` and `--pdf-code-font` to the registered families and keep fallbacks. Headings can use a separate registered family. Test missing glyphs, mathematical symbols, and emphasis as well as ordinary prose. Local paths resolve from the declaring configuration, including included files and target overrides.
+
+CSS imports, CSS URLs, and remote images aren't fetched by the renderer. Add fonts through their explicit settings and content images through staged assets. Don't copy reference-site scripts, remote font loaders, or analytics into a print theme.
+
+## Layout surfaces
+
+The print assembly exposes `.pdf-cover`, `.pdf-logo`, `.pdf-subtitle`, `.pdf-publication`, `.pdf-toc`, and `.pdf-chapter`. Headings, paragraphs, tables, blockquotes, and pre/code use ordinary HTML elements. Body colors and typography use `--pdf-accent`, `--pdf-text`, `--pdf-muted`, `--pdf-font`, and `--pdf-code-font`.
+
+Keep covers within the printable height after margins; don't assume a browser viewport matches the physical page. Plan enough room for title wrapping, subtitle, logo, and publication identity. Contents links don't have automatically printed page numbers. Default chapter boundaries start new pages; component interactions become labeled static content.
+
+The separate `header` and `footer` fields accept escaped text with `{title}`, `{page}`, and `{pages}`. They have fixed small-text typography and don't inherit body CSS. For more elaborate page furniture, use supported print CSS and verify it with the selected browser. Avoid duplicate numbering when combining CSS page-margin content and template footers.
+
+Chromium supports CSS margin boxes with page counters; see the [official print-margin reference](https://developer.chrome.com/blog/print-margins). Check the selected browser's support before relying on them. If CSS owns paper dimensions or margins, keep its `@page` settings consistent with the configured PDF geometry.
+
+## Optional single-page action
+
+```yaml
+outputs:
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after
+      include: [guide.start, guide.configure]
+```
+
+The action is off by default. An enabled mapping defaults to `mode: print`. Omit `include` for all eligible pages; `exclude` removes listed document IDs. `pdf: false` in page frontmatter suppresses the control. The browser action opens a native print dialog; readers can choose Save as PDF. It needs JavaScript for the button, while the browser's own Print command remains available without JavaScript.
+
+Browser printing copies semantic content from the current article into a separate passive print view. It uses `outputs.pdf` settings and the same `.pdf-cover`/`.pdf-chapter` theme surfaces as the manual. Optional `outputs.html.pdf.style` supplies a named target's PDF settings without changing page selection. The original page remains unchanged. Reader sections and tab panels remain printable, details become complete static sections, and active elements/controls aren't copied. Browser settings can affect pagination, backgrounds, headers, and footers.
+
+For a static site, enable `mode: print` and run the ordinary site build with the intended profile. This adds shared print scripts, theme CSS, settings, and configured fonts/logo, not a PDF or print document for every page. The build doesn't need Chromium for this action. Deploy the normal HTML/assets; the visitor's browser prepares the print view, waits for fonts/images, and opens the native dialog. Allow that view to open if pop-up blocking prevents it. Don't create per-page PDF caches for static hosting. The ordinary browser Print command remains a fallback, using website print CSS.
+
+A whole-publication CLI export is a separate artifact. If the user wants it on a static site, add its PDF to the deployment output after the site build and supply a deliberate download link at the correct base path. The compiler doesn't automatically create a whole-manual button or publish CLI export directories. Keep the export outside the site build destination until copying, because a site build replaces its output. Preserve the exact selected publication/profile in that deployment step.
+
+Endpoint mode prepares private page inputs and generates a direct PDF download on request through a Node host with Chromium. Configure its same-origin `endpoint` path as needed. Optional `style` names an existing export target's `pdf` mapping without applying that target's documents, publication, or filter. The Vercel adapter supports browser printing and rejects endpoint mode.
+
+Keep `pdf-runtime.json` and `__shoalrun/pdf-data` out of public static serving. Use the built-in Node server or a correctly mounted `@shoalrun/cli/pdf/server` handler behind the site's authentication boundary. Don't accept visitor-provided URLs, profiles, or CSS. Build-time audience selection isn't reader authentication. Endpoint downloads use no-store responses and per-instance work limits; they aren't a shared PDF cache.
+
+## Verification evidence
+
+Record the exact selection, source/style inputs, output file, and browser/renderer. Check the PDF manifest for identity and order. Confirm contents and cross-page links resolve within the PDF when their targets are included. Check font embedding and requested outline destinations with a PDF inspection tool rather than matching visible text alone.
+
+Render every page for a small publication. For a large manual, inspect a contact sheet of all pages and full-size views of the cover, chapter boundaries, dense layouts, and any suspected defects. Text extraction can identify omissions, but it can't verify clipping, contrast, or page geometry. Keep native-print demonstrations distinct from automated export verification.

package/styles/site.css

@@ -503,12 +503,14 @@ button{cursor:pointer}
 @media(prefers-reduced-motion:reduce){*{scroll-behavior:auto!important}}
 @media(forced-colors:active){.side a[aria-current=page]{outline:2px solid Highlight}.code-copy{border:1px solid ButtonText}}
 @media print{
-  .mast,.side,.page-toc,.navigation-dialog,.page-shortcuts,.region-return,.formats,.code-toolbar,.skip,.heading-anchor{display:none}
+  .mast,.side,.page-toc,.navigation-dialog,.page-shortcuts,.region-return,.formats,.code-toolbar,.skip,.heading-anchor,.reader-filter-slot,.reader-outside-view,.doc-tablist,.code-samples-bar{display:none!important}
   .layout,.layout.has-examples{display:flex;flex-direction:column;padding:0}
   .content{max-width:none}
   .page-rail{position:static;max-height:none;overflow:visible;order:2}
   .examples{display:block;position:static;max-height:none;overflow:visible;margin-top:2rem}
   .content pre,.example-body pre{white-space:pre-wrap;overflow-wrap:anywhere;background:white;color:black;border:1px solid #aaa}
+  .content .reader-section[hidden],.code-samples-panes>div[hidden]{display:block!important;visibility:visible!important}
+  .reader-section[data-reader-print-label]::before{content:attr(data-reader-print-label);display:block;font-weight:650;margin:.8rem 0 .4rem}
 }
 
 /* Document cards share their content with the Markdown representation. */