canopycms 0.0.63 → 0.0.65

package/dist/content-store.js

@@ -1,19 +1,23 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import matter from 'gray-matter';
-import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import { parse as yamlParse } from 'yaml';
 import { atomicWriteFile } from './utils/atomic-write.js';
+import { serializeFrontmatter, serializeYaml } from './utils/content-serialize.js';
 import { withLock } from './utils/async-mutex.js';
 import { ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from './utils/content-write-lock.js';
 import { findBodyFieldName } from './utils/body-field.js';
+import { buildResolvedReference } from './entry-schema.js';
+import { computeEntryUrl } from './utils/entry-url.js';
+import { findUrlPathClaimant } from './url-collision.js';
 import { ContentIdIndex, extractIdFromFilename, extractSlugFromFilename, extractEntryTypeFromFilename, resolveCollectionPath, } from './content-id-index.js';
 import { registerContentIndexForInvalidation } from './content-index-registry.js';
 import { bumpContentIndexGeneration, readContentIndexGeneration } from './content-index-generation.js';
 import { generateId } from './id.js';
 import { isNodeError } from './utils/error.js';
-import { filePathExists } from './utils/fs.js';
+import { filePathExists, readFileIfExists } from './utils/fs.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
-import { normalizeFilesystemPath, } from './paths/index.js';
+import { normalizeFilesystemPath, parseSlug, } from './paths/index.js';
 /**
  * Acquire multiple lock keys (via withLock) in a canonical (sorted) order
  * before running `fn`, to rule out AB-BA deadlocks between callers that need
@@ -107,6 +111,27 @@ export class DuplicateContentIdError extends ContentConflictError {
         this.paths = sorted;
     }
 }
+/**
+ * Thrown when a create or rename would give a SECOND entry a `urlPath` another entry already
+ * holds -- the write-boundary half of the invariant `assertNoDuplicateUrlPaths` enforces at build
+ * time (see url-collision.ts for which shapes count and, just as importantly, which do not).
+ *
+ * Why refuse rather than write: only one of the two entries can be served at that URL, so the
+ * other silently has no route anywhere. Allowing the write trades a clear error now for a page
+ * that quietly does not exist later -- and, because the loser is picked by resolver precedence
+ * rather than by the author, not necessarily the page they were editing.
+ *
+ * A `ContentConflictError` subclass so every existing 409 mapping keeps working; the distinct
+ * type exists so the API can surface THIS message rather than the generic "modified by another
+ * editor", which would send the editor into a reload-and-retry loop that cannot succeed.
+ */
+export class UrlPathConflictError extends ContentConflictError {
+    constructor(message, conflictingPath) {
+        super(message);
+        this.name = 'UrlPathConflictError';
+        this.conflictingPath = conflictingPath;
+    }
+}
 /**
  * Get the default entry type from a collection's entries array.
  * Returns the entry marked as default, or the first one, or undefined if no entries.
@@ -119,6 +144,13 @@ export function getDefaultEntryType(entries) {
 /**
  * Validates that a slug doesn't contain slashes or backslashes.
  * Slugs must be simple filenames (last path segment only).
+ *
+ * Deliberately WEAKER than `parseSlug`, and deliberately not merged with it: this runs on every
+ * resolution, reads included (`buildPaths`), so it can only enforce what must be true of content
+ * that already exists on disk -- i.e. path safety. Content whose slug predates CanopyCMS, or was
+ * hand-authored, or came in over git, has to stay readable. `parseSlug`'s stricter URL-addressable
+ * rule is enforced only where a NEW filename is minted (see the [SLUG] guards in `write()` and
+ * `renameEntry()`); applying it here would convert a build-time failure into unreachable data.
  */
 function validateSlug(slug) {
     if (slug.includes('/')) {
@@ -136,6 +168,8 @@ const DEFAULT_INDEX_FRESHNESS_INTERVAL_MS = 1000;
 const FORCED_REFRESH_MIN_INTERVAL_MS = 5000;
 /** Internal sentinel: a lookup result that suggests this store's index is stale. */
 const STALE_LOOKUP = Symbol('stale-index-lookup');
+/** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
+export const createReferenceResolveCache = () => new Map();
 export class ContentStore {
     constructor(root, flatSchema, options = {}) {
         /** Bumped by invalidateIndex(); when it differs from loadedIndexGeneration the index is stale. */
@@ -420,6 +454,32 @@ export class ContentStore {
             return this.createLockKey(schemaItem, slug);
         return prePass.id ? this.idLockKey(prePass.id) : prePass.absolutePath;
     }
+    /**
+     * Refuse a create/rename that would give a second entry a `urlPath` another entry already
+     * holds. See url-collision.ts for the two shapes that count, and the legitimate
+     * landing-page-beside-a-collection shape that deliberately does not.
+     *
+     * @param collectionDir Absolute physical directory the entry will live in.
+     * @param slug The entry's slug, as it will be written.
+     */
+    async assertUrlPathAvailable(collectionDir, slug) {
+        const claimant = await findUrlPathClaimant({
+            collectionDir,
+            slug,
+            contentRoot: path.resolve(this.root, this.contentRootName),
+        });
+        if (!claimant)
+            return;
+        const relative = path.relative(this.root, claimant.physicalPath);
+        const message = claimant.kind === 'sibling-collection-index'
+            ? `An entry with slug "${slug}" would share a URL with the index entry of the ` +
+                `"${claimant.name}" collection beside it ("${relative}"), and only one of them could ` +
+                `be served there. Rename this entry, or remove that collection's index entry.`
+            : `An index entry here would share a URL with the "${claimant.name}" entry in the parent ` +
+                `collection ("${relative}"), and only one of them could be served there. Rename that ` +
+                `entry, or give this collection's landing page a different slug.`;
+        throw new UrlPathConflictError(message, claimant.physicalPath);
+    }
     /**
      * Build absolute and relative paths with security validation.
      * All entries use the unified filename pattern: {type}.{slug}.{id}.{ext}
@@ -773,6 +833,54 @@ export class ContentStore {
                             }
                         }
                     }
+                    // [URL] Contested-URL guard, create only: an ordinary save cannot contest a URL it
+                    // already holds, and blocking it would trap the author in an entry they can no longer
+                    // edit.
+                    //
+                    // Keyed on whether the target file actually EXISTS, not on `inLock.existed`. That flag
+                    // is `foundExisting || Boolean(options.existingId)`, and the `existingId` half is a
+                    // caller ASSERTION rather than disk truth -- so an id-addressed write recreating an
+                    // entry that was deleted out from under it (git, another process) would skip the guard
+                    // while in fact creating one.
+                    //
+                    // The slug is read back off the filename `buildPaths` actually chose, never the
+                    // caller's raw argument: `buildPaths` strips leading slashes and lowercases, and for
+                    // the entry-type delegation shape substitutes the type name for an empty slug. Checking
+                    // the raw value let `write(collection, '/guides', ...)` sail past a `guides` claimant.
+                    //
+                    // Serialization comes from `withContentWriteExclusion` (the branch-wide, cross-host
+                    // content-write lock wrapping this whole reclassification loop), NOT from the per-entry
+                    // lock: the two halves of a contested pair live in DIFFERENT collections and so take
+                    // different entry-lock keys. The branch lock is what makes check-then-write atomic
+                    // against the other half landing concurrently.
+                    if (!(await filePathExists(absolutePath))) {
+                        const chosenSlug = extractSlugFromFilename(path.basename(absolutePath));
+                        // [SLUG] Routability guard, create only. `validateSlug` above (in buildPaths) is the
+                        // path-traversal check -- it only rejects `/` and `\`, and it has to stay that weak
+                        // because it also runs on every READ. So the filename grammar accepts slugs that
+                        // `parseSlug` does not (a dot, an underscore, a leading hyphen), and `readByUrlPath`
+                        // runs every URL candidate through `parseSlug` before trying a read -- meaning such
+                        // an entry writes fine, builds fine, gets a `generateStaticParams` entry and a
+                        // sitemap `<loc>`, and then 404s on every actual visit. `assertRoutableSlugs`
+                        // (static/index.ts) now fails the whole production build over it.
+                        //
+                        // Refuse at the moment the unroutable entry is CREATED, so the failure lands on the
+                        // caller that caused it rather than on whoever builds next. Create-only, keyed on the
+                        // target file not existing, for exactly the reason the [URL] guard below is: content
+                        // that already has a non-conforming slug (hand-authored, imported, or predating this
+                        // guard) must stay editable -- and must stay renameable, which is the only way out.
+                        // Tightening the read path instead would turn a red build into unreachable data.
+                        //
+                        // Checked against the slug `buildPaths` actually chose, not the caller's raw
+                        // argument: buildPaths lowercases, strips leading slashes, and substitutes the entry
+                        // type's name for an empty slug (the singleton shape, e.g. write('content/home', '')).
+                        const routable = parseSlug(chosenSlug);
+                        if (!routable.ok) {
+                            throw new ContentStoreError(`Cannot create entry "${chosenSlug}": ${routable.error}. An entry whose slug is ` +
+                                'not addressable as a URL segment would build and then 404 on every visit.', 'VALIDATION');
+                        }
+                        await this.assertUrlPathAvailable(path.dirname(absolutePath), chosenSlug);
+                    }
                     await fs.mkdir(path.dirname(absolutePath), { recursive: true });
                     // OCC: undefined means no opinion (skip entirely, back-compat blind
                     // write). A number means "must match this mtime" (stale-write
@@ -846,16 +954,36 @@ export class ContentStore {
                             throw new ContentConflictError();
                         }
                     }
+                    // Comment preservation: re-serialise onto the file's OWN parsed document rather than
+                    // a fresh one, so nodes the payload did not change -- and the comments attached to
+                    // them -- survive the write. Without this every editor save silently deleted every
+                    // comment in the file (JSON has no comment syntax, so it is unaffected and skips the
+                    // read). See utils/content-serialize.ts.
+                    //
+                    // This makes the write a genuine read-modify-write of the content file, so WHERE the
+                    // read happens matters: it is inside withLock(lockKey), inside
+                    // withContentWriteExclusion ([SYNC-C1]), and after the expectedVersion stat above --
+                    // so the bytes read here are the bytes that OCC check validated, and no rebase can be
+                    // running against this branch. Do not hoist it out of the critical section.
+                    //
+                    // INVARIANT, and the one case that does NOT preserve comments: this reads the path
+                    // being WRITTEN. A relocating write -- one where the ID resolves to a different
+                    // relativePath, so the block below unlinks `staleOldAbsPath` -- finds nothing at the
+                    // new path and falls back to a plain stringify, losing the old file's comments. Latent
+                    // today: the editor renames through renameEntry(), which link()s the bytes across
+                    // intact, and no caller passes `existingId`. If a relocating write ever becomes
+                    // reachable, read the ID's current path here instead of `absolutePath`.
+                    const existingRaw = input.format === 'json' ? undefined : await readFileIfExists(absolutePath);
                     // Serialize content string
                     let content;
                     if (input.format === 'json') {
                         content = `${JSON.stringify(input.data ?? {}, null, 2)}\n`;
                     }
                     else if (input.format === 'yaml') {
-                        content = yamlStringify(input.data ?? {});
+                        content = serializeYaml(input.data ?? {}, existingRaw);
                     }
                     else {
-                        content = matter.stringify(input.body, input.data ?? {});
+                        content = serializeFrontmatter(input.body, input.data ?? {}, existingRaw);
                     }
                     await atomicWriteFile(absolutePath, content);
                     // Update the ID index after a successful write. Look up and mutate the
@@ -1114,7 +1242,7 @@ export class ContentStore {
         // Warm the index outside the lock (a full scan must not hold the entry lock)
         await this.idIndex();
         const collection = this.assertCollection(collectionPath);
-        // Validate new slug format (Slug branded type guarantees lowercase alphanumeric+hyphens via parseSlug)
+        // Path-traversal check (rejects separators only).
         validateSlug(newSlug);
         const safeNewSlug = newSlug.replace(/^\/+/, '');
         if (!safeNewSlug) {
@@ -1124,6 +1252,21 @@ export class ContentStore {
         if (currentSlug === safeNewSlug) {
             return { newPath: `${collectionPath}/${currentSlug}` };
         }
+        // [SLUG] Routability check, run here rather than trusted from the caller. The `Slug` branded
+        // type does NOT guarantee it: `ContentStore.resolvePath` casts a raw path segment to `Slug`
+        // with only `.toLowerCase()`, and tests/callers reach for `unsafeAsSlug`. The API's
+        // `slugSchema` does run `parseSlug` on `newSlug`, but that is one caller of an exported
+        // method -- and a rename mints a new filename, so it is a write that can create an
+        // unroutable entry just as a create can. See write()'s [SLUG] guard for what goes wrong.
+        //
+        // Deliberately AFTER the no-op short-circuit above: a rename to the slug the entry already
+        // has mints nothing, so refusing it would only take an existing non-conforming entry and
+        // make one more operation on it fail, for no gain.
+        const routable = parseSlug(safeNewSlug);
+        if (!routable.ok) {
+            throw new ContentStoreError(`Cannot rename to "${safeNewSlug}": ${routable.error}. An entry whose slug is not ` +
+                'addressable as a URL segment would build and then 404 on every visit.', 'VALIDATION');
+        }
         // Pre-pass: classify via a directory scan (local ground truth, not the
         // index) and pick the source entry's stable lock key.
         const prePass = await this.buildPaths(collection, currentSlug);
@@ -1214,6 +1357,16 @@ export class ContentStore {
                             throw err;
                         // Ignore filesystem errors (e.g. ENOENT if parent dir doesn't exist)
                     }
+                    // [URL] Contested-URL guard. A rename moves the entry to a NEW url, so the same
+                    // check a create gets applies here -- including the index direction, since renaming
+                    // an entry TO `index` is how an existing collection acquires a landing page.
+                    //
+                    // Runs AFTER the same-slug scan above, deliberately. In an already-contested tree
+                    // both refusals apply, and the same-slug one is the more immediate and more
+                    // actionable of the two -- reporting the URL conflict first sent the author to fix
+                    // the other claimant, only to hit the same-slug refusal on the retry. Still before
+                    // link(), so either refusal leaves the tree untouched.
+                    await this.assertUrlPathAvailable(parentDir, safeNewSlug);
                     // Use link()+unlink() instead of rename() so a concurrent cross-process rename to the
                     // exact same destination path fails with EEXIST rather than silently overwriting.
                     //
@@ -1321,29 +1474,57 @@ export class ContentStore {
         }
         return entries;
     }
+    /**
+     * Resolve every `reference` field in `data` against `fields`, returning a copy.
+     *
+     * This is what `read()` applies automatically (unless `resolveReferences: false`), exposed
+     * so BATCH surfaces can opt into the same resolution without duplicating the walk: the
+     * listing primitives in content-listing.ts and content-tree.ts read entry files straight
+     * off disk and never touch this store, so before this existed a `reference` field reached
+     * `listEntries()`/`buildContentTree()` callers as a bare id string or `null`.
+     *
+     * Pass one {@link ReferenceResolveCache} across a whole batch so a target referenced by
+     * many entries is read once rather than once per referencing entry. Omit `cache` and the
+     * behavior is exactly what `read()` has always done, unmemoized.
+     *
+     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's
+     * own `read()`, below the per-entry permission check in content-reader.ts — so a resolved
+     * target may be an entry the caller could not `read()` directly. That is pre-existing
+     * `read()` behavior, matched here on purpose so one rule covers both; see the
+     * `resolveReferences` option in content-listing.ts for the note adopters see.
+     */
+    async resolveReferences(data, fields, cache) {
+        return this.resolveReferencesInData(data, fields, cache);
+    }
     /**
      * Recursively resolve reference fields in data.
      * This traverses objects, arrays, and blocks to find and resolve all reference fields.
      */
-    async resolveReferencesInData(data, fields) {
+    async resolveReferencesInData(data, fields, cache) {
         const resolved = { ...data };
         const idIndex = await this.idIndex();
         for (const field of fields) {
             // Inline groups are transparent — recurse into their children at the same data level
             if (field.type === 'group') {
-                const groupResolved = await this.resolveReferencesInData(resolved, field.fields);
+                const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache);
                 Object.assign(resolved, groupResolved);
                 continue;
             }
             const value = data[field.name];
             if (field.type === 'reference') {
+                // Whether this reference EMBEDS its target (wants the target's body) or merely LINKS
+                // to it is a property of the field, declared once in the schema -- not of the call,
+                // which routinely contains both kinds at once. See ReferenceFieldConfig.includeBody.
+                const includeBody = field.includeBody === true;
                 // Single reference
                 if (typeof value === 'string' && value) {
-                    resolved[field.name] = await this.resolveSingleReference(value, idIndex);
+                    resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache);
                 }
                 // Array of references (list: true)
                 else if (field.list && Array.isArray(value)) {
-                    resolved[field.name] = await Promise.all(value.map((id) => typeof id === 'string' ? this.resolveSingleReference(id, idIndex) : null));
+                    resolved[field.name] = await Promise.all(value.map((id) => typeof id === 'string'
+                        ? this.resolveSingleReference(id, idIndex, includeBody, cache)
+                        : null));
                 }
             }
             // Recursively handle nested objects
@@ -1353,11 +1534,11 @@ export class ContentStore {
                     continue;
                 if (objectField.list && Array.isArray(value)) {
                     resolved[field.name] = await Promise.all(value.map((item) => typeof item === 'object' && item !== null
-                        ? this.resolveReferencesInData(item, objectField.fields)
+                        ? this.resolveReferencesInData(item, objectField.fields, cache)
                         : item));
                 }
                 else if (typeof value === 'object') {
-                    resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields);
+                    resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache);
                 }
             }
             // Recursively handle blocks
@@ -1372,7 +1553,7 @@ export class ContentStore {
                         return block;
                     return {
                         ...b,
-                        value: await this.resolveReferencesInData(b.value, template.fields),
+                        value: await this.resolveReferencesInData(b.value, template.fields, cache),
                     };
                 }));
             }
@@ -1380,7 +1561,68 @@ export class ContentStore {
         return resolved;
     }
     /**
-     * Resolve a single reference ID to full entry data.
+     * Resolve a single reference ID to full entry data, memoized when a batch cache is
+     * supplied. Without a cache this is a straight pass-through to the uncached path, so
+     * `read()` behaves exactly as it always has.
+     *
+     * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo
+     * would hand one shared object to all 40 entries referencing the same block — a mutation
+     * in one caller's `extract` (truncating a body for a search index, deleting a field) would
+     * silently rewrite it for every sibling, and both `list: true` elements of `[id, id]` would
+     * be the same instance. The copy is what keeps the cache a pure performance optimization
+     * instead of a semantic change.
+     *
+     * Note the uncached path is NOT the clean baseline it looks like. For a json/yaml target it
+     * genuinely reparses fresh per occurrence, but for md/mdx gray-matter serves `data` from a
+     * process-global content-keyed cache, so `resolveSingleReferenceOnce`'s top-level spread
+     * severs exactly one level and NESTED frontmatter objects alias across occurrences, calls and
+     * requests. That is pre-existing `read()` behavior and out of scope here — deliberately, since
+     * touching it would change `read()` — but it means the cached path is the safer of the two,
+     * not a relaxation of a guarantee the uncached one provides. See
+     * `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+     *
+     * What the copy costs, measured rather than assumed (2000 occurrences of one target, local
+     * disk, so every read hits the page cache — the friendliest possible case for NOT caching):
+     * a snippet-sized target is ~63x cheaper to clone than to re-read-and-parse, while a 265KB
+     * JSON target is ~0.8x, i.e. cloning is marginally SLOWER than reparsing it. So the win is
+     * large in the case this exists for and roughly a wash at the pathological end, never a
+     * blow-up. Two things keep the bad end narrow: an md/mdx target resolves to its FRONTMATTER
+     * only *unless the field sets `includeBody`* (`read()` puts the body on `doc.body`, which
+     * `resolveSingleReferenceOnce` spreads in only for an embedding field), so by default body
+     * size is irrelevant no matter how long the document and only a genuinely huge JSON/YAML
+     * target reaches the wash. **`includeBody: true` is the case that CAN reach it on markdown**:
+     * the body then sits inside the memoized object and is cloned once per referencing entry, so
+     * a long document embedded by many pages pays that repeatedly — the reason `includeBody`
+     * exists as an opt-in per field rather than as resolution's default. And in the deployment this
+     * targets, content lives on EFS/NFS where the syscall the memo removes dominates parse and
+     * clone alike, which the local-disk numbers above understate badly. Correctness is the
+     * reason for the copy regardless; the numbers are here so nobody has to re-derive them
+     * before touching this.
+     */
+    resolveSingleReference(id, idIndex, includeBody, cache) {
+        if (!cache)
+            return this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+        // The key carries `includeBody`, not just the id: two fields can reference the SAME target
+        // with different settings, and sharing one entry between them would make the shape depend
+        // on which field the walk reached first -- the traversal-order nondeterminism the
+        // per-occurrence copy already exists to prevent.
+        const key = includeBody ? `${id}:body` : id;
+        let pending = cache.get(key);
+        if (!pending) {
+            // Store the in-flight promise, and do it with no `await` in between: the whole point is
+            // that concurrent lookups from one Promise.all batch find it and collapse onto a single
+            // read. Memoizing the promise also keeps the self-healing retry below shared rather than
+            // repeated — see ReferenceResolveCache for why misses are cached too.
+            pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+            cache.set(key, pending);
+        }
+        // The cached promise always has this handler attached, so it is never an unhandled
+        // rejection; entry data is plain parsed JSON/YAML/frontmatter, so it is always cloneable
+        // (verified against real parser output incl. `!!timestamp` Dates — the sole shape not
+        // preserved exactly is a `!!binary` Buffer, which clones to a plain Uint8Array).
+        return pending.then((resolved) => (resolved === null ? null : structuredClone(resolved)));
+    }
+    /**
      * Returns null if the reference is invalid or missing.
      * Includes id, slug, and collection fields for debugging.
      *
@@ -1394,9 +1636,14 @@ export class ContentStore {
      * idIndex() dedupes concurrent builds — so a sibling call that wins the
      * throttle and rebuilds heals every other miss in the same batch, not just
      * the first.
+     *
+     * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every
+     * distinct id still runs the full refresh-and-retry above. What a cache changes
+     * is only that repeats of the SAME id in one batch share that one attempt's
+     * outcome instead of each getting an independent throw of the dice.
      */
-    async resolveSingleReference(id, idIndex) {
-        const first = await this.resolveSingleReferenceOnce(id, idIndex);
+    async resolveSingleReferenceUncached(id, idIndex, includeBody) {
+        const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody);
         if (first !== STALE_LOOKUP)
             return first;
         // Force a rebuild (throttled). Even when this caller loses the throttle,
@@ -1404,10 +1651,10 @@ export class ContentStore {
         // won it and invalidated/rebuilt (idIndex() dedupes in-flight builds), so
         // every miss in a Promise.all batch heals, not just the first.
         await this.refreshIndexForSuspiciousLookup();
-        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex());
+        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody);
         return second === STALE_LOOKUP ? null : second;
     }
-    async resolveSingleReferenceOnce(id, idIndex) {
+    async resolveSingleReferenceOnce(id, idIndex, includeBody) {
         try {
             const location = idIndex.findById(id);
             if (!location)
@@ -1419,12 +1666,38 @@ export class ContentStore {
             const doc = await this.read(location.collection, location.slug, {
                 resolveReferences: false,
             });
-            return {
+            // `urlPath` is what makes a resolved reference linkable. Without it, a page rendering
+            // "see also: <Target>" as a real anchor had no way to get an href from the resolution
+            // it had already paid for — one adopter ran a SECOND full listEntries pass over the
+            // whole tree purely to build a contentId -> url table, and set `resolveReferences:
+            // false` on pages where paying for both was worse than hand-rolling it.
+            //
+            // Deliberately `computeEntryUrl` (utils/entry-url.ts), the same forward
+            // collection+slug -> url rule `listEntries` publishes as `item.urlPath` and
+            // `entry-link-resolver.ts` already uses for `entry:ID` links — NOT the reverse
+            // url -> entry resolver in url-path-resolver.ts. The two agree today (the reverse
+            // resolver was taught to skip its direct-entry candidate for a literal `index` slug,
+            // precisely so it stops answering at URLs this rule never emits — see
+            // .claude/future-tasks/resolved/url-resolver-index-entry-extra-url.md), but the
+            // direction still matters: this is the surface that DEFINES an entry's URL, and
+            // sourcing it from the resolver that consumes that definition would invert the
+            // dependency and let any future divergence propagate into every resolved reference.
+            //
+            // The assembly itself — data, then the embedded body, then the reserved metadata — is
+            // `buildResolvedReference`'s job rather than this function's, because the editor's
+            // live-preview endpoint (api/resolve-references.ts) builds the same object and the two
+            // had already drifted. That doc comment carries the reasoning for the ordering.
+            //
+            // `'body' in doc` is what narrows the ContentDocument union to its markdown variant, so
+            // `doc.body`/`doc.bodyFieldName` are reachable at all — a type guard, not a redundant
+            // runtime check. Only a field that asked to EMBED its target passes a body at all.
+            const bodyForEmbed = includeBody && 'body' in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : undefined;
+            return buildResolvedReference(doc.data, {
                 id,
                 slug: location.slug,
                 collection: location.collection,
-                ...doc.data,
-            };
+                urlPath: computeEntryUrl(location.collection, location.slug, this.contentRootName),
+            }, bodyForEmbed);
         }
         catch (error) {
             // Index hit but the file is gone — the typical symptom of an external
@@ -1436,4 +1709,3 @@ export class ContentStore {
         }
     }
 }
-//# sourceMappingURL=content-store.js.map

package/dist/content-tree.d.ts

@@ -8,7 +8,7 @@
  * metadata, entry metadata). Display concerns like labels are left to the
  * adopter via the `extract` callback.
  */
-import type { FlatSchemaItem, ContentFormat } from './config';
+import type { FlatSchemaItem, ContentFormat } from './config/index.js';
 /**
  * Adopter-supplied registry mapping entry type names (as they appear in
  * filenames: `partner.index.yaml` → `'partner'`) to their data shapes.
@@ -86,8 +86,8 @@ export interface ContentTreeExtractMeta<TEntryTypes = DefaultEntryTypes> {
         };
     }[keyof TEntryTypes & string];
 }
-import type { LogicalPath, ContentId, Slug } from './paths/types';
-import { type ContentVisibilityOptions } from './content-listing';
+import type { LogicalPath, ContentId, Slug } from './paths/types.js';
+import { type ContentVisibilityOptions } from './content-listing.js';
 export interface ContentTreeNode<T = unknown> {
     /** URL path, e.g. "/docs/getting-started". Computed by buildPath option. */
     path: string;
@@ -162,13 +162,24 @@ export interface BuildContentTreeOptions<T = unknown, TEntryTypes = DefaultEntry
     sort?: (a: ContentTreeNode<T>, b: ContentTreeNode<T>) => number;
     /** Max depth to traverse. Default: unlimited. */
     maxDepth?: number;
+    /**
+     * Resolve `reference` fields to the referenced entry's data, the way
+     * `read()`/`readByUrlPath()` do. Applies to both entry nodes and the `meta.indexEntry`
+     * handed to a collection's `extract`. Off leaves them as the bare id string, or `null`.
+     *
+     * Same flag, same default (`false`) and same reasoning as `listEntries`' option — see
+     * `ListEntriesOptions.resolveReferences` in content-listing.ts for why the default is
+     * opt-in rather than matching `read()`, what it costs, and why path ACLs are not applied
+     * to the resolved targets.
+     */
+    resolveReferences?: boolean;
 }
 /**
  * Default path builder: strips the content root prefix, lowercases, and prepends /.
  * All URL paths are lowercased unconditionally for consistency with slug normalization.
  * Adopters with case-sensitive slugs (e.g., "API-Reference") will get lowercased URLs.
  *
- * Index entries (slug 'index') are collapsed to their parent collection path,
+ * Index entries (slug 'index', any case) are collapsed to their parent collection path,
  * matching the URL convention used by readByUrlPath and listEntries.
  *
  * Exported (also re-exported from `canopycms/server`) so adopters who want to
@@ -187,4 +198,3 @@ export declare const defaultBuildPath: (logicalPath: LogicalPath, contentRootNam
  * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export declare function buildContentTree<T = unknown, TEntryTypes = DefaultEntryTypes>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: BuildContentTreeOptions<T, TEntryTypes>, visibility?: ContentVisibilityOptions): Promise<ContentTreeNode<T>[]>;
-//# sourceMappingURL=content-tree.d.ts.map

package/dist/content-tree.js

@@ -8,7 +8,11 @@
  * metadata, entry metadata). Display concerns like labels are left to the
  * adopter via the `extract` callback.
  */
-import { listCollectionEntries, sortByOrder, } from './content-listing.js';
+import { isIndexSlug } from './utils/entry-url.js';
+import { createReferenceResolver, listCollectionEntries, resolveCollectionItemReferences, sortByOrder, } from './content-listing.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
 /** Group flat schema items by parentPath for O(1) child lookup. */
 const groupByParent = (flat) => {
     const map = new Map();
@@ -27,7 +31,7 @@ const groupByParent = (flat) => {
  * All URL paths are lowercased unconditionally for consistency with slug normalization.
  * Adopters with case-sensitive slugs (e.g., "API-Reference") will get lowercased URLs.
  *
- * Index entries (slug 'index') are collapsed to their parent collection path,
+ * Index entries (slug 'index', any case) are collapsed to their parent collection path,
  * matching the URL convention used by readByUrlPath and listEntries.
  *
  * Exported (also re-exported from `canopycms/server`) so adopters who want to
@@ -40,11 +44,18 @@ export const defaultBuildPath = (logicalPath, contentRootName, kind) => {
     const stripped = prefix && logicalPath.startsWith(prefix) ? logicalPath.slice(prefix.length) : logicalPath;
     // Collapse index entries: content/guides/index → /guides (not /guides/index)
     // Only for entries — a collection named "index" should keep its path.
-    const collapsed = kind === 'entry' && stripped.endsWith('/index')
-        ? stripped.slice(0, -6)
-        : kind === 'entry' && stripped === 'index'
+    //
+    // The index test runs on the LAST SEGMENT through the shared `isIndexSlug`, so it is
+    // case-insensitive and agrees with `computeEntryUrl`. A string `endsWith('/index')` test
+    // did not: for an adopter-supplied `content/docs/Index` this said `/docs/index` while
+    // `computeEntryUrl` said `/docs`, and `/docs/index` is the one that does NOT round-trip.
+    const lastSlash = stripped.lastIndexOf('/');
+    const lastSegment = lastSlash === -1 ? stripped : stripped.slice(lastSlash + 1);
+    const collapsed = kind === 'entry' && isIndexSlug(lastSegment)
+        ? lastSlash === -1
             ? ''
-            : stripped;
+            : stripped.slice(0, lastSlash)
+        : stripped;
     const urlPath = collapsed ? `/${collapsed}` : '/';
     return urlPath.toLowerCase();
 };
@@ -74,9 +85,18 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
      * even though no node for it is ever emitted.
      */
     const shouldInclude = visibility?.shouldInclude;
+    // One store + cache for the whole recursive walk, so a block shared across collections is
+    // read once for the entire tree rather than once per collection. Null unless opted in —
+    // see the `resolveReferences` option above.
+    const resolver = options?.resolveReferences
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        : null;
     const listVisibleEntries = async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection);
-        return shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        // Resolved here rather than at the two node-building sites so BOTH inherit it — the same
+        // reason the ACL filter lives here. A denied entry is filtered above and never resolved.
+        return resolver ? resolveCollectionItemReferences(visible, collection, resolver) : visible;
     };
     // Find the starting collection(s)
     const rootPath = options?.rootPath ?? contentRootName;
@@ -209,4 +229,3 @@ function interleaveChildren(collectionNodes, entryNodes, order, customSort) {
     }
     return sortByOrder(all, order, (item) => item.kind === 'collection' ? (item.collection?.name ?? '') : (item.entry?.slug ?? ''));
 }
-//# sourceMappingURL=content-tree.js.map

package/dist/context.d.ts

@@ -1,8 +1,8 @@
-import type { CanopyUser } from './user';
-import type { CanopyServices } from './services';
-import type { ContentReadMeta } from './content-reader';
-import { type BuildContentTreeOptions, type ContentTreeNode, type DefaultEntryTypes } from './content-tree';
-import { type ListEntriesOptions, type ListEntriesItem } from './content-listing';
+import type { CanopyUser } from './user.js';
+import type { CanopyServices } from './services.js';
+import type { ContentReadMeta } from './content-reader.js';
+import { type BuildContentTreeOptions, type ContentTreeNode, type DefaultEntryTypes } from './content-tree.js';
+import { type ListEntriesOptions, type ListEntriesItem } from './content-listing.js';
 export interface CanopyContextOptions {
     services: CanopyServices;
     /**
@@ -78,6 +78,10 @@ export interface CanopyBuildContext {
      * Tries direct entry match first (last segment = slug, rest = collection path),
      * then falls back to index entry (full path = collection, slug = 'index').
      * Root path '/' resolves to the content root's index entry.
+     *
+     * The direct-entry attempt is SKIPPED when the last segment is an index slug (any case), so
+     * `/x/index` returns null rather than a second URL for the entry that already answers at `/x`.
+     * A collection literally named `index` is unaffected — the fallback resolves it.
      * Returns null if no content matches the path — including collection URLs that have no
      * index entry (use buildContentTree for those) and non-entry/invalid paths such as
      * `/favicon.ico` or Next internals (the slug validator rejects them, treated as a miss).
@@ -141,4 +145,3 @@ export declare function createCanopyContext(options: CanopyContextOptions): {
     getContext: () => Promise<CanopyContext>;
     services: CanopyServices;
 };
-//# sourceMappingURL=context.d.ts.map

package/dist/context.js

@@ -216,4 +216,3 @@ export function createCanopyContext(options) {
         services,
     };
 }
-//# sourceMappingURL=context.js.map