canopycms 0.0.67 → 0.0.68-int.101

package/dist/editor/media/crop-math.js

@@ -6,13 +6,7 @@
  * (no react-easy-crop import) so it's trivially unit-testable and reusable
  * without pulling in the cropper UI library.
  */
-import { isValidCropRect } from '../../assets/transform-directives.js';
-/** Matches transform-directives.ts's CROP_PRECISION so a crop rect round-trips through the URL directive unchanged. */
-const CROP_PRECISION = 4;
-function roundTo(value, decimals) {
-    const factor = 10 ** decimals;
-    return Math.round(value * factor) / factor;
-}
+import { isValidCropRect, roundCropRect } from '../../assets/transform-directives.js';
 function clamp01(value) {
     if (!Number.isFinite(value))
         return 0;
@@ -20,26 +14,21 @@ function clamp01(value) {
 }
 /**
  * Convert react-easy-crop's `onCropComplete(croppedArea, croppedAreaPixels)`
- * percentage area into a normalized `CropRect`, rounded to 4 decimals and
- * clamped to fit within bounds. Rounding can push `x+w`/`y+h` a hair over 1
- * (e.g. x=0.6667, w=0.3334 -> 1.0001) - shrink the extent to the remaining
- * space rather than reject a rect that was valid before rounding.
+ * percentage area into a normalized `CropRect`, clamped to [0,1] and then
+ * rounded by `roundCropRect` — the same rounding the transform URL's canonical
+ * form applies, so the stored crop is already canonical.
  *
  * Returns `null` if the input can't be coerced into a valid rect (e.g. a
  * zero-area selection).
  */
 export function cropAreaPercentToRect(area) {
-    const x = roundTo(clamp01(area.x / 100), CROP_PRECISION);
-    const y = roundTo(clamp01(area.y / 100), CROP_PRECISION);
-    let w = roundTo(clamp01(area.width / 100), CROP_PRECISION);
-    let h = roundTo(clamp01(area.height / 100), CROP_PRECISION);
-    if (x + w > 1)
-        w = roundTo(1 - x, CROP_PRECISION);
-    if (y + h > 1)
-        h = roundTo(1 - y, CROP_PRECISION);
-    if (!isValidCropRect(x, y, w, h))
-        return null;
-    return { x, y, w, h };
+    const rect = roundCropRect({
+        x: clamp01(area.x / 100),
+        y: clamp01(area.y / 100),
+        w: clamp01(area.width / 100),
+        h: clamp01(area.height / 100),
+    });
+    return isValidCropRect(rect.x, rect.y, rect.w, rect.h) ? rect : null;
 }
 /**
  * Inverse of `cropAreaPercentToRect` - seeds react-easy-crop's

package/dist/editor/media/editor-image-src.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The URL the editor displays a content image at. A src in canopycms's own `/assets` space is put
+ * behind `baseUrl` (the authenticated raw route, see `AssetContext`); any other src - a site's own
+ * static file, an off-site URL, a `data:` URI - is shown exactly as written, because the raw route
+ * serves only the asset store.
+ */
+export declare function editorImageSrc(src: string, baseUrl: string): string;

package/dist/editor/media/editor-image-src.js

@@ -0,0 +1,12 @@
+import { assetUrl } from '../../assets/asset-url.js';
+import { ASSET_PREFIXES } from '../../assets/asset-prefixes.js';
+const ASSET_SPACE = `/${ASSET_PREFIXES.public}/`;
+/**
+ * The URL the editor displays a content image at. A src in canopycms's own `/assets` space is put
+ * behind `baseUrl` (the authenticated raw route, see `AssetContext`); any other src - a site's own
+ * static file, an off-site URL, a `data:` URI - is shown exactly as written, because the raw route
+ * serves only the asset store.
+ */
+export function editorImageSrc(src, baseUrl) {
+    return src.startsWith(ASSET_SPACE) ? assetUrl({ src }, { baseUrl }) : src;
+}

package/dist/editor/preview-asset-base.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The asset prefix a framing editor hands its live preview, held for `assets/asset-url.ts`. Its
+ * only writer outside tests is `usePreviewData`, on a trusted draft message; the read is gated on `window` too,
+ * because `assetUrl` also runs in server renders and static builds. Imports nothing.
+ */
+export declare function setPreviewAssetBase(base: string | undefined): void;
+/** The stored prefix in a browser; always `undefined` on the server. */
+export declare function getPreviewAssetBase(): string | undefined;

package/dist/editor/preview-asset-base.js

@@ -0,0 +1,13 @@
+/**
+ * The asset prefix a framing editor hands its live preview, held for `assets/asset-url.ts`. Its
+ * only writer outside tests is `usePreviewData`, on a trusted draft message; the read is gated on `window` too,
+ * because `assetUrl` also runs in server renders and static builds. Imports nothing.
+ */
+let previewAssetBase;
+export function setPreviewAssetBase(base) {
+    previewAssetBase = base;
+}
+/** The stored prefix in a browser; always `undefined` on the server. */
+export function getPreviewAssetBase() {
+    return typeof window === 'undefined' ? undefined : previewAssetBase;
+}

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

@@ -1,6 +1,4 @@
-import type { CSSProperties } from 'react';
 import { type CanopyPathSegment } from './canopy-path.js';
-export declare const __CANOPY_PREVIEW_CLIENT__ = true;
 export declare const CANOPY_PREVIEW_MESSAGE = "canopycms:draft:update";
 export declare const CANOPY_PREVIEW_FOCUS = "canopycms:preview:focus";
 export declare const CANOPY_PREVIEW_HIGHLIGHT = "canopycms:preview:highlight";
@@ -11,6 +9,8 @@ export interface DraftUpdateMessage {
     path: string;
     data?: unknown;
     isLoading?: unknown;
+    /** The editor's authenticated asset route; see `PreviewFrame`'s `assetBase`. */
+    assetBase?: unknown;
 }
 /**
  * Resolve a (possibly relative) URL to an origin for postMessage targeting.
@@ -18,6 +18,13 @@ export interface DraftUpdateMessage {
  * need no configuration.
  */
 export declare const resolveMessageOrigin: (url?: string) => string;
+/**
+ * Opaque origins (sandboxed iframes, data: URLs) serialize to the string 'null':
+ * never trust them for inbound messages, and never post to them — every window in
+ * a sandboxed embed shares that string, so it identifies nothing, and postMessage
+ * throws on a literal 'null' targetOrigin. '' covers the SSR fallback.
+ */
+export declare const isOpaqueOrigin: (origin: string) => boolean;
 /**
  * True only for messages from the embedding editor window with the expected origin.
  *
@@ -28,7 +35,6 @@ export declare const resolveMessageOrigin: (url?: string) => string;
  * expected editor origin (same-origin unless `editorOrigin` is configured).
  */
 export declare const isTrustedEditorMessage: (event: MessageEvent, editorOrigin?: string) => boolean;
-export declare const sendDraftUpdate: (iframe: HTMLIFrameElement | null, message: DraftUpdateMessage, targetOrigin?: string) => void;
 export interface PreviewFocusMessage {
     type: typeof CANOPY_PREVIEW_FOCUS;
     entryPath: string;
@@ -88,21 +94,3 @@ export declare const usePreviewHighlight: (opts?: {
 export declare const usePreviewFocusEmitter: (entryPath: string, opts?: {
     editorOrigin?: string;
 }) => void;
-/**
- * Lightweight iframe wrapper to keep the preview in sync with form state.
- * It posts the latest draft data to the iframe after load and when data changes.
- */
-export declare const PreviewFrame: ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, }: {
-    src: string;
-    path: string;
-    data?: unknown;
-    isLoading?: unknown;
-    className?: string;
-    style?: CSSProperties;
-    highlightEnabled?: boolean;
-    /** Called when the preview reports a draft compile/render error; null clears it. */
-    onPreviewError?: (error: {
-        message: string;
-        fieldPath?: string;
-    } | null) => void;
-}) => import("react/jsx-runtime").JSX.Element;

package/dist/editor/preview-bridge.js

@@ -1,13 +1,23 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * The preview bridge's protocol and its host-page side: the hooks a framed page runs. Served to
+ * hosts through `canopycms/preview`, so everything it reaches stays free of CSS and editor UI
+ * (`pnpm lint:bundle`); the editor's side is `PreviewFrame.tsx`.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { toSameOriginPath } from '../utils/url-prefix.js';
 import { formatCanopyPath } from './canopy-path.js';
-export const __CANOPY_PREVIEW_CLIENT__ = true;
+import { setPreviewAssetBase } from './preview-asset-base.js';
+import { isSamePreviewPath } from './preview-path.js';
 export const CANOPY_PREVIEW_MESSAGE = 'canopycms:draft:update';
 export const CANOPY_PREVIEW_FOCUS = 'canopycms:preview:focus';
 export const CANOPY_PREVIEW_HIGHLIGHT = 'canopycms:preview:highlight';
 export const CANOPY_PREVIEW_READY = 'canopycms:preview:ready';
 export const CANOPY_PREVIEW_ERROR = 'canopycms:preview:error';
+/** `assetBase` from a draft, only if it is a same-origin path: nothing else may steer `<img>`s. */
+const readAssetBase = (value) => typeof value === 'string' && value.startsWith('/') && toSameOriginPath(value) === value
+    ? value
+    : undefined;
 /**
  * Resolve a (possibly relative) URL to an origin for postMessage targeting.
  * Falls back to the page's own origin, so same-origin editor/preview setups
@@ -31,7 +41,7 @@ export const resolveMessageOrigin = (url) => {
  * a sandboxed embed shares that string, so it identifies nothing, and postMessage
  * throws on a literal 'null' targetOrigin. '' covers the SSR fallback.
  */
-const isOpaqueOrigin = (origin) => origin === 'null' || origin === '';
+export const isOpaqueOrigin = (origin) => origin === 'null' || origin === '';
 /**
  * True only for messages from the embedding editor window with the expected origin.
  *
@@ -49,14 +59,6 @@ export const isTrustedEditorMessage = (event, editorOrigin) => {
         return false;
     return event.origin === expected && event.source === window.parent;
 };
-export const sendDraftUpdate = (iframe, message, targetOrigin) => {
-    if (!iframe?.contentWindow)
-        return;
-    const target = targetOrigin ?? resolveMessageOrigin(iframe.src);
-    if (isOpaqueOrigin(target))
-        return;
-    iframe.contentWindow.postMessage(message, target);
-};
 const resolvePreviewPath = (explicit) => {
     if (explicit)
         return explicit;
@@ -116,8 +118,12 @@ 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;
+            // Before setData, so the render the draft triggers already reads it.
+            setPreviewAssetBase(readAssetBase(msg.assetBase));
             setData(msg.data);
             if (msg.isLoading !== undefined) {
                 setIsLoading(msg.isLoading);
@@ -204,129 +210,3 @@ export const usePreviewFocusEmitter = (entryPath, opts) => {
         return () => document.removeEventListener('click', handleClick);
     }, [entryPath, editorOrigin]);
 };
-/**
- * Lightweight iframe wrapper to keep the preview in sync with form state.
- * It posts the latest draft data to the iframe after load and when data changes.
- */
-export const PreviewFrame = ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, }) => {
-    const iframeRef = useRef(null);
-    // Pin the preview origin from the src prop: outbound messages target it (never '*'),
-    // and inbound messages must come from it. An iframe that navigates cross-origin
-    // silently stops participating in the bridge.
-    const previewOrigin = resolveMessageOrigin(src);
-    // Show progress bar while waiting for the preview's ready handshake.
-    const [syncPending, setSyncPending] = useState(data !== undefined);
-    // Reset when navigating to a different entry (src change = new iframe page load).
-    const [prevSrc, setPrevSrc] = useState(src);
-    if (src !== prevSrc) {
-        setPrevSrc(src);
-        setSyncPending(data !== undefined);
-    }
-    // Inject the progress bar keyframe animation once per page.
-    useEffect(() => {
-        const styleId = 'canopycms-preview-sync-style';
-        if (!document.getElementById(styleId)) {
-            const el = document.createElement('style');
-            el.id = styleId;
-            el.textContent = `@keyframes canopy-preview-sync { 0% { transform: translateX(-100%); } 100% { transform: translateX(250%); } }`;
-            document.head.appendChild(el);
-        }
-    }, []);
-    const post = () => {
-        if (data === undefined)
-            return;
-        sendDraftUpdate(iframeRef.current, {
-            type: CANOPY_PREVIEW_MESSAGE,
-            path,
-            data,
-            isLoading,
-        }, previewOrigin);
-    };
-    const postHighlight = () => {
-        if (!iframeRef.current?.contentWindow)
-            return;
-        if (isOpaqueOrigin(previewOrigin))
-            return;
-        const msg = {
-            type: CANOPY_PREVIEW_HIGHLIGHT,
-            enabled: Boolean(highlightEnabled),
-        };
-        iframeRef.current.contentWindow.postMessage(msg, previewOrigin);
-    };
-    // Keep refs pointing at the latest closures so the message handler below never goes stale.
-    const postRef = useRef(post);
-    const postHighlightRef = useRef(postHighlight);
-    const onPreviewErrorRef = useRef(onPreviewError);
-    useEffect(() => {
-        postRef.current = post;
-        postHighlightRef.current = postHighlight;
-        onPreviewErrorRef.current = onPreviewError;
-    });
-    useEffect(() => {
-        post();
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- post is tracked via ref
-    }, [data, isLoading]);
-    useEffect(() => {
-        postHighlight();
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- postHighlight is tracked via ref
-    }, [highlightEnabled]);
-    // When the preview page's React effects have run and its message listener is ready,
-    // it sends CANOPY_PREVIEW_READY. We respond with the current data so the preview
-    // receives the draft even if it wasn't ready when onLoad fired.
-    useEffect(() => {
-        const handleMessage = (event) => {
-            if (!iframeRef.current || event.source !== iframeRef.current.contentWindow)
-                return;
-            // Source check alone is insufficient if the iframe navigated cross-origin.
-            if (isOpaqueOrigin(previewOrigin) || event.origin !== previewOrigin)
-                return;
-            const type = event.data?.type;
-            if (type === CANOPY_PREVIEW_READY) {
-                postRef.current();
-                postHighlightRef.current();
-                setSyncPending(false);
-            }
-            else if (type === CANOPY_PREVIEW_ERROR) {
-                const msg = event.data;
-                // Shape-check the payload: an adopter passing an Error object (instead of
-                // err.message) must not crash the editor when rendered as a React child.
-                if (msg.message != null && typeof msg.message !== 'string')
-                    return;
-                const fieldPath = typeof msg.fieldPath === 'string' ? msg.fieldPath : undefined;
-                onPreviewErrorRef.current?.(msg.message == null
-                    ? null
-                    : { message: msg.message, ...(fieldPath ? { fieldPath } : {}) });
-            }
-        };
-        window.addEventListener('message', handleMessage);
-        return () => window.removeEventListener('message', handleMessage);
-    }, [previewOrigin]);
-    return (_jsxs("div", { className: className, style: { position: 'relative', overflow: 'hidden', ...style }, children: [syncPending && (_jsx("div", { style: {
-                    position: 'absolute',
-                    top: 0,
-                    left: 0,
-                    right: 0,
-                    height: 3,
-                    zIndex: 1,
-                    overflow: 'hidden',
-                }, children: _jsx("div", { style: {
-                        position: 'absolute',
-                        top: 0,
-                        left: 0,
-                        height: '100%',
-                        width: '40%',
-                        background: 'var(--mantine-color-blue-filled, #228be6)',
-                        borderRadius: '0 2px 2px 0',
-                        animation: 'canopy-preview-sync 1.5s ease-in-out infinite',
-                    } }) })), _jsx("iframe", { ref: iframeRef, src: src, style: {
-                    display: 'block',
-                    position: 'absolute',
-                    inset: 0,
-                    width: '100%',
-                    height: '100%',
-                    border: 'none',
-                }, onLoad: () => {
-                    post();
-                    postHighlight();
-                } })] }));
-};

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/editor/theme.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { DEFAULT_THEME, MantineProvider, createTheme, } from '@mantine/core';
+import { DEFAULT_THEME, MantineProvider, getDefaultZIndex, createTheme, } from '@mantine/core';
 import { Notifications } from '@mantine/notifications';
 import { ModalsProvider } from '@mantine/modals';
 import { generateColors } from '@mantine/colors-generator';
@@ -62,5 +62,5 @@ export const createCanopyTheme = (options) => {
 };
 export const CanopyCMSProvider = ({ children, colors, colorScheme = 'light', themeOverride, withNotifications = true, }) => {
     const theme = useMemo(() => createCanopyTheme({ colors, themeOverride }), [colors, themeOverride]);
-    return (_jsx(MantineProvider, { theme: theme, defaultColorScheme: colorScheme, children: _jsxs(ModalsProvider, { children: [withNotifications ? _jsx(Notifications, { position: "bottom-left" }) : null, children] }) }));
+    return (_jsx(MantineProvider, { theme: theme, defaultColorScheme: colorScheme, children: _jsxs(ModalsProvider, { modalProps: { zIndex: getDefaultZIndex('popover') }, children: [withNotifications ? _jsx(Notifications, { position: "bottom-left" }) : null, children] }) }));
 };

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;
 /**