@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/content-export-config.d.ts

@@ -1,6 +1,8 @@
 import { type ReaderSelection } from './reader-filters.js';
 import type { Variant } from './content.js';
-export type ExportFormat = 'markdown' | 'html';
+import { type PdfConfig } from './pdf-config.js';
+export type ExportFormat = 'markdown' | 'html' | 'pdf';
+export type PortableExportFormat = Exclude<ExportFormat, 'pdf'>;
 export type ExportResourceSelector = {
     kind: 'page';
     documentId: string;
@@ -26,6 +28,7 @@ export type ExportTarget = {
     assetRoots: string[];
     apiReview: Record<string, string>;
     notices: string[];
+    pdf?: PdfConfig;
 };
 export declare function validateExportResources(value: unknown): ExportResourceSelector[];
 export declare function exportPublicBase(value: unknown): string;

package/dist/content-export-config.js

@@ -2,6 +2,7 @@ import { isConfigMapping } from './compiler-config.js';
 import { validateContentFilter } from './content-filter.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { validSectionId } from './section-identity.js';
+import { validatePdfConfig } from './pdf-config.js';
 const nonempty = (value) => typeof value === 'string' && value.trim() === value && value.length > 0;
 const snippetId = (value) => nonempty(value) && /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value)
     && value.split('.').every(part => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(part) && !['__proto__', 'prototype', 'constructor'].includes(part));
@@ -50,13 +51,17 @@ export function exportPublicBase(value) {
     return value;
 }
 export function validateExportTarget(value, readerFilters) {
-    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'resources', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices'].includes(key)))
-        throw new Error('Export target accepts formats, documents or resources, publication, contentFilter, publicBase, assetRoots, apiReview, and notices');
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'resources', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices', 'pdf'].includes(key)))
+        throw new Error('Export target accepts formats, documents or resources, publication, contentFilter, publicBase, assetRoots, apiReview, notices, and pdf');
     if (value.documents !== undefined && value.resources !== undefined)
         throw new Error('Export documents and resources are mutually exclusive');
     const formats = value.formats ?? ['markdown', 'html'];
-    if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html'].includes(format)) || new Set(formats).size !== formats.length)
-        throw new Error('Export formats must be a nonempty unique list of markdown and/or html');
+    if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html', 'pdf'].includes(format)) || new Set(formats).size !== formats.length)
+        throw new Error('Export formats must be a nonempty unique list of markdown, html, or pdf');
+    if (formats.includes('pdf') && formats.length !== 1)
+        throw new Error('PDF exports use their own bundle; select pdf alone, or export HTML/Markdown separately');
+    if (formats.includes('pdf') && value.resources !== undefined)
+        throw new Error('PDF exports select whole pages with documents; section and snippet resources are not supported');
     const strings = (raw, field) => {
         if (raw === undefined)
             return undefined;
@@ -76,7 +81,7 @@ export function validateExportTarget(value, readerFilters) {
         throw new Error('Export apiReview must map API IDs to lowercase SHA-256 digests');
     return { formats: [...formats].sort(), ...(value.documents !== undefined ? { documents: strings(value.documents, 'documents') } : {}), ...(value.resources !== undefined ? { resources: validateExportResources(value.resources) } : {}), ...(publication ? { publication } : {}),
         ...(value.contentFilter !== undefined ? { contentFilter: validateContentFilter(value.contentFilter, validateReaderFilters(readerFilters)) } : {}),
-        publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [] };
+        publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [], ...(value.pdf !== undefined ? { pdf: validatePdfConfig(value.pdf) } : {}) };
 }
 export function validateExports(value, readerFilters) {
     if (value === undefined)

package/dist/content-export-render.d.ts

@@ -1,7 +1,13 @@
-import type { ExportFormat } from './content-export-config.js';
+import type { PortableExportFormat } from './content-export-config.js';
+import type { CodeHighlighter } from './highlight.js';
 /** Lower interactions while representation-specific source blocks still exist. */
-export declare function portableTree(tree: any, format: ExportFormat, routes: Set<string>, basePath: string): any;
-export declare function passiveHtml(tree: any, prefix: string, checkAnchors?: boolean): {
+export declare function portableTree(tree: any, format: PortableExportFormat, routes: Set<string>, basePath: string, options?: {
+    print?: boolean;
+}): any;
+export declare function passiveHtml(tree: any, prefix: string, checkAnchors?: boolean, options?: {
+    print?: boolean;
+    highlighter?: CodeHighlighter;
+}): {
     html: string;
     anchors: Array<{
         id: string;

package/dist/content-export-render.js

@@ -4,7 +4,7 @@ import { renderHtmlWithHeadings } from './html-renderer.js';
 import { heading, link, paragraph, root, text, renderMarkdown } from './content.js';
 import { walkthroughMarkdown } from './walkthrough.js';
 /** Lower interactions while representation-specific source blocks still exist. */
-export function portableTree(tree, format, routes, basePath) {
+export function portableTree(tree, format, routes, basePath, options = {}) {
     // Provenance is internal export metadata. Keep it when component lowering
     // synthesizes headings so a slice can retain its full-source identities.
     const inherit = (node, key) => {
@@ -37,7 +37,7 @@ export function portableTree(tree, format, routes, basePath) {
             return [heading(3, node.title), ...node.children.flatMap(walk)];
         if (['docTooltip', 'docInfoHint'].includes(node.type))
             return [node.inline ? text(`${node.label} (${node.definition})`) : paragraph(text(`${node.label}: ${node.definition}`))];
-        if (node.type === 'docMath')
+        if (node.type === 'docMath' && !options.print)
             return [node.display ? { type: 'code', lang: 'latex', value: node.expression } : { type: 'inlineCode', value: node.expression }];
         if (node.type === 'docDiagram')
             return [paragraph({ type: 'image', url: node.url, alt: node.title }), paragraph(text(`${node.title}: ${node.summary}`)), ...(format === 'markdown' ? [{ type: 'code', lang: node.engine, value: node.source }] : [])];
@@ -78,7 +78,8 @@ export function portableTree(tree, format, routes, basePath) {
         const data = node.data ? { ...node.data } : undefined;
         if (data) {
             delete data.hChildren;
-            delete data.mathMarkup;
+            if (!options.print)
+                delete data.mathMarkup;
         }
         return { ...node, ...(data ? { data } : {}), ...(node.children ? { children: node.children.filter((child) => child.type !== 'definition').map(clean) } : {}) };
     };
@@ -86,8 +87,10 @@ export function portableTree(tree, format, routes, basePath) {
 }
 const tags = new Set('a abbr article b blockquote br caption code col colgroup dd del details div dl dt em figcaption figure h1 h2 h3 h4 h5 h6 hr i img input kbd li ol p pre progress s section small span strong sub summary sup table tbody td th thead time tr ul'.split(' '));
 const attrs = new Set(['id', 'href', 'src', 'alt', 'title', 'colspan', 'rowspan', 'start', 'reversed', 'value', 'max', 'datetime', 'scope', 'align', 'type', 'checked', 'disabled', 'aria-label', 'aria-labelledby', 'aria-describedby', 'aria-hidden', 'role', 'tabindex', 'data-footnote-ref', 'data-footnote-backref', 'data-export-link']);
-export function passiveHtml(tree, prefix, checkAnchors = true) {
-    const rendered = renderHtmlWithHeadings(tree);
+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 mathAttrs = 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(' '));
+export function passiveHtml(tree, prefix, checkAnchors = true, options = {}) {
+    const rendered = renderHtmlWithHeadings(tree, options.highlighter);
     const fragment = parseFragment(rendered.html);
     const anchors = [];
     const ids = new Set();
@@ -95,7 +98,7 @@ export function passiveHtml(tree, prefix, checkAnchors = true) {
         if (node.nodeName === '#text')
             return;
         if (node.tagName) {
-            if (!tags.has(node.tagName))
+            if (!tags.has(node.tagName) && !(options.print && mathTags.has(node.tagName)))
                 throw new Error(`Unsupported passive HTML element <${node.tagName}>`);
             const original = node.attrs ?? [];
             for (const attr of original) {
@@ -107,7 +110,8 @@ export function passiveHtml(tree, prefix, checkAnchors = true) {
                         throw new Error(`Unsafe exported URL: ${attr.value}`);
                 }
             }
-            node.attrs = original.filter((attr) => attrs.has(attr.name));
+            node.attrs = original.filter((attr) => attrs.has(attr.name) || options.print && (attr.name === 'class' || mathTags.has(node.tagName) && mathAttrs.has(attr.name)
+                || attr.name === 'style' && /^(?:(?:color|background-color):(?:#[a-f\d]{3,8}|var\(--code-(?:foreground|token-[a-z-]+)\));?)+$/i.test(attr.value)));
             const id = node.attrs.find((attr) => attr.name === 'id');
             if (id) {
                 if (ids.has(id.value))

package/dist/content-export.d.ts

@@ -1,5 +1,7 @@
 import { type ExportFormat } from './content-export-config.js';
 import { type Variant } from './content.js';
+import { type PdfRenderInput } from './pdf-renderer.js';
+import type { ContentLink } from './content-delivery-contract.js';
 export type ContentExportOptions = {
     profile?: string;
     target?: string;
@@ -10,9 +12,132 @@ export type ContentExportOptions = {
     review?: boolean;
     previousManifest?: string;
     failOnRemoved?: boolean;
+    preparePdfOnly?: boolean;
+    pdfLinks?: 'internal' | 'canonical';
+    pdfStyleTarget?: string;
+};
+export type PdfExportPreparation = {
+    input: PdfRenderInput;
+    manifest: {
+        schemaVersion: number;
+        kind: string;
+        publication: Variant;
+        title: string;
+        documents: Array<{
+            id: string;
+            title: string;
+            contentDigest: string;
+            anchors: Representation['anchors'];
+            links: ExportLink[];
+        }>;
+        review: {
+            status: string;
+            apis: Array<{
+                apiId: string;
+                digest: string;
+            }>;
+        };
+        diagnostics: Array<{
+            code: string;
+            documentId?: string;
+            message: string;
+        }>;
+    };
+    inputs: string[];
+};
+/** Prepare passive, scoped print inputs without launching a browser or writing output. */
+export declare function preparePdfExport(configFile: string, options?: Omit<ContentExportOptions, 'formats' | 'preparePdfOnly'>): Promise<PdfExportPreparation>;
+type ExportLink = ContentLink;
+type Representation = {
+    path: string;
+    mediaType: string;
+    bytes: number;
+    digest: string;
+    anchors: Array<{
+        id: string;
+        exportedId: string;
+        title?: string;
+    }>;
+    links: ExportLink[];
 };
 /** Export selected source content; never invoke the website shell/compiler. */
 export declare function exportContent(configFile: string, destination: string, options?: ContentExportOptions): Promise<{
+    digest: string;
+    preparedPdf: PdfExportPreparation;
+    status: string;
+    output: string;
+    publication: Variant;
+    formats: ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
+    digest: string;
+    pdf: string;
+    status: string;
+    output: string;
+    publication: Variant;
+    formats: ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
     status: string;
     output: string;
     publication: Variant;
@@ -45,3 +170,4 @@ export declare function exportContent(configFile: string, destination: string, o
         message: string;
     }[];
 }>;
+export {};