canopycms 0.9.0 → 0.11.0

package/dist/editor/comments/FieldWrapper.js

@@ -6,6 +6,7 @@ import { CommentThreadsPopover } from './CommentThreadsPopover.js';
 import { FieldCommentContext } from './field-comment-context.js';
 import { useFormComments } from './form-comments.js';
 import { whenRevealed } from '../field-target.js';
+import { usePreviewFollowRequest } from '../hooks/usePreviewFollow.js';
 const FIELD_SCOPE_ATTR = 'data-field-comments';
 /**
  * Gives a form field its comment control. The control shows while the pointer or focus is on
@@ -23,6 +24,7 @@ export const FieldWrapper = ({ children, canopyPath, entryPath, threads, autoFoc
     const highlightHere = !!highlightThreadId && threads.some((t) => t.id === highlightThreadId);
     const [openRequest, setOpenRequest] = useState(undefined);
     const formComments = useFormComments();
+    const followInPreview = usePreviewFollowRequest();
     useEffect(() => formComments?.register(canopyPath, {
         subject: fieldLabel,
         blockedReason: commentBlockedReason,
@@ -51,7 +53,7 @@ export const FieldWrapper = ({ children, canopyPath, entryPath, threads, autoFoc
     const ownsTarget = (target) => target instanceof Element &&
         wrapperRef.current !== null &&
         target.closest(`[${FIELD_SCOPE_ATTR}]`) === wrapperRef.current;
-    const control = (_jsx(CommentThreadsPopover, { threads: threads, subject: fieldLabel, variant: "field", revealed: pointerOn || focusOn, anchors: anchors, openRequest: openRequest, currentUserId: currentUserId, canResolve: canResolve, onAddComment: (text, threadId) => onAddComment(text, 'field', entryPath, canopyPath, threadId), onResolveThread: onResolveThread, onGetUserMetadata: onGetUserMetadata, highlightThreadId: highlightThreadId, composeBlockedReason: commentBlockedReason, testId: `field-comment-${canopyPath}` }, resetKey));
+    const control = (_jsx(CommentThreadsPopover, { threads: threads, subject: fieldLabel, variant: "field", revealed: pointerOn || focusOn, anchors: anchors, openRequest: openRequest, currentUserId: currentUserId, canResolve: canResolve, onAddComment: (text, threadId) => onAddComment(text, 'field', entryPath, canopyPath, threadId), onResolveThread: onResolveThread, onGetUserMetadata: onGetUserMetadata, highlightThreadId: highlightThreadId, composeBlockedReason: commentBlockedReason, onOpened: () => followInPreview?.(canopyPath), testId: `field-comment-${canopyPath}` }, resetKey));
     return (_jsxs(Box, { ref: wrapperRef, "data-canopy-field": canopyPath, [FIELD_SCOPE_ATTR]: '', pos: "relative", style: { width: '100%' }, onMouseOver: (event) => setPointerOn(ownsTarget(event.target)), onMouseLeave: () => setPointerOn(false), onFocus: (event) => {
             const owned = ownsTarget(event.target);
             setFocusOn(owned);

package/dist/editor/copy.d.ts

@@ -14,6 +14,7 @@ export declare const EDITOR_ACTIONS: {
     readonly requestChanges: "Request changes";
     readonly switchBranch: "Switch branch";
     readonly newBranch: "New branch";
+    readonly archiveBranch: "Archive branch";
     readonly remove: "Remove";
     readonly restore: "Restore";
     readonly clear: "Clear";
@@ -34,5 +35,7 @@ export declare const rewrittenSubmitReason: (isAdmin: boolean) => string;
  * says how to finish the submit, where it can be retried at all.
  */
 export declare const UNFINISHED_SUBMIT_APPROVE_REASON = "The last submit didn't finish, so this branch can't be approved yet. Use \"Request changes\" to send it back to its editor.";
+/** Why only an admin may delete a branch that may hold commits nothing else has. */
+export declare const DELETE_NEEDS_ADMIN_REASON = "This branch may hold changes that are missing from GitHub. Ask an admin to check it before deleting it.";
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */
 export declare const CLOSED_PULL_REQUEST_REASON = "The pull request was closed on GitHub. Use \"Withdraw from review\", then submit it again to open a new one.";

package/dist/editor/copy.js

@@ -14,6 +14,7 @@ export const EDITOR_ACTIONS = {
     requestChanges: 'Request changes',
     switchBranch: 'Switch branch',
     newBranch: 'New branch',
+    archiveBranch: 'Archive branch',
     remove: 'Remove',
     restore: 'Restore',
     clear: 'Clear',
@@ -36,5 +37,7 @@ export const rewrittenSubmitReason = (isAdmin) => isAdmin
  * says how to finish the submit, where it can be retried at all.
  */
 export const UNFINISHED_SUBMIT_APPROVE_REASON = 'The last submit didn\'t finish, so this branch can\'t be approved yet. Use "Request changes" to send it back to its editor.';
+/** Why only an admin may delete a branch that may hold commits nothing else has. */
+export const DELETE_NEEDS_ADMIN_REASON = 'This branch may hold changes that are missing from GitHub. Ask an admin to check it before deleting it.';
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */
 export const CLOSED_PULL_REQUEST_REASON = 'The pull request was closed on GitHub. Use "Withdraw from review", then submit it again to open a new one.';

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

@@ -28,8 +28,11 @@ export declare const CREATED_BRANCH_GRACE_MS = 120000;
 interface BranchSummary {
     name: string;
     shortName?: string;
+    title?: string;
     status: string;
     createdBy?: string;
+    /** The creator's display name, when the listing carried it. */
+    ownerName?: string;
     updatedAt?: string;
     access: {
         users: string[] | undefined;
@@ -126,6 +129,8 @@ export interface UseBranchManagerReturn {
     /** Confirms first, taking an optional note; focus returns as for `handleApprove`. */
     handleRequestChanges: (branchName: string, returnFocusTo?: () => HTMLElement | null) => Promise<void>;
     handleDelete: (branchName: string) => Promise<void>;
+    /** Admin only: confirms first, then archives a branch whose pull request closed unmerged. */
+    handleArchive: (branchName: string) => Promise<void>;
     handleReloadBranchData: () => Promise<void>;
     loadBranches: () => Promise<void>;
 }

package/dist/editor/hooks/useBranchManager.js

@@ -201,7 +201,7 @@ const showDeleteConfirmation = (branchName, pr, mayHoldUnpublished, onConfirm, o
             : undefined,
         'Discard any unsaved or unmerged changes',
         mayHoldUnpublished
-            ? 'Remove the only copy of any changes that never reached GitHub, and the warning about them'
+            ? 'Remove the only copy of any changes missing from GitHub, and the warning about them'
             : undefined,
     ].filter((b) => b !== undefined);
     openConfirm({
@@ -217,6 +217,16 @@ const showDeleteConfirmation = (branchName, pr, mayHoldUnpublished, onConfirm, o
         ...confirmModalHandlers(onConfirm, onDismiss),
     });
 };
+/** Archiving is a one-way status change on a branch whose review is over. */
+const showArchiveConfirmation = (branchName, inReview, onConfirm, onDismiss) => {
+    openConfirm({
+        title: EDITOR_ACTIONS.archiveBranch,
+        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Archive “${branchName}”?\n\nIts pull request was closed without merging. This will:\n• Make the branch read-only and move it to “Archived”\n• Keep it marked as not merged\n\nAn archived branch can't go back to editing. This one stays until someone deletes it: automatic and bulk deletes only take merged branches.${inReview ? ` To keep working on it, use “${EDITOR_ACTIONS.withdrawFromReview}” instead.` : ''}` })),
+        labels: { confirm: EDITOR_ACTIONS.archiveBranch, cancel: 'Cancel' },
+        confirmProps: { color: 'orange', 'data-testid': 'confirm-archive-branch' },
+        ...confirmModalHandlers(onConfirm, onDismiss),
+    });
+};
 /**
  * How long a branch this session created stays overlaid on listings. Each warm
  * server container caches the shared filesystem separately, so for its
@@ -381,8 +391,10 @@ export function useBranchManager(options) {
             return {
                 name: b.name,
                 shortName: b.shortName,
+                title: b.title,
                 status: b.status,
                 createdBy: b.createdBy,
+                ownerName: branchesData?.ownerNames?.[b.createdBy],
                 updatedAt: b.updatedAt,
                 access: {
                     users: b.access.allowedUsers,
@@ -423,7 +435,7 @@ export function useBranchManager(options) {
                 submitBlocked: b.submitBlocked ?? true,
             };
         });
-    }, [branches, currentBranchName, options.comments]);
+    }, [branches, branchesData?.ownerNames, currentBranchName, options.comments]);
     // Explicit reload: always issues a fresh, independent fetch (raw call, not
     // SWR's `mutate()` revalidate path) so callers requesting a reload right
     // after mount aren't coalesced against the still-in-flight automatic load
@@ -730,6 +742,45 @@ export function useBranchManager(options) {
             }, () => resolve(), returnFocusTo);
         }));
     };
+    const handleArchive = (requested) => {
+        const branchNameToArchive = listedName(requested);
+        return singleFlight('archive', branchNameToArchive, () => new Promise((resolve, reject) => {
+            const status = latest.current.branches.find((b) => b.name === branchNameToArchive)?.status;
+            showArchiveConfirmation(shownName(branchNameToArchive), status === 'submitted' || status === 'approved', async () => {
+                options.setBusy(true);
+                try {
+                    const result = await apiClient.workflow.archive({
+                        branch: sendName(branchNameToArchive),
+                    });
+                    if (!result.ok)
+                        throw actionError(result, 'Failed to archive branch');
+                    notifications.show({ message: 'Branch archived', color: 'blue' });
+                    forgetCreatedBranch(branchNameToArchive);
+                    await loadBranches();
+                    resolve();
+                }
+                catch (err) {
+                    if (err instanceof RefusedError && err.status === 409) {
+                        // Nothing is lost, and the list says what changed.
+                        notifications.show({
+                            message: err.message,
+                            color: 'yellow',
+                            autoClose: false,
+                            withCloseButton: true,
+                        });
+                        await reloadBranches();
+                        resolve();
+                        return;
+                    }
+                    await reportActionFailure(err, 'Failed to archive branch', EDITOR_ACTIONS.archiveBranch);
+                    reject(err);
+                }
+                finally {
+                    options.setBusy(false);
+                }
+            }, () => resolve());
+        }));
+    };
     const handleApprove = (requested, returnFocusTo) => {
         const branchNameToApprove = listedName(requested);
         return singleFlight('approve', branchNameToApprove, () => new Promise((resolve, reject) => {
@@ -838,8 +889,7 @@ export function useBranchManager(options) {
         const branchNameToDelete = listedName(requested);
         const listedBefore = latest.current.branches;
         return singleFlight('delete', branchNameToDelete, () => new Promise((resolve) => {
-            showDeleteConfirmation(shownName(branchNameToDelete), pullRequestOf(branchNameToDelete), listedBefore.find((b) => b.name === branchNameToDelete)?.hold?.kind ===
-                'unpublished-at-merge', async () => {
+            showDeleteConfirmation(shownName(branchNameToDelete), pullRequestOf(branchNameToDelete), ['unpublished-at-merge', 'rewritten-at-merge'].includes(listedBefore.find((b) => b.name === branchNameToDelete)?.hold?.kind ?? ''), async () => {
                 options.setBusy(true);
                 try {
                     const result = await apiClient.branches.delete({
@@ -960,6 +1010,7 @@ export function useBranchManager(options) {
         handleApprove,
         handleRequestChanges,
         handleDelete,
+        handleArchive,
         handleReloadBranchData,
         loadBranches,
     };

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

@@ -19,6 +19,8 @@ export declare const BRANCHES_KEY = "canopy:branches";
 export interface BranchesData {
     branches: BranchListItem[];
     defaultBranch?: string;
+    /** Display names of the listed branches' creators, by user id. */
+    ownerNames?: Readonly<Record<string, string>>;
     /**
      * Client clock when this listing arrived. It makes listings fetched at
      * different moments distinct `data` values even when their branches match,

package/dist/editor/hooks/useBranchesData.js

@@ -33,10 +33,12 @@ export async function fetchBranches(apiClient, swr) {
     if (!result.ok) {
         throw new Error(result.error ?? `Failed to load branches: ${result.status}`);
     }
-    await seedUserProfiles(swr, result.data?.users ?? []);
+    const users = result.data?.users ?? [];
+    await seedUserProfiles(swr, users);
     return {
         branches: result.data?.branches ?? [],
         defaultBranch: result.data?.defaultBranch,
+        ownerNames: Object.fromEntries(users.map((user) => [user.id, user.name])),
         receivedAt: Date.now(),
     };
 }

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

@@ -8,6 +8,8 @@ interface EditorLayoutPrefs {
     /** Unset until the user picks one, so it follows `defaultLayout`; JSON drops it while unset. */
     layout?: PaneArrangement;
     highlightEnabled: boolean;
+    /** The preview scrolls to the field the form is on; see `usePreviewFollow`. */
+    previewFollowsForm: boolean;
     sideSplitPercent: number;
     stackedSplitPercent: number;
     previewWidth: PreviewWidth;
@@ -42,6 +44,8 @@ export interface UseEditorLayoutReturn {
     setLayout: (layout: PaneArrangement) => void;
     highlightEnabled: boolean;
     setHighlightEnabled: (enabled: boolean) => void;
+    previewFollowsForm: boolean;
+    setPreviewFollowsForm: (follows: boolean) => void;
     sideSplitPercent: number;
     stackedSplitPercent: number;
     /** Stores the clamped primary-pane size for one layout; a non-finite percent is ignored. */

package/dist/editor/hooks/useEditorLayout.js

@@ -12,6 +12,7 @@ export const CONTENT_PANEL_WIDTH_MAX = 400;
  */
 export const DEFAULT_EDITOR_LAYOUT_PREFS = {
     highlightEnabled: false,
+    previewFollowsForm: true,
     sideSplitPercent: DEFAULT_SIDE_SPLIT_PERCENT,
     stackedSplitPercent: DEFAULT_STACKED_SPLIT_PERCENT,
     previewWidth: 'fit',
@@ -48,6 +49,7 @@ export function parseEditorLayoutPrefs(raw) {
     return {
         layout: PANE_LAYOUTS.find((layout) => layout === parsed.layout),
         highlightEnabled: boolOr(parsed.highlightEnabled, defaults.highlightEnabled),
+        previewFollowsForm: boolOr(parsed.previewFollowsForm, defaults.previewFollowsForm),
         sideSplitPercent: numberOr(parsed.sideSplitPercent, defaults.sideSplitPercent, clampSplitPercent),
         stackedSplitPercent: numberOr(parsed.stackedSplitPercent, defaults.stackedSplitPercent, clampSplitPercent),
         previewWidth: oneOf(PREVIEW_WIDTHS, parsed.previewWidth, defaults.previewWidth),
@@ -73,6 +75,7 @@ export function useEditorLayout(options) {
     const loaded = useMounted();
     const setLayout = useCallback((layout) => setPrefs((prev) => ({ ...prev, layout })), [setPrefs]);
     const setHighlightEnabled = useCallback((highlightEnabled) => setPrefs((prev) => ({ ...prev, highlightEnabled })), [setPrefs]);
+    const setPreviewFollowsForm = useCallback((previewFollowsForm) => setPrefs((prev) => ({ ...prev, previewFollowsForm })), [setPrefs]);
     const setSplitPercent = useCallback((layout, percent) => {
         if (!Number.isFinite(percent))
             return;
@@ -96,6 +99,8 @@ export function useEditorLayout(options) {
         setLayout,
         highlightEnabled: prefs.highlightEnabled,
         setHighlightEnabled,
+        previewFollowsForm: prefs.previewFollowsForm,
+        setPreviewFollowsForm,
         sideSplitPercent: prefs.sideSplitPercent,
         stackedSplitPercent: prefs.stackedSplitPercent,
         setSplitPercent,

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

@@ -0,0 +1,26 @@
+import type { PreviewReveal } from '../PreviewFrame.js';
+/**
+ * How long the form rests on one field before the preview follows, so tabbing through doesn't.
+ * @internal Exported for tests.
+ */
+export declare const PREVIEW_FOLLOW_DELAY_MS = 250;
+/** Has the preview follow the form to a field; null while it doesn't follow. */
+export declare const PreviewFollowContext: import("react").Context<((canopyPath: string) => void) | null>;
+export declare const usePreviewFollowRequest: () => ((canopyPath: string) => void) | null;
+export interface UsePreviewFollowReturn {
+    /** The latest field to bring into view in the preview, for `PreviewFrame`'s `reveal`. */
+    reveal: PreviewReveal | undefined;
+    /** Asks for a field, as a comment opening on it does; undefined while the preview doesn't follow. */
+    follow: ((canopyPath: string) => void) | undefined;
+}
+/**
+ * The preview follows the form: focus moving to another form field, or `follow` for one, asks the
+ * preview to bring that field's element into view, once the form has rested on it for
+ * `PREVIEW_FOLLOW_DELAY_MS`. A reveal belongs to one page, which the branch names too, so a change
+ * of either drops it.
+ */
+export declare function usePreviewFollow({ enabled, branch, entryId, }: {
+    enabled: boolean;
+    branch: string;
+    entryId: string | undefined;
+}): UsePreviewFollowReturn;

package/dist/editor/hooks/usePreviewFollow.js

@@ -0,0 +1,54 @@
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { normalizeCanopyPath } from '../canopy-path.js';
+import { FORM_PANE_ID } from '../shell/PaneLayout.js';
+/**
+ * How long the form rests on one field before the preview follows, so tabbing through doesn't.
+ * @internal Exported for tests.
+ */
+export const PREVIEW_FOLLOW_DELAY_MS = 250;
+/** Has the preview follow the form to a field; null while it doesn't follow. */
+export const PreviewFollowContext = createContext(null);
+export const usePreviewFollowRequest = () => useContext(PreviewFollowContext);
+/**
+ * The preview follows the form: focus moving to another form field, or `follow` for one, asks the
+ * preview to bring that field's element into view, once the form has rested on it for
+ * `PREVIEW_FOLLOW_DELAY_MS`. A reveal belongs to one page, which the branch names too, so a change
+ * of either drops it.
+ */
+export function usePreviewFollow({ enabled, branch, entryId, }) {
+    const [reveal, setReveal] = useState(undefined);
+    const timer = useRef(undefined);
+    const lastId = useRef(0);
+    const lastPath = useRef(undefined);
+    const follow = useCallback((canopyPath) => {
+        lastPath.current = normalizeCanopyPath(canopyPath);
+        window.clearTimeout(timer.current);
+        timer.current = window.setTimeout(() => {
+            lastId.current += 1;
+            setReveal({ path: normalizeCanopyPath(canopyPath), id: lastId.current });
+        }, PREVIEW_FOLLOW_DELAY_MS);
+    }, []);
+    useEffect(() => {
+        window.clearTimeout(timer.current);
+        lastPath.current = undefined;
+        setReveal(undefined);
+    }, [branch, entryId, enabled]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const onFocusIn = (event) => {
+            const target = event.target;
+            if (!(target instanceof Element) || !target.closest(`#${FORM_PANE_ID}`))
+                return;
+            const path = target.closest('[data-canopy-field]')?.getAttribute('data-canopy-field');
+            // Focus coming back to the field, after a popover or the window, leaves the preview as the
+            // user scrolled it; a comment opening still asks, through `follow`.
+            if (path && normalizeCanopyPath(path) !== lastPath.current)
+                follow(path);
+        };
+        document.addEventListener('focusin', onFocusIn);
+        return () => document.removeEventListener('focusin', onFocusIn);
+    }, [enabled, follow]);
+    useEffect(() => () => window.clearTimeout(timer.current), []);
+    return { reveal, follow: enabled ? follow : undefined };
+}

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

@@ -6,6 +6,7 @@ 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";
+export declare const CANOPY_PREVIEW_REVEAL = "canopycms:preview:reveal";
 /**
  * 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
@@ -85,6 +86,15 @@ export interface PreviewMarksMessage {
     count: number;
     paths?: string[];
 }
+/**
+ * Editor → preview: bring the element marked for this field into view, else the marks inside it,
+ * else its nearest marked ancestor's (`findRevealTargets`). A bridge older than the message
+ * ignores it.
+ */
+export interface PreviewRevealMessage {
+    type: typeof CANOPY_PREVIEW_REVEAL;
+    path: 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;
@@ -146,6 +156,21 @@ export declare const usePreviewAssetBaseGate: (assetBase: unknown) => boolean;
 export declare const usePreviewHighlight: (opts?: {
     editorOrigin?: string;
 }) => boolean;
+/**
+ * The rendered elements marked for `path`, else those inside it in page order, such as a list
+ * marked item by item, else those for its nearest marked ancestor: a list item, then its list or
+ * block. Compares values, never builds a selector: the path is untrusted.
+ * @internal Exported for tests.
+ */
+export declare const findRevealTargets: (path: string, root?: ParentNode) => HTMLElement[];
+/**
+ * Hook for preview pages to bring the element the editor's form is on into view and mark it
+ * briefly, whether or not highlighting is on. It leaves focus where it is, and an element already
+ * as much in view as it can be where it is.
+ */
+export declare const usePreviewReveal: (opts?: {
+    editorOrigin?: string;
+}) => void;
 /**
  * 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.

package/dist/editor/preview-bridge.js

@@ -5,6 +5,7 @@
  * (`pnpm lint:bundle`); the editor's side is `PreviewFrame.tsx`.
  */
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { formatCanopyPath, normalizeCanopyPath, parseCanopyPath } from './canopy-path.js';
 import { createFieldProps } from './field-props.js';
 import { setPreviewAssetBase } from './preview-asset-base.js';
 import { isSamePreviewPath } from './preview-path.js';
@@ -16,6 +17,7 @@ export const CANOPY_PREVIEW_READY = 'canopycms:preview:ready';
 export const CANOPY_PREVIEW_ERROR = 'canopycms:preview:error';
 export const CANOPY_PREVIEW_MARKS = 'canopycms:preview:marks';
 export const CANOPY_PREVIEW_NAVIGATE = 'canopycms:preview:navigate';
+export const CANOPY_PREVIEW_REVEAL = 'canopycms:preview:reveal';
 /**
  * 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
@@ -80,6 +82,7 @@ export const useCanopyPreview = (opts) => {
     });
     const highlightEnabled = usePreviewHighlight(bridgeOpts);
     usePreviewFocusEmitter(resolvedPath, bridgeOpts);
+    usePreviewReveal(bridgeOpts);
     usePreviewLinkNavigation({ editorOrigin, highlighting: highlightEnabled });
     const fieldProps = createFieldProps();
     /**
@@ -273,6 +276,178 @@ export const usePreviewHighlight = (opts) => {
     }, [enabled, editorOrigin]);
     return enabled;
 };
+const REVEALED_ATTR = 'data-canopy-revealed';
+/** How long a revealed element stays marked. */
+const REVEAL_MARK_MS = 1500;
+/** A field just opened may render after its reveal arrives, so a miss is tried once more. */
+const REVEAL_RETRY_MS = 300;
+/** How long the page's scrolling must pause before a smooth scroll counts as arrived. */
+const REVEAL_SCROLL_SETTLE_MS = 150;
+/** The longest a smooth scroll is waited for before the mark's time starts anyway. */
+const REVEAL_SCROLL_WAIT_MS = 3000;
+/**
+ * The rendered elements marked for `path`, else those inside it in page order, such as a list
+ * marked item by item, else those for its nearest marked ancestor: a list item, then its list or
+ * block. Compares values, never builds a selector: the path is untrusted.
+ * @internal Exported for tests.
+ */
+export const findRevealTargets = (path, root = document) => {
+    const byPath = new Map();
+    for (const element of root.querySelectorAll('[data-canopy-path]')) {
+        if (element.getClientRects().length === 0)
+            continue;
+        const key = normalizeCanopyPath(element.getAttribute('data-canopy-path') ?? '');
+        byPath.set(key, [...(byPath.get(key) ?? []), element]);
+    }
+    const segments = parseCanopyPath(path);
+    const field = formatCanopyPath(segments);
+    if (!field)
+        return [];
+    const exact = byPath.get(field);
+    if (exact)
+        return exact;
+    const inside = [...byPath]
+        .filter(([key]) => key.startsWith(`${field}.`) || key.startsWith(`${field}[`))
+        .flatMap(([, elements]) => elements)
+        .sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+    if (inside.length > 0)
+        return inside;
+    for (let length = segments.length - 1; length > 0; length--) {
+        const found = byPath.get(formatCanopyPath(segments.slice(0, length)));
+        if (found)
+            return found;
+    }
+    return [];
+};
+const CLIPPING = new Set(['hidden', 'clip', 'auto', 'scroll']);
+/** Where `element` can show: the window, clipped by each ancestor whose overflow clips. */
+const shownRect = (element) => {
+    const shown = { top: 0, bottom: window.innerHeight, left: 0, right: window.innerWidth };
+    for (let at = element.parentElement; at && at !== document.body; at = at.parentElement) {
+        const style = getComputedStyle(at);
+        const overflow = [style.overflowX, style.overflowY, ...style.overflow.split(' ')];
+        if (!overflow.some((value) => CLIPPING.has(value)))
+            continue;
+        const clip = at.getBoundingClientRect();
+        shown.top = Math.max(shown.top, clip.top);
+        shown.bottom = Math.min(shown.bottom, clip.bottom);
+        shown.left = Math.max(shown.left, clip.left);
+        shown.right = Math.min(shown.right, clip.right);
+    }
+    return shown;
+};
+/** As much of `element` shows as can: all of it, or all the room there is for a larger one. */
+const isInView = (element) => {
+    const rect = element.getBoundingClientRect();
+    const room = shownRect(element);
+    // A clipping box off the page has no room at all, so nothing in it shows.
+    if (room.bottom <= room.top || room.right <= room.left)
+        return false;
+    const tall = Math.min(rect.bottom, room.bottom) - Math.max(rect.top, room.top);
+    const wide = Math.min(rect.right, room.right) - Math.max(rect.left, room.left);
+    return (tall >= Math.min(rect.height, room.bottom - room.top) - 1 &&
+        wide >= Math.min(rect.width, room.right - room.left) - 1);
+};
+/**
+ * Hook for preview pages to bring the element the editor's form is on into view and mark it
+ * briefly, whether or not highlighting is on. It leaves focus where it is, and an element already
+ * as much in view as it can be where it is.
+ */
+export const usePreviewReveal = (opts) => {
+    const editorOrigin = opts?.editorOrigin;
+    useEffect(() => {
+        if (window.parent === window)
+            return;
+        const styleId = 'canopycms-preview-reveal-style';
+        if (!document.getElementById(styleId)) {
+            const styleEl = document.createElement('style');
+            styleEl.id = styleId;
+            // Two attributes, so it outranks the highlight outline.
+            styleEl.textContent = `[data-canopy-path][${REVEALED_ATTR}] { outline: 3px solid #4338ca; outline-offset: 3px; }`;
+            document.head.appendChild(styleEl);
+        }
+        let marked;
+        let unmarkTimer;
+        let retryTimer;
+        let stopWaiting;
+        const unmark = () => {
+            stopWaiting?.();
+            clearTimeout(unmarkTimer);
+            marked?.removeAttribute(REVEALED_ATTR);
+            marked = undefined;
+        };
+        // The mark's time starts once the scrolling that holds `target` pauses, so a slow smooth
+        // scroll can't use it up; another scroller on the page, such as a carousel, doesn't count.
+        const unmarkAfterScroll = (target, smooth) => {
+            if (!smooth) {
+                unmarkTimer = setTimeout(unmark, REVEAL_MARK_MS);
+                return;
+            }
+            const arrived = () => {
+                stopWaiting?.();
+                unmarkTimer = setTimeout(unmark, REVEAL_MARK_MS);
+            };
+            let settle = setTimeout(arrived, REVEAL_SCROLL_SETTLE_MS);
+            const cap = setTimeout(arrived, REVEAL_SCROLL_WAIT_MS);
+            const onScroll = (event) => {
+                const from = event.target;
+                if (from !== document && !(from instanceof Node && from.contains(target)))
+                    return;
+                clearTimeout(settle);
+                settle = setTimeout(arrived, REVEAL_SCROLL_SETTLE_MS);
+            };
+            document.addEventListener('scroll', onScroll, true);
+            stopWaiting = () => {
+                clearTimeout(settle);
+                clearTimeout(cap);
+                document.removeEventListener('scroll', onScroll, true);
+                stopWaiting = undefined;
+            };
+        };
+        const reveal = (path) => {
+            const targets = findRevealTargets(path);
+            if (targets.length === 0)
+                return false;
+            // Mid-scroll, a mark passed on the way only looks in view.
+            if (!stopWaiting && targets.some(isInView))
+                return true;
+            const target = targets[0];
+            const smooth = !window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+            target.scrollIntoView({
+                // One taller than the page shows its top.
+                block: target.getBoundingClientRect().height > window.innerHeight ? 'start' : 'center',
+                inline: 'nearest',
+                // `instant`, not `auto`, which a page's `scroll-behavior: smooth` animates.
+                behavior: smooth ? 'smooth' : 'instant',
+            });
+            unmark();
+            // An attribute and a stylesheet only: the page's own styles are never written to.
+            marked = target;
+            target.setAttribute(REVEALED_ATTR, '');
+            unmarkAfterScroll(target, smooth);
+            return true;
+        };
+        const handler = (event) => {
+            if (!isTrustedEditorMessage(event, editorOrigin))
+                return;
+            const msg = event.data;
+            if (msg?.type !== CANOPY_PREVIEW_REVEAL)
+                return;
+            const path = msg.path;
+            if (typeof path !== 'string' || path.length > MARK_REPORT_LIMITS.pathLength)
+                return;
+            clearTimeout(retryTimer);
+            if (!reveal(path))
+                retryTimer = setTimeout(() => reveal(path), REVEAL_RETRY_MS);
+        };
+        window.addEventListener('message', handler);
+        return () => {
+            window.removeEventListener('message', handler);
+            clearTimeout(retryTimer);
+            unmark();
+        };
+    }, [editorOrigin]);
+};
 const isPlainClick = (event) => event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
 const linkClick = (event) => {
     // The composed path reaches a link inside a shadow root, which the retargeted `target` hides.

package/dist/preview.d.ts

@@ -3,6 +3,6 @@
  * CSS, `@mantine/*` and editor UI (`pnpm lint:bundle`): a page that imports it renders in the
  * adopter's own styles inside the editor's preview, and ships no editor code to the public.
  */
-export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, } from './editor/preview-bridge.js';
-export type { DraftUpdateMessage, HighlightMessage, PreviewErrorMessage, PreviewFocusMessage, PreviewLoadingState, } from './editor/preview-bridge.js';
+export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, CANOPY_PREVIEW_REVEAL, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, usePreviewReveal, } from './editor/preview-bridge.js';
+export type { DraftUpdateMessage, HighlightMessage, PreviewErrorMessage, PreviewFocusMessage, PreviewLoadingState, PreviewRevealMessage, } from './editor/preview-bridge.js';
 export type { CanopyPathSegment } from './editor/canopy-path.js';

package/dist/preview.js

@@ -4,4 +4,4 @@
  * CSS, `@mantine/*` and editor UI (`pnpm lint:bundle`): a page that imports it renders in the
  * adopter's own styles inside the editor's preview, and ships no editor code to the public.
  */
-export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, } from './editor/preview-bridge.js';
+export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, CANOPY_PREVIEW_REVEAL, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, usePreviewReveal, } from './editor/preview-bridge.js';