@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/budget.d.ts

@@ -0,0 +1,45 @@
+export type BudgetStore = {
+    add(key: string, amount: number, ttlSeconds: number): Promise<number>;
+    get(key: string): Promise<number>;
+};
+export type BudgetLimits = {
+    perCaller: number;
+    perDay: number;
+};
+export type BudgetReservation = {
+    readonly callerKey: string;
+    readonly siteKey: string;
+};
+export declare function memoryBudgetStore(now?: () => number): BudgetStore;
+export declare class SharedRateLimit {
+    private readonly store;
+    readonly perMinute: number;
+    private readonly now;
+    private readonly onError;
+    private readonly namespace;
+    constructor(store: BudgetStore, perMinute: number, now?: () => number, onError?: (error: Error) => void, namespace?: string);
+    take(caller: string): Promise<{
+        allowed: boolean;
+        retryAfterSeconds: number;
+    }>;
+}
+export declare class DailyBudget {
+    private readonly store;
+    readonly limits: BudgetLimits;
+    private readonly now;
+    private readonly onError;
+    private readonly namespace;
+    constructor(store: BudgetStore, limits: BudgetLimits, now?: () => number, onError?: (error: Error) => void, namespace?: string);
+    private keys;
+    usage(caller: string): Promise<{
+        mine: number;
+        all: number;
+    }>;
+    reserve(caller: string): Promise<boolean>;
+    reserveWithReceipt(caller: string): Promise<BudgetReservation | undefined>;
+    releaseReservation(reservation: BudgetReservation): Promise<void>;
+}
+export declare function adaptiveChallenge(budget: Pick<DailyBudget, 'usage' | 'limits'>, options?: {
+    freeQuestions?: number;
+    busyShare?: number;
+}): (caller: string) => Promise<boolean>;

package/dist/budget.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+export function memoryBudgetStore(now = Date.now) {
+    const counters = new Map();
+    const live = (key) => {
+        const entry = counters.get(key);
+        if (entry && entry.expires <= now()) {
+            counters.delete(key);
+            return undefined;
+        }
+        return entry;
+    };
+    return {
+        async add(key, amount, ttlSeconds) {
+            const entry = live(key) ?? { total: 0, expires: now() + ttlSeconds * 1000 };
+            entry.total += amount;
+            counters.set(key, entry);
+            // Bounded by the number of callers in a day; drop expired counters when it grows.
+            if (counters.size > 10_000)
+                for (const name of [...counters.keys()])
+                    live(name);
+            return entry.total;
+        },
+        async get(key) { return live(key)?.total ?? 0; }
+    };
+}
+const callerHash = (caller) => createHash('sha256').update(caller).digest('hex').slice(0, 16);
+// A per-minute limit that holds across server instances, on the same store as the daily budget. A fixed one-minute window per caller: a
+// caller can send a burst on each side of a minute boundary, which the daily budget still bounds. A request that is over the limit still
+// counts, so hammering keeps a caller limited. A store that fails refuses the request.
+export class SharedRateLimit {
+    store;
+    perMinute;
+    now;
+    onError;
+    namespace;
+    constructor(store, perMinute, now = Date.now, onError = () => { }, namespace = 'rate') {
+        this.store = store;
+        this.perMinute = perMinute;
+        this.now = now;
+        this.onError = onError;
+        this.namespace = namespace;
+        if (!Number.isSafeInteger(perMinute) || perMinute < 1)
+            throw new Error('The per-minute limit must be a whole number of 1 or more');
+    }
+    async take(caller) {
+        const at = this.now();
+        const minute = Math.floor(at / 60_000);
+        const retryAfterSeconds = Math.max(1, Math.ceil(((minute + 1) * 60_000 - at) / 1000));
+        try {
+            return { allowed: await this.store.add(`${this.namespace}:${minute}:${callerHash(caller)}`, 1, 120) <= this.perMinute, retryAfterSeconds };
+        }
+        catch (error) {
+            this.onError(error);
+            return { allowed: false, retryAfterSeconds: 5 };
+        }
+    }
+}
+export class DailyBudget {
+    store;
+    limits;
+    now;
+    onError;
+    namespace;
+    constructor(store, limits, now = Date.now, onError = () => { }, namespace = 'budget') {
+        this.store = store;
+        this.limits = limits;
+        this.now = now;
+        this.onError = onError;
+        this.namespace = namespace;
+    }
+    // Counters roll over at midnight UTC. The caller is hashed, so the store never holds an address.
+    keys(caller) {
+        const day = new Date(this.now()).toISOString().slice(0, 10);
+        return { caller: `${this.namespace}:${day}:${callerHash(caller)}`, all: `${this.namespace}:${day}:all` };
+    }
+    // How much of today's budget this caller and the whole site have used, counting questions that reached the model. It reads the counters and
+    // changes nothing. A store that cannot be read throws, and the caller of this decides what that means.
+    async usage(caller) {
+        const keys = this.keys(caller);
+        const [mine, all] = await Promise.all([this.store.get(keys.caller), this.store.get(keys.all)]);
+        return { mine, all };
+    }
+    // Take one of this caller's slots for today, before the question is answered. The counters go up first and the totals are checked
+    // afterwards, so questions that arrive together on many server instances cannot all pass a check that none has been counted in yet.
+    // A store that fails counts as spent: an outage must not open the model to everyone.
+    async reserve(caller) { return Boolean(await this.reserveWithReceipt(caller)); }
+    async reserveWithReceipt(caller) {
+        let keys;
+        try {
+            keys = this.keys(caller);
+            const [mine, all] = await Promise.all([this.store.add(keys.caller, 1, 172_800), this.store.add(keys.all, 1, 172_800)]);
+            if (mine <= this.limits.perCaller && all <= this.limits.perDay)
+                return { callerKey: keys.caller, siteKey: keys.all };
+            await Promise.all([this.store.add(keys.caller, -1, 172_800), this.store.add(keys.all, -1, 172_800)]);
+            return undefined;
+        }
+        catch (error) {
+            this.onError(error);
+            return undefined;
+        }
+    }
+    // Give a slot back when the question turned out not to need the model, such as one served from the cache. A slot that cannot be
+    // given back stays counted, which errs toward the cap.
+    async releaseReservation(reservation) {
+        try {
+            await Promise.all([this.store.add(reservation.callerKey, -1, 172_800), this.store.add(reservation.siteKey, -1, 172_800)]);
+        }
+        catch (error) {
+            this.onError(error);
+        }
+    }
+}
+// When to ask a visitor to prove they are a person. Nobody is asked at first. A caller is asked once they have used `freeQuestions` model answers
+// in a day, and everyone is asked once the site has used `busyShare` of its daily budget. A
+// store that cannot be read means "ask", so an outage never removes the check.
+export function adaptiveChallenge(budget, options = {}) {
+    const free = options.freeQuestions ?? 3;
+    const busy = options.busyShare ?? 0.5;
+    return async (caller) => {
+        try {
+            const { mine, all } = await budget.usage(caller);
+            return mine >= free || all >= budget.limits.perDay * busy;
+        }
+        catch {
+            return true;
+        }
+    };
+}

package/dist/build-info.d.ts

@@ -0,0 +1,10 @@
+export type BuildProvenance = {
+    sourceCommit?: string;
+    releaseLabel?: string;
+};
+export declare function buildInfo(configDigest: string, provenance?: BuildProvenance): {
+    releaseLabel?: string | undefined;
+    sourceCommit?: string | undefined;
+    schemaVersion: number;
+    configDigest: string;
+};

package/dist/build-info.js

@@ -0,0 +1,15 @@
+export function buildInfo(configDigest, provenance = {}) {
+    const { sourceCommit, releaseLabel } = provenance;
+    if (sourceCommit !== undefined && !/^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/.test(sourceCommit)) {
+        throw new Error('sourceCommit must be a full 40- or 64-character Git commit hash');
+    }
+    if (releaseLabel !== undefined && (!releaseLabel.trim() || releaseLabel.length > 128 || /[\x00-\x1f\x7f]/.test(releaseLabel))) {
+        throw new Error('releaseLabel must be 1–128 printable characters');
+    }
+    return {
+        schemaVersion: 1,
+        configDigest,
+        ...(sourceCommit ? { sourceCommit: sourceCommit.toLowerCase() } : {}),
+        ...(releaseLabel ? { releaseLabel } : {})
+    };
+}

package/dist/callouts.d.ts

@@ -0,0 +1,18 @@
+export declare const calloutTones: readonly ["note", "tip", "important", "warning", "caution"];
+type ToneColors = {
+    line: string;
+    background: string;
+    text: string;
+};
+export type CalloutColors = ToneColors & {
+    dark?: ToneColors;
+};
+export type CalloutType = {
+    label: string;
+    tone: string;
+    icon?: string;
+    colors?: CalloutColors;
+};
+export type CalloutTypes = Map<string, CalloutType>;
+export declare function resolveCalloutTypes(config: unknown, file: string): CalloutTypes;
+export {};

package/dist/callouts.js

@@ -0,0 +1,63 @@
+import { validateLucideIcon } from './icons.js';
+export const calloutTones = ['note', 'tip', 'important', 'warning', 'caution'];
+const defaults = {
+    note: { label: 'Note', tone: 'note', icon: 'info' },
+    tip: { label: 'Tip', tone: 'tip', icon: 'lightbulb' },
+    important: { label: 'Important', tone: 'important', icon: 'circle-alert' },
+    warning: { label: 'Warning', tone: 'warning', icon: 'triangle-alert' },
+    caution: { label: 'Caution', tone: 'caution', icon: 'octagon-alert' }
+};
+const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const namePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const hexColor = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+export function resolveCalloutTypes(config, file) {
+    const types = new Map(Object.entries(defaults));
+    if (config === undefined)
+        return types;
+    if (!mapping(config) || Object.keys(config).some(key => !['types', 'tones'].includes(key)) || (config.types !== undefined && !mapping(config.types)) || (config.tones !== undefined && !mapping(config.tones)))
+        throw new Error(`${file}: callouts must contain types and/or tones mappings`);
+    const tones = new Map();
+    for (const [name, value] of Object.entries(config.tones ?? {})) {
+        if (!namePattern.test(name))
+            throw new Error(`${file}: callouts.tones name "${name}" must use lowercase kebab-case`);
+        if (!mapping(value) || Object.keys(value).some(key => !['line', 'background', 'text', 'dark'].includes(key)))
+            throw new Error(`${file}: callouts.tones.${name} only accepts line, background, text, and dark`);
+        for (const key of ['line', 'background', 'text'])
+            if (typeof value[key] !== 'string' || !hexColor.test(value[key]))
+                throw new Error(`${file}: callouts.tones.${name}.${key} must be a hex color`);
+        const dark = value.dark;
+        if (dark !== undefined) {
+            if (!mapping(dark) || Object.keys(dark).some(key => !['line', 'background', 'text'].includes(key)))
+                throw new Error(`${file}: callouts.tones.${name}.dark only accepts line, background, and text`);
+            for (const key of ['line', 'background', 'text'])
+                if (typeof dark[key] !== 'string' || !hexColor.test(dark[key]))
+                    throw new Error(`${file}: callouts.tones.${name}.dark.${key} must be a hex color`);
+        }
+        const colors = { line: value.line, background: value.background, text: value.text };
+        tones.set(name, dark === undefined ? colors : { ...colors, dark: { line: dark.line, background: dark.background, text: dark.text } });
+    }
+    for (const [name, value] of Object.entries(config.types ?? {})) {
+        if (!namePattern.test(name))
+            throw new Error(`${file}: callouts.types name "${name}" must use lowercase kebab-case`);
+        if (!mapping(value) || Object.keys(value).some(key => !['label', 'tone', 'icon'].includes(key)))
+            throw new Error(`${file}: callouts.types.${name} only accepts label, tone, and icon`);
+        const original = types.get(name);
+        const label = value.label ?? original?.label;
+        const tone = value.tone ?? original?.tone;
+        const icon = value.icon ?? original?.icon;
+        if (typeof label !== 'string' || !label.trim())
+            throw new Error(`${file}: callouts.types.${name}.label must be nonempty text`);
+        if (typeof tone !== 'string' || !(calloutTones.includes(tone) || tones.has(tone)))
+            throw new Error(`${file}: callouts.types.${name}.tone must be a built-in or registered tone`);
+        if (icon !== undefined) {
+            if (typeof icon !== 'string')
+                throw new Error(`${file}: callouts.types.${name}.icon must be a Lucide icon name`);
+            validateLucideIcon(icon, file, `callouts.types.${name}.icon`);
+        }
+        types.set(name, { label: label.trim(), tone, icon, ...(tones.has(tone) ? { colors: tones.get(tone) } : {}) });
+    }
+    for (const [name, definition] of types)
+        if (tones.has(definition.tone))
+            types.set(name, { ...definition, colors: tones.get(definition.tone) });
+    return types;
+}

package/dist/cards.d.ts

@@ -0,0 +1,35 @@
+import type { Document } from './content.js';
+export type Relationship = {
+    id: string;
+    from: string;
+    to: string;
+    type: 'next-step' | 'see-also' | 'prerequisite' | 'reference' | 'advanced' | 'not-confused-with';
+    reason: string;
+    order?: number;
+};
+export type CardRequest = {
+    component: 'DocCard' | 'DocCards' | 'DocCollection' | 'RelatedReading';
+    layout?: 'list' | 'cards';
+    doc?: string;
+    docs?: string[];
+    relatedTo?: string;
+    relation?: Relationship['type'];
+    type?: string;
+    tag?: string;
+    operation?: string;
+    audience?: string;
+    orderBy?: 'title' | 'id' | 'date' | 'releaseVersion';
+    limit?: number;
+    exclude?: string[];
+    pin?: string[];
+    empty?: string;
+};
+export type CardUse = {
+    targets: string[];
+    queries: CardRequest[];
+};
+export declare function validateCardMetadata(value: unknown, file: string): void;
+export declare function validateRelationships(value: unknown, knownIds: Set<string>): Relationship[];
+export declare function publicationRelationships(edges: Relationship[], registry: Map<string, Document>): Relationship[];
+export declare function cardComponent(node: any, file: string): any;
+export declare function resolveCardTree(tree: any, current: Document, documents: Map<string, Document>, edges: Relationship[], operations: Set<string>, use: CardUse, config?: any): any;

package/dist/cards.js

@@ -0,0 +1,237 @@
+import { cardIcon, validateCardIcon } from './icons.js';
+import { surfaceText } from './surface-text.js';
+import { heading, link, list, paragraph, text } from './content.js';
+import { readerFilterAttribute } from './reader-filters.js';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const relationLabels = { prerequisite: 'Read first', 'next-step': 'Next steps', reference: 'Reference while working', advanced: 'Go deeper', 'see-also': 'Related topics', 'not-confused-with': 'Often confused with' };
+const relationTypes = new Set(Object.keys(relationLabels));
+const symmetric = (type) => type === 'see-also' || type === 'not-confused-with';
+const sameVariant = (a, b) => a.channel === b.channel && a.version === b.version && a.language === b.language;
+export function validateCardMetadata(value, file) {
+    if (value === undefined)
+        return;
+    if (!object(value))
+        throw new Error(`${file}: card must be a mapping`);
+    for (const [key, field] of Object.entries(value)) {
+        if (!['title', 'description', 'eyebrow', 'icon'].includes(key))
+            throw new Error(`${file}: unsupported card setting ${key}`);
+        if (typeof field !== 'string' || !field.trim())
+            throw new Error(`${file}: card.${key} must be nonempty text`);
+        if (key === 'icon')
+            validateCardIcon(field, file);
+    }
+}
+export function validateRelationships(value, knownIds) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('relationships must be a list');
+    const ids = new Set();
+    const pairs = new Set();
+    for (const edge of value) {
+        if (!object(edge))
+            throw new Error('Each relationship must be a mapping');
+        for (const key of Object.keys(edge))
+            if (!['id', 'from', 'to', 'type', 'reason', 'order'].includes(key))
+                throw new Error(`Unknown relationship setting ${key}`);
+        for (const key of ['id', 'from', 'to', 'type', 'reason'])
+            if (typeof edge[key] !== 'string' || !edge[key].trim())
+                throw new Error(`Relationship needs ${key}`);
+        if (!relationTypes.has(edge.type))
+            throw new Error(`Unsupported relationship type ${edge.type}`);
+        if (ids.has(edge.id))
+            throw new Error(`Duplicate relationship ID ${edge.id}`);
+        ids.add(edge.id);
+        for (const id of [edge.from, edge.to])
+            if (!knownIds.has(id))
+                throw new Error(`Relationship ${edge.id} targets unknown document ${id}`);
+        if (edge.from === edge.to)
+            throw new Error(`Relationship ${edge.id} cannot link a document to itself`);
+        if (edge.order !== undefined && (typeof edge.order !== 'number' || !Number.isFinite(edge.order)))
+            throw new Error(`Relationship ${edge.id}.order must be a finite number`);
+        const endpoints = symmetric(edge.type) ? [edge.from, edge.to].sort(compare) : [edge.from, edge.to];
+        const key = JSON.stringify([edge.type, ...endpoints]);
+        if (pairs.has(key))
+            throw new Error(`Duplicate relationship ${edge.from} ${edge.type} ${edge.to}`);
+        pairs.add(key);
+    }
+    return value;
+}
+export function publicationRelationships(edges, registry) {
+    const visible = edges.filter(edge => registry.has(edge.from) && registry.has(edge.to));
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new Error(`Prerequisite cycle at document ${id}`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const edge of visible)
+            if (edge.from === id && edge.type === 'prerequisite')
+                visit(edge.to);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const id of registry.keys())
+        visit(id);
+    return visible.slice().sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || compare(a.id, b.id));
+}
+export function cardComponent(node, file) {
+    const fail = (message) => { throw new Error(`${file}: <${node.name}> ${message}`); };
+    if (node.type !== 'mdxJsxFlowElement' || node.children?.length)
+        fail('must be a standalone empty element');
+    const allowed = node.name === 'RelatedReading' ? ['relatedTo', 'relation', 'layout', 'empty'] : node.name === 'DocCard' ? ['doc'] : node.name === 'DocCards'
+        ? ['docs', 'relatedTo', 'relation', 'empty']
+        : ['type', 'tag', 'operation', 'audience', 'orderBy', 'limit', 'exclude', 'pin', 'empty'];
+    const request = { component: node.name };
+    for (const attribute of node.attributes ?? []) {
+        const name = attribute.name;
+        if (attribute.type !== 'mdxJsxAttribute' || !allowed.includes(name) || Object.hasOwn(request, name))
+            fail(`has unknown or duplicate attribute ${name ?? '(spread)'}`);
+        let value = attribute.value;
+        if (typeof value !== 'string') {
+            const program = attribute.value?.data?.estree;
+            const expression = program?.body?.length === 1 && program.body[0].type === 'ExpressionStatement' ? program.body[0].expression : null;
+            if (expression?.type === 'Literal')
+                value = expression.value;
+            else if (expression?.type === 'ArrayExpression' && expression.elements.every((item) => item?.type === 'Literal' && typeof item.value === 'string'))
+                value = expression.elements.map((item) => item.value);
+            else
+                fail(`${name} must be a literal value`);
+        }
+        if (['docs', 'exclude', 'pin'].includes(name)) {
+            if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim()) || new Set(value).size !== value.length)
+                fail(`${name} must be an array of unique document IDs`);
+        }
+        else if (name === 'limit') {
+            if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+                fail('limit must be a positive integer');
+        }
+        else if (typeof value !== 'string' || !value.trim())
+            fail(`${name} must be nonempty text`);
+        request[name] = value;
+    }
+    if (node.name === 'DocCard' && !request.doc)
+        fail('needs doc');
+    if (node.name === 'DocCards') {
+        if (request.docs !== undefined ? request.relatedTo !== undefined || request.relation !== undefined : !request.relation)
+            fail('needs either docs or relation (with optional relatedTo)');
+    }
+    if (request.relation && !relationTypes.has(request.relation))
+        fail(`has unsupported relation ${request.relation}`);
+    if (request.layout && !['list', 'cards'].includes(request.layout))
+        fail('layout must be list or cards');
+    if (request.orderBy && !['title', 'id', 'date', 'releaseVersion'].includes(request.orderBy))
+        fail('orderBy must be title, id, date, or releaseVersion');
+    return { type: 'docCards', request, sourceFile: file };
+}
+export function resolveCardTree(tree, current, documents, edges, operations, use, config = {}) {
+    const registry = new Map([...documents.values()].filter(doc => sameVariant(doc.variant, current.variant)).map(doc => [doc.frontmatter.id, doc]));
+    const requireDoc = (id, file) => {
+        const doc = registry.get(id);
+        if (!doc)
+            throw new Error(`${file}: card target ${id} is unavailable in ${Object.values(current.variant).join('/')}`);
+        return doc;
+    };
+    const walk = (node) => {
+        if (node.type !== 'docCards')
+            return node.children ? { ...node, children: node.children.flatMap(walk) } : node;
+        const request = node.request;
+        const file = node.sourceFile;
+        let selected = [];
+        if (request.component === 'DocCard' || request.docs !== undefined) {
+            selected = (request.docs ?? [request.doc]).map(id => ({ doc: requireDoc(id, file) }));
+        }
+        else if (request.component === 'DocCards' || request.component === 'RelatedReading') {
+            const from = request.relatedTo ?? current.frontmatter.id;
+            requireDoc(from, file);
+            selected = edges.filter(edge => (!request.relation || edge.type === request.relation) && (edge.from === from || (symmetric(edge.type) && edge.to === from)))
+                .map(edge => ({ doc: registry.get(edge.from === from ? edge.to : edge.from), reason: edge.reason, relation: edge.type }));
+        }
+        else {
+            if (request.operation && !operations.has(request.operation))
+                throw new Error(`${file}: unknown card collection operation ${request.operation}`);
+            let matches = [...registry.values()].filter(doc => doc !== current
+                && (!request.type || doc.frontmatter.type === request.type)
+                && (!request.tag || doc.frontmatter.tags?.includes(request.tag))
+                && (!request.operation || doc.frontmatter.operations?.includes(request.operation))
+                && (!request.audience || doc.frontmatter.audiences?.includes(request.audience))
+                && !request.exclude?.includes(doc.frontmatter.id));
+            if (request.orderBy === 'date' && matches.some(doc => !doc.frontmatter.date))
+                throw new Error(`${file}: date-ordered collection includes a page without date`);
+            if (request.orderBy === 'releaseVersion' && matches.some(doc => !doc.frontmatter.releaseVersion))
+                throw new Error(`${file}: version-ordered collection includes a page without releaseVersion`);
+            const versionOrder = new Intl.Collator('en', { numeric: true, sensitivity: 'base' });
+            matches.sort((a, b) => (request.orderBy === 'date' ? compare(b.frontmatter.date, a.frontmatter.date) : request.orderBy === 'releaseVersion' ? versionOrder.compare(b.frontmatter.releaseVersion, a.frontmatter.releaseVersion) : request.orderBy === 'id' ? 0 : compare(a.frontmatter.title.toLowerCase(), b.frontmatter.title.toLowerCase())) || compare(a.frontmatter.id, b.frontmatter.id));
+            const pinned = (request.pin ?? []).map(id => {
+                const doc = requireDoc(id, file);
+                if (!matches.includes(doc))
+                    throw new Error(`${file}: pinned card ${id} does not match the collection filters`);
+                return doc;
+            });
+            matches = [...pinned, ...matches.filter(doc => !pinned.includes(doc))];
+            selected = matches.slice(0, request.limit).map(doc => ({ doc }));
+        }
+        if (request.component === 'DocCollection' || request.component === 'RelatedReading' || request.relation)
+            use.queries.push(request);
+        for (const { doc } of selected)
+            if (!use.targets.includes(doc.frontmatter.id))
+                use.targets.push(doc.frontmatter.id);
+        if (!selected.length)
+            return { ...paragraph(text(request.empty ?? 'No matching documents.')), data: { hProperties: { className: ['doc-cards-empty'] } } };
+        // Keep explicit current-page reading paths available to smaller section reads.
+        // The section extractor only carries root-level views, never conditional ones.
+        const rememberPath = (node, entries) => {
+            if (request.component !== 'RelatedReading' || (request.relatedTo ?? current.frontmatter.id) !== current.frontmatter.id)
+                return node;
+            const paths = entries.filter(entry => entry.relation === 'prerequisite' || entry.relation === 'next-step').map(({ doc, reason, relation }) => ({
+                id: doc.frontmatter.id, type: relation, title: doc.frontmatter.title, url: doc.route, reason,
+                ...(doc.frontmatter.subjectLifecycle ? { status: doc.frontmatter.subjectLifecycle.replaceAll('-', ' ') } : {})
+            }));
+            if (paths.length)
+                node.data = { ...node.data, sectionReadingPath: paths };
+            return node;
+        };
+        const render = (entries) => {
+            if (request.component === 'RelatedReading' && request.layout !== 'cards') {
+                const links = list(entries.map(({ doc, reason }) => [paragraph({ ...link(doc.route, doc.frontmatter.title), exportDocumentId: doc.frontmatter.id }, ...(reason ? [text(` — ${reason}`)] : []), ...(doc.frontmatter.subjectLifecycle ? [text(` (Status: ${doc.frontmatter.subjectLifecycle.replaceAll('-', ' ')}.)`)] : []))]));
+                links.data = { hProperties: { className: ['related-reading'] } };
+                for (const [index, item] of links.children.entries())
+                    item.data = { hProperties: { 'data-reader-filters': readerFilterAttribute(entries[index].doc.readerFilters ?? {}) } };
+                return rememberPath(links, entries);
+            }
+            const cards = list(entries.map(({ doc, reason }) => {
+                const meta = doc.frontmatter.card;
+                const subjectLifecycle = doc.frontmatter.subjectLifecycle;
+                const label = subjectLifecycle === 'in-development' ? 'In development' : subjectLifecycle === 'deprecated' ? 'Deprecated' : subjectLifecycle === 'beta' ? 'Beta' : subjectLifecycle === 'experimental' ? 'Experimental' : undefined;
+                const description = meta?.description ?? surfaceText(doc.frontmatter, 'card', config);
+                return [
+                    ...(meta?.icon ? [cardIcon(meta.icon)] : []),
+                    ...(meta?.eyebrow ? [{ ...paragraph(text(meta.eyebrow)), data: { hProperties: { className: ['doc-card-eyebrow'] } } }] : []),
+                    ...(doc.frontmatter.date ? [{ ...paragraph(text(doc.frontmatter.date)), data: { hName: 'time', hProperties: { dateTime: doc.frontmatter.date, className: ['doc-card-date'] } } }] : []),
+                    ...(doc.frontmatter.releaseVersion ? [{ ...paragraph(text(`Version ${doc.frontmatter.releaseVersion}`)), data: { hProperties: { className: ['doc-card-version'] } } }] : []),
+                    { ...paragraph({ ...link(doc.route, meta?.title ?? doc.frontmatter.title), exportDocumentId: doc.frontmatter.id }), data: { hProperties: { className: ['doc-card-title'] } } },
+                    ...(description ? [paragraph(text(description))] : []),
+                    ...(label ? [paragraph(text(`Status: ${label}.`))] : []),
+                    ...(reason ? [{ ...paragraph(text(reason)), data: { hProperties: { className: ['doc-card-reason'] } } }] : [])
+                ];
+            }));
+            cards.data = { hProperties: { className: ['doc-cards'] } };
+            for (const [index, item] of cards.children.entries()) {
+                item.spread = true;
+                item.data = { hProperties: { className: ['doc-card'], 'data-reader-filters': readerFilterAttribute(entries[index].doc.readerFilters ?? {}) } };
+            }
+            return rememberPath(cards, entries);
+        };
+        if (request.component === 'RelatedReading' && !request.relation) {
+            return Object.entries(relationLabels).flatMap(([type, label]) => {
+                const entries = selected.filter(item => item.relation === type);
+                return entries.length ? [heading(3, label), render(entries)] : [];
+            });
+        }
+        return render(selected);
+    };
+    return walk(tree);
+}