canopycms 0.0.68-int.98 → 0.1.0

package/dist/ai/json-to-markdown.js

@@ -4,20 +4,38 @@
  * Converts a single entry's data + schema fields to clean markdown.
  * Handles all CanopyCMS field types including nested objects and blocks.
  */
+import { RESTRICTED_REFERENCE_MARKER } from '../entry-schema.js';
 import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { resolveEntryTitle } from '../utils/title-field.js';
 import { stripMdxImports } from './strip-mdx.js';
 import { applyComponentTransforms } from './transform-components.js';
+const DEFAULT_REFERENCE_RENDERING = {
+    title: (target) => resolveEntryTitle(target, { slug: typeof target.slug === 'string' ? target.slug : undefined }),
+    url: (target) => typeof target.urlPath === 'string' && target.urlPath ? target.urlPath : undefined,
+};
+/**
+ * The entry's `title` as frontmatter carries it. Only a scalar qualifies: a `reference` field
+ * named `title` holds an object and renders as a field instead.
+ */
+export function frontmatterTitle(data) {
+    const { title } = data;
+    return (typeof title === 'string' || typeof title === 'number') && title !== ''
+        ? String(title)
+        : undefined;
+}
 /**
  * Convert an entry to clean markdown suitable for AI consumption.
  *
  * For MD/MDX entries: renders frontmatter fields as metadata, appends body verbatim.
  * For JSON entries: full schema-driven conversion of all fields.
  */
-export function entryToMarkdown(entry, config) {
+export function entryToMarkdown(entry, config, references = DEFAULT_REFERENCE_RENDERING) {
+    const opts = { config, references };
     const parts = [];
+    const title = frontmatterTitle(entry.data);
     parts.push('---');
-    if (entry.data.title) {
-        parts.push(`title: ${yamlValue(String(entry.data.title))}`);
+    if (title !== undefined) {
+        parts.push(`title: ${yamlValue(title)}`);
     }
     parts.push(`slug: ${yamlValue(entry.slug)}`);
     parts.push(`collection: ${yamlValue(entry.collection)}`);
@@ -26,13 +44,13 @@ export function entryToMarkdown(entry, config) {
     parts.push('');
     // Fields already in frontmatter — skip from body rendering to avoid duplication
     const skipFields = new Set();
-    if (entry.data.title)
+    if (title !== undefined)
         skipFields.add('title');
     if (entry.format === 'md' || entry.format === 'mdx') {
-        parts.push(...renderMarkdownEntry(entry, config, skipFields));
+        parts.push(...renderMarkdownEntry(entry, opts, skipFields));
     }
     else {
-        parts.push(...renderJsonEntry(entry, config, skipFields));
+        parts.push(...renderJsonEntry(entry, opts, skipFields));
     }
     // Markdown appended by an entry transform (e.g. a folded-in sibling artifact). Computed once
     // upstream, so it flows into the per-entry file, the collection all.md, and bundles alike.
@@ -45,27 +63,39 @@ export function entryToMarkdown(entry, config) {
 /**
  * Render a MD/MDX entry: metadata fields as a section, body verbatim.
  */
-function renderMarkdownEntry(entry, config, skipFields) {
+function renderMarkdownEntry(entry, opts, skipFields) {
+    const { config } = opts;
     const parts = [];
     // Render frontmatter fields (excluding body-like fields and already-rendered fields)
     const bodyFieldTypes = new Set(['markdown', 'mdx']);
     const metadataFields = flattenGroupFields(entry.fields).filter((f) => !bodyFieldTypes.has(f.type) && !skipFields.has(f.name));
+    // Blocks of output are separated by exactly one blank line, which is what Prettier leaves.
+    const endBlock = () => {
+        if (parts.length > 0 && parts[parts.length - 1] !== '')
+            parts.push('');
+    };
     for (const field of metadataFields) {
         const value = entry.data[field.name];
         if (value === undefined || value === null)
             continue;
-        const transformed = applyFieldTransform(entry, field, value, config);
+        // A structured field has no one-line form, so it gets a section as in a JSON entry.
+        const transformed = field.type === 'object' || field.type === 'block'
+            ? renderField(field, value, 2, entry, opts)
+            : applyFieldTransform(entry, field, value, config);
         if (transformed !== undefined) {
-            parts.push(transformed);
-            parts.push('');
+            if (transformed) {
+                endBlock();
+                parts.push(transformed);
+                parts.push('');
+            }
             continue;
         }
-        const label = field.label || field.name;
-        parts.push(`**${label}:** ${formatInlineValue(field, value)}`);
-    }
-    if (parts.length > 0) {
-        parts.push('');
+        const inline = formatInlineValue(field, value, opts.references);
+        if (inline === '' && field.type === 'reference')
+            continue;
+        parts.push(`**${field.label || field.name}:** ${inline}`);
     }
+    endBlock();
     if (entry.body) {
         let body = entry.format === 'mdx' ? stripMdxImports(entry.body) : entry.body;
         if (config?.componentTransforms && Object.keys(config.componentTransforms).length > 0) {
@@ -83,7 +113,7 @@ function renderMarkdownEntry(entry, config, skipFields) {
 /**
  * Render a JSON entry: full schema-driven conversion of all fields.
  */
-function renderJsonEntry(entry, config, skipFields) {
+function renderJsonEntry(entry, opts, skipFields) {
     const parts = [];
     for (const field of flattenGroupFields(entry.fields)) {
         if (skipFields.has(field.name))
@@ -91,7 +121,7 @@ function renderJsonEntry(entry, config, skipFields) {
         const value = entry.data[field.name];
         if (value === undefined || value === null)
             continue;
-        const rendered = renderField(field, value, 2, entry, config);
+        const rendered = renderField(field, value, 2, entry, opts);
         if (rendered) {
             parts.push(rendered);
             parts.push('');
@@ -104,8 +134,8 @@ function renderJsonEntry(entry, config, skipFields) {
  *
  * @param depth - Heading depth (2 = ##, 3 = ###, etc.)
  */
-function renderField(field, value, depth, entry, config) {
-    const transformed = applyFieldTransform(entry, field, value, config);
+function renderField(field, value, depth, entry, opts) {
+    const transformed = applyFieldTransform(entry, field, value, opts.config);
     if (transformed !== undefined) {
         return transformed;
     }
@@ -117,7 +147,7 @@ function renderField(field, value, depth, entry, config) {
     // already agrees with is what keeps a regenerated bundle diff-free.
     const descriptionLine = 'description' in field && field.description ? `\n\n_${field.description}_` : '';
     if ('list' in field && field.list && Array.isArray(value)) {
-        return renderListField(field, value, depth, label, heading, descriptionLine, entry, config);
+        return renderListField(field, value, depth, label, heading, descriptionLine, entry, opts);
     }
     switch (field.type) {
         case 'string':
@@ -136,11 +166,11 @@ function renderField(field, value, depth, entry, config) {
         case 'select':
             return renderSelectField(field, value, heading, label, descriptionLine);
         case 'reference':
-            return renderReferenceField(value, heading, label, descriptionLine);
+            return renderReferenceField(field, value, heading, label, descriptionLine, opts.references);
         case 'object':
-            return renderObjectField(field, value, depth, heading, label, descriptionLine, entry, config);
+            return renderObjectField(field, value, depth, heading, label, descriptionLine, entry, opts);
         case 'block':
-            return renderBlockField(field, value, depth, heading, label, descriptionLine, entry, config);
+            return renderBlockField(field, value, depth, heading, label, descriptionLine, entry, opts);
         default:
             return `${heading} ${label}${descriptionLine}\n\n${String(value)}`;
     }
@@ -148,7 +178,7 @@ function renderField(field, value, depth, entry, config) {
 /**
  * Render a list field (field with list: true).
  */
-function renderListField(field, values, depth, label, heading, descriptionLine, entry, config) {
+function renderListField(field, values, depth, label, heading, descriptionLine, entry, opts) {
     if (values.length === 0)
         return '';
     // Arrays of flat records (object items whose subfields are all single-line scalars) render far
@@ -156,7 +186,7 @@ function renderListField(field, values, depth, label, heading, descriptionLine,
     // headings. Genuinely nested items (subfields that are lists/objects/blocks/long text) keep the
     // heading-per-item fallback below.
     if (field.type === 'object' && isFlatObjectList(field)) {
-        return renderObjectListTable(field, values, label, heading, descriptionLine);
+        return renderObjectListTable(field, values, label, heading, descriptionLine, opts.references);
     }
     const isComplex = field.type === 'object' || field.type === 'block';
     if (isComplex) {
@@ -171,7 +201,7 @@ function renderListField(field, values, depth, label, heading, descriptionLine,
                     const v = item[f.name];
                     if (v === undefined || v === null)
                         return '';
-                    return renderField(f, v, depth + 2, entry, config);
+                    return renderField(f, v, depth + 2, entry, opts);
                 })
                     .filter(Boolean);
                 return `${itemHeading} ${itemLabel}\n\n${subFields.join('\n\n')}`;
@@ -181,8 +211,12 @@ function renderListField(field, values, depth, label, heading, descriptionLine,
             .filter(Boolean);
         return `${heading} ${label}${descriptionLine}\n\n${items.join('\n\n')}`;
     }
-    const items = values.map((v) => `- ${formatInlineValue(field, v)}`).join('\n');
-    return `${heading} ${label}${descriptionLine}\n\n${items}`;
+    const items = values
+        .map((v) => formatInlineValue(field, v, opts.references))
+        .filter((item) => item !== '' || field.type !== 'reference');
+    if (items.length === 0)
+        return '';
+    return `${heading} ${label}${descriptionLine}\n\n${items.map((item) => `- ${item}`).join('\n')}`;
 }
 /** Subfield types that render to a single line and so fit cleanly in a table cell. */
 const FLAT_CELL_TYPES = new Set([
@@ -213,7 +247,7 @@ function isFlatObjectList(field) {
  * Render an array of flat object records as a GFM table. Columns are the subfields in schema order;
  * absent values become empty cells; pipes and newlines in cells are escaped.
  */
-function renderObjectListTable(field, values, label, heading, descriptionLine) {
+function renderObjectListTable(field, values, label, heading, descriptionLine, references) {
     const columns = field.fields;
     const headerRow = `| ${columns.map((f) => escapeTableCell(f.label || f.name)).join(' | ')} |`;
     const separatorRow = `| ${columns.map(() => '---').join(' | ')} |`;
@@ -223,7 +257,7 @@ function renderObjectListTable(field, values, label, heading, descriptionLine) {
             const v = record[f.name];
             if (v === undefined || v === null)
                 return '';
-            return escapeTableCell(formatCellValue(f, v));
+            return escapeTableCell(formatCellValue(f, v, references));
         });
         return `| ${cells.join(' | ')} |`;
     });
@@ -231,12 +265,12 @@ function renderObjectListTable(field, values, label, heading, descriptionLine) {
     return `${heading} ${label}${descriptionLine}\n\n${table}`;
 }
 /** Render a single scalar subfield value to its one-line table-cell form. */
-function formatCellValue(field, value) {
+function formatCellValue(field, value, references) {
     switch (field.type) {
         case 'boolean':
             return value ? 'Yes' : 'No';
         case 'reference':
-            return formatReference(value);
+            return formatReference(field, value, references);
         case 'select':
             return Array.isArray(value)
                 ? value.map((v) => resolveSelectLabel(field, v)).join(', ')
@@ -283,12 +317,14 @@ function resolveSelectLabel(field, value) {
     }
     return strValue;
 }
-function renderReferenceField(value, heading, label, descriptionLine) {
-    if (Array.isArray(value)) {
-        const items = value.map((v) => `- ${formatReference(v)}`).join('\n');
-        return `${heading} ${label}${descriptionLine}\n\n${items}`;
-    }
-    return `${heading} ${label}${descriptionLine}\n\n${formatReference(value)}`;
+function renderReferenceField(field, value, heading, label, descriptionLine, references) {
+    const items = (Array.isArray(value) ? value : [value])
+        .map((v) => formatReference(field, v, references))
+        .filter(Boolean);
+    if (items.length === 0)
+        return '';
+    const body = Array.isArray(value) ? items.map((item) => `- ${item}`).join('\n') : items[0];
+    return `${heading} ${label}${descriptionLine}\n\n${body}`;
 }
 function isImageValueLike(value) {
     return (typeof value === 'object' &&
@@ -297,8 +333,8 @@ function isImageValueLike(value) {
         typeof value.src === 'string');
 }
 /**
- * Sanitizes `alt` for the `[...]` span of `![alt](src)`: unescaped, a crafted alt like
- * `x](/a) [pwn](https://evil.com)` injects a second attacker-chosen link/image. Strips
+ * Sanitizes text for the `[...]` span of `![alt](src)` or `[title](url)`: unescaped, a crafted
+ * value like `x](/a) [pwn](https://evil.com)` injects a second attacker-chosen link/image. Strips
  * (rather than escapes) `[`, `]`, backslash, and newlines — losing a stray bracket from
  * descriptive text is harmless, and escaping would break under `escapeTableCell`'s blind
  * backslash-doubling once this lands in a table cell (formatCellValue's image case).
@@ -339,20 +375,41 @@ function formatImageMarkdown(value, altFallback) {
     return `![${sanitizeMarkdownAltText(alt)}](${encodeMarkdownLinkDestination(value.src)})`;
 }
 /**
- * References may be resolved (objects with data) or unresolved (string IDs).
+ * One reference value as inline markdown: a target the export shows becomes `[title](url)`, its
+ * page, then its markdown copy labeled as such, so a reader can tell the two apart; one it does
+ * not becomes its id with a marker, so the copy shows the break instead of hiding it. An
+ * unavailable target renders from its id alone, whatever else it carries, so no title can leak.
+ * A bare string is an id that resolution never replaced.
  */
-function formatReference(value) {
-    if (typeof value === 'object' && value !== null) {
-        const ref = value;
-        // Resolved reference — use title, name, or slug
-        const display = ref.title || ref.name || ref.slug || ref.id;
-        if (display)
-            return String(display);
+function formatReference(field, value, references) {
+    // `''` is what the editor saves when a reference is cleared: no value, not a broken one.
+    if (value === '')
+        return '';
+    if (typeof value === 'string')
+        return `(missing entry ${sanitizeMarkdownAltText(value)})`;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return '(missing entry)';
+    const target = value;
+    const id = typeof target.id === 'string' ? sanitizeMarkdownAltText(target.id) : '';
+    if (target[RESTRICTED_REFERENCE_MARKER] === true) {
+        const marker = target.reason === 'missing' ? 'missing entry' : 'unavailable entry';
+        return id ? `(${marker} ${id})` : `(${marker})`;
     }
-    // Unresolved — raw ID or string
-    return String(value);
+    const displayField = field.displayField;
+    const displayValue = displayField ? target[displayField] : undefined;
+    const title = sanitizeMarkdownAltText(typeof displayValue === 'string' && displayValue.trim()
+        ? displayValue
+        : references.title(target)) || id;
+    const url = references.url(target);
+    if (url === false)
+        return title;
+    const page = url ? `[${title}](${encodeMarkdownLinkDestination(url)})` : title;
+    const markdownUrl = references.markdownUrl?.(target);
+    return markdownUrl
+        ? `${page} ([markdown version](${encodeMarkdownLinkDestination(markdownUrl)}))`
+        : page;
 }
-function renderObjectField(field, value, depth, heading, label, descriptionLine, entry, config) {
+function renderObjectField(field, value, depth, heading, label, descriptionLine, entry, opts) {
     if (typeof value !== 'object' || value === null) {
         return `${heading} ${label}${descriptionLine}\n\n${String(value)}`;
     }
@@ -362,7 +419,7 @@ function renderObjectField(field, value, depth, heading, label, descriptionLine,
         const v = obj[f.name];
         if (v === undefined || v === null)
             return '';
-        return renderField(f, v, depth + 1, entry, config);
+        return renderField(f, v, depth + 1, entry, opts);
     })
         .filter(Boolean);
     if (subFields.length === 0)
@@ -372,7 +429,7 @@ function renderObjectField(field, value, depth, heading, label, descriptionLine,
 /**
  * Render a block field (array of typed block items).
  */
-function renderBlockField(field, value, depth, heading, label, descriptionLine, entry, config) {
+function renderBlockField(field, value, depth, heading, label, descriptionLine, entry, opts) {
     if (!Array.isArray(value))
         return '';
     const items = value
@@ -394,7 +451,7 @@ function renderBlockField(field, value, depth, heading, label, descriptionLine,
             const v = blockItem[f.name] ?? blockItem.value?.[f.name];
             if (v === undefined || v === null)
                 return '';
-            return renderField(f, v, depth + 2, entry, config);
+            return renderField(f, v, depth + 2, entry, opts);
         })
             .filter(Boolean);
         if (blockFields.length === 0)
@@ -420,11 +477,17 @@ function applyFieldTransform(entry, field, value, config) {
 /**
  * Format a value for inline display (metadata lines, list items).
  */
-function formatInlineValue(field, value) {
+function formatInlineValue(field, value, references) {
     if (field.type === 'boolean')
         return value ? 'Yes' : 'No';
-    if (field.type === 'reference')
-        return formatReference(value);
+    if (field.type === 'reference') {
+        return Array.isArray(value)
+            ? value
+                .map((v) => formatReference(field, v, references))
+                .filter(Boolean)
+                .join(', ')
+            : formatReference(field, value, references);
+    }
     // Without this, an `image` field falls through to `String(value)` below,
     // which stringifies the structured `{ src, alt }` value object as the
     // useless literal text "[object Object]" - hit by MD/MDX frontmatter

package/dist/ai/references.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Reference fields in AI content: resolving them, hiding targets the export leaves out, and the
+ * title and URL a resolved one renders with.
+ *
+ * A reference renders as a link to its target, never as the target's content, so a shared block
+ * referenced by forty pages appears once in the export rather than forty times.
+ */
+import type { ContentStore } from '../content-store.js';
+import { type ContentIdIndex } from '../content-id-index.js';
+import type { FieldConfig, FlatSchemaItem } from '../config/index.js';
+import { type EntryLinkUrlResolver } from '../entry-link-resolver.js';
+import type { ReferenceRendering } from './json-to-markdown.js';
+import type { AIEntry, AIReferenceLinkFn, AIResolvedReference, AIReferenceValue } from './types.js';
+export type ReferenceTargetResolver = (id: string) => Promise<AIReferenceValue>;
+/**
+ * Resolve reference ids to their targets, reading each target once.
+ *
+ * Create one per `generateAIContent` call and never keep it: the route handler is long-lived in
+ * prod, and a memo held across calls would serve a target as it was when first read.
+ * `resolveReferenceTarget` embeds no body, which keeps the target's content out of the export,
+ * and resolves an id naming no readable entry to a `MissingReference`, which keeps the id.
+ */
+export declare function createReferenceTargetResolver(store: ContentStore): ReferenceTargetResolver;
+/**
+ * A copy of `data` with every reference id replaced by its target, or by a `MissingReference`
+ * when the id names no readable entry, so the id survives into the output.
+ * A `list: true` field resolves each non-empty string element; any other value, including the
+ * `''` of a cleared reference, is left as stored.
+ */
+export declare function resolveReferenceFields(data: Record<string, unknown>, fields: readonly FieldConfig[], resolveTarget: ReferenceTargetResolver): Promise<Record<string, unknown>>;
+/**
+ * Replace, in place, every resolved target that is not itself in this export with an
+ * {@link AIExcludedReference}, so no title, URL or field of an excluded entry reaches the
+ * output. Runs before each round of entry transforms and rendering, so their final output never
+ * carries such a target. Returns whether it replaced anything.
+ */
+export declare function maskUnexportedTargets(entry: AIEntry, exported: {
+    has(id: string): boolean;
+}): boolean;
+/** A target's page link as `referenceLink` decided it: a URL, `false` for none, or the default. */
+export type ReferenceLinkLookup = (id: string) => string | false | undefined;
+/** What `referenceLink` is told about one exported target. */
+export interface ReferenceLinkSubject {
+    target: AIResolvedReference;
+    body: string | undefined;
+}
+/**
+ * Ask `referenceLink` once for each exported target the export's entries reference or link from
+ * their bodies, in entry order, and return the answers, each URL encoded by
+ * {@link encodeLinkUrl}. `subjectOf` builds a target from the export's own read of it, so the
+ * callback never sees a target outside the export set, and the body it is shown reaches no linking
+ * entry's output. A throw
+ * or a return other than a non-empty string, `false` or `undefined` is logged and becomes
+ * `false`, so a broken callback withholds a link rather than advertising a page the site may not
+ * have. A target whose `entryLinkUrl` throws is left undecided, unasked, so every link to it fails
+ * and is reported as it is without the hook.
+ */
+export declare function decideReferenceLinks(referenceLink: AIReferenceLinkFn, entries: ReadonlyArray<{
+    entry: AIEntry;
+    body?: string;
+}>, subjectOf: (id: string) => ReferenceLinkSubject | undefined, entryLinkUrl: EntryLinkUrlResolver | undefined): Promise<ReferenceLinkLookup>;
+/**
+ * Title and URLs for a resolved target. The title is `resolveEntryTitle` against the target's own
+ * entry type, the chain the entries API labels an entry with. The page URL is `linkFor`'s
+ * decision, else {@link defaultPageUrl}; body `entry:` links follow both, so the two kinds of link
+ * in one document agree. The markdown copy is the file
+ * this export wrote for the target (`files`: content id to output path), under `mountPath`.
+ */
+export declare function createReferenceRendering(idIndex: ContentIdIndex, flatSchema: readonly FlatSchemaItem[], entryLinkUrl: EntryLinkUrlResolver | undefined, markdownCopies: {
+    mountPath: string;
+    files: ReadonlyMap<string, string>;
+}, linkFor?: ReferenceLinkLookup): ReferenceRendering;

package/dist/ai/references.js

@@ -0,0 +1,223 @@
+/**
+ * Reference fields in AI content: resolving them, hiding targets the export leaves out, and the
+ * title and URL a resolved one renders with.
+ *
+ * A reference renders as a link to its target, never as the target's content, so a shared block
+ * referenced by forty pages appears once in the export rather than forty times.
+ */
+import path from 'node:path';
+import { getDefaultEntryType } from '../content-store.js';
+import { extractEntryTypeFromFilename } from '../content-id-index.js';
+import { RESTRICTED_REFERENCE_MARKER } from '../entry-schema.js';
+import { extractEntryLinkIds } from '../entry-link-resolver.js';
+import { trimSlashes } from '../paths/normalize.js';
+import { getErrorMessage } from '../utils/error.js';
+import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { resolveEntryTitle } from '../utils/title-field.js';
+import { traverseFields } from '../validation/field-traversal.js';
+/**
+ * Resolve reference ids to their targets, reading each target once.
+ *
+ * Create one per `generateAIContent` call and never keep it: the route handler is long-lived in
+ * prod, and a memo held across calls would serve a target as it was when first read.
+ * `resolveReferenceTarget` embeds no body, which keeps the target's content out of the export,
+ * and resolves an id naming no readable entry to a `MissingReference`, which keeps the id.
+ */
+export function createReferenceTargetResolver(store) {
+    const reads = new Map();
+    return async (id) => {
+        let read = reads.get(id);
+        if (!read) {
+            read = store.resolveReferenceTarget(id);
+            reads.set(id, read);
+        }
+        // Each occurrence gets its own copy, since masking and adopter transforms may mutate it.
+        return structuredClone(await read);
+    };
+}
+/** Each reference field's holding record, at every depth: objects, object lists, blocks, groups. */
+function referenceSlots(fields, data) {
+    return traverseFields(fields, data, () => [], '', ({ fields: containerFields, data: record }) => flattenGroupFields(containerFields)
+        .filter((field) => field.type === 'reference')
+        .map((field) => ({ record, field })));
+}
+/**
+ * A copy of `data` with every reference id replaced by its target, or by a `MissingReference`
+ * when the id names no readable entry, so the id survives into the output.
+ * A `list: true` field resolves each non-empty string element; any other value, including the
+ * `''` of a cleared reference, is left as stored.
+ */
+export async function resolveReferenceFields(data, fields, resolveTarget) {
+    const resolved = structuredClone(data);
+    await Promise.all(referenceSlots(fields, resolved).map(async ({ record, field }) => {
+        const value = record[field.name];
+        if (typeof value === 'string' && value) {
+            record[field.name] = await resolveTarget(value);
+        }
+        else if (field.list && Array.isArray(value)) {
+            record[field.name] = await Promise.all(value.map((id) => (typeof id === 'string' && id ? resolveTarget(id) : id)));
+        }
+    }));
+    return resolved;
+}
+function isShownTarget(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.id === 'string' &&
+        value[RESTRICTED_REFERENCE_MARKER] !== true);
+}
+/**
+ * Replace, in place, every resolved target that is not itself in this export with an
+ * {@link AIExcludedReference}, so no title, URL or field of an excluded entry reaches the
+ * output. Runs before each round of entry transforms and rendering, so their final output never
+ * carries such a target. Returns whether it replaced anything.
+ */
+export function maskUnexportedTargets(entry, exported) {
+    let masked = false;
+    const mask = (value) => {
+        if (!isShownTarget(value) || exported.has(value.id))
+            return value;
+        masked = true;
+        return { id: value.id, unavailable: true, reason: 'excluded' };
+    };
+    for (const { record, field } of referenceSlots(entry.fields, entry.data)) {
+        const value = record[field.name];
+        if (value === undefined)
+            continue;
+        record[field.name] = Array.isArray(value) ? value.map(mask) : mask(value);
+    }
+    return masked;
+}
+/**
+ * The page URL a resolved target links by default: `entryLinkUrl`'s, else its `urlPath`, the rule
+ * body `entry:` links use.
+ */
+function defaultPageUrl(target, entryLinkUrl) {
+    const { id, slug, collection, urlPath } = target;
+    if (entryLinkUrl &&
+        typeof id === 'string' &&
+        typeof slug === 'string' &&
+        typeof collection === 'string') {
+        return entryLinkUrl({ collection, slug, id });
+    }
+    return typeof urlPath === 'string' && urlPath ? urlPath : undefined;
+}
+/**
+ * Percent-encode every character that would end a link destination, an autolink or an HTML
+ * attribute value early (whitespace, controls, quotes, angle brackets and parentheses) or escape
+ * the character after it (a backslash). Body links splice the URL into all three as it is.
+ */
+function encodeLinkUrl(url) {
+    let out = '';
+    for (const char of url) {
+        const code = char.charCodeAt(0);
+        out +=
+            code <= 0x20 || code === 0x7f || `"'<>()\\`.includes(char)
+                ? `%${code.toString(16).toUpperCase().padStart(2, '0')}`
+                : char;
+    }
+    return out;
+}
+/**
+ * Ask `referenceLink` once for each exported target the export's entries reference or link from
+ * their bodies, in entry order, and return the answers, each URL encoded by
+ * {@link encodeLinkUrl}. `subjectOf` builds a target from the export's own read of it, so the
+ * callback never sees a target outside the export set, and the body it is shown reaches no linking
+ * entry's output. A throw
+ * or a return other than a non-empty string, `false` or `undefined` is logged and becomes
+ * `false`, so a broken callback withholds a link rather than advertising a page the site may not
+ * have. A target whose `entryLinkUrl` throws is left undecided, unasked, so every link to it fails
+ * and is reported as it is without the hook.
+ */
+export async function decideReferenceLinks(referenceLink, entries, subjectOf, entryLinkUrl) {
+    const ids = new Set();
+    for (const { entry, body } of entries) {
+        for (const { record, field } of referenceSlots(entry.fields, entry.data)) {
+            const value = record[field.name];
+            for (const target of Array.isArray(value) ? value : [value]) {
+                if (isShownTarget(target))
+                    ids.add(target.id);
+            }
+        }
+        for (const { id } of body ? extractEntryLinkIds(body) : [])
+            ids.add(id);
+    }
+    const decisions = new Map();
+    for (const id of ids) {
+        const subject = subjectOf(id);
+        if (!subject)
+            continue;
+        let defaultUrl;
+        try {
+            defaultUrl = defaultPageUrl(subject.target, entryLinkUrl);
+        }
+        catch {
+            continue;
+        }
+        let decision;
+        try {
+            decision = await referenceLink(subject.target, { body: subject.body, defaultUrl });
+        }
+        catch (err) {
+            console.warn(`AI content: referenceLink threw for entry ${id}:`, getErrorMessage(err));
+            decision = false;
+        }
+        if (typeof decision === 'string' && decision.trim()) {
+            decisions.set(id, encodeLinkUrl(decision.trim()));
+        }
+        else if (decision === false) {
+            decisions.set(id, false);
+        }
+        else if (decision !== undefined) {
+            console.warn(`AI content: referenceLink returned ${typeof decision === 'string' ? 'an empty string' : typeof decision} for entry ${id}; expected a URL, false or undefined`);
+            decisions.set(id, false);
+        }
+    }
+    return (id) => decisions.get(id);
+}
+/**
+ * Title and URLs for a resolved target. The title is `resolveEntryTitle` against the target's own
+ * entry type, the chain the entries API labels an entry with. The page URL is `linkFor`'s
+ * decision, else {@link defaultPageUrl}; body `entry:` links follow both, so the two kinds of link
+ * in one document agree. The markdown copy is the file
+ * this export wrote for the target (`files`: content id to output path), under `mountPath`.
+ */
+export function createReferenceRendering(idIndex, flatSchema, entryLinkUrl, markdownCopies, linkFor) {
+    const mountSegment = trimSlashes(markdownCopies.mountPath);
+    const mount = mountSegment === '' ? '' : `/${mountSegment}`;
+    const entryTypeOf = (id) => {
+        const location = typeof id === 'string' ? idIndex.findById(id) : null;
+        if (!location?.collection)
+            return {};
+        const item = flatSchema.find((candidate) => candidate.logicalPath === location.collection);
+        if (!item)
+            return {};
+        if (item.type === 'entry-type')
+            return { schema: item.schema, label: item.label };
+        if (item.type !== 'collection')
+            return {};
+        const typeName = extractEntryTypeFromFilename(path.basename(location.relativePath));
+        const entries = item.entries;
+        const entryType = entries?.find((candidate) => candidate.name === typeName) ?? getDefaultEntryType(entries);
+        return { schema: entryType?.schema, label: entryType?.label };
+    };
+    return {
+        title: (target) => {
+            const { schema, label } = entryTypeOf(target.id);
+            return resolveEntryTitle(target, {
+                schema,
+                entryTypeLabel: label,
+                slug: typeof target.slug === 'string' ? target.slug : undefined,
+            });
+        },
+        url: (target) => {
+            const decided = typeof target.id === 'string' ? linkFor?.(target.id) : undefined;
+            return decided ?? defaultPageUrl(target, entryLinkUrl);
+        },
+        markdownUrl: (target) => {
+            const file = typeof target.id === 'string' ? markdownCopies.files.get(target.id) : undefined;
+            return file ? `${mount}/${file}` : undefined;
+        },
+    };
+}