canopycms 0.1.0 → 0.2.0-int.121

package/dist/editor/media/MediaLibraryBody.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { ActionIcon, Alert, Button, Center, Group, Progress, ScrollArea, SegmentedControl, Select, SimpleGrid, Stack, Text, TextInput, Tooltip, VisuallyHidden, } from '@mantine/core';
+import { ActionIcon, Alert, Button, Center, Group, Progress, ScrollArea, SegmentedControl, Select, SimpleGrid, Stack, Switch, Text, TextInput, Tooltip, VisuallyHidden, } from '@mantine/core';
 import { Dropzone } from '@mantine/dropzone';
 import { openConfirm } from '../utils/confirm-modal.js';
 import { IconAlertCircle, IconGridDots, IconLayoutGrid, IconList, IconSearch, IconUpload, IconX, } from '@tabler/icons-react';
@@ -42,8 +42,14 @@ const DENSITY_OPTIONS = [
     },
     { value: 'list', label: _jsx(DensityLabel, { icon: _jsx(IconList, { size: 16 }), text: "List" }) },
 ];
+/** A restored file's record: the same asset, no longer marked `hidden`. */
+function withoutHidden(asset) {
+    const restored = { ...asset };
+    delete restored.hidden;
+    return restored;
+}
 /**
- * Shared grid/list/upload/search/delete core for both MediaLibrary
+ * Shared grid/list/upload/search/remove core for both MediaLibrary
  * presentations (Drawer "manage" mode, Modal "picker" mode) - see
  * MediaLibrary.tsx for the two wrappers.
  */
@@ -51,40 +57,49 @@ export const MediaLibraryBody = ({ opened, mode, onSelect }) => {
     const client = useApiClient();
     const { baseUrl } = useAssetContext();
     const { userContext } = useUserContext();
-    // Mirrors the server's rule in api/assets.ts's deleteAssetHandler: an admin
-    // may delete anything, anyone else only what they uploaded. Kept per-asset
+    const admin = isAdmin(userContext?.groups);
+    // Mirrors the server's rule in api/assets.ts's visibilityRefusal: an admin may
+    // remove or restore any file, anyone else only what they uploaded. Kept per-asset
     // (not a single boolean) because ownership varies row by row. The server is
     // still the authority - this only decides whether to render the control.
-    const canDeleteAsset = (asset) => {
+    const canChangeVisibility = (asset) => {
         if (mode !== 'manage')
             return false;
-        if (isAdmin(userContext?.groups))
+        if (admin)
             return true;
         return !!asset.uploadedBy && asset.uploadedBy === userContext?.userId;
     };
+    // Only an admin in the manage drawer can list removed files, so a picker never offers one.
+    const [showRemovedChoice, setShowRemoved] = useState(false);
+    const showRemoved = showRemovedChoice && admin && mode === 'manage';
     const upload = useAssetUpload();
     // `picker` mode is used exclusively by ImageField and the MDX image dialog
     // (see MediaLibraryProps.mode's doc comment) - both image-only contexts.
     // `manage` mode (the Editor's Media Library drawer) keeps accepting PDFs.
     const imageOnly = mode === 'picker';
-    const library = useAssetLibrary(opened);
+    const library = useAssetLibrary(opened, showRemoved);
     const { sort, density, setSort, setDensity } = useMediaLibraryPrefs();
     const [kind, setKind] = useState('all');
     const [filterText, setFilterText] = useState('');
     const [actionError, setActionError] = useState(null);
-    // The result of the last remove, for the live region; the removed card itself is gone.
-    // `id` re-keys the region's text, so a second remove with the same words is announced too.
+    // The result of the last remove or restore, for the live region; the card may be gone.
+    // `id` re-keys the region's text, so a second action with the same words is announced too.
     const [actionNotice, setActionNotice] = useState(null);
     const searchRef = useRef(null);
-    // A removed card takes its focused button with it, so focus moves to the search field once the
-    // removal has rendered (Mantine returns focus to the trash button when the confirm closes).
-    const focusAfterRemove = useRef(false);
+    // A remove or restore takes the focused button with it (the card goes, or its button swaps), so
+    // focus moves to the search field once that has rendered (Mantine returns focus to the remove
+    // button when the confirm closes).
+    const focusAfterAction = useRef(false);
     useEffect(() => {
-        if (!focusAfterRemove.current)
+        if (!focusAfterAction.current)
             return;
-        focusAfterRemove.current = false;
+        focusAfterAction.current = false;
         searchRef.current?.focus();
     });
+    const announce = (text) => {
+        setActionNotice((prev) => ({ id: (prev?.id ?? 0) + 1, text }));
+        focusAfterAction.current = true;
+    };
     // Clearing hides the control that did it, so focus moves to the search field.
     const clearSearch = () => {
         setFilterText('');
@@ -142,39 +157,52 @@ export const MediaLibraryBody = ({ opened, mode, onSelect }) => {
     const handleReject = (rejections) => {
         setActionError(rejections[0]?.errors[0]?.message ?? 'The file was rejected.');
     };
-    const handleDelete = async (asset) => {
+    /**
+     * Runs a remove or restore; `failure` words its error, and the raw server message is for admins.
+     * A non-admin's 403 from the API is the ownership refusal, so it says so (`refusal`) rather than
+     * to retry. Restore shows only to admins, so it has none.
+     */
+    const changeVisibility = async (request, failure, refusal, onDone) => {
         setActionError(null);
-        const failure = (detail) => `Couldn't remove ${asset.filename} from the library. ${detail}`;
-        // The raw server message is a diagnostic, shown to admins only.
-        const generic = (serverMessage) => failure((isAdmin(userContext?.groups) && serverMessage) || 'Try again.');
+        const fail = (serverMessage) => setActionError(`${failure} ${(admin && serverMessage) || 'Try again.'}`);
         try {
-            const result = await client.assets.delete({ key: asset.hash32 });
+            const result = await request();
             if (!result.ok) {
-                // An editor sees this button only for their own upload, and the endpoint answers a
-                // missing file with the same 403 as someone else's, so their 403 means it is gone.
-                const alreadyGone = result.status === 403 && !isNonApiResponse(result) && !isAdmin(userContext?.groups);
-                setActionError(alreadyGone ? failure('It may have been removed already.') : generic(result.error));
+                if (refusal && result.status === 403 && !admin && !isNonApiResponse(result)) {
+                    setActionError(`${failure} ${refusal}`);
+                }
+                else {
+                    fail(result.error);
+                }
                 return;
             }
-            library.remove(asset.hash32);
-            setActionNotice((prev) => ({
-                id: (prev?.id ?? 0) + 1,
-                text: `Removed ${asset.filename} from library`,
-            }));
-            focusAfterRemove.current = true;
+            onDone();
         }
         catch (err) {
-            setActionError(generic(getErrorMessage(err)));
+            fail(getErrorMessage(err));
         }
     };
-    const handleDeleteClick = (asset) => {
+    const handleRemove = (asset) => changeVisibility(() => client.assets.hide({ key: asset.hash32 }), `Couldn't remove ${asset.filename} from the library.`, 'You can only remove files you uploaded. Ask an admin to remove it.', () => {
+        if (showRemoved)
+            library.replace({ ...asset, hidden: true });
+        else
+            library.remove(asset.hash32);
+        announce(`Removed ${asset.filename} from library`);
+    });
+    const handleRestore = (asset) => changeVisibility(() => client.assets.restore({ key: asset.hash32 }), `Couldn't restore ${asset.filename} to the library.`, null, () => {
+        library.replace(withoutHidden(asset));
+        announce(`Restored ${asset.filename} to library`);
+    });
+    // A confirm, not an Undo: only an admin can restore, from the "Show removed files" view.
+    const handleRemoveClick = (asset) => {
         openConfirm({
             title: 'Remove from library',
-            children: (_jsxs(Text, { size: "sm", children: ["Remove \u201C", asset.filename, "\u201D from the media library? Content that already uses this file keeps working, and the file itself is not deleted."] })),
+            children: (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", children: ["\u201C", asset.filename, "\u201D will no longer be listed in the media library or offered when choosing an image. Entries that already use it keep working, including published and earlier versions of the site."] }), _jsx(Text, { size: "sm", children: admin
+                            ? 'To restore it, turn on “Show removed files”, or upload it again.'
+                            : 'To restore it, upload it again or ask an admin.' })] })),
             labels: { confirm: 'Remove from library', cancel: 'Cancel' },
-            confirmProps: { color: 'red' },
             onConfirm: () => {
-                void handleDelete(asset);
+                void handleRemove(asset);
             },
         });
     };
@@ -228,9 +256,9 @@ export const MediaLibraryBody = ({ opened, mode, onSelect }) => {
     })();
     const renderList = () => {
         if (density === 'list') {
-            return (_jsx(Stack, { gap: 4, children: visibleAssets.map((asset) => (_jsx(AssetListRow, { asset: asset, baseUrl: baseUrl, onSelect: mode === 'picker' ? onSelect : undefined, onDelete: canDeleteAsset(asset) ? () => handleDeleteClick(asset) : undefined }, asset.hash32))) }));
+            return (_jsx(Stack, { gap: 4, children: visibleAssets.map((asset) => (_jsx(AssetListRow, { asset: asset, baseUrl: baseUrl, onSelect: mode === 'picker' ? onSelect : undefined, onRemove: canChangeVisibility(asset) ? handleRemoveClick : undefined, onRestore: canChangeVisibility(asset) ? handleRestore : undefined }, asset.hash32))) }));
         }
-        return (_jsx(SimpleGrid, { cols: GRID_COLUMNS[density], spacing: "sm", children: visibleAssets.map((asset) => (_jsx(AssetCard, { asset: asset, baseUrl: baseUrl, density: density, onSelect: mode === 'picker' ? onSelect : undefined, onDelete: canDeleteAsset(asset) ? () => handleDeleteClick(asset) : undefined }, asset.hash32))) }));
+        return (_jsx(SimpleGrid, { cols: GRID_COLUMNS[density], spacing: "sm", children: visibleAssets.map((asset) => (_jsx(AssetCard, { asset: asset, baseUrl: baseUrl, density: density, onSelect: mode === 'picker' ? onSelect : undefined, onRemove: canChangeVisibility(asset) ? handleRemoveClick : undefined, onRestore: canChangeVisibility(asset) ? handleRestore : undefined }, asset.hash32))) }));
     };
     const listContent = (_jsxs(_Fragment, { children: [!library.firstPageLoaded && !library.error && visibleAssets.length === 0 && (_jsx(MediaLibrarySkeleton, { density: density })), visibleAssets.length > 0 && renderList(), emptyState && (_jsxs(Stack, { align: "center", gap: "xs", py: "xl", "data-testid": "media-library-empty", children: [_jsx(Text, { size: "sm", c: "dimmed", ta: "center", children: emptyState }), _jsxs(Group, { gap: "xs", justify: "center", children: [needle && (_jsx(Button, { variant: "light", size: "xs", onClick: clearSearch, children: "Clear search" })), kind !== 'all' && !libraryEmpty && (_jsx(Button, { variant: "light", size: "xs", onClick: () => setKind('all'), children: "Show all files" }))] })] })), hasMore && (_jsxs(_Fragment, { children: [_jsx("div", { ref: setSentinel, "aria-hidden": "true", style: { height: 1 } }), _jsx(Group, { justify: "center", py: "sm", children: _jsx(Button, { variant: "light", onClick: showMore, "data-testid": "media-library-show-more", children: "Show more" }) })] }))] }));
     return (
@@ -242,7 +270,7 @@ export const MediaLibraryBody = ({ opened, mode, onSelect }) => {
                 (upload.progress !== null ? (_jsx(Progress, { value: upload.progress * 100, size: "sm", "data-testid": "upload-progress" })) : (_jsx(Progress, { value: 100, size: "sm", animated: true, "data-testid": "upload-progress-indeterminate" }))), upload.error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", "data-testid": "upload-error", children: upload.error })), _jsx(TextInput, { placeholder: "Search by filename", "aria-label": "Search by filename", leftSection: _jsx(IconSearch, { size: 16 }), rightSection: filterText ? (_jsx(Tooltip, { label: "Clear search", children: _jsx(ActionIcon, { variant: "subtle", color: "gray", size: "sm", "aria-label": "Clear search", onClick: clearSearch, children: _jsx(IconX, { size: 14 }) }) })) : null, ref: searchRef, value: filterText, onChange: (event) => setFilterText(event.currentTarget.value), "data-mantine-stop-propagation": filterText ? 'true' : undefined, onKeyDown: (event) => {
                     if (event.key === 'Escape' && filterText)
                         setFilterText('');
-                }, "data-testid": "media-library-filter" }), _jsxs(Group, { justify: "space-between", wrap: "wrap", gap: "xs", children: [imageOnly ? (_jsx("span", {})) : (_jsx(SegmentedControl, { "aria-label": "File type", data: KIND_OPTIONS, value: kind, onChange: (value) => setKind(KIND_OPTIONS.find((o) => o.value === value)?.value ?? 'all'), "data-testid": "media-library-kind" })), _jsxs(Group, { gap: "xs", wrap: "wrap", children: [_jsx(Select, { "aria-label": "Sort by", data: SORT_OPTIONS, value: sort, onChange: (value) => {
+                }, "data-testid": "media-library-filter" }), _jsxs(Group, { justify: "space-between", wrap: "wrap", gap: "xs", children: [imageOnly ? (_jsx("span", {})) : (_jsxs(Group, { gap: "md", wrap: "wrap", children: [_jsx(SegmentedControl, { "aria-label": "File type", data: KIND_OPTIONS, value: kind, onChange: (value) => setKind(KIND_OPTIONS.find((o) => o.value === value)?.value ?? 'all'), "data-testid": "media-library-kind" }), admin && mode === 'manage' && (_jsx(Switch, { label: "Show removed files", checked: showRemoved, onChange: (event) => setShowRemoved(event.currentTarget.checked), "data-testid": "media-library-show-removed" }))] })), _jsxs(Group, { gap: "xs", wrap: "wrap", children: [_jsx(Select, { "aria-label": "Sort by", data: SORT_OPTIONS, value: sort, onChange: (value) => {
                                     const next = SORT_OPTIONS.find((option) => option.value === value);
                                     if (next)
                                         setSort(next.value);

package/dist/editor/media/crop-availability.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Why `src` can't be cropped, as the full sentence its disabled Crop button shows; `undefined`
+ * when it can. A crop is a directive on a transform URL, which `assetUrl` writes only for a raster
+ * in the asset store, so a vector file or a file outside the store never renders one.
+ */
+export declare function cropBlockedReason(src: string): string | undefined;

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

@@ -0,0 +1,19 @@
+import { ASSET_PREFIXES } from '../../assets/asset-prefixes.js';
+import { isAssetStoreSrc } from '../../assets/asset-url.js';
+const TRANSFORM_SPACE_PREFIX = `/${ASSET_PREFIXES.transform}/`;
+/**
+ * Why `src` can't be cropped, as the full sentence its disabled Crop button shows; `undefined`
+ * when it can. A crop is a directive on a transform URL, which `assetUrl` writes only for a raster
+ * in the asset store, so a vector file or a file outside the store never renders one.
+ */
+export function cropBlockedReason(src) {
+    const path = src.split(/[?#]/)[0] ?? src;
+    if (/\.svg$/i.test(path))
+        return "SVG images can't be cropped. Replace it with a PNG or JPEG to crop it.";
+    if (!isAssetStoreSrc(src)) {
+        return 'Crop works on media-library images. Replace this file with a library copy to crop it.';
+    }
+    if (!src.startsWith(TRANSFORM_SPACE_PREFIX))
+        return "This file type can't be cropped. Replace it with a PNG or JPEG to crop it.";
+    return undefined;
+}

package/dist/editor/media/crop-math.d.ts

@@ -1,13 +1,13 @@
 /**
- * Pure math for the ImageField crop step: converting between react-easy-crop's
- * percentage-based `Area` shape and CanopyCMS's normalized 0..1 `CropRect`
+ * Pure math for the ImageField crop step: converting between react-image-crop's
+ * percentage-based crop shape and CanopyCMS's normalized 0..1 `CropRect`
  * (the same shape stored in `ImageFieldValue.crop` and accepted by the `c=`
  * transform directive - see assets/transform-directives.ts). Kept dependency-free
- * (no react-easy-crop import) so it's trivially unit-testable and reusable
+ * (no react-image-crop import) so it's trivially unit-testable and reusable
  * without pulling in the cropper UI library.
  */
 import { type CropRect } from '../../assets/transform-directives.js';
-/** react-easy-crop's `Area` shape, expressed in percentages (0..100). */
+/** A crop box in percentages (0..100) of the image, the shape react-image-crop reports for `unit: '%'`. */
 export interface CropAreaPercent {
     x: number;
     y: number;
@@ -15,8 +15,7 @@ export interface CropAreaPercent {
     height: number;
 }
 /**
- * Convert react-easy-crop's `onCropComplete(croppedArea, croppedAreaPixels)`
- * percentage area into a normalized `CropRect`, clamped to [0,1] and then
+ * Convert a percentage crop box 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.
  *
@@ -24,12 +23,19 @@ export interface CropAreaPercent {
  * zero-area selection).
  */
 export declare function cropAreaPercentToRect(area: CropAreaPercent): CropRect | null;
+/** "W:H" -> the numeric aspect ratio react-image-crop's `aspect` prop expects. Mirrors config/schemas/field.ts's ASPECT_RATIO_RE; returns undefined for anything malformed rather than throwing (defensive - the field config was already validated at schema-parse time). */
+export declare function parseAspectRatio(aspect: string | undefined): number | undefined;
 /**
- * Inverse of `cropAreaPercentToRect` - seeds react-easy-crop's
- * `initialCroppedAreaPercentages` when re-opening the crop step for an
- * already-cropped image, so the user sees their previous selection instead
- * of starting over.
+ * The crop box the crop step opens with, once the image's displayed size is known.
+ * A stored crop is kept as it was drawn, unless the field has an `aspect` it no longer
+ * matches (the config changed since); then, like a first crop of a locked field, a box of that
+ * ratio centred on the image. A free field's first box is the whole frame, so Apply with no change trims nothing.
  */
-export declare function cropRectToAreaPercent(rect: CropRect): CropAreaPercent;
-/** "W:H" -> the numeric aspect ratio react-easy-crop's `aspect` prop expects. Mirrors config/schemas/field.ts's ASPECT_RATIO_RE; returns undefined for anything malformed rather than throwing (defensive - the field config was already validated at schema-parse time). */
-export declare function parseAspectRatio(aspect: string | undefined): number | undefined;
+export declare function initialCropBox(opts: {
+    imageWidth: number;
+    imageHeight: number;
+    aspect?: number;
+    existing?: CropRect;
+}): CropAreaPercent;
+/** True for a rectangle covering the whole frame, which renders the image unchanged. */
+export declare function isFullFrameCrop(rect: CropRect): boolean;

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

@@ -1,9 +1,9 @@
 /**
- * Pure math for the ImageField crop step: converting between react-easy-crop's
- * percentage-based `Area` shape and CanopyCMS's normalized 0..1 `CropRect`
+ * Pure math for the ImageField crop step: converting between react-image-crop's
+ * percentage-based crop shape and CanopyCMS's normalized 0..1 `CropRect`
  * (the same shape stored in `ImageFieldValue.crop` and accepted by the `c=`
  * transform directive - see assets/transform-directives.ts). Kept dependency-free
- * (no react-easy-crop import) so it's trivially unit-testable and reusable
+ * (no react-image-crop import) so it's trivially unit-testable and reusable
  * without pulling in the cropper UI library.
  */
 import { isValidCropRect, roundCropRect } from '../../assets/transform-directives.js';
@@ -13,8 +13,7 @@ function clamp01(value) {
     return Math.min(1, Math.max(0, value));
 }
 /**
- * Convert react-easy-crop's `onCropComplete(croppedArea, croppedAreaPixels)`
- * percentage area into a normalized `CropRect`, clamped to [0,1] and then
+ * Convert a percentage crop box 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.
  *
@@ -31,15 +30,14 @@ export function cropAreaPercentToRect(area) {
     return isValidCropRect(rect.x, rect.y, rect.w, rect.h) ? rect : null;
 }
 /**
- * Inverse of `cropAreaPercentToRect` - seeds react-easy-crop's
- * `initialCroppedAreaPercentages` when re-opening the crop step for an
- * already-cropped image, so the user sees their previous selection instead
- * of starting over.
+ * Inverse of `cropAreaPercentToRect` - seeds the crop box when re-opening
+ * the crop step for an already-cropped image, so the user sees their previous
+ * selection instead of starting over.
  */
-export function cropRectToAreaPercent(rect) {
+function cropRectToAreaPercent(rect) {
     return { x: rect.x * 100, y: rect.y * 100, width: rect.w * 100, height: rect.h * 100 };
 }
-/** "W:H" -> the numeric aspect ratio react-easy-crop's `aspect` prop expects. Mirrors config/schemas/field.ts's ASPECT_RATIO_RE; returns undefined for anything malformed rather than throwing (defensive - the field config was already validated at schema-parse time). */
+/** "W:H" -> the numeric aspect ratio react-image-crop's `aspect` prop expects. Mirrors config/schemas/field.ts's ASPECT_RATIO_RE; returns undefined for anything malformed rather than throwing (defensive - the field config was already validated at schema-parse time). */
 export function parseAspectRatio(aspect) {
     if (!aspect)
         return undefined;
@@ -48,3 +46,44 @@ export function parseAspectRatio(aspect) {
         return undefined;
     return Number(match[1]) / Number(match[2]);
 }
+const INITIAL_BOX_FRACTION = 0.9;
+const FREE_BOX = { x: 0, y: 0, width: 100, height: 100 };
+/** How far a stored crop's pixel ratio may sit from the field's `aspect` before it is replaced by a fresh box. */
+const ASPECT_TOLERANCE = 0.02;
+/**
+ * The crop box the crop step opens with, once the image's displayed size is known.
+ * A stored crop is kept as it was drawn, unless the field has an `aspect` it no longer
+ * matches (the config changed since); then, like a first crop of a locked field, a box of that
+ * ratio centred on the image. A free field's first box is the whole frame, so Apply with no change trims nothing.
+ */
+export function initialCropBox(opts) {
+    const { imageWidth, imageHeight, aspect, existing } = opts;
+    const sized = imageWidth > 0 && imageHeight > 0;
+    if (existing) {
+        const box = cropRectToAreaPercent(existing);
+        if (aspect === undefined || !sized)
+            return box;
+        const storedRatio = (existing.w * imageWidth) / (existing.h * imageHeight);
+        if (Math.abs(storedRatio - aspect) / aspect <= ASPECT_TOLERANCE)
+            return box;
+    }
+    if (aspect === undefined || !sized)
+        return { ...FREE_BOX };
+    const wide = aspect >= imageWidth / imageHeight;
+    const width = wide
+        ? imageWidth * INITIAL_BOX_FRACTION
+        : imageHeight * INITIAL_BOX_FRACTION * aspect;
+    const height = wide ? width / aspect : imageHeight * INITIAL_BOX_FRACTION;
+    const widthPct = (width / imageWidth) * 100;
+    const heightPct = (height / imageHeight) * 100;
+    return {
+        x: (100 - widthPct) / 2,
+        y: (100 - heightPct) / 2,
+        width: widthPct,
+        height: heightPct,
+    };
+}
+/** True for a rectangle covering the whole frame, which renders the image unchanged. */
+export function isFullFrameCrop(rect) {
+    return rect.x === 0 && rect.y === 0 && rect.w === 1 && rect.h === 1;
+}

package/dist/editor/media/useAssetLibrary.d.ts

@@ -15,16 +15,19 @@ export interface UseAssetLibraryResult {
     retry: () => void;
     /** Puts an uploaded asset in the list; the one already loaded under its hash is replaced. */
     prepend: (asset: AssetRecord) => void;
-    /** Drops a deleted asset, including from a page still on its way. */
+    /** Drops a removed asset, including from a page still on its way. */
     remove: (hash32: string) => void;
+    /** Replaces the loaded asset with the same hash in place, such as one just removed or restored. */
+    replace: (asset: AssetRecord) => void;
 }
 /**
  * Loads the whole library in the background while `opened`: page 1 first, then each following
  * page in turn, so search and sort see every asset. Closing (or unmounting) stops the walk, and
- * reopening starts again from page 1.
+ * reopening, or changing `includeHidden`, starts again from page 1. `includeHidden` (admins only)
+ * also lists the files removed from the library, each marked `hidden`.
  *
  * Finalize dedups content, so a re-uploaded file comes back as an existing record that may also
  * arrive in a later page; assets are merged by `hash32`.
  */
-export declare function useAssetLibrary(opened: boolean): UseAssetLibraryResult;
+export declare function useAssetLibrary(opened: boolean, includeHidden?: boolean): UseAssetLibraryResult;
 export {};

package/dist/editor/media/useAssetLibrary.js

@@ -18,12 +18,13 @@ function mergeAssets(existing, incoming, removed) {
 /**
  * Loads the whole library in the background while `opened`: page 1 first, then each following
  * page in turn, so search and sort see every asset. Closing (or unmounting) stops the walk, and
- * reopening starts again from page 1.
+ * reopening, or changing `includeHidden`, starts again from page 1. `includeHidden` (admins only)
+ * also lists the files removed from the library, each marked `hidden`.
  *
  * Finalize dedups content, so a re-uploaded file comes back as an existing record that may also
  * arrive in a later page; assets are merged by `hash32`.
  */
-export function useAssetLibrary(opened) {
+export function useAssetLibrary(opened, includeHidden = false) {
     const client = useApiClient();
     const [assets, setAssets] = useState([]);
     const [firstPageLoaded, setFirstPageLoaded] = useState(false);
@@ -44,9 +45,11 @@ export function useAssetLibrary(opened) {
             let page;
             let message = '';
             try {
-                const result = await client.assets.list(cursor === undefined
-                    ? { limit: String(PAGE_SIZE) }
-                    : { cursor, limit: String(PAGE_SIZE) });
+                const result = await client.assets.list({
+                    limit: String(PAGE_SIZE),
+                    ...(cursor !== undefined && { cursor }),
+                    ...(includeHidden && { includeHidden: 'true' }),
+                });
                 if (result.ok && result.data)
                     page = result.data;
                 else
@@ -74,7 +77,7 @@ export function useAssetLibrary(opened) {
                 return;
             }
             // A cursor seen before means the listing moved under the walk (the local store restarts
-            // from page 1 when its anchor asset is deleted), so pages may be missing: never report
+            // from page 1 when its anchor's meta file is gone), so pages may be missing: never report
             // that as complete. Retry starts over.
             if (requested.current.has(next)) {
                 failedCursor.current = undefined;
@@ -83,7 +86,7 @@ export function useAssetLibrary(opened) {
             }
             cursor = next;
         }
-    }, [client]);
+    }, [client, includeHidden]);
     const start = useCallback(() => {
         generation.current += 1;
         requested.current = new Set();
@@ -102,8 +105,9 @@ export function useAssetLibrary(opened) {
         return () => {
             generation.current += 1;
         };
-        // Restart only when the drawer/modal (re)opens, not when `start`'s identity changes.
-    }, [opened]);
+        // Restart only when the drawer/modal (re)opens or the listing changes, not when `start`'s
+        // identity changes.
+    }, [opened, includeHidden]);
     const retry = useCallback(() => {
         const cursor = failedCursor.current;
         if (cursor === undefined) {
@@ -122,5 +126,8 @@ export function useAssetLibrary(opened) {
         removed.current.add(hash32);
         setAssets((prev) => prev.filter((existing) => existing.hash32 !== hash32));
     }, []);
-    return { assets, firstPageLoaded, complete, error, retry, prepend, remove };
+    const replace = useCallback((asset) => {
+        setAssets((prev) => prev.map((existing) => (existing.hash32 === asset.hash32 ? asset : existing)));
+    }, []);
+    return { assets, firstPageLoaded, complete, error, retry, prepend, remove, replace };
 }

package/dist/editor/pane-header.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The height of the bar atop each half of the main region, the preview toolbar and the form
+ * header, so their bottom borders line up side by side. Border-box: it includes the bar's border,
+ * and the preview pane's own top border above its toolbar.
+ */
+export declare const PANE_HEADER_HEIGHT = 40;

package/dist/editor/pane-header.js

@@ -0,0 +1,6 @@
+/**
+ * The height of the bar atop each half of the main region, the preview toolbar and the form
+ * header, so their bottom borders line up side by side. Border-box: it includes the bar's border,
+ * and the preview pane's own top border above its toolbar.
+ */
+export const PANE_HEADER_HEIGHT = 40;

package/dist/editor/permission-manager/index.js

@@ -111,7 +111,7 @@ const PermissionManagerDrawer = ({ opened, onClose, onExited, returnFocusTo, col
             allowedUsers: currentTarget.allowedUsers,
         });
     }, [annotatedTree, localPermissions, updateNodePermission]);
-    return (_jsx(StagedChangesDrawer, { opened: opened, onClose: onClose, title: "Permissions", description: "Manage content access by path (read, edit, review)", size: 700, isDirty: isDirty, isSaving: isSaving, canEdit: canEdit, saveLabel: "Save permissions", onSave: handleSave, onDiscard: handleDiscard, onExited: onExited, returnFocusTo: returnFocusTo, children: _jsxs(Stack, { h: "100%", style: { display: 'flex', flexDirection: 'column' }, gap: 0, children: [!canEdit && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "yellow", mb: "sm", title: "Read-only", children: "You need admin access to edit permissions" })), error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: errorIsConflict ? 'yellow' : 'red', mb: "sm", title: errorIsConflict ? 'Not saved' : 'Error', withCloseButton: true, onClose: () => setError(null), children: error })), groupLoadError && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "orange", mb: "sm", title: "Warning", withCloseButton: true, onClose: clearGroupLoadError, children: groupLoadError })), _jsxs(Group, { gap: "xs", pb: "sm", children: [_jsx(Button, { variant: "subtle", onClick: expandAll, children: "Expand all" }), _jsx(Button, { variant: "subtle", onClick: collapseAll, children: "Collapse all" })] }), _jsx(ScrollArea, { style: { flex: 1 }, pb: "md", children: loading ? (_jsxs(Group, { justify: "center", py: "xl", children: [_jsx(Loader, { size: "md" }), _jsx(Text, { size: "sm", c: "dimmed", children: "Loading permissions..." })] })) : (_jsx(PermissionTree, { node: annotatedTree, expandedNodes: expandedNodes, selectedNode: selectedNode, canEdit: canEdit, groups: groupSelectData, activeLevel: activeLevel, userSearchResults: userSearchResults, isSearchingUsers: isSearchingUsers, showUserSearch: showUserSearch, userSearchQuery: userSearchQuery, userSearchError: userSearchError, showGroupSearch: showGroupSearch, groupSearchQuery: groupSearchQuery, filteredGroups: filteredGroups, onToggle: toggleNode, onSelect: selectNode, onSetActiveLevel: setActiveLevel, onUpdatePermission: updateNodePermission, onSearchUsers: setUserSearchQuery, onGetUserMetadata: onGetUserMetadata, onToggleUserSearch: toggleUserSearch, onAddUser: handleAddUser, onRemoveUser: handleRemoveUser, onSearchGroups: setGroupSearchQuery, onToggleGroupSearch: setShowGroupSearch, onAddGroup: handleAddGroup, onRemoveGroup: handleRemoveGroup })) })] }) }));
+    return (_jsx(StagedChangesDrawer, { opened: opened, onClose: onClose, title: "Permissions", size: 700, isDirty: isDirty, isSaving: isSaving, canEdit: canEdit, saveLabel: "Save permissions", onSave: handleSave, onDiscard: handleDiscard, onExited: onExited, returnFocusTo: returnFocusTo, children: _jsxs(Stack, { h: "100%", style: { display: 'flex', flexDirection: 'column' }, gap: 0, children: [!canEdit && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "yellow", mb: "sm", title: "Read-only", children: "You need admin access to edit permissions" })), error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: errorIsConflict ? 'yellow' : 'red', mb: "sm", title: errorIsConflict ? 'Not saved' : 'Error', withCloseButton: true, onClose: () => setError(null), children: error })), groupLoadError && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "orange", mb: "sm", title: "Warning", withCloseButton: true, onClose: clearGroupLoadError, children: groupLoadError })), _jsxs(Group, { gap: "xs", pb: "sm", children: [_jsx(Button, { variant: "subtle", onClick: expandAll, children: "Expand all" }), _jsx(Button, { variant: "subtle", onClick: collapseAll, children: "Collapse all" })] }), _jsx(ScrollArea, { style: { flex: 1 }, pb: "md", children: loading ? (_jsxs(Group, { justify: "center", py: "xl", children: [_jsx(Loader, { size: "md" }), _jsx(Text, { size: "sm", c: "dimmed", children: "Loading permissions..." })] })) : (_jsx(PermissionTree, { node: annotatedTree, expandedNodes: expandedNodes, selectedNode: selectedNode, canEdit: canEdit, groups: groupSelectData, activeLevel: activeLevel, userSearchResults: userSearchResults, isSearchingUsers: isSearchingUsers, showUserSearch: showUserSearch, userSearchQuery: userSearchQuery, userSearchError: userSearchError, showGroupSearch: showGroupSearch, groupSearchQuery: groupSearchQuery, filteredGroups: filteredGroups, onToggle: toggleNode, onSelect: selectNode, onSetActiveLevel: setActiveLevel, onUpdatePermission: updateNodePermission, onSearchUsers: setUserSearchQuery, onGetUserMetadata: onGetUserMetadata, onToggleUserSearch: toggleUserSearch, onAddUser: handleAddUser, onRemoveUser: handleRemoveUser, onSearchGroups: setGroupSearchQuery, onToggleGroupSearch: setShowGroupSearch, onAddGroup: handleAddGroup, onRemoveGroup: handleRemoveGroup })) })] }) }));
 };
 export { usePermissionTree } from './hooks/usePermissionTree.js';
 export { useGroupsAndUsers } from './hooks/useGroupsAndUsers.js';

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

@@ -5,6 +5,7 @@ export declare const CANOPY_PREVIEW_HIGHLIGHT = "canopycms:preview:highlight";
 export declare const CANOPY_PREVIEW_READY = "canopycms:preview:ready";
 export declare const CANOPY_PREVIEW_ERROR = "canopycms:preview:error";
 export declare const CANOPY_PREVIEW_MARKS = "canopycms:preview:marks";
+export declare const CANOPY_PREVIEW_NAVIGATE = "canopycms:preview:navigate";
 /**
  * The shape of the preview's `isLoading` for data of type `T`: a `boolean` at each reference
  * position, `true` while the editor is still resolving that reference, under the same keys and
@@ -49,6 +50,16 @@ export declare const isOpaqueOrigin: (origin: string) => boolean;
  * expected editor origin (same-origin unless `editorOrigin` is configured).
  */
 export declare const isTrustedEditorMessage: (event: MessageEvent, editorOrigin?: string) => boolean;
+/**
+ * Preview → editor, once the page listens for drafts: the editor answers with the current draft.
+ * `siteChrome` says the page renders the site's header and footer when its URL carries
+ * `chrome=1`, so the editor offers the toggle that adds it.
+ */
+export interface PreviewReadyMessage {
+    type: typeof CANOPY_PREVIEW_READY;
+    path: string;
+    siteChrome?: boolean;
+}
 export interface PreviewFocusMessage {
     type: typeof CANOPY_PREVIEW_FOCUS;
     entryPath: string;
@@ -74,6 +85,11 @@ export interface PreviewMarksMessage {
     count: number;
     paths?: string[];
 }
+/** Preview → editor: a plain click on a link to another page of this origin, left unfollowed. */
+export interface PreviewNavigateMessage {
+    type: typeof CANOPY_PREVIEW_NAVIGATE;
+    href: string;
+}
 /**
  * Preview → editor report that the current draft fails to compile/render
  * (e.g. malformed MDX). `message: null` clears an earlier error.
@@ -93,6 +109,11 @@ export declare const useCanopyPreview: <T>(opts: {
     initialData: T;
     /** Editor origin to trust for preview messages. Defaults to this page's own origin. */
     editorOrigin?: string;
+    /**
+     * This page renders the site's header and footer when its URL carries `chrome=1`, so the editor
+     * offers a toggle for them; see `PreviewReadyMessage`.
+     */
+    siteChrome?: boolean;
 }) => {
     data: T;
     isLoading: PreviewLoadingState<T>;
@@ -106,6 +127,7 @@ export declare const useCanopyPreview: <T>(opts: {
  */
 export declare const usePreviewData: <T>(path: string, initialData: T, opts?: {
     editorOrigin?: string;
+    siteChrome?: boolean;
 }) => {
     data: T;
     isLoading: PreviewLoadingState<T>;
@@ -126,6 +148,7 @@ export declare const usePreviewHighlight: (opts?: {
 }) => boolean;
 /**
  * Hook for preview pages to emit focus messages when elements with data-canopy-path are clicked.
+ * A click that follows a link, ours or the browser's, goes to another page, not to a field.
  */
 export declare const usePreviewFocusEmitter: (entryPath: string, opts?: {
     editorOrigin?: string;