canopycms 0.10.0 → 0.11.1

package/dist/editor/PreviewFrame.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MARKS, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_NAVIGATE, CANOPY_PREVIEW_READY, isOpaqueOrigin, MARK_REPORT_LIMITS, resolveMessageOrigin, } from './preview-bridge.js';
+import { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MARKS, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_NAVIGATE, CANOPY_PREVIEW_READY, CANOPY_PREVIEW_REVEAL, isOpaqueOrigin, MARK_REPORT_LIMITS, resolveMessageOrigin, } from './preview-bridge.js';
 /**
  * How long after the iframe's `load` the preview has to send its ready message before the frame
  * says live updates are off. Ready can also arrive before `load`, which waits for images too.
@@ -51,7 +51,7 @@ const sendDraftUpdate = (iframe, message, targetOrigin) => {
  * runs until the preview's ready message arrives; when none does, a "Live updates off" chip offers
  * to reload the preview. While `busy`, the page stays in view, dimmed and inert, under the bar.
  */
-export const PreviewFrame = ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, onMarks, assetBase, iframeStyle, onReload, onSiteChrome, onNavigate, busy = false, }) => {
+export const PreviewFrame = ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, onMarks, assetBase, iframeStyle, onReload, onSiteChrome, onNavigate, reveal, busy = false, }) => {
     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
@@ -166,6 +166,19 @@ export const PreviewFrame = ({ src, path, data, isLoading, className, style, hig
         postHighlight();
         // eslint-disable-next-line react-hooks/exhaustive-deps -- postHighlight is tracked via ref
     }, [highlightEnabled]);
+    // Each frame, a retry's or a new page's, gets the latest reveal once it connects.
+    const revealSent = useRef(undefined);
+    useEffect(() => {
+        const contentWindow = iframeRef.current?.contentWindow;
+        if (!reveal || handshake !== 'ready' || !contentWindow || isOpaqueOrigin(previewOrigin))
+            return;
+        const frame = `${retries}:${src}`;
+        if (revealSent.current?.frame === frame && revealSent.current.id === reveal.id)
+            return;
+        revealSent.current = { frame, id: reveal.id };
+        const msg = { type: CANOPY_PREVIEW_REVEAL, path: reveal.path };
+        contentWindow.postMessage(msg, previewOrigin);
+    }, [reveal, handshake, previewOrigin, retries, src]);
     // 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.

package/dist/editor/PreviewPane.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import type { PreviewWidth } from './hooks/useEditorLayout.js';
-import { type PreviewMarks } from './PreviewFrame.js';
+import { type PreviewMarks, type PreviewReveal } from './PreviewFrame.js';
 import type { InexactMark } from './preview-marks.js';
 import type { PaneArrangement } from './shell/PaneLayout.js';
 import { type PreviewMount } from './preview-path.js';
@@ -54,10 +54,15 @@ export interface PreviewPaneProps {
     onSiteChromeChange?: (siteChrome: boolean) => void;
     /** Called with the absolute URL of a link clicked in the preview; see `PreviewFrame`. */
     onNavigate?: (href: string) => void;
+    /** The field the form is on, for the preview to bring into view; see `usePreviewFollow`. */
+    reveal?: PreviewReveal;
+    /** With `onPreviewFollowsFormChange`, the toolbar shows the follow toggle. */
+    previewFollowsForm?: boolean;
+    onPreviewFollowsFormChange?: (follows: boolean) => void;
 }
 /**
  * The preview region: a toolbar (path, width, reload, saved version) over a `PreviewFrame`. A
  * fixed width renders the iframe at that CSS width, so the site's own breakpoints apply, scaled
  * down to fit a narrower pane.
  */
-export declare const PreviewPane: ({ src, path, pending, mount, previewWidth, onPreviewWidthChange, notice, onHighlightToggle, marksNothing, inexactMarks, showMarkDiagnostics, layout, maximized, onMaximizedChange, resizing, siteChrome, onSiteChromeChange, data, isLoading, onMarks, ...frameProps }: PreviewPaneProps) => import("react/jsx-runtime").JSX.Element;
+export declare const PreviewPane: ({ src, path, pending, mount, previewWidth, onPreviewWidthChange, notice, onHighlightToggle, marksNothing, inexactMarks, showMarkDiagnostics, layout, maximized, onMaximizedChange, resizing, siteChrome, onSiteChromeChange, previewFollowsForm, onPreviewFollowsFormChange, reveal, data, isLoading, onMarks, ...frameProps }: PreviewPaneProps) => import("react/jsx-runtime").JSX.Element;

package/dist/editor/PreviewPane.js

@@ -4,8 +4,8 @@ import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { ActionIcon, Box, Group, Select, Skeleton, Text, Tooltip, UnstyledButton, VisuallyHidden, } from '@mantine/core';
 import { useClipboard, useElementSize, useWindowEvent } from '@mantine/hooks';
 import { IconCheck, IconExternalLink, IconRefresh } from '@tabler/icons-react';
-import { PreviewFrame } from './PreviewFrame.js';
-import { HighlightToggle, MaximizeToggle, SiteChromeToggle, UnmappedMarksChip, } from './PreviewToolbarTools.js';
+import { PreviewFrame, } from './PreviewFrame.js';
+import { FollowFormToggle, HighlightToggle, MaximizeToggle, SiteChromeToggle, UnmappedMarksChip, } from './PreviewToolbarTools.js';
 import { PANE_HEADER_HEIGHT } from './pane-header.js';
 import { displayPreviewPath, siteChromeSrc } from './preview-path.js';
 import { computePreviewViewport, formatPreviewWidthReadout, PREVIEW_DEVICE_WIDTHS, } from './preview-scale.js';
@@ -28,7 +28,7 @@ const OPEN_SAVED_LABEL = 'Open saved version in a new tab';
  * fixed width renders the iframe at that CSS width, so the site's own breakpoints apply, scaled
  * down to fit a narrower pane.
  */
-export const PreviewPane = ({ src, path = src, pending = false, mount, previewWidth, onPreviewWidthChange, notice, onHighlightToggle, marksNothing, inexactMarks = [], showMarkDiagnostics = false, layout, maximized = false, onMaximizedChange, resizing = false, siteChrome = false, onSiteChromeChange, data, isLoading, onMarks, ...frameProps }) => {
+export const PreviewPane = ({ src, path = src, pending = false, mount, previewWidth, onPreviewWidthChange, notice, onHighlightToggle, marksNothing, inexactMarks = [], showMarkDiagnostics = false, layout, maximized = false, onMaximizedChange, resizing = false, siteChrome = false, onSiteChromeChange, previewFollowsForm = false, onPreviewFollowsFormChange, reveal, data, isLoading, onMarks, ...frameProps }) => {
     const { ref: viewportRef, width, height } = useElementSize();
     const rootRef = useRef(null);
     const maximizeRef = useRef(null);
@@ -160,13 +160,14 @@ export const PreviewPane = ({ src, path = src, pending = false, mount, previewWi
                             if (isPreviewWidth(value))
                                 onPreviewWidthChange(value);
                         }, allowDeselect: false, size: "xs", w: 96, style: { flexShrink: 0 }, styles: { input: { height: 24, minHeight: 24 } }, comboboxProps: { width: 170, position: 'bottom-end' }, renderOption: ({ option, checked }) => (_jsxs(Group, { gap: 6, wrap: "nowrap", w: "100%", children: [_jsx(IconCheck, { "aria-hidden": true, size: 14, style: { visibility: checked ? 'visible' : 'hidden' } }), _jsx("span", { style: { flex: 1 }, children: option.label }), _jsx(Text, { component: "span", size: "xs", children: WIDTH_OPTIONS.find((o) => o.value === option.value)?.detail })] })) }), width > 0 && (_jsx(Text, { size: "xs", c: "dimmed", "data-testid": "preview-width-readout", style: { flexShrink: 0, whiteSpace: 'nowrap', fontVariantNumeric: 'tabular-nums' }, children: formatPreviewWidthReadout(viewport) })), (onHighlightToggle ||
+                        onPreviewFollowsFormChange ||
                         showChromeToggle ||
                         (showMarkDiagnostics && inexactMarks.length > 0)) && (_jsxs(Group, { gap: 6, wrap: "nowrap", children: [showChromeToggle && onSiteChromeChange && (_jsx(SiteChromeToggle, { enabled: siteChrome, failed: chromeFallback === 'confirmed', onToggle: () => {
                                     setChromeFallback('off');
                                     onSiteChromeChange(!siteChrome);
-                                } })), onHighlightToggle && (_jsx(HighlightToggle, { enabled: Boolean(frameProps.highlightEnabled), onToggle: onHighlightToggle, marksNothing: marksNothing })), showMarkDiagnostics && _jsx(UnmappedMarksChip, { marks: inexactMarks })] })), _jsxs(Group, { gap: 6, wrap: "nowrap", children: [onMaximizedChange && (_jsx(MaximizeToggle, { maximized: maximized, onChange: onMaximizedChange, maximizeRef: maximizeRef, restoreRef: restoreRef })), _jsx(Tooltip, { label: RELOAD_LABEL, children: _jsx(ActionIcon, { ref: reloadButtonRef, variant: "subtle", size: "md", "aria-label": RELOAD_LABEL, onClick: reload, children: _jsx(IconRefresh, { size: 16 }) }) }), _jsx(Tooltip, { label: OPEN_SAVED_LABEL, children: _jsx(ActionIcon, { component: "a", href: liveSrc, target: "_blank", rel: "noopener noreferrer", variant: "subtle", size: "md", "aria-label": OPEN_SAVED_LABEL, children: _jsx(IconExternalLink, { size: 16 }) }) })] })] }), notice, _jsxs(Box, { ref: viewportRef, pos: "relative", style: { flex: '1 1 auto', minHeight: 0 }, children: [frame ? (_jsx(PreviewFrame, { src: frame.src, path: frame.path, ...frameProps, 
+                                } })), onPreviewFollowsFormChange && (_jsx(FollowFormToggle, { enabled: previewFollowsForm, onToggle: () => onPreviewFollowsFormChange(!previewFollowsForm) })), onHighlightToggle && (_jsx(HighlightToggle, { enabled: Boolean(frameProps.highlightEnabled), onToggle: onHighlightToggle, marksNothing: marksNothing })), showMarkDiagnostics && _jsx(UnmappedMarksChip, { marks: inexactMarks })] })), _jsxs(Group, { gap: 6, wrap: "nowrap", children: [onMaximizedChange && (_jsx(MaximizeToggle, { maximized: maximized, onChange: onMaximizedChange, maximizeRef: maximizeRef, restoreRef: restoreRef })), _jsx(Tooltip, { label: RELOAD_LABEL, children: _jsx(ActionIcon, { ref: reloadButtonRef, variant: "subtle", size: "md", "aria-label": RELOAD_LABEL, onClick: reload, children: _jsx(IconRefresh, { size: 16 }) }) }), _jsx(Tooltip, { label: OPEN_SAVED_LABEL, children: _jsx(ActionIcon, { component: "a", href: liveSrc, target: "_blank", rel: "noopener noreferrer", variant: "subtle", size: "md", "aria-label": OPEN_SAVED_LABEL, children: _jsx(IconExternalLink, { size: 16 }) }) })] })] }), notice, _jsxs(Box, { ref: viewportRef, pos: "relative", style: { flex: '1 1 auto', minHeight: 0 }, children: [frame ? (_jsx(PreviewFrame, { src: frame.src, path: frame.path, ...frameProps, 
                         // A held page gets no draft and its reports go nowhere: it belongs to another entry.
-                        data: pending ? undefined : data, isLoading: pending ? undefined : isLoading, onMarks: pending ? undefined : onMarks, onPreviewError: pending ? undefined : frameProps.onPreviewError, busy: pending, onSiteChrome: onSiteChrome, onReload: () => {
+                        data: pending ? undefined : data, isLoading: pending ? undefined : isLoading, onMarks: pending ? undefined : onMarks, reveal: pending ? undefined : reveal, onPreviewError: pending ? undefined : frameProps.onPreviewError, busy: pending, onSiteChrome: onSiteChrome, onReload: () => {
                             // Retry goes with the frame it sits in; the toolbar's reload offers the same action.
                             reload();
                             reloadButtonRef.current?.focus();

package/dist/editor/PreviewToolbarTools.d.ts

@@ -8,6 +8,12 @@ export interface HighlightToggleProps {
 }
 /** Turns preview highlights on and off; says so when the page marks nothing to highlight. */
 export declare function HighlightToggle({ enabled, onToggle, marksNothing }: HighlightToggleProps): import("react/jsx-runtime").JSX.Element;
+export interface FollowFormToggleProps {
+    enabled: boolean;
+    onToggle: () => void;
+}
+/** Turns on and off the preview following the form to the field it is on. */
+export declare function FollowFormToggle({ enabled, onToggle }: FollowFormToggleProps): import("react/jsx-runtime").JSX.Element;
 export interface SiteChromeToggleProps {
     enabled: boolean;
     onToggle: () => void;

package/dist/editor/PreviewToolbarTools.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useRef, useState } from 'react';
 import { ActionIcon, Button, Group, Popover, Stack, Text, Tooltip, UnstyledButton, VisuallyHidden, } from '@mantine/core';
-import { IconArrowsMaximize, IconArrowsMinimize, IconLayoutNavbar, IconMarquee, } from '@tabler/icons-react';
+import { IconArrowsMaximize, IconArrowsMinimize, IconFocusCentered, IconLayoutNavbar, IconMarquee, } from '@tabler/icons-react';
 const HIGHLIGHT_LABEL = 'Highlight fields in the preview';
 const NOTHING_MARKED_NOTE = "This page marks no editable elements, so nothing can be highlighted or clicked to focus. The site's developer can mark them with fieldProps.";
 /** Turns preview highlights on and off; says so when the page marks nothing to highlight. */
@@ -11,6 +11,11 @@ export function HighlightToggle({ enabled, onToggle, marksNothing = false }) {
     const showNote = enabled && marksNothing;
     return (_jsxs(Group, { gap: 4, wrap: "nowrap", children: [_jsx(Tooltip, { label: HIGHLIGHT_LABEL, children: _jsx(ActionIcon, { variant: enabled ? 'filled' : 'subtle', color: enabled ? 'brand' : 'gray', size: "md", "aria-pressed": enabled, "aria-label": HIGHLIGHT_LABEL, "aria-describedby": showNote ? noteId : undefined, "data-testid": "toggle-highlights-button", onClick: onToggle, children: _jsx(IconMarquee, { size: 16 }) }) }), showNote && (_jsx(Tooltip, { label: NOTHING_MARKED_NOTE, multiline: true, w: 260, children: _jsxs(Text, { size: "xs", c: "dimmed", style: { whiteSpace: 'nowrap' }, children: ["Nothing to highlight", _jsx(VisuallyHidden, { id: noteId, children: NOTHING_MARKED_NOTE })] }) }))] }));
 }
+const FOLLOW_FORM_LABEL = "Scroll the preview to the field you're on";
+/** Turns on and off the preview following the form to the field it is on. */
+export function FollowFormToggle({ enabled, onToggle }) {
+    return (_jsx(Tooltip, { label: FOLLOW_FORM_LABEL, children: _jsx(ActionIcon, { variant: enabled ? 'filled' : 'subtle', color: enabled ? 'brand' : 'gray', size: "md", "aria-pressed": enabled, "aria-label": FOLLOW_FORM_LABEL, "data-testid": "toggle-follow-form-button", onClick: onToggle, children: _jsx(IconFocusCentered, { size: 16 }) }) }));
+}
 const SITE_CHROME_LABEL = 'Show site header and footer';
 const SITE_CHROME_FAILED_NOTE = "The site couldn't show its header and footer, so the preview shows pages without them. Turn this off and on, or reload the preview, to try again.";
 /** Shows and hides the site's header and footer; says so when the site couldn't show them. */

package/dist/editor/comments/CommentThreadsPopover.d.ts

@@ -33,6 +33,8 @@ export interface CommentThreadsPopoverProps {
      * Shown before anyone types; the box stays usable, so a draft survives until it can be posted.
      */
     composeBlockedReason?: string;
+    /** Called each time the popover opens, by any route. */
+    onOpened?: () => void;
     testId: string;
 }
 export interface OpenRequest {

package/dist/editor/comments/CommentThreadsPopover.js

@@ -24,7 +24,7 @@ const openThreadsLabel = (count) => count === 1 ? '1 open thread' : `${count} op
  * with reply and Resolve, and a box for a new thread. Comments stay open on a read-only form,
  * since reviewers comment on submitted branches.
  */
-export const CommentThreadsPopover = ({ threads, subject, variant, revealed = false, anchors, openRequest, currentUserId, canResolve, onAddComment, onResolveThread, onGetUserMetadata, highlightThreadId, threadFieldLabel, composeBlockedReason, testId, }) => {
+export const CommentThreadsPopover = ({ threads, subject, variant, revealed = false, anchors, openRequest, currentUserId, canResolve, onAddComment, onResolveThread, onGetUserMetadata, highlightThreadId, threadFieldLabel, composeBlockedReason, onOpened, testId, }) => {
     const [opened, setOpened] = useState(false);
     const [composing, setComposing] = useState(false);
     // Drafts live here, not in the dropdown, which unmounts whenever the popover closes.
@@ -139,6 +139,14 @@ export const CommentThreadsPopover = ({ threads, subject, variant, revealed = fa
         }, 20);
         return () => window.clearTimeout(timer);
     }, [opened]);
+    const onOpenedRef = useRef(onOpened);
+    useEffect(() => {
+        onOpenedRef.current = onOpened;
+    });
+    useEffect(() => {
+        if (opened)
+            onOpenedRef.current?.();
+    }, [opened]);
     useEffect(() => {
         if (!flashThreadId)
             return;

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/comments/ThreadReplyControls.js

@@ -1,9 +1,10 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
-import { Button, Group, Stack, Textarea } from '@mantine/core';
+import { Button, Group, Stack, Textarea, Tooltip } from '@mantine/core';
 import { moveFocusIfUnmoved } from './move-focus-if-unmoved.js';
 import { CommentWriteAlert, toCommentWriteFailure, } from './CommentWriteAlert.js';
+const RESOLVE_BLOCKED_REASON = "Only the person who started this thread or a reviewer can resolve it. Reply to let them know it's done.";
 /** Refocuses `box` when a submit settles: the busy button disabled itself and dropped focus. */
 export const useRefocusAfterSubmit = (submitting, box) => {
     const wasSubmitting = useRef(false);
@@ -90,6 +91,8 @@ export const ThreadReplyControls = ({ thread, onAddReply, onResolve, focusAfterR
         }
     };
     const mayResolve = canResolve || thread.authorId === currentUserId;
-    const resolveButton = mayResolve && (_jsx(Button, { variant: "light", color: "green", onClick: handleResolve, loading: resolving, disabled: replying, "data-testid": "resolve-thread-button", children: hasDraft ? 'Reply and resolve' : 'Resolve' }));
+    // Shown disabled with its reason rather than hidden: the same user may resolve threads they start.
+    // `data-disabled` without native `disabled` keeps it focusable, so the Tooltip can open on focus.
+    const resolveButton = mayResolve ? (_jsx(Button, { variant: "light", color: "green", onClick: handleResolve, loading: resolving, disabled: replying, "data-testid": "resolve-thread-button", children: hasDraft ? 'Reply and resolve' : 'Resolve' })) : (_jsx(Tooltip, { label: RESOLVE_BLOCKED_REASON, multiline: true, maw: 280, events: { hover: true, focus: true, touch: true }, children: _jsx(Button, { variant: "light", color: "green", "data-disabled": true, "aria-disabled": true, onClick: (e) => e.preventDefault(), "data-testid": "resolve-thread-button", children: "Resolve" }) }));
     return (_jsxs(Stack, { gap: "xs", children: [error && _jsx(CommentWriteAlert, { failure: error, onClose: () => setError(null) }), expanded ? (_jsxs(_Fragment, { children: [_jsx(Textarea, { ref: boxRef, placeholder: "Write a reply\u2026", "aria-label": "Reply to this thread", value: replyText, onChange: (e) => setReplyText(e.target.value), minRows: 2, disabled: replying || resolving }), _jsxs(Group, { gap: "xs", children: [_jsx(Button, { onClick: handleReply, loading: replying, disabled: !replyText.trim() || resolving, "data-testid": "submit-reply-button", children: "Reply" }), _jsx(Button, { variant: "subtle", color: "gray", onClick: collapse, disabled: replying, children: "Cancel" }), resolveButton] })] })) : (_jsxs(Group, { gap: "xs", children: [_jsx(Button, { ref: replyButtonRef, variant: "light", onClick: expand, disabled: resolving, "data-testid": "reply-thread-button", children: "Reply\u2026" }), resolveButton] }))] }));
 };

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';