canopycms 0.0.63 → 0.0.65

package/dist/utils/title-field.js

@@ -154,4 +154,3 @@ function collectAllTitleFields(fields, parentPath) {
     }
     return found;
 }
-//# sourceMappingURL=title-field.js.map

package/dist/utils/typed-filename.d.ts

@@ -0,0 +1,61 @@
+import type { EntryTypeConfig } from '../config/index.js';
+import type { ContentId, Slug } from '../paths/types.js';
+/**
+ * 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, or a dot) 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." `listCollectionEntries` (content-listing.ts)
+ *   is exactly such a caller that does NOT re-validate — it lists the file and computes a
+ *   `urlPath` for it regardless — so a dotted slug listed this way builds and gets
+ *   advertised (sitemap, `generateStaticParams`) but can never be read back through
+ *   `readByUrlPath`, which does run every URL-resolution candidate through `parseSlug`.
+ *   `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this.
+ */
+export declare const parseTypedFilename: (filename: string, entryTypes?: readonly EntryTypeConfig[]) => {
+    type: string;
+    slug: Slug;
+    id: ContentId;
+} | null;

package/dist/utils/typed-filename.js

@@ -0,0 +1,92 @@
+import { isValidId } from '../id.js';
+// Lives here rather than in content-listing.ts, where it was born, purely so dependency-light
+// modules can use it: content-listing imports ContentStore, so anything content-store itself
+// imports (url-collision.ts) cannot reach back into it without a cycle. content-listing
+// re-exports this and `canopycms/server` re-exports it from there, so the public surface is
+// unchanged.
+/**
+ * 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, or a dot) 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." `listCollectionEntries` (content-listing.ts)
+ *   is exactly such a caller that does NOT re-validate — it lists the file and computes a
+ *   `urlPath` for it regardless — so a dotted slug listed this way builds and gets
+ *   advertised (sitemap, `generateStaticParams`) but can never be read back through
+ *   `readByUrlPath`, which does run every URL-resolution candidate through `parseSlug`.
+ *   `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this.
+ */
+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();
+    return {
+        type: potentialType,
+        slug: slug,
+        id: id,
+    };
+};

package/dist/utils/url-prefix.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Joining a URL prefix onto a root-relative path, in ONE place.
+ *
+ * Two surfaces need the identical operation and had drifted into two implementations:
+ *
+ * - `static/seo.ts`'s `resolveSeoUrl` puts a site origin in front of an entry's URL path.
+ * - `assets/asset-url.ts`'s `assetUrl` puts an asset-space mount point in front of a stored
+ *   `/assets/…` src.
+ *
+ * The asset copy was the weaker one - it checked neither absoluteness of the path nor the shape
+ * of the prefix - so it silently produced `/prefix/https://cdn.example.com/x.png` for an
+ * off-site src, and a *document-relative* URL for a prefix that had no leading slash. Both bugs
+ * were already solved on the SEO side. Sharing one function is what stops a third caller from
+ * inheriting the weaker half again.
+ *
+ * Dependency-free apart from `./sanitize-href` (itself pure - its only dependency is the global
+ * `URL`), because this is reachable from client bundles via `assets/asset-url.ts`. Do not add a
+ * node built-in here; `pnpm lint:bundle` fails the build if you do.
+ */
+/**
+ * Whether `url` is a DECLARED off-site pointer - a scheme-qualified absolute URL
+ * (`https://example.com/x`) or a literal protocol-relative one (`//cdn.example.com/x`).
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. Callers handle that case
+ * separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. Both prefixes that reach here - a `siteUrl` and an asset `baseUrl` - are
+ * adopter-supplied and can come from config or an env var, so they count as uncontrolled. A
+ * character scan is linear and needs no reasoning about backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export declare function stripTrailingSlashes(value: string): string;
+/**
+ * Reduce a URL reference to a value that is safe to emit as a SAME-ORIGIN path.
+ *
+ * `neutralizeImplicitOffOrigin` alone is not sufficient, and this is the subtle part: it returns
+ * `pathname + search + hash`, and a WHATWG `pathname` can ITSELF begin with `//`. `/\evil.com//a`
+ * parses to host `evil.com` with pathname `//a`, so neutralizing yields the string `//a` — which,
+ * re-emitted as a URL reference, reads as protocol-relative all over again and points at a host
+ * literally named `a`. Neutralizing a second time does not help: the value is now indistinguishable
+ * from a caller's legitimate `//cdn.example.com` pointer, so every absolute-URL check downstream
+ * (correctly) passes it straight through, prefix and all.
+ *
+ * The value is same-origin by construction at this point, so collapse the leading slash run to a
+ * single slash. Linear scan rather than a regex, for the reason `stripTrailingSlashes` documents.
+ *
+ * Use this instead of calling `neutralizeImplicitOffOrigin` directly anywhere the result is going
+ * to be prefixed or emitted as a path.
+ */
+export declare function toSameOriginPath(url: string): string;
+/**
+ * Whether `url` is something a prefix cannot meaningfully be put in front of.
+ *
+ * Two kinds: **scheme-bearing** (`data:`, `blob:`, `mailto:`, `https://…`) and **literal
+ * protocol-relative** (`//cdn.example.com/x`). Neither is a site-relative path, so rooting or
+ * prefixing them only corrupts them (`data:image/png;…` → `/data:image/png;…`, a broken
+ * `<img src>`).
+ *
+ * NOTE this is deliberately NOT consulted by `joinUrlPrefix` for the scheme half. A URL-space
+ * mount point (`assetUrl`) wants scheme-bearing values handed back untouched; a site ORIGIN
+ * (`resolveSeoUrl`) does not - it must still produce an absolute URL, because a non-absolute
+ * sitemap `<loc>` invalidates the whole sitemap. Letting the two share one rule silently made
+ * `resolveSeoUrl('mailto:a@b.c', { siteUrl })` return `mailto:a@b.c` and drop the origin. Callers
+ * that want the pass-through opt in by checking this themselves.
+ */
+export declare function isUnprefixablePath(url: string): boolean;
+/**
+ * Make `url` safe to emit AS-IS, changing nothing else.
+ *
+ * For a caller with no mount point to apply, which must hand a value back byte-identical wherever
+ * it legitimately can: an `isUnprefixablePath` value passes straight through, and everything else
+ * goes through `toSameOriginPath`, so a value that merely *reads* as off-origin to a browser (the
+ * backslash spellings) is still neutralized rather than passed along.
+ */
+export declare function sanitizeUnprefixedPath(url: string): string;
+/**
+ * Put `prefix` in front of the root-relative `path`, and return `path` untouched when it is
+ * already a declared off-site URL.
+ *
+ * ORDER MATTERS — the absolute check on `path` runs FIRST. An absolute or protocol-relative
+ * value is a deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and
+ * must pass through verbatim; prefixing first turns `https://other.org/page` into
+ * `<prefix>/https://other.org/page`.
+ *
+ * `prefix` normalization, in order:
+ * - Empty/undefined, or nothing but slashes (`'/'`, `'///'`) → no prefix at all, so the result
+ *   stays root-relative. This is what makes an unset option a clean no-op. It also kills a
+ *   `'//'` prefix, which would otherwise concatenate to `//assets/…` — read by browsers as
+ *   protocol-relative, i.e. a request to a host literally named `assets`.
+ * - A declared off-site prefix (`https://cdn.example.com`, `//cdn.example.com`) is used as-is.
+ *   A literal protocol-relative prefix is an intentionally-supported off-site pointer here (see
+ *   `utils/sanitize-href.ts`), so it is NOT collapsed to a path.
+ * - Anything else is a same-origin path prefix and is given a leading slash if it lacks one.
+ *   Without this, a prefix like `preview-123` (the shape an env var often carries) produces a
+ *   *document-relative* URL that resolves to a different place on every page — an intermittent
+ *   failure that is harder to diagnose than the plain 404 it replaced.
+ *
+ * `path` is run through `toSameOriginPath` when it is not a pass-through, so a
+ * backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call "absolute"
+ * (see its doc) can't still be read by a browser as protocol-relative once emitted. Note this
+ * needs the `//`-pathname collapse, not just neutralization — see `toSameOriginPath`.
+ *
+ * `prefix` is NOT neutralized: it is adopter-supplied configuration rather than content, and
+ * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
+ */
+export declare function joinUrlPrefix(prefix: string | undefined, path: string): string;

package/dist/utils/url-prefix.js

@@ -0,0 +1,158 @@
+/**
+ * Joining a URL prefix onto a root-relative path, in ONE place.
+ *
+ * Two surfaces need the identical operation and had drifted into two implementations:
+ *
+ * - `static/seo.ts`'s `resolveSeoUrl` puts a site origin in front of an entry's URL path.
+ * - `assets/asset-url.ts`'s `assetUrl` puts an asset-space mount point in front of a stored
+ *   `/assets/…` src.
+ *
+ * The asset copy was the weaker one - it checked neither absoluteness of the path nor the shape
+ * of the prefix - so it silently produced `/prefix/https://cdn.example.com/x.png` for an
+ * off-site src, and a *document-relative* URL for a prefix that had no leading slash. Both bugs
+ * were already solved on the SEO side. Sharing one function is what stops a third caller from
+ * inheriting the weaker half again.
+ *
+ * Dependency-free apart from `./sanitize-href` (itself pure - its only dependency is the global
+ * `URL`), because this is reachable from client bundles via `assets/asset-url.ts`. Do not add a
+ * node built-in here; `pnpm lint:bundle` fails the build if you do.
+ */
+import { declaresScheme, neutralizeImplicitOffOrigin } from './sanitize-href.js';
+/**
+ * Whether `url` is a DECLARED off-site pointer - a scheme-qualified absolute URL
+ * (`https://example.com/x`) or a literal protocol-relative one (`//cdn.example.com/x`).
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. Callers handle that case
+ * separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export function isAbsoluteUrl(url) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('//');
+}
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. Both prefixes that reach here - a `siteUrl` and an asset `baseUrl` - are
+ * adopter-supplied and can come from config or an env var, so they count as uncontrolled. A
+ * character scan is linear and needs no reasoning about backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * Reduce a URL reference to a value that is safe to emit as a SAME-ORIGIN path.
+ *
+ * `neutralizeImplicitOffOrigin` alone is not sufficient, and this is the subtle part: it returns
+ * `pathname + search + hash`, and a WHATWG `pathname` can ITSELF begin with `//`. `/\evil.com//a`
+ * parses to host `evil.com` with pathname `//a`, so neutralizing yields the string `//a` — which,
+ * re-emitted as a URL reference, reads as protocol-relative all over again and points at a host
+ * literally named `a`. Neutralizing a second time does not help: the value is now indistinguishable
+ * from a caller's legitimate `//cdn.example.com` pointer, so every absolute-URL check downstream
+ * (correctly) passes it straight through, prefix and all.
+ *
+ * The value is same-origin by construction at this point, so collapse the leading slash run to a
+ * single slash. Linear scan rather than a regex, for the reason `stripTrailingSlashes` documents.
+ *
+ * Use this instead of calling `neutralizeImplicitOffOrigin` directly anywhere the result is going
+ * to be prefixed or emitted as a path.
+ */
+export function toSameOriginPath(url) {
+    const neutralized = neutralizeImplicitOffOrigin(url);
+    let slashes = 0;
+    while (slashes < neutralized.length && neutralized.charCodeAt(slashes) === 47 /* '/' */)
+        slashes++;
+    return slashes > 1 ? `/${neutralized.slice(slashes)}` : neutralized;
+}
+/**
+ * Whether `url` is something a prefix cannot meaningfully be put in front of.
+ *
+ * Two kinds: **scheme-bearing** (`data:`, `blob:`, `mailto:`, `https://…`) and **literal
+ * protocol-relative** (`//cdn.example.com/x`). Neither is a site-relative path, so rooting or
+ * prefixing them only corrupts them (`data:image/png;…` → `/data:image/png;…`, a broken
+ * `<img src>`).
+ *
+ * NOTE this is deliberately NOT consulted by `joinUrlPrefix` for the scheme half. A URL-space
+ * mount point (`assetUrl`) wants scheme-bearing values handed back untouched; a site ORIGIN
+ * (`resolveSeoUrl`) does not - it must still produce an absolute URL, because a non-absolute
+ * sitemap `<loc>` invalidates the whole sitemap. Letting the two share one rule silently made
+ * `resolveSeoUrl('mailto:a@b.c', { siteUrl })` return `mailto:a@b.c` and drop the origin. Callers
+ * that want the pass-through opt in by checking this themselves.
+ */
+export function isUnprefixablePath(url) {
+    return declaresScheme(url) || isAbsoluteUrl(url);
+}
+/**
+ * Make `url` safe to emit AS-IS, changing nothing else.
+ *
+ * For a caller with no mount point to apply, which must hand a value back byte-identical wherever
+ * it legitimately can: an `isUnprefixablePath` value passes straight through, and everything else
+ * goes through `toSameOriginPath`, so a value that merely *reads* as off-origin to a browser (the
+ * backslash spellings) is still neutralized rather than passed along.
+ */
+export function sanitizeUnprefixedPath(url) {
+    if (isUnprefixablePath(url))
+        return url;
+    return toSameOriginPath(url);
+}
+/**
+ * Put `prefix` in front of the root-relative `path`, and return `path` untouched when it is
+ * already a declared off-site URL.
+ *
+ * ORDER MATTERS — the absolute check on `path` runs FIRST. An absolute or protocol-relative
+ * value is a deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and
+ * must pass through verbatim; prefixing first turns `https://other.org/page` into
+ * `<prefix>/https://other.org/page`.
+ *
+ * `prefix` normalization, in order:
+ * - Empty/undefined, or nothing but slashes (`'/'`, `'///'`) → no prefix at all, so the result
+ *   stays root-relative. This is what makes an unset option a clean no-op. It also kills a
+ *   `'//'` prefix, which would otherwise concatenate to `//assets/…` — read by browsers as
+ *   protocol-relative, i.e. a request to a host literally named `assets`.
+ * - A declared off-site prefix (`https://cdn.example.com`, `//cdn.example.com`) is used as-is.
+ *   A literal protocol-relative prefix is an intentionally-supported off-site pointer here (see
+ *   `utils/sanitize-href.ts`), so it is NOT collapsed to a path.
+ * - Anything else is a same-origin path prefix and is given a leading slash if it lacks one.
+ *   Without this, a prefix like `preview-123` (the shape an env var often carries) produces a
+ *   *document-relative* URL that resolves to a different place on every page — an intermittent
+ *   failure that is harder to diagnose than the plain 404 it replaced.
+ *
+ * `path` is run through `toSameOriginPath` when it is not a pass-through, so a
+ * backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call "absolute"
+ * (see its doc) can't still be read by a browser as protocol-relative once emitted. Note this
+ * needs the `//`-pathname collapse, not just neutralization — see `toSameOriginPath`.
+ *
+ * `prefix` is NOT neutralized: it is adopter-supplied configuration rather than content, and
+ * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
+ */
+export function joinUrlPrefix(prefix, path) {
+    // Only a DECLARED off-site pointer passes through. A scheme-bearing but non-absolute value
+    // (`mailto:x`, `data:…`) is rooted, which is what a site origin needs - see
+    // `isUnprefixablePath` for why this deliberately differs from the asset-mount case.
+    if (isAbsoluteUrl(path))
+        return path;
+    const safePath = toSameOriginPath(path);
+    const normalizedPath = safePath.startsWith('/') ? safePath : `/${safePath}`;
+    if (!prefix)
+        return normalizedPath;
+    const trimmedPrefix = stripTrailingSlashes(prefix);
+    if (!trimmedPrefix)
+        return normalizedPath;
+    const normalizedPrefix = isAbsoluteUrl(trimmedPrefix) || trimmedPrefix.startsWith('/')
+        ? trimmedPrefix
+        : `/${trimmedPrefix}`;
+    return `${normalizedPrefix}${normalizedPath}`;
+}

package/dist/validation/block-structural-keys.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The keys a block item carries that are STRUCTURE rather than content.
+ *
+ * A block on disk is `{ template: 'hero', value: { ...fields } }` — the canonical shape the
+ * editor writes and `ContentStore` persists — or, defensively, the inline `{ _type: 'hero',
+ * ...fields }` shape (see `resolveBlockItem` in `./field-traversal`). Either way the
+ * discriminator names the block's TEMPLATE, which is a category label shared by every block of
+ * that kind, not an identifier for this particular block.
+ *
+ * That distinction matters to two callers for opposite-looking reasons, which is why the list
+ * lives here rather than in either of them:
+ *
+ * - `findUnknownKeys` (./entry-validator) must not report the discriminator as a stale key: it
+ *   is not a schema field, but it is supposed to be there.
+ * - `looksLikeSameItem` (../utils/content-serialize) must not accept the discriminator as
+ *   evidence that two list items are the same item: two `hero` blocks share `template: hero`,
+ *   so counting it migrated an editorial comment off a deleted block onto an unrelated
+ *   survivor.
+ *
+ * A single list keeps those two from drifting apart — a third discriminator added for one of
+ * them but not the other would resurrect exactly one of those bugs.
+ *
+ * Note that two other readers deliberately still spell the keys out themselves, because they
+ * READ the discriminator's value positionally rather than testing membership, and they do not
+ * agree on precedence: `resolveBlockItem` prefers `template`, while `ai/json-to-markdown.ts`
+ * prefers `_type`. Reconciling that is a behaviour question, not a refactor — see
+ * `.claude/future-tasks/block-discriminator-precedence-disagreement.md`.
+ *
+ * Dependency-free on purpose: both importers are reachable from contexts that must not pull in
+ * schema types or node built-ins.
+ */
+/**
+ * The discriminator keys, in the precedence `resolveBlockItem` reads them.
+ *
+ * Ordered (rather than a bare Set) so a caller that needs the VALUE can iterate it, and so the
+ * canonical shape's key stays visibly first.
+ */
+export declare const BLOCK_DISCRIMINATOR_KEYS: readonly ["template", "_type"];
+/** Membership form of {@link BLOCK_DISCRIMINATOR_KEYS}, for the two set-test callers. */
+export declare const BLOCK_STRUCTURAL_KEYS: ReadonlySet<string>;
+/** True for a key that names a block's template rather than holding any of its content. */
+export declare function isBlockStructuralKey(key: string): boolean;

package/dist/validation/block-structural-keys.js

@@ -0,0 +1,44 @@
+/**
+ * The keys a block item carries that are STRUCTURE rather than content.
+ *
+ * A block on disk is `{ template: 'hero', value: { ...fields } }` — the canonical shape the
+ * editor writes and `ContentStore` persists — or, defensively, the inline `{ _type: 'hero',
+ * ...fields }` shape (see `resolveBlockItem` in `./field-traversal`). Either way the
+ * discriminator names the block's TEMPLATE, which is a category label shared by every block of
+ * that kind, not an identifier for this particular block.
+ *
+ * That distinction matters to two callers for opposite-looking reasons, which is why the list
+ * lives here rather than in either of them:
+ *
+ * - `findUnknownKeys` (./entry-validator) must not report the discriminator as a stale key: it
+ *   is not a schema field, but it is supposed to be there.
+ * - `looksLikeSameItem` (../utils/content-serialize) must not accept the discriminator as
+ *   evidence that two list items are the same item: two `hero` blocks share `template: hero`,
+ *   so counting it migrated an editorial comment off a deleted block onto an unrelated
+ *   survivor.
+ *
+ * A single list keeps those two from drifting apart — a third discriminator added for one of
+ * them but not the other would resurrect exactly one of those bugs.
+ *
+ * Note that two other readers deliberately still spell the keys out themselves, because they
+ * READ the discriminator's value positionally rather than testing membership, and they do not
+ * agree on precedence: `resolveBlockItem` prefers `template`, while `ai/json-to-markdown.ts`
+ * prefers `_type`. Reconciling that is a behaviour question, not a refactor — see
+ * `.claude/future-tasks/block-discriminator-precedence-disagreement.md`.
+ *
+ * Dependency-free on purpose: both importers are reachable from contexts that must not pull in
+ * schema types or node built-ins.
+ */
+/**
+ * The discriminator keys, in the precedence `resolveBlockItem` reads them.
+ *
+ * Ordered (rather than a bare Set) so a caller that needs the VALUE can iterate it, and so the
+ * canonical shape's key stays visibly first.
+ */
+export const BLOCK_DISCRIMINATOR_KEYS = ['template', '_type'];
+/** Membership form of {@link BLOCK_DISCRIMINATOR_KEYS}, for the two set-test callers. */
+export const BLOCK_STRUCTURAL_KEYS = new Set(BLOCK_DISCRIMINATOR_KEYS);
+/** True for a key that names a block's template rather than holding any of its content. */
+export function isBlockStructuralKey(key) {
+    return BLOCK_STRUCTURAL_KEYS.has(key);
+}

package/dist/validation/deletion-checker.d.ts

@@ -1,7 +1,7 @@
-import type { ContentStore } from '../content-store';
-import type { ContentIdIndex } from '../content-id-index';
-import type { FieldConfig } from '../config';
-import { type LogicalPath, type Slug } from '../paths';
+import type { ContentStore } from '../content-store.js';
+import type { ContentIdIndex } from '../content-id-index.js';
+import type { FieldConfig } from '../config/index.js';
+import { type LogicalPath, type Slug } from '../paths/index.js';
 export interface ReferenceInfo {
     entryPath: string;
     entryTitle?: string;
@@ -63,4 +63,3 @@ export declare class DeletionChecker {
      */
     private listEntriesInCollection;
 }
-//# sourceMappingURL=deletion-checker.d.ts.map

package/dist/validation/deletion-checker.js

@@ -162,4 +162,3 @@ export class DeletionChecker {
         return entries;
     }
 }
-//# sourceMappingURL=deletion-checker.js.map

package/dist/validation/entry-link-validator.d.ts

@@ -6,8 +6,8 @@
  * This parallels ReferenceValidator but operates on inline links in text content
  * rather than structured reference fields.
  */
-import type { ContentIdIndex } from '../content-id-index';
-import type { FieldConfig } from '../config';
+import type { ContentIdIndex } from '../content-id-index.js';
+import type { FieldConfig } from '../config/index.js';
 export interface EntryLinkWarning {
     field: string;
     fieldPath: string;
@@ -24,4 +24,3 @@ export interface EntryLinkValidationResult {
  * and checks that each referenced ID exists in the content index.
  */
 export declare function validateEntryLinks(data: Record<string, unknown>, schema: readonly FieldConfig[], idIndex: ContentIdIndex, bodyContent?: string): EntryLinkValidationResult;
-//# sourceMappingURL=entry-link-validator.d.ts.map

package/dist/validation/entry-link-validator.js

@@ -46,4 +46,3 @@ function checkText(text, fieldName, fieldPath, idIndex, warnings) {
         }
     }
 }
-//# sourceMappingURL=entry-link-validator.js.map

package/dist/validation/entry-type-reference-validator.d.ts

@@ -13,7 +13,7 @@
  * at entry-schema *registration* (entry-schema-registry.ts), before any branch
  * schema exists, and so cannot perform this check.
  */
-import type { RootCollectionConfig } from '../config';
+import type { RootCollectionConfig } from '../config/index.js';
 /**
  * Collect every entry type name defined anywhere in the schema.
  *
@@ -30,4 +30,3 @@ export declare const collectEntryTypeNames: (schema: RootCollectionConfig) => Se
  * @returns One human-readable message per offending value; empty when valid.
  */
 export declare const validateReferenceEntryTypes: (schema: RootCollectionConfig) => string[];
-//# sourceMappingURL=entry-type-reference-validator.d.ts.map

package/dist/validation/entry-type-reference-validator.js

@@ -107,4 +107,3 @@ export const validateReferenceEntryTypes = (schema) => {
     });
     return issues;
 };
-//# sourceMappingURL=entry-type-reference-validator.js.map

package/dist/validation/entry-validator.d.ts

@@ -21,7 +21,7 @@
  * content ID index (filesystem) and is enforced server-side only, by running
  * `ReferenceValidator` at the write boundary.
  */
-import type { ContentFormat, EntrySchema } from '../config';
+import type { ContentFormat, EntrySchema } from '../config/index.js';
 /**
  * One per-field validation error. `fieldPath` uses the canonical CanopyCMS
  * path format shared with field-traversal and the editor's canopy-path
@@ -56,6 +56,28 @@ export declare function validateEntryData(fields: EntrySchema, data: Record<stri
  * schema's body field before validating so required/type checks see it.
  */
 export declare function validateEntryFormValue(fields: EntrySchema, format: ContentFormat | undefined, value: Record<string, unknown>): EntryFieldError[];
+/**
+ * Find data keys that have no counterpart in the schema, as canonical field paths
+ * (`author.nickname`, `blocks[2].headline`).
+ *
+ * `validateEntryData` iterates the SCHEMA, so it can only ever report fields the schema knows
+ * about. Nothing reported the inverse: rename or reshape a field and the old key persists on
+ * disk forever, because the editor's form state is the whole record verbatim and every save
+ * posts it back. The only symptom is a component quietly receiving `undefined`.
+ *
+ * Pure — safe in the browser. Reports rather than rejects: a save carrying a stale key still
+ * succeeds (and now the write path even preserves the key and its comments), so this feeds the
+ * non-blocking `validationWarnings` channel, not the 422 path.
+ *
+ * Two things it deliberately does not report:
+ *
+ * - **A container with no fields at all.** `api/content.ts` falls back to `[]` for a collection
+ *   with no configured entry type; "no schema" is not "every key is unknown".
+ * - **Anything inside a `reference` value.** Reads resolve references by default, so a reference
+ *   field's value is `{ ...target data, id, slug, collection, urlPath }`. The traversal only
+ *   descends into `object` and `block`, so it never looks inside one.
+ */
+export declare function findUnknownKeys(fields: EntrySchema, data: Record<string, unknown>): string[];
 /**
  * Return a copy of `data` with resolved reference objects (`{ id, ... }`)
  * collapsed back to their id strings, recursing through objects, lists, and
@@ -64,4 +86,3 @@ export declare function validateEntryFormValue(fields: EntrySchema, format: Cont
  * that may still carry resolved objects from a prior read.
  */
 export declare function normalizeReferenceValues(fields: EntrySchema, data: Record<string, unknown>): Record<string, unknown>;
-//# sourceMappingURL=entry-validator.d.ts.map