@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/dist/content-rest-contract.d.ts

@@ -0,0 +1,27 @@
+import type { ContentPublication, ContentRef, ContentResource } from './content-delivery-contract.js';
+/** Public identity only: independent of publication, revision, and export filenames. */
+export declare function contentResourceKey(ref: ContentRef): string;
+export type ContentRestEntry = {
+    key: string;
+    resource: ContentResource;
+};
+export type ContentRestList = {
+    schemaVersion: 1;
+    revision: string;
+    publication: ContentPublication;
+    resources: ContentRestEntry[];
+};
+export type ContentRestResource = {
+    schemaVersion: 1;
+    revision: string;
+    publication: ContentPublication;
+    key: string;
+    resource: ContentResource;
+};
+export type ContentRestErrorCode = 'invalid_request' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'method_not_allowed' | 'internal_error';
+export type ContentRestError = {
+    error: {
+        code: ContentRestErrorCode;
+        message: string;
+    };
+};

package/dist/content-rest-contract.js

@@ -0,0 +1,9 @@
+import { contentRefKey } from './content-delivery-contract.js';
+/** Public identity only: independent of publication, revision, and export filenames. */
+export function contentResourceKey(ref) {
+    const bytes = new TextEncoder().encode(contentRefKey(ref));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return 'k_' + btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}

package/dist/content-rest-server.d.ts

@@ -0,0 +1,7 @@
+import type { ContentSnapshot } from './content-delivery-contract.js';
+export type ContentRestHandlerOptions = {
+    sources: readonly ContentSnapshot[];
+    basePath?: string;
+};
+/** Serve already-approved, pinned snapshots. The caller retains source ownership. */
+export declare function createContentRestHandler(options: ContentRestHandlerOptions): (request: Request) => Promise<Response>;

package/dist/content-rest-server.js

@@ -0,0 +1,99 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+import { contentResourceKey } from './content-rest-contract.js';
+const publicationKey = (publication) => JSON.stringify([publication.channel, publication.version, publication.language]);
+const digest = async (bytes) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(value => value.toString(16).padStart(2, '0')).join('');
+const encoder = new TextEncoder();
+const validPublication = (value) => value && Object.keys(value).sort().join(',') === 'channel,language,version' && Object.values(value).every(part => typeof part === 'string' && part.length > 0 && part.length <= 2048);
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const same = (left, right) => JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+/** Serve already-approved, pinned snapshots. The caller retains source ownership. */
+export function createContentRestHandler(options) {
+    const basePath = options.basePath ?? '/content/v1';
+    if (!/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(basePath))
+        throw new Error('Content REST basePath must be an absolute path without a trailing slash.');
+    const publications = new Map();
+    for (const source of options.sources) {
+        if (!/^[a-f0-9]{64}$/.test(source.revision) || !validPublication(source.publication))
+            throw new Error('Content REST source requires a valid revision and publication.');
+        const publication = structuredClone(source.publication);
+        const key = publicationKey(publication);
+        if (publications.has(key))
+            throw new Error('Content REST sources must have distinct publications.');
+        const resources = source.list().map(resource => ({ key: contentResourceKey(resource.ref), resource: structuredClone(resource) }));
+        if (resources.some(item => !validPublication(item.resource.publication) || publicationKey(item.resource.publication) !== key) || new Set(resources.map(item => item.key)).size !== resources.length)
+            throw new Error('Content REST source contains inconsistent publication or duplicate references.');
+        resources.sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0);
+        publications.set(key, { source, publication, revision: source.revision, resources });
+    }
+    return async (request) => {
+        request.signal.throwIfAborted();
+        const head = request.method === 'HEAD';
+        const error = (status, code, message, headers = {}) => new Response(head ? null : JSON.stringify({ error: { code, message } }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers } });
+        if (!['GET', 'HEAD'].includes(request.method))
+            return error(405, 'method_not_allowed', 'Use GET or HEAD.', { Allow: 'GET, HEAD' });
+        const url = new URL(request.url);
+        const prefix = `${basePath}/resources`;
+        if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`))
+            return error(404, 'not_found', 'Unknown content route.');
+        const parts = url.pathname.slice(prefix.length).split('/').slice(1);
+        if (parts.length !== 0 && parts.length !== 1 && !(parts.length === 3 && parts[1] === 'representations'))
+            return error(404, 'not_found', 'Unknown content route.');
+        const allowed = new Set(['channel', 'version', 'language', 'revision']);
+        if ([...url.searchParams.keys()].some(key => !allowed.has(key) || url.searchParams.getAll(key).length !== 1))
+            return error(400, 'invalid_request', 'Unknown or repeated query parameter.');
+        const publication = Object.fromEntries(['channel', 'version', 'language'].map(key => [key, url.searchParams.get(key)]));
+        if (Object.values(publication).some(value => !value || value.length > 2048))
+            return error(400, 'invalid_request', 'channel, version, and language are required.');
+        const revision = url.searchParams.get('revision');
+        if (revision !== null && !/^[a-f0-9]{64}$/.test(revision) || parts.length > 0 && revision === null)
+            return error(400, 'invalid_request', 'A valid revision is required for resource requests.');
+        const selected = publications.get(publicationKey(publication));
+        if (!selected)
+            return error(404, 'not_found', 'Publication not found.');
+        if (revision !== null && revision !== selected.revision)
+            return error(409, 'stale_revision', 'The requested revision is not available.');
+        const resource = parts.length ? selected.resources.find(item => item.key === parts[0]) : undefined;
+        if (parts.length && !resource)
+            return error(404, 'not_found', 'Resource not found.');
+        try {
+            let body;
+            let mediaType = 'application/json';
+            if (!parts.length)
+                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, resources: selected.resources });
+            else if (parts.length === 1)
+                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, ...resource });
+            else {
+                const format = parts[2];
+                if (!['html', 'markdown'].includes(format) || !resource.resource.representations[format])
+                    return error(406, 'unsupported_format', 'Representation not available.');
+                const descriptor = resource.resource.representations[format];
+                const result = await selected.source.get(resource.resource.ref, { format, signal: request.signal });
+                request.signal.throwIfAborted();
+                if (result.revision !== selected.revision)
+                    return error(409, 'stale_revision', 'The requested revision is no longer available.');
+                if (typeof result.content !== 'string' || contentRefKey(result.resource.ref) !== contentRefKey(resource.resource.ref) || result.format !== format || !same(result.resource, resource.resource) || !same(result.representation, descriptor))
+                    return error(500, 'internal_error', 'Content source returned inconsistent metadata.');
+                const bytes = encoder.encode(result.content);
+                if (bytes.byteLength !== descriptor.bytes || await digest(bytes) !== descriptor.digest)
+                    return error(409, 'stale_revision', 'The requested revision bytes are no longer available.');
+                body = result.content;
+                mediaType = descriptor.mediaType;
+            }
+            const bytes = encoder.encode(body);
+            const etag = `"sha256-${await digest(bytes)}"`;
+            request.signal.throwIfAborted();
+            const headers = { 'Content-Type': `${mediaType}; charset=utf-8`, 'Content-Length': String(bytes.byteLength), ETag: etag, 'Cache-Control': revision === null ? 'no-cache' : 'public, max-age=31536000, immutable' };
+            const condition = request.headers.get('if-none-match');
+            const matches = condition?.trim() === '*' || condition?.split(',').some(value => value.trim().replace(/^W\//, '') === etag);
+            if (matches)
+                return new Response(null, { status: 304, headers });
+            return new Response(head ? null : body, { status: 200, headers });
+        }
+        catch (cause) {
+            request.signal.throwIfAborted();
+            if (cause instanceof ContentDeliveryError && ['stale_revision', 'not_found'].includes(cause.code))
+                return error(409, 'stale_revision', 'The requested revision is no longer available.');
+            return error(500, 'internal_error', 'Content source could not serve the request.');
+        }
+    };
+}

package/dist/content-source.d.ts

@@ -1,6 +1,7 @@
 import type { AuthoredChange, ResolvedChange } from './authored-change.js';
 import type { SubjectDeprecation, ResolvedSubjectDeprecation } from './subject-deprecation.js';
 import type { ReaderSelection } from './reader-filters.js';
+import type { StandaloneSectionDeclaration } from './section-identity.js';
 export type Variant = {
     channel: string;
     version: string;
@@ -32,7 +33,7 @@ export type Frontmatter = {
     product?: string;
     area?: string | string[];
     subarea?: string | string[];
-    standaloneSections?: string[];
+    standaloneSections?: StandaloneSectionDeclaration[];
     access?: {
         policy: string;
     };
@@ -45,6 +46,7 @@ export type Frontmatter = {
     layout?: 'docs' | 'wide' | 'landing' | 'splash';
     image?: string;
     showNavigationTabs?: boolean;
+    showVerified?: boolean;
     [key: string]: unknown;
 };
 export type Document = {

package/dist/frontmatter.js

@@ -2,8 +2,9 @@ import { validateAuthoredChange, changeKinds } from './authored-change.js';
 import { validateSubjectDeprecation } from './subject-deprecation.js';
 import { validateCardMetadata } from './cards.js';
 import { resolveTaxonomy, validateTaxonomy, taxonomySchema } from './taxonomy.js';
+import { validateStandaloneSectionDeclarations } from './section-identity.js';
 export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
-export const protectedMetadataRoots = new Set(['standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
+export const protectedMetadataRoots = new Set(['standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
 const fieldTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array']);
 const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -116,10 +117,7 @@ export function validateFrontmatter(frontmatter, config, file, source) {
     validateCardMetadata(frontmatter.card, file);
     validateSubjectDeprecation(frontmatter.subjectDeprecation, file);
     validateAuthoredChange(frontmatter, file);
-    const standalone = frontmatter.standaloneSections;
-    if (standalone !== undefined && (!Array.isArray(standalone) || standalone.some(title => typeof title !== 'string' || !title.trim() || title !== title.trim()) || new Set(standalone).size !== standalone.length)) {
-        throw new Error(`${file}: standaloneSections must be a unique list of nonempty, trimmed heading titles`);
-    }
+    validateStandaloneSectionDeclarations(frontmatter.standaloneSections, file);
     const mode = config?.changelogIdentifier ?? 'either';
     if (frontmatter.type === 'changelog-entry' &&
         (mode === 'date' && frontmatter.date === undefined || mode === 'version' && frontmatter.releaseVersion === undefined || mode === 'either' && frontmatter.date === undefined && frontmatter.releaseVersion === undefined))
@@ -180,6 +178,8 @@ export function validateFrontmatter(frontmatter, config, file, source) {
         throw new Error(`${file}: tocDepth must be 0 or an integer from 2 through 6`);
     if (frontmatter.layout !== undefined && !['docs', 'wide', 'landing', 'splash'].includes(frontmatter.layout))
         throw new Error(`${file}: layout must be docs, wide, landing, or splash`);
+    if (frontmatter.showVerified !== undefined && typeof frontmatter.showVerified !== 'boolean')
+        throw new Error(`${file}: showVerified must be true or false`);
     if (frontmatter.showNavigationTabs !== undefined && typeof frontmatter.showNavigationTabs !== 'boolean')
         throw new Error(`${file}: showNavigationTabs must be true or false`);
     if (frontmatter.image !== undefined && (typeof frontmatter.image !== 'string' || !/\.(?:png|jpe?g)$/i.test(frontmatter.image) || /^[a-z][a-z0-9+.-]*:/i.test(frontmatter.image)))
@@ -245,8 +245,9 @@ export function frontmatterSchema(config) {
         subjectDeprecation: { type: 'object', minProperties: 1, additionalProperties: false, description: 'Page-specific subject retirement dates and stable document IDs; requires deprecated subjectLifecycle, including OpenAPI inference. Dates do not change status automatically.', properties: { deprecatedOn: { type: 'string', format: 'date' }, sunsetOn: { type: 'string', format: 'date' }, replacement: { type: 'string', minLength: 1 }, migration: { type: 'string', minLength: 1 } } },
         subjectLifecycle: { type: 'string', enum: ['deprecated', 'in-development', 'beta', 'experimental'], description: 'Displays a content status badge in the page and navigation.' },
         lifecycle: { type: 'string', minLength: 1, description: 'Editorial lifecycle of the document; validated by an opted-in external vocabulary.' },
-        standaloneSections: { type: 'array', items: { type: 'string' }, uniqueItems: true, description: 'Page-specific exact level-two heading titles reviewed by the author as self-contained with the page introduction. Allows eligible sections to be recommended alone; omitted means full-page reads.' },
+        standaloneSections: { type: 'array', items: { oneOf: [{ type: 'string', minLength: 1 }, { type: 'object', additionalProperties: false, required: ['id', 'context'], properties: { id: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,511}$' }, context: { const: 'section' } } }] }, uniqueItems: true, description: 'Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads.' },
         tocDepth: { type: 'integer', enum: [0, 2, 3, 4, 5, 6], description: 'Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.' },
+        showVerified: { type: 'boolean', description: 'Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.' },
         showNavigationTabs: { type: 'boolean', description: 'Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.' },
         image: { type: 'string', pattern: '\\.(?:png|jpe?g)$', description: 'Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.' },
         layout: { type: 'string', enum: ['docs', 'wide', 'landing', 'splash'], description: 'HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).' },
@@ -319,7 +320,7 @@ export function frontmatterReference(config, sectionsOnly = false) {
         'Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.', '',
         '## Categorize, connect, and present the page', '',
         'By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document\'s editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project\'s `frontmatter.changelogIdentifier` rule.', '',
-        ...table, ...nativeRows(['product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'image']), '',
+        ...table, ...nativeRows(['product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
         'Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.', '',
         '## Control output details', '',
         '`seo` changes the browser title or HTML meta description. `displayText` overrides the text chosen for one output surface on this page. `variables` supplies values to registered snippets before they expand into the page body. `markdownMetadata` selects or overrides the YAML preamble of the generated Markdown twin—the machine-readable copy of this page. That generated preamble is separate from the source frontmatter shown above.', '',

package/dist/html-renderer.js

@@ -15,6 +15,7 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
     const hast = html.runSync(tree);
     const used = new Set(reservedIds);
     const headings = [];
+    const aliases = new Map();
     const textOf = (node) => node.type === 'text' ? node.value : (node.children ?? []).map(textOf).join('');
     const checkUrl = (value) => {
         if (typeof value !== 'string')
@@ -34,6 +35,11 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
     };
     collectIds(hast);
     const visit = (node) => {
+        const sectionId = node.properties?.['data-shoalrun-section-id'] ?? node.properties?.dataShoalrunSectionId;
+        if (node.properties) {
+            delete node.properties['data-shoalrun-section-id'];
+            delete node.properties.dataShoalrunSectionId;
+        }
         const match = /^h([2-6])$/.exec(node.tagName ?? '');
         if (match && !node.properties?.className?.some((name) => ['tab-fallback-heading', 'walkthrough-step-title'].includes(name))) {
             const title = textOf(node).trim();
@@ -50,11 +56,30 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
                 }
                 if (!node.properties?.className?.includes('doc-step-heading-toc-ignore'))
                     headings.push({ depth, id, title });
+                if (typeof sectionId === 'string' && sectionId !== id)
+                    aliases.set(node, sectionId);
             }
         }
         node.children?.forEach(visit);
     };
     visit(hast);
+    // Preserve existing heading-derived URLs. Explicit identities add aliases,
+    // rather than reserving names early and renumbering unrelated headings.
+    for (const id of aliases.values()) {
+        if (used.has(id))
+            throw new Error(`Explicit section ID ${id} conflicts with an existing HTML anchor`);
+        used.add(id);
+    }
+    const addAliases = (node) => {
+        if (!node.children)
+            return;
+        node.children = node.children.flatMap((child) => {
+            addAliases(child);
+            const id = aliases.get(child);
+            return id ? [{ type: 'element', tagName: 'span', properties: { id, ariaHidden: 'true' }, children: [] }, child] : [child];
+        });
+    };
+    addAliases(hast);
     let rendered = String(html.stringify(hast));
     for (const [marker, markup] of math)
         rendered = rendered.replaceAll(marker, markup);

package/dist/markdown-sections.d.ts

@@ -1,3 +1,4 @@
+import { type StandaloneSectionDeclaration } from './section-identity.js';
 export type MarkdownSection = {
     id: string;
     title: string;
@@ -12,4 +13,4 @@ export type MarkdownSection = {
     markdownTokenEncoding: string;
     content: string;
 };
-export declare function markdownSections(tree: any, markdownUrl: string, parent: string, prefix: string, render: (tree: any) => string, standaloneTitles?: string[]): MarkdownSection[];
+export declare function markdownSections(tree: any, markdownUrl: string, parent: string, prefix: string, render: (tree: any) => string, declarations?: StandaloneSectionDeclaration[]): MarkdownSection[];

package/dist/markdown-sections.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { markdownSize } from './markdown-size.js';
 import { link, list, paragraph, renderMarkdown, root, text } from './semantic-markdown.js';
+import { validateStandaloneSections } from './section-identity.js';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const pathKey = (item) => `${item.type}:${item.id}`;
 // Only direct page children qualify: hoisting a view from a ReaderSection, tab,
@@ -27,34 +28,23 @@ function missingReadingPath(all, included) {
 const textOf = (node) => typeof node.value === 'string' ? node.value : (node.children ?? []).map(textOf).join('');
 // Split the semantic root, never the flattened Markdown: a reader section or tab
 // remains intact even when it contains headings. Nested headings are not resources.
-export function markdownSections(tree, markdownUrl, parent, prefix, render, standaloneTitles = []) {
+export function markdownSections(tree, markdownUrl, parent, prefix, render, declarations = []) {
     const parentSize = markdownSize(parent);
     const children = tree.children ?? [];
-    const starts = children.flatMap((node, index) => node.type === 'heading' && node.depth === 2 ? [index] : []);
+    const identities = validateStandaloneSections(tree, declarations, markdownUrl);
+    const starts = identities.map(section => section.start);
     // Check declarations even on short pages: a renamed or ambiguous heading must
     // never silently retain an author's approval. Titles refer to normalized text.
-    for (const title of standaloneTitles) {
-        if (starts.filter(start => textOf(children[start]).trim() === title).length !== 1) {
-            throw new Error(`${markdownUrl}: standaloneSections title "${title}" must match exactly one top-level level-two heading`);
-        }
-    }
     if (parentSize.markdownTokens < 2000)
         return [];
     const preamble = children.slice(0, starts[0] ?? 0);
-    const used = new Set();
-    return starts.map(start => {
-        const title = textOf(children[start]).trim();
-        const stem = title.normalize('NFKD').toLowerCase().replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'section';
-        let id = stem;
-        for (let suffix = 2; used.has(id); suffix++)
-            id = `${stem}-${suffix}`;
-        used.add(id);
-        const end = children.findIndex((node, position) => position > start && node.type === 'heading' && node.depth <= 2);
-        const nodes = [...preamble, ...children.slice(start, end === -1 ? children.length : end)].filter(node => !['definition', 'footnoteDefinition'].includes(node.type));
+    return identities.map(({ start, end, id, title }) => {
+        const nodes = [...preamble, ...children.slice(start, end)].filter(node => !['definition', 'footnoteDefinition'].includes(node.type));
         const definitions = children.filter(node => ['definition', 'footnoteDefinition'].includes(node.type));
         const content = prefix + renderMarkdown(root([paragraph(text('Parent page: '), link(markdownUrl, 'Full Markdown page'))])) + '\n'
             + render(root([...missingReadingPath(children, nodes), ...nodes, ...definitions]));
-        return { id, title, depth: 2, ...(standaloneTitles.includes(title) ? { standalone: true } : {}), markdownUrl: `${markdownUrl.slice(0, -3)}.sections/${id}.md`, parentMarkdownUrl: markdownUrl,
+        const standalone = declarations.some(item => typeof item === 'string' ? item === title : item.id === id);
+        return { id, title, depth: 2, ...(standalone ? { standalone: true } : {}), markdownUrl: `${markdownUrl.slice(0, -3)}.sections/${id}.md`, parentMarkdownUrl: markdownUrl,
             parentDigest: digest(parent), digest: digest(content), ...markdownSize(content), content };
     }).filter(section => section.markdownTokens <= parentSize.markdownTokens / 2 && section.markdownBytes <= parentSize.markdownBytes / 2);
 }

package/dist/page-renderer.js

@@ -1,5 +1,5 @@
 import { resolveAgentDiscovery } from './agent-discovery.js';
-import { navigationCounts } from './compiler-config.js';
+import { navigationCounts, navigationHeading } from './compiler-config.js';
 import { navigationTab } from './project-navigation.js';
 import { highlightedExample } from './highlight.js';
 import { readerFilterAttribute } from './reader-filters.js';
@@ -81,8 +81,9 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const date = doc.frontmatter.date ? `<time class="page-date" datetime="${esc(doc.frontmatter.date)}">${esc(doc.frontmatter.date)}</time>` : '';
     const changelogEntry = doc.frontmatter.type === 'changelog-entry';
     const updated = doc.frontmatter.updated && !(changelogEntry && doc.frontmatter.date) ? `<span class="page-date">Updated <time datetime="${esc(doc.frontmatter.updated)}">${esc(doc.frontmatter.updated.slice(0, 10))}</time></span>` : '';
+    const verified = doc.frontmatter.verified && doc.frontmatter.showVerified !== false ? `<span class="page-date">Verified <time datetime="${esc(doc.frontmatter.verified)}">${esc(doc.frontmatter.verified)}</time></span>` : '';
     const releaseVersion = doc.frontmatter.releaseVersion ? `<span class="page-version">Version ${esc(doc.frontmatter.releaseVersion)}</span>` : '';
-    const pageDates = changelogEntry ? `<div class="page-meta">${date}${updated}${releaseVersion}</div>` : `${date}${updated}${releaseVersion}`;
+    const pageDates = changelogEntry ? `<div class="page-meta">${date}${updated}${verified}${releaseVersion}</div>` : `${date}${updated}${verified}${releaseVersion}`;
     const containsCurrent = (item) => item.route === doc.route || !!item.items?.some(containsCurrent);
     const activeTab = navigationTab(navigation, doc.route);
     const analyticsBootstrap = config.analytics ? `<script type="application/json" id="analytics-config">${JSON.stringify({ pageId: doc.frontmatter.id, pageUrl: doc.route, documentType: doc.frontmatter.type, channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language, ...(activeTab ? { navigationSectionId: activeTab.id } : {}) }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/analytics.js"></script>` : '';
@@ -107,7 +108,8 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
         return `<li class="nav-entry${deprecated ? ' nav-deprecated' : ''}" data-search="${esc(search)}"${config.readerFilters ? ` data-reader-filters="${esc(readerFilterAttribute(item.readerFilters ?? {}))}"` : ''}><a href="${esc(item.route)}"${item.route === doc.route ? ' aria-current="page"' : ''}>${method}${label}${status}</a></li>`;
     }).join('');
     const readerControls = readerConfig?.controls.sidebar ? readerFilterSlot({ display: 'checks', label: 'Reader view' }, esc) : '';
-    const nav = `<details class="nav-disclosure" open><summary>Menu</summary><div class="nav-body"><a class="region-return" href="#main" data-region-return>Back to article</a><div class="nav-tools"><h2>Explore</h2>${readerControls}<div class="nav-search" hidden><label for="nav-filter">Filter navigation</label><input id="nav-filter" type="search" autocomplete="off"><p class="nav-filter-status" role="status" aria-live="polite"></p></div></div><ul class="nav-tree">${renderNav(sidebarNavigation)}</ul></div></details>`;
+    const heading = navigationHeading(config.outputs);
+    const nav = `<details class="nav-disclosure" open><summary>Menu</summary><div class="nav-body"><a class="region-return" href="#main" data-region-return>Back to article</a><div class="nav-tools">${heading === false ? '' : `<h2>${esc(heading)}</h2>`}${readerControls}<div class="nav-search" hidden><label for="nav-filter">Filter navigation</label><input id="nav-filter" type="search" autocomplete="off"><p class="nav-filter-status" role="status" aria-live="polite"></p></div></div><ul class="nav-tree">${renderNav(sidebarNavigation)}</ul></div></details>`;
     const readerBanner = readerConfig ? '<aside class="reader-outside-view" role="status" hidden></aside>' : '';
     const readerBootstrap = readerConfig ? `<script type="application/json" id="reader-filter-config">${JSON.stringify({ facets: readerConfig.facets, storageKey: `shoalrun-reader-view:${basePath || '/'}`, moduleUrl: readerConfig.module ? sitePath(basePath, '/assets/reader-view-custom.js') : null }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/reader-filters.js"></script>` : '';
     const groups = new Map();

package/dist/publication-plan.js

@@ -1,3 +1,4 @@
+import { hasScaffoldPlaceholders } from './scaffold-placeholders.js';
 import { matchesContentFilter } from './content-filter.js';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
@@ -60,7 +61,7 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
         const marks = pageReaderFilters(frontmatter, readerFilters, file);
         if (!matchesContentFilter(marks, contentFilter))
             continue;
-        if (/\[\[TODO:[\s\S]*?\]\]/.test(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
+        if (hasScaffoldPlaceholders(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
             throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
         for (const variant of variants) {
             if (pagePublications ? !pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version))

package/dist/scaffold-placeholders.d.ts

@@ -0,0 +1,2 @@
+/** Fenced code are teaching examples, not scaffold prose. */
+export declare function hasScaffoldPlaceholders(body: string): boolean;

package/dist/scaffold-placeholders.js

@@ -0,0 +1,19 @@
+import { parse } from './semantic-markdown.js';
+/** Fenced code are teaching examples, not scaffold prose. */
+export function hasScaffoldPlaceholders(body) {
+    const placeholder = /\[\[TODO:[\s\S]*?\]\]/;
+    if (!placeholder.test(body))
+        return false;
+    const ranges = [];
+    const visit = (node) => {
+        if (node.type === 'code' && node.position)
+            ranges.push([node.position.start.offset, node.position.end.offset]);
+        else
+            for (const child of node.children ?? [])
+                visit(child);
+    };
+    visit(parse.parse(body));
+    for (const [start, end] of ranges.sort((a, b) => b[0] - a[0]))
+        body = body.slice(0, start) + ' '.repeat(end - start) + body.slice(end);
+    return placeholder.test(body);
+}

package/dist/section-identity.d.ts

@@ -0,0 +1,24 @@
+/** Section identities are independent of a representation's DOM anchors. */
+export type StandaloneSectionDeclaration = string | {
+    id: string;
+    context: 'section';
+};
+export type SectionIdentity = {
+    id: string;
+    title: string;
+    depth: 2;
+    start: number;
+    end: number;
+    explicit: boolean;
+};
+export declare const validSectionId: (value: unknown) => value is string;
+/** Consume only a direct trailing marker on an authored root H2. Code stays inert. */
+export declare function lowerSectionMarkers(tree: any, label?: string): any;
+export declare function sectionIdentities(tree: any, label?: string): SectionIdentity[];
+export declare function validateStandaloneSectionDeclarations(value: unknown, label?: string): asserts value is StandaloneSectionDeclaration[] | undefined;
+export declare function validateStandaloneSections(tree: any, declarations?: StandaloneSectionDeclaration[], label?: string): SectionIdentity[];
+/** Slice-only delivery is a distinct author approval from contextual discovery. */
+export declare function selectSection(tree: any, id: string, declarations?: StandaloneSectionDeclaration[], label?: string): {
+    section: SectionIdentity;
+    tree: any;
+};

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] } };
+}