canopycms 0.0.67 → 0.0.68-int.94

package/dist/editor/components/NoEditPermissionNotice.js

@@ -0,0 +1,17 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Text } from '@mantine/core';
+/**
+ * Explains why an entry cannot be edited and whom to ask. An entry's `canEdit` is false only
+ * when a path rule (or `defaultPathAccess`) denies edit, so that is the reason it gives; a
+ * locked or protected branch shows its own banner in the header and a read-only form instead.
+ */
+export function NoEditPermissionNotice({ entryPath }) {
+    return (_jsx("div", { role: "status", "data-testid": "no-edit-permission-notice", style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100%',
+            padding: '0 var(--mantine-spacing-md)',
+            textAlign: 'center',
+        }, children: _jsxs(Text, { size: "sm", c: "dimmed", children: ["You don't have edit access to \"", entryPath, "\". Ask a CanopyCMS admin to grant it in Manage Permissions."] }) }));
+}

package/dist/editor/editor-utils.d.ts

@@ -9,29 +9,31 @@ export { normalizeCollectionPath };
 export interface PreviewContext {
     branchName?: string;
     previewBaseByCollection?: Record<string, string>;
+    /** `editor.previewPrefix`: where the host mounts the pages the preview pane loads. */
+    previewPrefix?: string;
 }
-/**
- * Builds the preview iframe `src` for an entry, prefixed with the deployment `basePath`
- * (`CanopyClientConfig.basePath`, e.g. `/preview-123`) when configured.
- *
- * This matters twice: the raw `<iframe src>` (`PreviewFrame` in preview-bridge.tsx) 404s
- * without the prefix under a basePath, and `resolvePreviewPath` there compares the same
- * string against `window.location.pathname` -- which browsers report WITH the basePath --
- * so an unprefixed `previewSrc` also breaks draft sync / click-to-focus even when the
- * iframe itself resolves.
- *
- * Applied via `joinUrlPrefix`: a no-op when `basePath` is unset, and passes an
- * already-absolute `previewSrc` (a cross-origin override) through untouched.
- */
-export declare const buildPreviewSrc: (entry: {
+type PreviewEntry = {
     collectionPath?: string;
     collectionName?: string;
     slug?: string;
     itemType?: string;
     previewSrc?: string;
-}, context: PreviewContext & {
+};
+/**
+ * Builds the preview iframe `src` for an entry: its route under `previewPrefix`, under the
+ * deployment `basePath` (`CanopyClientConfig.basePath`, e.g. `/preview-123`), in the host's
+ * trailing-slash form, with `?branch=`. An absolute prefix skips the `basePath`. An absolute route
+ * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
+ * `previewSrc` gets only the `basePath`.
+ *
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
+ * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
+ */
+export declare const buildPreviewSrc: (entry: PreviewEntry, context: PreviewContext & {
     contentRoot?: string;
     basePath?: string;
+    trailingSlash?: boolean;
 }) => string;
 export declare const normalizeContentPayload: (raw: unknown) => FormValue;
 export declare const buildWritePayload: (entry: {

package/dist/editor/editor-utils.js

@@ -2,7 +2,7 @@
 import { normalizeCollectionPath } from '../paths/normalize.js';
 import { isIndexSlug } from '../utils/entry-url.js';
 import { isDataOnlyFormat } from '../utils/format.js';
-import { joinUrlPrefix } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, joinUrlPrefix, matchTrailingSlash, readTrailingSlashEnv, stripTrailingSlashes, } from '../utils/url-prefix.js';
 /** @internal Exported for tests. */
 export { normalizeCollectionPath };
 /**
@@ -22,31 +22,34 @@ const encodeSlug = (value) => (value ?? '')
     .filter(Boolean)
     .map((segment) => encodeURIComponent(segment))
     .join('/');
+/** Splits `url` before its query or fragment, so a path can be extended without entering either. */
+const splitPathSuffix = (url) => {
+    const index = url.search(/[?#]/);
+    return index === -1 ? [url, ''] : [url.slice(0, index), url.slice(index)];
+};
+/** Adds `?branch=` to the query, ahead of any fragment. */
+const appendBranch = (url, branchName) => {
+    if (!branchName)
+        return url;
+    const hashIndex = url.indexOf('#');
+    const beforeHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const separator = beforeHash.includes('?') ? '&' : '?';
+    return `${beforeHash}${separator}branch=${encodeURIComponent(branchName)}${hash}`;
+};
 /**
- * Builds the (unprefixed) preview URL -- see `buildPreviewSrc` below, which wraps this with the
- * deployment `basePath`. Split out so that prefixing happens exactly once, at the end, uniformly
- * across every branch (including the `entry.previewSrc` escape hatch).
+ * The entry's route on the host site: its `previewBaseByCollection` value when one matches,
+ * otherwise its collection path plus slug. Site-relative unless a matching value is absolute.
  */
-const buildRawPreviewSrc = (entry, { branchName, previewBaseByCollection, contentRoot }) => {
-    if (entry.previewSrc)
-        return entry.previewSrc;
-    const appendBranch = (url) => {
-        if (!branchName)
-            return url;
-        const separator = url.includes('?') ? '&' : '?';
-        return `${url}${separator}branch=${encodeURIComponent(branchName)}`;
-    };
+const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot }) => {
     // Root-level entries have collectionPath === contentRoot (e.g., 'content')
     const isRootEntry = contentRoot && entry.collectionPath === contentRoot;
     if (isRootEntry) {
-        const customPreview = previewBaseByCollection?.[`${contentRoot}/${entry.slug}`];
-        if (customPreview) {
-            return appendBranch(customPreview);
-        }
-        return appendBranch('/');
+        return previewBaseByCollection?.[`${contentRoot}/${entry.slug}`] || '/';
     }
     const base = (entry.collectionPath && previewBaseByCollection?.[entry.collectionPath]) ??
         (entry.collectionName && previewBaseByCollection?.[entry.collectionName]);
+    const encoded = encodePreviewSlug(entry.slug);
     if (!base) {
         // Pass contentRoot through so a non-default (or multi-segment, e.g.
         // "cms/content") configured root is stripped too; normalizeCollectionPath
@@ -54,31 +57,35 @@ const buildRawPreviewSrc = (entry, { branchName, previewBaseByCollection, conten
         const collectionPath = entry.collectionPath
             ? normalizeCollectionPath(entry.collectionPath, contentRoot)
             : '';
-        const encoded = encodePreviewSlug(entry.slug);
         const segments = [collectionPath, encoded].filter(Boolean);
-        const url = segments.length > 0 ? `/${segments.join('/')}` : '/';
-        return appendBranch(url);
+        return segments.length > 0 ? `/${segments.join('/')}` : '/';
     }
-    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
-    const encoded = encodePreviewSlug(entry.slug);
-    const url = encoded ? `${trimmed}/${encoded}` : trimmed || '/';
-    return appendBranch(url);
+    const [basePathPart, suffix] = splitPathSuffix(base);
+    const trimmed = stripTrailingSlashes(basePathPart);
+    return `${encoded ? `${trimmed}/${encoded}` : basePathPart || '/'}${suffix}`;
 };
 /**
- * Builds the preview iframe `src` for an entry, prefixed with the deployment `basePath`
- * (`CanopyClientConfig.basePath`, e.g. `/preview-123`) when configured.
+ * Builds the preview iframe `src` for an entry: its route under `previewPrefix`, under the
+ * deployment `basePath` (`CanopyClientConfig.basePath`, e.g. `/preview-123`), in the host's
+ * trailing-slash form, with `?branch=`. An absolute prefix skips the `basePath`. An absolute route
+ * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
+ * `previewSrc` gets only the `basePath`.
  *
- * This matters twice: the raw `<iframe src>` (`PreviewFrame` in preview-bridge.tsx) 404s
- * without the prefix under a basePath, and `resolvePreviewPath` there compares the same
- * string against `window.location.pathname` -- which browsers report WITH the basePath --
- * so an unprefixed `previewSrc` also breaks draft sync / click-to-focus even when the
- * iframe itself resolves.
- *
- * Applied via `joinUrlPrefix`: a no-op when `basePath` is unset, and passes an
- * already-absolute `previewSrc` (a cross-origin override) through untouched.
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
+ * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
  */
 export const buildPreviewSrc = (entry, context) => {
-    return joinUrlPrefix(context.basePath, buildRawPreviewSrc(entry, context));
+    if (entry.previewSrc)
+        return joinUrlPrefix(context.basePath, entry.previewSrc);
+    const route = buildPreviewRoute(entry, context);
+    // An absolute route is another site's URL, so the host's trailing-slash form says nothing
+    // about it.
+    if (isAbsoluteUrl(route))
+        return appendBranch(route, context.branchName);
+    const mounted = joinUrlPrefix(context.basePath, joinUrlPrefix(context.previewPrefix, route));
+    const shaped = matchTrailingSlash(mounted, context.trailingSlash ?? readTrailingSlashEnv());
+    return appendBranch(shaped, context.branchName);
 };
 export const normalizeContentPayload = (raw) => {
     const candidate = raw;

package/dist/editor/hooks/useBranchesData.js

@@ -13,6 +13,7 @@
  * `mutate()` to revalidate.
  */
 import useSWR from 'swr';
+import { isNonApiResponse } from '../../api/client.js';
 /** Cache key for the branches list. */
 export const BRANCHES_KEY = 'canopy:branches';
 /**
@@ -21,9 +22,10 @@ export const BRANCHES_KEY = 'canopy:branches';
  */
 export async function fetchBranches(apiClient) {
     const result = await apiClient.branches.list();
-    if (result.status === 404) {
+    if (result.status === 404 && !isNonApiResponse(result)) {
         // No branch endpoint available; stay branchless rather than erroring --
         // the branch dropdown stays clickable so the user can retry from there.
+        // A proxy's 404 page means the API was not reached, so it is an error.
         return { branches: [] };
     }
     if (!result.ok) {

package/dist/editor/hooks/useCommentSystem.js

@@ -4,6 +4,7 @@ import { notifications } from '@mantine/notifications';
 import { normalizeCanopyPath } from '../canopy-path.js';
 import { useApiClient } from '../context/index.js';
 import { resolveMessageOrigin } from '../preview-bridge.js';
+import { isSamePreviewPath } from '../preview-path.js';
 import { commentsKey, fetchComments, useCommentsData } from './useCommentsData.js';
 /**
  * Custom hook for managing the comment system.
@@ -121,8 +122,11 @@ export function useCommentSystem(options) {
             const msg = event.data;
             if (msg?.type !== 'canopycms:preview:focus')
                 return;
+            const currentPath = options.currentEntry?.previewSrc ?? options.currentEntry?.path;
             if (msg.entryPath &&
-                msg.entryPath !== (options.currentEntry?.previewSrc ?? options.currentEntry?.path))
+                (typeof msg.entryPath !== 'string' ||
+                    currentPath === undefined ||
+                    !isSamePreviewPath(msg.entryPath, currentPath)))
                 return;
             const normalizedPath = msg.fieldPath ? normalizeCanopyPath(msg.fieldPath) : undefined;
             const target = normalizedPath

package/dist/editor/hooks/useDraftManager.d.ts

@@ -14,7 +14,7 @@ export interface UseDraftManagerOptions {
      * shown (useEntryManager's `getEntryVersion`). Stamps each draft with the
      * version it was based on, and detects at save time that the token has
      * since moved on. Optional: without it no base versions are recorded and
-     * conflict detection falls back entirely to the server's 409.
+     * conflict detection falls back entirely to saveEntry's token check.
      */
     getEntryVersion?: (contentId: string) => number | undefined;
     setBusy: (busy: boolean) => void;

package/dist/editor/hooks/useDraftManager.js

@@ -316,7 +316,8 @@ export function useDraftManager(options) {
             return 'ok';
         const currentVersion = options.getEntryVersion?.(currentId);
         // No server version known for this entry at all -- nothing to compare
-        // against, so this check has no opinion (the server's 409 still applies).
+        // against, so this check has no opinion: saveEntry refuses a save without
+        // a token, and the server refuses a version-less update.
         if (currentVersion === undefined)
             return 'ok';
         const base = draftBaseVersionsRef.current[currentId];

package/dist/editor/hooks/useEntriesData.js

@@ -40,7 +40,7 @@ export async function listAllEntries(apiClient, branch) {
             ...(cursor !== undefined ? { cursor } : {}),
         });
         if (!result.ok || !result.data)
-            throw new Error(`Refresh failed: ${result.status}`);
+            throw new Error(`Refresh failed: ${result.status}${result.error ? ` — ${result.error}` : ''}`);
         const data = result.data;
         for (const entry of data.entries)
             byPath.set(entry.logicalPath, entry);
@@ -60,7 +60,7 @@ export async function fetchEntriesAndSchema(apiClient, branch, params) {
     // Fetch schema from schema API
     const schemaResult = await apiClient.schema.get({ branch });
     if (!schemaResult.ok || !schemaResult.data) {
-        throw new Error(`Schema fetch failed: ${schemaResult.status}`);
+        throw new Error(`Schema fetch failed: ${schemaResult.status}${schemaResult.error ? ` — ${schemaResult.error}` : ''}`);
     }
     // Hydrate wire flatSchema: resolve schemaRef -> schema from entrySchemas dict
     const { entrySchemas } = schemaResult.data;

package/dist/editor/hooks/useEntryManager.js

@@ -50,11 +50,9 @@ export function useEntryManager(options) {
     // case -- any first visit to a branch, for the whole duration of its fetch),
     // or a stale SWR slot. The editor then auto-selected one of those stale
     // entries (see the selection effect below), and a save could file its OCC
-    // token under one contentId and look it up under another, silently skipping
-    // conflict detection -- `content-store.ts` only compares mtimes when
-    // `expectedVersion !== undefined`, so the write became a blind overwrite.
-    // Deriving from a stamped record fixes that structurally instead of relying
-    // on every code path remembering to clear.
+    // token under one contentId and look it up under another. Deriving from a
+    // stamped record fixes that structurally instead of relying on every code
+    // path remembering to clear.
     const [view, setView] = useState(() => ({
         branch: options.branchName,
         entries: options.initialEntries,
@@ -86,6 +84,9 @@ export function useEntryManager(options) {
     // branch can repopulate the map after the branch-change clear() below and
     // poison the next save with the old branch's mtime — a deterministic 409
     // ("modified by another editor") on save-after-switch, proven by e2e trace.
+    // The contentId half matches how useDraftManager keys drafts and loaded
+    // values, so a form value and its token always belong to the same file even
+    // when a path is deleted and recreated; it also survives a rename.
     const entryVersionsRef = useRef(new Map());
     const versionKey = (branch, contentId) => `${branch}:${contentId}`;
     // PER-BRANCH monotonic tokens guarding every commit of the fetched
@@ -192,7 +193,7 @@ export function useEntryManager(options) {
             path,
         });
         if (!result.ok)
-            throw new Error(`Load failed: ${result.status}`);
+            throw new Error(`Load failed: ${result.status}${result.error ? ` — ${result.error}` : ''}`);
         // Capture OCC version token for next save
         if (entry.contentId && typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
@@ -220,18 +221,23 @@ export function useEntryManager(options) {
         };
         if (entry.entryType)
             writeParams.entryType = entry.entryType;
-        const expectedVersion = entry.contentId
-            ? entryVersionsRef.current.get(versionKey(requestBranch, entry.contentId))
-            : undefined;
+        const expectedVersion = entryVersionsRef.current.get(versionKey(requestBranch, entry.contentId));
+        // Every entry saved here already exists (creates go through handleCreateModalSubmit), so
+        // no token means this entry was never successfully read on this branch and nothing could check the save
+        // against other editors' work. Refused as a conflict; the server refuses it too.
+        if (expectedVersion === undefined) {
+            throw new SaveApiError(409, 'This entry has not been loaded from the server, so the save cannot be checked ' +
+                "against other editors' changes. Reload it and try again.");
+        }
         const writeBody = {
             ...payload,
-            ...(expectedVersion !== undefined ? { expectedVersion } : {}),
+            expectedVersion,
         };
         const result = await apiClient.content.write(writeParams, writeBody);
         if (!result.ok)
             throw new SaveApiError(result.status, result.error, result.fieldErrors);
         // Update stored version token from write response
-        if (entry.contentId && typeof result.data?.version === 'number') {
+        if (typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
         }
         // Warning-level issues from the adopter's validateEntry hook: saved, but surface them

package/dist/editor/preview-bridge.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { formatCanopyPath } from './canopy-path.js';
+import { isSamePreviewPath } from './preview-path.js';
 export const __CANOPY_PREVIEW_CLIENT__ = true;
 export const CANOPY_PREVIEW_MESSAGE = 'canopycms:draft:update';
 export const CANOPY_PREVIEW_FOCUS = 'canopycms:preview:focus';
@@ -116,7 +117,9 @@ export const usePreviewData = (path, initialData, opts) => {
             if (!isTrustedEditorMessage(event, editorOrigin))
                 return;
             const msg = event.data;
-            if (!msg || msg.type !== CANOPY_PREVIEW_MESSAGE || msg.path !== path)
+            if (!msg || msg.type !== CANOPY_PREVIEW_MESSAGE)
+                return;
+            if (typeof msg.path !== 'string' || !isSamePreviewPath(msg.path, path))
                 return;
             setData(msg.data);
             if (msg.isLoading !== undefined) {

package/dist/editor/preview-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reduces a preview URL to what identifies the page, its path and query, with no origin,
+ * fragment or trailing slash. The editor names a page by the `src` it built and the framed page
+ * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
+ * spells the same page two ways, and the bridge must still match them.
+ * @internal Exported for tests.
+ */
+export declare const normalizePreviewPath: (url: string) => string;
+/** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
+export declare const isSamePreviewPath: (a: string, b: string) => boolean;

package/dist/editor/preview-path.js

@@ -0,0 +1,20 @@
+import { stripTrailingSlashes } from '../utils/url-prefix.js';
+/**
+ * Reduces a preview URL to what identifies the page, its path and query, with no origin,
+ * fragment or trailing slash. The editor names a page by the `src` it built and the framed page
+ * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
+ * spells the same page two ways, and the bridge must still match them.
+ * @internal Exported for tests.
+ */
+export const normalizePreviewPath = (url) => {
+    let parsed;
+    try {
+        parsed = new URL(url, 'http://preview.invalid');
+    }
+    catch {
+        return url;
+    }
+    return `${stripTrailingSlashes(parsed.pathname) || '/'}${parsed.search}`;
+};
+/** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
+export const isSamePreviewPath = (a, b) => normalizePreviewPath(a) === normalizePreviewPath(b);

package/dist/entry-schema-registry.d.ts

@@ -12,10 +12,10 @@ import type { EntrySchemaRegistry } from './schema/types.js';
  * interface to maintain. Keyed any other way, the derived map is keyed by that
  * string instead and will not plug into `TEntryTypes`.
  *
- * Rejected at call time: an empty registry; a schema that is not a non-empty
- * `EntrySchema` array; more than one `isTitle` per schema, or one on a non-string
- * field or inside a list; more than one `isBody`, or one on a field that is not
- * markdown/mdx or is named one of `RESOLVED_REFERENCE_KEYS`. This is also the one
+ * Rejected at call time: an empty registry; a schema that is not a non-empty `EntrySchema`
+ * array; more than one `isTitle` per schema, or one on a non-string field or inside a list;
+ * more than one `isBody`, or one on a field that is not markdown/mdx or is named one of
+ * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups
  * inside object/block fields, no field-name collisions after group flattening.

package/dist/entry-schema-registry.js

@@ -1,8 +1,8 @@
 import { countTitleFields, findInvalidTitleFields, findTitleFieldsInLists, } from './utils/title-field.js';
 import { countBodyFields, findInvalidBodyFields, findReservedBodyFieldName, } from './utils/body-field.js';
-import { RESOLVED_REFERENCE_KEYS } from './entry-schema.js';
+import { RESOLVED_REFERENCE_KEYS, RESTRICTED_REFERENCE_MARKER } from './entry-schema.js';
 import { flattenGroupFields } from './utils/flatten-group-fields.js';
-import { ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, } from './config/validation.js';
+import { ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, } from './config/validation.js';
 /** Look up a field's type by dotted path (e.g., "meta.order").
  * Groups are transparent — their children are searched at the same path level. */
 function findFieldType(fields, dottedPath) {
@@ -35,10 +35,10 @@ function findFieldType(fields, dottedPath) {
  * interface to maintain. Keyed any other way, the derived map is keyed by that
  * string instead and will not plug into `TEntryTypes`.
  *
- * Rejected at call time: an empty registry; a schema that is not a non-empty
- * `EntrySchema` array; more than one `isTitle` per schema, or one on a non-string
- * field or inside a list; more than one `isBody`, or one on a field that is not
- * markdown/mdx or is named one of `RESOLVED_REFERENCE_KEYS`. This is also the one
+ * Rejected at call time: an empty registry; a schema that is not a non-empty `EntrySchema`
+ * array; more than one `isTitle` per schema, or one on a non-string field or inside a list;
+ * more than one `isBody`, or one on a field that is not markdown/mdx or is named one of
+ * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups
  * inside object/block fields, no field-name collisions after group flattening.
@@ -92,8 +92,12 @@ export function createEntrySchemaRegistry(registry) {
         if (reservedBodyField) {
             throw new Error(`Entry schema registry entry "${key}": field "${reservedBodyField}" has isBody: true but "${reservedBodyField}" is reserved — reference resolution sets ${RESOLVED_REFERENCE_KEYS.map((k) => `"${k}"`).join(', ')} on a resolved reference, and a body field with one of those names would overwrite it. Rename the field (the body's field name is yours to choose; only these four are reserved).`);
         }
+        if (flattenGroupFields(schema).some((f) => f.name === RESTRICTED_REFERENCE_MARKER)) {
+            throw new Error(`Entry schema registry entry "${key}": field "${RESTRICTED_REFERENCE_MARKER}" is reserved — a resolved reference carries "${RESTRICTED_REFERENCE_MARKER}: true" only when the reader may not read its target, so a field with that name cannot be delivered on a reference to this entry type. Rename the field.`);
+        }
         ensureSelectFieldsHaveOptions(schema);
         ensureReferenceFieldsHaveScope(schema);
+        ensureItemTitleFieldsExist(schema);
         ensureNoGroupsInsideComplexFields(schema);
         ensureNoFlattenedFieldNameCollisions(schema, `entry schema "${key}"`);
     }

package/dist/entry-schema.d.ts

@@ -81,9 +81,6 @@ export interface ResolvedReferenceMeta {
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
  * embed it, then the reserved metadata.
  *
- * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
- *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
  * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
@@ -95,6 +92,30 @@ export declare function buildResolvedReference(data: Record<string, unknown>, me
     fieldName: string;
     value: string | undefined;
 }): Record<string, unknown>;
+/**
+ * The key that marks a `RestrictedReference`. Reserved as an entry field name, at the top level
+ * of any schema, because any schema can be a reference target.
+ */
+export declare const RESTRICTED_REFERENCE_MARKER = "unavailable";
+/**
+ * What a reference resolves to when the reader may not read its target: enough to render a
+ * link (a title and the URL, which a denied reader can follow to a sign-in page) and nothing
+ * else of the target's data.
+ *
+ * `unavailable: true` is the marker a renderer branches on, so a denied target never arrives
+ * looking like a full one with its fields `undefined`; `reason` says why, leaving room for
+ * other reasons a target cannot be shown. A reference the reader may see in full never carries
+ * `unavailable`. `id` is always present, so a save of the referring entry writes the reference
+ * back unchanged (`normalizeReferenceValues` recovers it from `value.id`).
+ */
+export type RestrictedReference = Simplify<ResolvedReferenceMeta & {
+    /** The target's display title, by `resolveEntryTitle`'s fallback chain. */
+    title: string;
+    unavailable: true;
+    reason: 'restricted';
+}>;
+/** Assemble a {@link RestrictedReference}. Takes no target data, so none can leak into it. */
+export declare function buildRestrictedReference(meta: ResolvedReferenceMeta, title: string): RestrictedReference;
 /**
  * Recursively flatten inline groups (type: 'group') out of a field tuple: they contribute
  * no key to the content shape, so their children merge into the parent level and
@@ -205,7 +226,9 @@ type FieldValue<F extends InferableField> = F extends {
 } ? ScalarValue<F, SelectValue<F>> : F extends {
     type: 'reference';
     resolvedSchema: infer S;
-} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta) | null> : F extends {
+} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta & {
+    unavailable?: undefined;
+}) | RestrictedReference | null> : F extends {
     type: 'reference';
 } ? ScalarValue<F, string | null> : F extends {
     type: 'image';

package/dist/entry-schema.js

@@ -14,9 +14,6 @@ export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
  * embed it, then the reserved metadata.
  *
- * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
- *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
  * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
@@ -35,8 +32,28 @@ export function buildResolvedReference(data, meta, body) {
     resolved.slug = meta.slug;
     resolved.collection = meta.collection;
     resolved.urlPath = meta.urlPath;
+    // Backstop for the registry's rejection of a field with this name (entry-schema-registry.ts):
+    // a full reference carrying the marker would read as one the reader may not see.
+    delete resolved[RESTRICTED_REFERENCE_MARKER];
     return resolved;
 }
+/**
+ * The key that marks a `RestrictedReference`. Reserved as an entry field name, at the top level
+ * of any schema, because any schema can be a reference target.
+ */
+export const RESTRICTED_REFERENCE_MARKER = 'unavailable';
+/** Assemble a {@link RestrictedReference}. Takes no target data, so none can leak into it. */
+export function buildRestrictedReference(meta, title) {
+    return {
+        id: meta.id,
+        slug: meta.slug,
+        collection: meta.collection,
+        urlPath: meta.urlPath,
+        title,
+        unavailable: true,
+        reason: 'restricted',
+    };
+}
 /** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export const defineEntrySchema = (fields) => fields;
 /**