canopycms 0.0.63 → 0.0.64

package/dist/config/types.d.ts

@@ -2,13 +2,13 @@
  * Type definitions for CanopyCMS configuration.
  * These are pure TypeScript types - Zod schemas are in ./schemas/
  */
-import type { CanopyGroupId, CanopyUserId } from '../types';
-import type { OperatingMode } from '../operating-mode';
-import type { AuthPlugin } from '../auth/plugin';
-import type { LogicalPath, ContentId } from '../paths/types';
-import type { PermissionPath } from '../authorization/types';
-import type { EntryLinkUrlResolver } from '../entry-link-resolver';
-import type { CropRect } from '../assets/transform-directives';
+import type { CanopyGroupId, CanopyUserId } from '../types.js';
+import type { OperatingMode } from '../operating-mode/index.js';
+import type { AuthPlugin } from '../auth/plugin.js';
+import type { LogicalPath, ContentId } from '../paths/types.js';
+import type { PermissionPath } from '../authorization/types.js';
+import type { EntryLinkUrlResolver } from '../entry-link-resolver.js';
+import type { CropRect } from '../assets/transform-directives.js';
 export declare const primitiveFieldTypes: readonly ["string", "number", "boolean", "datetime", "markdown", "mdx", "code"];
 export declare const fieldTypes: readonly ["string", "number", "boolean", "datetime", "markdown", "mdx", "code", "image", "select", "reference", "object", "block", "group"];
 export type PrimitiveFieldType = (typeof primitiveFieldTypes)[number];
@@ -68,6 +68,27 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
     entryTypes?: string[];
     displayField?: string;
     options?: ReferenceOption[];
+    /**
+     * Include the referenced entry's body in the resolved value, under that entry type's own
+     * body field name (`isBody: true`, else `body`). Defaults to `false`.
+     *
+     * This is the embed-vs-link distinction, declared where it is actually known. A reference
+     * that **embeds** its target — a shared call-to-action block rendered inline — needs the
+     * target's prose, and without this a resolved md/mdx target arrives as frontmatter only, so
+     * a search index built over pages with shared blocks silently contains nothing for them. A
+     * reference that merely **links** to its target — related posts, an author byline — wants
+     * `urlPath` and a title, and emphatically not the target's full body inlined into every
+     * page read.
+     *
+     * It lives on the field rather than on `read()`/`listEntries()` because one call routinely
+     * contains both kinds: a page with a shared CTA *and* a related-posts list cannot be served
+     * by a single call-level setting, and a call-level flag would mean the same field resolved
+     * to different shapes in different places.
+     *
+     * Only affects formats that HAVE a separate body — md and mdx. A json/yaml target's whole
+     * document is already its data, so this is a no-op there.
+     */
+    includeBody?: boolean;
 }
 /**
  * Image field config. The value is a structured object (see `ImageFieldValue`
@@ -215,6 +236,15 @@ export interface CanopyEditorConfig {
     title?: string;
     subtitle?: string;
     theme?: unknown;
+    /**
+     * Per-collection overrides for the preview pane's URL, keyed by collection path or name
+     * (e.g. `{ 'content/posts': '/blog' }`) for sites whose routes don't mirror their content tree.
+     *
+     * Values are **site-relative** and must NOT include the deployment `basePath` — that is applied
+     * on top of whatever this yields (see `CanopyConfig.basePath`), so including it here would
+     * prefix it twice. An absolute value (`https://…`) is passed through untouched instead, which
+     * is the escape hatch for previewing against a different origin entirely.
+     */
     previewBase?: Record<string, string>;
     onAccountClick?: () => void;
     onLogoutClick?: () => void;
@@ -315,6 +345,21 @@ export interface CanopyConfig {
     deploymentName?: string;
     contentRoot: ContentRoot;
     sourceRoot?: SourceRoot;
+    /**
+     * The deployment prefix the host Next.js app is served under (e.g. `/preview-123`), matching
+     * that app's `next.config` `basePath`. CanopyCMS cannot read `next.config` at runtime, so this
+     * must be stated here explicitly if the app sets one — without it, editor requests, the preview
+     * iframe `src`, and preview↔editor path matching all target the un-prefixed root and 404 or
+     * silently stop syncing. Normalized (leading slash added, trailing slashes stripped) via
+     * `joinUrlPrefix` at every use site; unset/empty means the app is served at its origin's root.
+     *
+     * NOT the same option as `collectStaticParams`'s `basePath` in
+     * `packages/canopycms-next/src/static.ts` — that one means "the route prefix of a nested
+     * catch-all route" (e.g. `/docs` for `app/docs/[[...slug]]`) and *filters* enumerated entries
+     * down to that prefix. Passing this deployment basePath to `collectStaticParams` instead would
+     * silently filter out every entry (zero static params, a build that goes green with no pages).
+     */
+    basePath?: string;
     editor?: CanopyEditorConfig;
     authPlugin?: AuthPlugin;
     /** Custom URL resolver for entry links. Overrides the default URL computation. */
@@ -362,6 +407,8 @@ export interface CanopyConfigInput {
     deploymentName?: string;
     contentRoot?: string;
     sourceRoot?: string;
+    /** See `CanopyConfig.basePath` — the deployment prefix the host Next.js app is served under. */
+    basePath?: string;
     editor?: CanopyEditorConfig;
     authPlugin?: AuthPlugin;
     /** Custom URL resolver for entry links. Overrides the default URL computation. */
@@ -413,7 +460,7 @@ export type FlatSchemaItem = {
  * Use flatSchema for O(1) cached access to the flattened schema structure.
  * Schema is loaded from .collection.json files on the server and provided as flatSchema.
  */
-export type CanopyClientConfig = Pick<CanopyConfig, 'defaultBaseBranch' | 'defaultActiveBranch' | 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl'> & {
+export type CanopyClientConfig = Pick<CanopyConfig, 'defaultBaseBranch' | 'defaultActiveBranch' | 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl' | 'basePath'> & {
     flatSchema: FlatSchemaItem[];
     /**
      * `media.publicBaseUrl`, when configured - the only part of `media` safe/
@@ -431,4 +478,3 @@ export interface ClientOnlyFields {
         AccountComponent?: React.ComponentType;
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/config/types.js

@@ -24,4 +24,3 @@ export const fieldTypes = [
     'block',
     'group',
 ];
-//# sourceMappingURL=types.js.map

package/dist/config/validation.d.ts

@@ -5,7 +5,7 @@
  * from `createEntrySchemaRegistry` so the canonical schema-authoring path runs
  * the same checks. Exported so the test suite can exercise them directly.
  */
-import type { CanopyConfig } from './types';
+import type { CanopyConfig } from './types.js';
 /**
  * Recursively check that all select fields have options defined.
  * Throws an error if a select field is missing options.
@@ -59,4 +59,3 @@ export declare const ensureNoGroupsInsideComplexFields: (fields: unknown) => voi
  * @throws Error if validation fails
  */
 export declare const validateCanopyConfig: (config: unknown) => CanopyConfig;
-//# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.js

@@ -200,4 +200,3 @@ export const validateCanopyConfig = (config) => {
     };
     return normalized;
 };
-//# sourceMappingURL=validation.js.map

package/dist/config.d.ts

@@ -2,9 +2,8 @@
  * CanopyCMS Configuration
  *
  * This file re-exports from the config module for backward compatibility.
- * New code should import directly from './config/index' or './config'.
+ * New code should import directly from './config/index.js' or './config'.
  *
  * @module config
  */
-export * from './config/index';
-//# sourceMappingURL=config.d.ts.map
+export * from './config/index.js';

package/dist/config.js

@@ -8,4 +8,3 @@
  */
 // Re-export everything from the config module
 export * from './config/index.js';
-//# sourceMappingURL=config.js.map

package/dist/content-id-index.d.ts

@@ -1,4 +1,4 @@
-import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
+import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export interface IdLocation {
     id: ContentId;
     type: 'entry' | 'collection';
@@ -267,4 +267,3 @@ export declare function extractEntryTypeFromFilename(filename: string): string |
  *                        If provided and matches first part, strips it from slug
  */
 export declare function extractSlugFromFilename(filename: string, entryTypeName?: string): Slug;
-//# sourceMappingURL=content-id-index.d.ts.map

package/dist/content-id-index.js

@@ -616,4 +616,3 @@ export function extractSlugFromFilename(filename, entryTypeName) {
     }
     return filename.toLowerCase();
 }
-//# sourceMappingURL=content-id-index.js.map

package/dist/content-index-generation.d.ts

@@ -63,4 +63,3 @@ export declare function invalidateContentIndexesDurable(root: string): Promise<v
  * staleness behavior plus whatever backstop the consumer implements.
  */
 export declare function invalidateBranchContentCaches(root: string): Promise<void>;
-//# sourceMappingURL=content-index-generation.d.ts.map

package/dist/content-index-generation.js

@@ -125,4 +125,3 @@ export async function invalidateBranchContentCaches(root) {
     await bumpResourceGeneration(root, SCHEMA_GENERATION_RESOURCE);
     invalidateContentIndexesForRoot(root);
 }
-//# sourceMappingURL=content-index-generation.js.map

package/dist/content-index-registry.d.ts

@@ -35,4 +35,3 @@ export declare function registerContentIndexForInvalidation(root: string, target
  * index access, so calling this for a root with no live stores is free.
  */
 export declare function invalidateContentIndexesForRoot(root: string): void;
-//# sourceMappingURL=content-index-registry.d.ts.map

package/dist/content-index-registry.js

@@ -50,4 +50,3 @@ export function invalidateContentIndexesForRoot(root) {
             registry.delete(storeRoot);
     }
 }
-//# sourceMappingURL=content-index-registry.js.map

package/dist/content-listing.d.ts

@@ -3,8 +3,9 @@
  *
  * Extracted from api/entries.ts to avoid duplication.
  */
-import type { ContentFormat, FlatSchemaItem, EntryTypeConfig, EntrySchema } from './config';
-import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types';
+import type { ContentFormat, FlatSchemaItem, EntrySchema } from './config/index.js';
+import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types.js';
+import { ContentStore, type ReferenceResolveCache } from './content-store.js';
 /**
  * An entry listing item with raw data from the filesystem.
  * Does not include API-specific fields like canEdit.
@@ -30,60 +31,7 @@ export interface CollectionListItem {
  * Returns an empty object on read/parse failure.
  */
 export declare const readEntryData: (filePath: string, format: ContentFormat, bodyFieldName?: string) => Promise<Record<string, unknown>>;
-/**
- * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
- *
- * ## Filename grammar
- *
- * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
- * - `type` — the entry type name (a key in the collection's `entries` config).
- * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
- *   `getting.started.guide`), so the type and ID anchor the split: the ID is
- *   always the second-to-last dot-separated segment, and the slug is
- *   everything between the type and the ID. The returned `slug` is
- *   lowercased.
- * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
- *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
- *   unambiguous when read aloud or hand-transcribed. A filename whose
- *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
- *   parse returns `null`, even if the rest of the shape looks right.
- * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
- *   before parsing and not part of the returned result.
- *
- * @param filename - The bare filename (no directory component). **This precondition is
- *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
- *   rejected and is not treated as special — it becomes part of whichever segment it
- *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
- *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
- *   `path.basename(filePath)`) before calling this — every internal caller already does.
- * @param entryTypes - When provided, the parsed `type` segment must match one
- *   of these entry types by name, or the parse is rejected (this is how
- *   `listCollectionEntries` filters out files that don't belong to the
- *   collection's configured entry types). Omit this argument to parse
- *   structurally without validating the type against a known list — useful
- *   for adopter code that needs to recover `{type, slug, id}` from a
- *   filename without having a schema/entry-types list on hand (e.g. a
- *   filesystem walk over content for tooling or diagnostics). Even without
- *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
- *   is always rejected — an empty string is never a legal type, matching the
- *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
- *   `content-id-index.ts` already applies.
- * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
- *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
- *   leading dot, an invalid ID, or — when `entryTypes` is given — an
- *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
- *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
- *   `Slug` type without running `parseSlug`'s validation. A filename with an
- *   unconventional slug segment (e.g. containing a space) still parses and still
- *   receives the `Slug` brand. Callers that need a validated slug must run the result
- *   through `parseSlug` themselves; this function's contract is "split the filename
- *   grammar apart," not "validate every part."
- */
-export declare const parseTypedFilename: (filename: string, entryTypes?: readonly EntryTypeConfig[]) => {
-    type: string;
-    slug: Slug;
-    id: ContentId;
-} | null;
+export { parseTypedFilename } from './utils/typed-filename.js';
 /**
  * A flat entry item from listEntries.
  * Structural metadata is always present; `data` is controlled by the extract option.
@@ -97,7 +45,12 @@ export interface ListEntriesItem<T = Record<string, unknown>> {
      * For regular entries: '/guides/glossary-of-terms'.
      * For a root index entry: '/'.
      *
-     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry.
+     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry. That guarantee
+     * depends on `slug` passing `parseSlug` — the filename grammar (`utils/typed-filename.ts`)
+     * allows a slug to contain characters `parseSlug` rejects (a dot, most commonly), and an entry
+     * whose slug does is listed here same as any other but can never be read back by URL.
+     * `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this outside
+     * this doc comment's promise.
      */
     urlPath: string;
     /** Entry slug within its collection */
@@ -152,6 +105,33 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
     rootPath?: string;
     /** Custom sort. */
     sort?: (a: ListEntriesItem<T>, b: ListEntriesItem<T>) => number;
+    /**
+     * Resolve `reference` fields to the referenced entry's data, the way
+     * `read()`/`readByUrlPath()` do — including references nested inside `object` fields,
+     * inline `group`s and block templates (so a shared/referenced block finally carries its
+     * snippet's content here). Off leaves them as the bare id string, or `null`.
+     *
+     * **Defaults to `false`, unlike `read()`, which defaults to `true`.** The asymmetry is
+     * deliberate rather than an oversight. `data` is `T` and `extract` receives an untyped
+     * `Record<string, unknown>`, so turning this on changes a reference from `'a1b2c3d4e5f6'`
+     * to `{ ...data, id, slug, collection, urlPath }` with no compile error anywhere to catch it — an
+     * `/authors/${data.author}` template silently becomes `/authors/[object Object]`. Opting
+     * in is a decision you make per call site, next to the code that reads the field. It also
+     * keeps the common batch uses free: `collectStaticPaths` discards `data` outright, and
+     * `build/generate-ai-content.ts` lists purely to validate entry shapes.
+     *
+     * **Cost, and why it is bounded.** Resolution needs a `ContentStore` and its ContentId
+     * index, so turning it on adds one index scan per call plus one read per DISTINCT
+     * referenced entry — not per referencing entry. A single {@link ReferenceResolveCache}
+     * spans the whole call, so a shared block referenced by 40 pages is read once, not 40
+     * times. Nothing is constructed and nothing is scanned when this is off.
+     *
+     * **Path ACLs are not applied to the resolved targets**, matching `read()` exactly: a
+     * reference can resolve to an entry the user could not `read()` directly. The entries
+     * being LISTED are still ACL-filtered as always, and a filtered-out entry is never
+     * resolved at all.
+     */
+    resolveReferences?: boolean;
 }
 /**
  * Server-only path-ACL predicate, applied to raw entries before any of their data
@@ -170,6 +150,43 @@ export interface ContentVisibilityOptions {
     /** Return false to drop an entry. Receives the entry's branch-root-relative physical path. */
     shouldInclude?: (physicalPath: PhysicalPath) => boolean;
 }
+/** A collection node from the flattened schema. */
+export type CollectionSchemaItem = Extract<FlatSchemaItem, {
+    type: 'collection';
+}>;
+/**
+ * Build the `ContentStore` + shared cache that a batch listing resolves references through.
+ *
+ * Unrelated to the `ReferenceResolver` class in reference-resolver.ts despite the adjacent
+ * name — that one resolves an id to a human-readable *display label* for the editor UI. This
+ * resolves a reference to the referenced entry's *data* for server-side listings.
+ *
+ * Constructed lazily by each listing surface, and ONLY when the caller opted in — a store
+ * builds a ContentId index on first use, which is a full scan of the content tree, and the
+ * default (`resolveReferences` off) must stay a pure filesystem walk with no index at all.
+ *
+ * One store and one cache per listing call, not per collection: the cache is the reason a
+ * shared block referenced from 40 pages costs one read instead of 40, so it has to span the
+ * whole batch. Per-call construction is the established shape here — content-reader.ts's
+ * `resolveStore` builds a store per read, and content-index-registry.ts holds stores through
+ * `WeakRef` + a `FinalizationRegistry` precisely so short-lived instances stay collectable.
+ */
+export declare const createReferenceResolver: (branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string) => {
+    store: ContentStore;
+    cache: ReferenceResolveCache;
+};
+/**
+ * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
+ *
+ * Shared by `listEntries` and `buildContentTree` so both opt into resolution through one
+ * implementation. Each entry resolves against its OWN entry type's field list, since that is
+ * what says which fields are references at all; an entry whose type has no resolvable schema
+ * is returned untouched rather than guessed at.
+ */
+export declare const resolveCollectionItemReferences: (items: CollectionListItem[], collection: CollectionSchemaItem, resolver: {
+    store: ContentStore;
+    cache: ReferenceResolveCache;
+}) => Promise<CollectionListItem[]>;
 /**
  * List all content entries as a flat array.
  *
@@ -196,7 +213,7 @@ export interface ContentVisibilityOptions {
  * @param branchRoot - Absolute path to the branch workspace root
  * @param flatSchema - Flattened schema items (from flattenSchema)
  * @param contentRootName - The content root name (e.g. "content")
- * @param options - Listing options (extract, filter, rootPath, sort)
+ * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
  * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export declare function listEntries<T = Record<string, unknown>>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: ListEntriesOptions<T>, visibility?: ContentVisibilityOptions): Promise<ListEntriesItem<T>[]>;
@@ -231,4 +248,3 @@ export interface SkippedListingFile {
  *   failure instead of a silent one.
  */
 export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem, onSkip?: (file: SkippedListingFile) => void) => Promise<CollectionListItem[]>;
-//# sourceMappingURL=content-listing.d.ts.map

package/dist/content-listing.js

@@ -8,13 +8,13 @@ import path from 'node:path';
 import matter from 'gray-matter';
 import { parse as yamlParse } from 'yaml';
 import { findBodyFieldName } from './utils/body-field.js';
+import { computeEntryUrl } from './utils/entry-url.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
 import { resolveCollectionPath } from './content-id-index.js';
 import { validateAndNormalizePath } from './paths/index.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
-import { isValidId } from './id.js';
-import { ContentStoreError } from './content-store.js';
+import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
 import { isBuildMode } from './build-mode.js';
 const log = createDebugLogger({ prefix: 'ContentListing' });
 /**
@@ -45,7 +45,17 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
             return asRecord(yamlParse(raw));
         }
         const parsed = matter(raw);
-        const data = parsed.data ?? {};
+        // Copy before writing the body in. gray-matter keeps a PROCESS-GLOBAL cache keyed by file
+        // content and hands every caller the same `data` object instance, so mutating it in place
+        // wrote the body into a shared object that later, unrelated `matter()` calls then saw as
+        // frontmatter. Concretely, before this copy: listing a collection that contains an md entry
+        // poisoned the cache, and a subsequent reference resolution to that same entry — which goes
+        // through `ContentStore.read()`, whose md branch calls `matter()` again — returned the body
+        // as a frontmatter field. So a resolved md snippet came back WITH `body` on a whole-site
+        // listing and WITHOUT it on one scoped past its own collection: the same entry, two shapes,
+        // decided by unrelated scoping. Regression coverage lives with the reference-resolution
+        // tests in content-listing.test.ts.
+        const data = { ...(parsed.data ?? {}) };
         if (parsed.content) {
             data[bodyFieldName] = parsed.content;
         }
@@ -58,87 +68,52 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
         return {};
     }
 };
+// `parseTypedFilename` now lives in utils/typed-filename.ts so dependency-light modules can
+// use it without importing this one (which pulls in ContentStore). Re-exported here because
+// this is where callers -- and `canopycms/server` -- have always imported it from.
+export { parseTypedFilename } from './utils/typed-filename.js';
+import { parseTypedFilename } from './utils/typed-filename.js';
+// ---------------------------------------------------------------------------
+// Reference resolution for batch listings
+// ---------------------------------------------------------------------------
 /**
- * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
+ * Build the `ContentStore` + shared cache that a batch listing resolves references through.
  *
- * ## Filename grammar
+ * Unrelated to the `ReferenceResolver` class in reference-resolver.ts despite the adjacent
+ * name — that one resolves an id to a human-readable *display label* for the editor UI. This
+ * resolves a reference to the referenced entry's *data* for server-side listings.
  *
- * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
- * - `type` — the entry type name (a key in the collection's `entries` config).
- * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
- *   `getting.started.guide`), so the type and ID anchor the split: the ID is
- *   always the second-to-last dot-separated segment, and the slug is
- *   everything between the type and the ID. The returned `slug` is
- *   lowercased.
- * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
- *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
- *   unambiguous when read aloud or hand-transcribed. A filename whose
- *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
- *   parse returns `null`, even if the rest of the shape looks right.
- * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
- *   before parsing and not part of the returned result.
+ * Constructed lazily by each listing surface, and ONLY when the caller opted in — a store
+ * builds a ContentId index on first use, which is a full scan of the content tree, and the
+ * default (`resolveReferences` off) must stay a pure filesystem walk with no index at all.
  *
- * @param filename - The bare filename (no directory component). **This precondition is
- *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
- *   rejected and is not treated as special — it becomes part of whichever segment it
- *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
- *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
- *   `path.basename(filePath)`) before calling this — every internal caller already does.
- * @param entryTypes - When provided, the parsed `type` segment must match one
- *   of these entry types by name, or the parse is rejected (this is how
- *   `listCollectionEntries` filters out files that don't belong to the
- *   collection's configured entry types). Omit this argument to parse
- *   structurally without validating the type against a known list — useful
- *   for adopter code that needs to recover `{type, slug, id}` from a
- *   filename without having a schema/entry-types list on hand (e.g. a
- *   filesystem walk over content for tooling or diagnostics). Even without
- *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
- *   is always rejected — an empty string is never a legal type, matching the
- *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
- *   `content-id-index.ts` already applies.
- * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
- *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
- *   leading dot, an invalid ID, or — when `entryTypes` is given — an
- *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
- *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
- *   `Slug` type without running `parseSlug`'s validation. A filename with an
- *   unconventional slug segment (e.g. containing a space) still parses and still
- *   receives the `Slug` brand. Callers that need a validated slug must run the result
- *   through `parseSlug` themselves; this function's contract is "split the filename
- *   grammar apart," not "validate every part."
+ * One store and one cache per listing call, not per collection: the cache is the reason a
+ * shared block referenced from 40 pages costs one read instead of 40, so it has to span the
+ * whole batch. Per-call construction is the established shape here — content-reader.ts's
+ * `resolveStore` builds a store per read, and content-index-registry.ts holds stores through
+ * `WeakRef` + a `FinalizationRegistry` precisely so short-lived instances stay collectable.
  */
-export const parseTypedFilename = (filename, entryTypes) => {
-    // Reject dotfiles outright (matching extractEntryTypeFromFilename's guard in
-    // content-id-index.ts): a leading dot can never be a legal entry type, and this
-    // is exactly the shape of the files a structural (no-entryTypes) parse would
-    // otherwise misparse -- e.g. '.hidden.file.aB3cD4eF5gH6.md' -> potentialType ''.
-    if (filename.startsWith('.'))
-        return null;
-    // Remove extension
-    const lastDot = filename.lastIndexOf('.');
-    if (lastDot === -1)
-        return null;
-    const nameWithoutExt = filename.slice(0, lastDot);
-    // Parse: {type}.{slug}.{id}
-    const parts = nameWithoutExt.split('.');
-    if (parts.length < 3)
-        return null;
-    const potentialType = parts[0];
-    // When a known-types list is supplied, the first segment must match one of
-    // them. Without it, any non-empty first segment is accepted as the type.
-    if (entryTypes && !entryTypes.some((e) => e.name === potentialType)) {
-        return null;
-    }
-    const id = parts[parts.length - 1];
-    if (!isValidId(id))
-        return null;
-    const slug = parts.slice(1, -1).join('.').toLowerCase();
+export const createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+    store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
+    cache: createReferenceResolveCache(),
+});
+/**
+ * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
+ *
+ * Shared by `listEntries` and `buildContentTree` so both opt into resolution through one
+ * implementation. Each entry resolves against its OWN entry type's field list, since that is
+ * what says which fields are references at all; an entry whose type has no resolvable schema
+ * is returned untouched rather than guessed at.
+ */
+export const resolveCollectionItemReferences = async (items, collection, resolver) => Promise.all(items.map(async (item) => {
+    const fields = collection.entries?.find((e) => e.name === item.entryType)?.schema;
+    if (!fields)
+        return item;
     return {
-        type: potentialType,
-        slug: slug,
-        id: id,
+        ...item,
+        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache),
     };
-};
+}));
 /**
  * List all content entries as a flat array.
  *
@@ -165,7 +140,7 @@ export const parseTypedFilename = (filename, entryTypes) => {
  * @param branchRoot - Absolute path to the branch workspace root
  * @param flatSchema - Flattened schema items (from flattenSchema)
  * @param contentRootName - The content root name (e.g. "content")
- * @param options - Listing options (extract, filter, rootPath, sort)
+ * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
  * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export async function listEntries(branchRoot, flatSchema, contentRootName, options, visibility) {
@@ -182,10 +157,21 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
     // data never reaches `extract` (let alone the returned items).
     const shouldInclude = visibility?.shouldInclude;
     const skippedFiles = [];
+    // One store + cache for the whole call, or nothing at all when the caller did not opt in.
+    // See the `resolveReferences` option for the cost this buys back.
+    const resolver = options?.resolveReferences
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        : null;
     const collectionResults = await Promise.all(collections.map(async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
         const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
-        return visible.map((entry) => ({ entry, collection }));
+        // Resolve AFTER the visibility filter (a denied entry is never resolved, so its
+        // references cost nothing and leak nothing) and BEFORE the mapping below, so
+        // `extract` and `filter` both see resolved data — which is the entire point.
+        const resolved = resolver
+            ? await resolveCollectionItemReferences(visible, collection, resolver)
+            : visible;
+        return resolved.map((entry) => ({ entry, collection }));
     }));
     // Build-time only: fail loudly rather than silently shipping a build with a page missing. See
     // the build-time-only-failure note in this function's own doc comment above. Only files that
@@ -214,9 +200,17 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
                 ? entry.logicalPath.slice(contentPrefix.length)
                 : entry.logicalPath;
             const pathSegments = pathWithoutRoot.split('/').filter(Boolean);
-            // Compute urlPath: collapse index entries to parent collection path
-            const urlSegments = entry.slug === 'index' ? pathSegments.slice(0, -1) : pathSegments;
-            const urlPath = urlSegments.length > 0 ? `/${urlSegments.join('/')}`.toLowerCase() : '/';
+            // Compute urlPath (collapses an `index` entry to its parent collection path) through
+            // the SHARED rule rather than a local copy of it. A resolved reference now carries a
+            // `urlPath` too, and the whole point of that field is that it addresses the same entry
+            // this listing does, so the two must not be free to drift apart.
+            //
+            // One deliberate copy of this rule remains: `content-tree.ts`'s `defaultBuildPath`,
+            // which is exported for adopters to extend and also handles the collection case
+            // `computeEntryUrl` does not model. It agrees today; folding it in is tracked in
+            // `.claude/future-tasks/default-build-path-url-rule-copy.md`.
+            // `content-listing.test.ts` pins the listing-vs-resolved-reference agreement.
+            const urlPath = computeEntryUrl(entry.collectionPath, entry.slug, contentRootName);
             const raw = entry.data;
             const meta = {
                 entryPath: entry.logicalPath,
@@ -398,4 +392,3 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
     }));
     return entries.filter((e) => e !== null);
 };
-//# sourceMappingURL=content-listing.js.map

package/dist/content-reader.d.ts

@@ -1,7 +1,7 @@
-import { type ContentId, type LogicalPath, type PhysicalPath, type Slug } from './paths';
-import type { CanopyServices } from './services';
-import type { BranchContext } from './types';
-import type { CanopyUser } from './user';
+import { type ContentId, type LogicalPath, type PhysicalPath, type Slug } from './paths/index.js';
+import type { CanopyServices } from './services.js';
+import type { BranchContext } from './types.js';
+import type { CanopyUser } from './user.js';
 export interface ContentReaderOptions {
     services: CanopyServices;
     basePathOverride?: string;
@@ -73,4 +73,3 @@ export interface ContentReader {
  * Falls back to creating the branch workspace (metadata + checkout) if missing.
  */
 export declare const createContentReader: (options: ContentReaderOptions) => ContentReader;
-//# sourceMappingURL=content-reader.d.ts.map