@ptengine/inline-editor 0.1.6 → 0.1.8

package/dist/kernel/selection/buildRootShelf.js

@@ -19,6 +19,8 @@ const SAME_TOP_PX = 2;
 const CHROME_ROWS_CAP = 5;
 const CHROME_TAGS = new Set(['header', 'nav', 'footer']);
 const TEXT_LEAF_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'a', 'button', 'span']);
+const isTextLeaf = (n) => n.tag === 'img' || (TEXT_LEAF_TAGS.has(n.tag) && n.textSummary.trim().length > 0);
+const hasContent = (n) => isTextLeaf(n) || !!n.image || n.textSummary.trim().length > 0 || n.children.some(c => !c.hidden && hasContent(c));
 function analyzeBlockRoots(root, opts) {
     const viewportWidth = typeof opts.viewportWidth === 'number' && opts.viewportWidth > 0
         ? opts.viewportWidth
@@ -76,13 +78,23 @@ function analyzeBlockRoots(root, opts) {
         for (const e of entries)
             e.demoted = false;
     }
-    const isCandidate = (e) => e.landmark && !e.demoted;
     const entryBySelector = new Map();
     for (const e of entries)
         if (!entryBySelector.has(e.node.selector))
             entryBySelector.set(e.node.selector, e);
+    const memberBoxes = new Set();
+    for (const b of opts.blocks ?? []) {
+        for (const member of b.members) {
+            const e = entryBySelector.get(member.selector);
+            const r = e?.node.rect;
+            if (e && r && r.height > 0 && r.width >= minWidth)
+                memberBoxes.add(e);
+        }
+    }
+    const isCandidate = (e) => (e.landmark || memberBoxes.has(e)) && !e.demoted;
     const claimed = new Map();
     const blocksIn = new Map();
+    const memberEntries = new Set();
     const addTo = (m, e, id) => {
         let set = m.get(e);
         if (!set)
@@ -91,14 +103,17 @@ function analyzeBlockRoots(root, opts) {
     };
     for (const b of opts.blocks ?? []) {
         for (const member of b.members) {
-            let e = entryBySelector.get(member.selector) ?? null;
-            while (e && !isCandidate(e))
-                e = e.parent;
-            if (!e)
+            const own = entryBySelector.get(member.selector);
+            if (!own)
                 continue;
-            addTo(claimed, e, b.id);
-            for (let a = e; a; a = a.parent)
+            memberEntries.add(own);
+            for (let a = own; a; a = a.parent)
                 addTo(blocksIn, a, b.id);
+            let e = own;
+            while (e && !isCandidate(e))
+                e = e.parent;
+            if (e)
+                addTo(claimed, e, b.id);
         }
     }
     const modelBlockCount = (e) => blocksIn.get(e)?.size ?? 0;
@@ -126,7 +141,7 @@ function analyzeBlockRoots(root, opts) {
     for (const e of [...candidates].reverse()) {
         const ks = kids.get(e) ?? [];
         let unit;
-        if (isAtomic(e))
+        if (isAtomic(e) && (memberEntries.has(e) || ks.length < 2))
             unit = true;
         else if (modelBlockCount(e) >= 2)
             unit = ks.length === 0;
@@ -148,6 +163,25 @@ function analyzeBlockRoots(root, opts) {
         }
     };
     takeRoots(tops);
+    const rootSet = new Set(blockRoots);
+    const holdsRoot = new Set();
+    for (const r of blockRoots)
+        for (let a = r.parent; a; a = a.parent)
+            holdsRoot.add(a);
+    const layers = new Set(blockRoots.map(r => r.parent?.node ?? root));
+    for (const layer of layers) {
+        if (laysOutInRow(layer))
+            continue;
+        for (const child of layer.children) {
+            const e = entryOf.get(child);
+            if (!e || rootSet.has(e) || holdsRoot.has(e) || e.landmark || e.demoted || e.chromeKey !== null)
+                continue;
+            const r = child.rect;
+            if (r && r.height > 0 && r.width >= minWidth && hasContent(child))
+                blockRoots.push(e);
+        }
+    }
+    blockRoots.sort((a, b) => a.order - b.order);
     const blockIdOf = (e) => {
         const ids = blocksIn.get(e);
         return ids && ids.size === 1 ? [...ids][0] : undefined;
@@ -226,7 +260,6 @@ export function buildRootShelf(root, opts) {
             chromeRows.set(e.chromeKey, (chromeRows.get(e.chromeKey) ?? 0) + 1);
         return true;
     };
-    const isTextLeaf = (n) => n.tag === 'img' || (TEXT_LEAF_TAGS.has(n.tag) && n.textSummary.trim().length > 0);
     const leavesPerBlock = landmarks.length
         ? Math.min(LEAVES_PER_LANDMARK, Math.max(1, Math.floor((limit - landmarks.length) / landmarks.length)))
         : LEAVES_PER_LANDMARK;

package/dist/kernel/useCanvasSession.d.ts

@@ -32,6 +32,13 @@ export declare function useCanvasSession(input: {
     device: CanvasDevice;
     /** agent 主动发来的流（lifecycle / geometry / elementPicked / …）转出去给 useCanvasStream 消费。 */
     onStreamEvent?: (msg: CanvasStreamMessage) => void;
+    /**
+     * 递增即按同一 url/device **重建会话**（新 sessionId、新 iframe）。
+     *
+     * 交互模式里用户点链接让画布整页跳走后，退出时要回到实验页：同会话里跳走的文档
+     * 不是编辑对象（拾取没开、改动没放），只能整个重开 —— 与切设备同一条路。
+     */
+    reloadKey?: number;
 }): {
     state: State;
     reason: LoadFailedReason | undefined;

package/dist/kernel/useCanvasSession.js

@@ -177,6 +177,6 @@ export function useCanvasSession(input) {
             void sendCanvasCommand({ command: 'destroy', sessionId }).catch(() => { });
             port?.disconnect();
         };
-    }, [input.url, input.device]);
+    }, [input.url, input.device, input.reloadKey]);
     return { state, reason, portError, frameProps, handshake, readyPayload, capabilities };
 }

package/dist/locales.d.ts

@@ -54,6 +54,7 @@ export declare const zhCN: {
             title: string;
             pickTarget: string;
             cancel: string;
+            confirm: string;
             position: string;
             top: string;
             bottom: string;
@@ -89,6 +90,12 @@ export declare const zhCN: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -234,6 +241,7 @@ export declare const enUS: {
             title: string;
             pickTarget: string;
             cancel: string;
+            confirm: string;
             position: string;
             top: string;
             bottom: string;
@@ -269,6 +277,12 @@ export declare const enUS: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -414,6 +428,7 @@ export declare const jaJP: {
             title: string;
             pickTarget: string;
             cancel: string;
+            confirm: string;
             position: string;
             top: string;
             bottom: string;
@@ -449,6 +464,12 @@ export declare const jaJP: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -553,6 +574,9 @@ export declare const inlineEditorLocales: {
     readonly 'zh-CN': {
         readonly inlineCanvas: {
             readonly review: {
+                readonly pageLoadFailed: "目标页面无法加载";
+                readonly pageLoadHint: "请返回检查页面地址、网站访问权限和网络连接后重试。";
+                readonly backFromFailed: "返回修改";
                 readonly generating: "正在生成截图…";
                 readonly noLayers: "没有匹配的图层";
                 readonly clearSearch: "清除搜索";
@@ -641,6 +665,7 @@ export declare const inlineEditorLocales: {
                 title: string;
                 pickTarget: string;
                 cancel: string;
+                confirm: string;
                 position: string;
                 top: string;
                 bottom: string;
@@ -676,6 +701,12 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
             readonly version: {
                 switching: string;
             };
@@ -779,6 +810,9 @@ export declare const inlineEditorLocales: {
     readonly 'en-US': {
         readonly inlineCanvas: {
             readonly review: {
+                readonly pageLoadFailed: "Unable to load the target page";
+                readonly pageLoadHint: "Go back to check the page URL, site permissions and network connection, then retry.";
+                readonly backFromFailed: "Go back";
                 readonly generating: "Generating screenshot…";
                 readonly noLayers: "No matching layers";
                 readonly clearSearch: "Clear search";
@@ -867,6 +901,7 @@ export declare const inlineEditorLocales: {
                 title: string;
                 pickTarget: string;
                 cancel: string;
+                confirm: string;
                 position: string;
                 top: string;
                 bottom: string;
@@ -902,6 +937,12 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
             readonly version: {
                 switching: string;
             };
@@ -1005,6 +1046,9 @@ export declare const inlineEditorLocales: {
     readonly 'ja-JP': {
         readonly inlineCanvas: {
             readonly review: {
+                readonly pageLoadFailed: "対象ページを読み込めません";
+                readonly pageLoadHint: "戻ってページ URL、サイトへのアクセス権限、ネットワーク接続を確認して再試行してください。";
+                readonly backFromFailed: "戻って修正";
                 readonly generating: "スクリーンショットを生成中…";
                 readonly noLayers: "一致するレイヤーがありません";
                 readonly clearSearch: "検索をクリア";
@@ -1093,6 +1137,7 @@ export declare const inlineEditorLocales: {
                 title: string;
                 pickTarget: string;
                 cancel: string;
+                confirm: string;
                 position: string;
                 top: string;
                 bottom: string;
@@ -1128,6 +1173,12 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
             readonly version: {
                 switching: string;
             };

package/dist/locales.js

@@ -44,6 +44,7 @@ export const zhCN = {
             title: '移动元素',
             pickTarget: '在画布里点选目标元素',
             cancel: '取消移动',
+            confirm: '确认移动',
             position: '相对目标的位置',
             top: '移入开头',
             bottom: '移入末尾',
@@ -79,6 +80,12 @@ export const zhCN = {
             pc: 'PC',
             mobile: '移动'
         },
+        interactive: {
+            enter: '交互模式',
+            tips: '切换到交互模式可以对页面进行交互，以修改需要交互后才能看到的内容。',
+            active: '您当前正在交互模式',
+            exit: '返回编辑模式'
+        },
         version: {
             switching: '正在切换版本，请稍候'
         },
@@ -224,6 +231,7 @@ export const enUS = {
             title: 'Move element',
             pickTarget: 'Pick a target element on the canvas',
             cancel: 'Cancel move',
+            confirm: 'Confirm move',
             position: 'Position relative to target',
             top: 'Inside, first',
             bottom: 'Inside, last',
@@ -259,6 +267,12 @@ export const enUS = {
             pc: 'Desktop',
             mobile: 'Mobile'
         },
+        interactive: {
+            enter: 'Interactive mode',
+            tips: 'Switch to interactive mode to interact with the page like in a live website.',
+            active: 'You are now in interactive mode',
+            exit: 'Back to edit mode'
+        },
         version: {
             switching: 'Switching version, please wait'
         },
@@ -404,6 +418,7 @@ export const jaJP = {
             title: '要素を移動',
             pickTarget: 'キャンバスで対象要素を選択',
             cancel: '移動をキャンセル',
+            confirm: '移動を確定',
             position: '対象に対する位置',
             top: '内側の先頭',
             bottom: '内側の末尾',
@@ -439,6 +454,12 @@ export const jaJP = {
             pc: 'PC',
             mobile: 'モバイル'
         },
+        interactive: {
+            enter: '画面操作モード',
+            tips: '画面操作できるようになります。表示されていない要素を開き、その後編集モードに切り替えることで隠れた要素を変更することが可能です。',
+            active: '現在、画面操作モードです',
+            exit: '編集モードに戻る'
+        },
         version: {
             switching: 'バージョンを切り替えています。しばらくお待ちください'
         },

package/dist/panels/MovePositionControls.d.ts

@@ -0,0 +1,6 @@
+import type { MovePosition } from '../kernel/moveState.js';
+export declare function MovePositionControls({ onConfirm, onCancel, onError }: {
+    onConfirm: (position: MovePosition) => Promise<void>;
+    onCancel: () => void;
+    onError: (error: unknown) => void;
+}): import("react").JSX.Element;

package/dist/panels/MovePositionControls.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button, ToggleGroup, ToggleGroupItem } from '@ptengine/design-components';
+const positions = ['top', 'bottom', 'before', 'after'];
+export function MovePositionControls({ onConfirm, onCancel, onError }) {
+    const { t } = useTranslation();
+    const [position, setPosition] = useState(null);
+    const [pending, setPending] = useState(false);
+    const submitting = useRef(false);
+    const confirm = async () => {
+        if (!position || submitting.current)
+            return;
+        submitting.current = true;
+        setPending(true);
+        try {
+            await onConfirm(position);
+        }
+        catch (error) {
+            onError(error);
+        }
+        finally {
+            submitting.current = false;
+            setPending(false);
+        }
+    };
+    return (_jsxs("div", { className: "flex w-full min-w-0 flex-col gap-2.5", children: [_jsx("span", { className: "text-xs text-muted-foreground", children: t('inlineCanvas.move.position') }), _jsxs("div", { className: "flex flex-col items-stretch gap-3", children: [_jsx(ToggleGroup, { type: "single", variant: "outline", value: position ?? '', disabled: pending, "aria-label": t('inlineCanvas.move.position'), onValueChange: value => {
+                            if (positions.includes(value)) {
+                                setPosition(value);
+                            }
+                        }, style: {
+                            display: 'grid',
+                            gridTemplateColumns: 'repeat(4, minmax(0, 1fr))'
+                        }, children: positions.map(pos => (_jsx(ToggleGroupItem, { value: pos, "data-testid": `move-position-${pos}`, children: t(`inlineCanvas.move.${pos}`) }, pos))) }), _jsxs("div", { className: "flex items-center justify-end gap-2", children: [_jsx(Button, { size: "default", variant: "secondary", type: "button", "data-testid": "move-cancel", disabled: pending, onClick: onCancel, children: t('inlineCanvas.move.cancel') }), _jsx(Button, { size: "default", type: "button", "data-testid": "move-confirm", disabled: !position || pending, onClick: () => void confirm(), children: t('inlineCanvas.move.confirm') })] })] })] }));
+}

package/dist/panels/StylePanel.d.ts

@@ -22,9 +22,11 @@ export interface StylePanelProps {
     capabilities: ElementCapabilities | null;
     /** 元素当前的 author 层声明，用作输入框初值。 */
     declaredStyles?: Record<string, string>;
+    /** Only these properties have an editor override that can be cleared. */
+    resettableProperties?: string[];
     /** 提交一条样式改动。由宿主接到 `changeList.addStyle`。 */
     onApply: (property: string, value: string) => void | Promise<unknown>;
     onClose: () => void;
     onReset?: (property: string) => void;
 }
-export declare function StylePanel({ anchor, tag, capabilities, declaredStyles, onApply, onReset, onClose }: StylePanelProps): import("react").JSX.Element | null;
+export declare function StylePanel({ anchor, tag, capabilities, declaredStyles, resettableProperties, onApply, onReset, onClose }: StylePanelProps): import("react").JSX.Element | null;

package/dist/panels/StylePanel.js

@@ -4,7 +4,7 @@ import { useTranslation } from 'react-i18next';
 import { X } from 'lucide-react';
 import { Button, InputGroup, InputGroupInput, InputGroupAddon, InputGroupText, Label, NativeSelect, Separator } from '@ptengine/design-components';
 import { composeStyleValue, visibleSections } from './styleFields.js';
-export function StylePanel({ anchor, tag, capabilities, declaredStyles = {}, onApply, onReset, onClose }) {
+export function StylePanel({ anchor, tag, capabilities, declaredStyles = {}, resettableProperties, onApply, onReset, onClose }) {
     const { t } = useTranslation();
     const sections = visibleSections(capabilities);
     const panelRef = useRef(null);
@@ -88,7 +88,10 @@ export function StylePanel({ anchor, tag, capabilities, declaredStyles = {}, onA
                     drag.current = null;
                 }, onLostPointerCapture: () => {
                     drag.current = null;
-                }, className: "flex cursor-grab touch-none select-none h-11 shrink-0 items-center justify-between border-b\n                border-[#EBECF0] bg-[#F4F5F7] px-3.5", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("code", { className: "text-xs text-[#6B778C]", children: ["<", tag, ">"] }), _jsx("span", { className: "text-[13px] font-semibold text-[#091E42]", children: t(`taginfo.${tag.toUpperCase()}`, tag) })] }), _jsx(Button, { variant: "ghost", size: "icon", "aria-label": t('inlineCanvas.chrome.close', '关闭'), "data-testid": "inline-style-panel-close", onClick: onClose, children: _jsx(X, { className: "size-4" }) })] }), _jsx("div", { className: "min-h-0 flex-1 flex-col overflow-y-auto", children: sections.map((section, index) => (_jsxs("section", { "data-testid": `style-section-${section.id}`, className: "flex flex-col gap-3 px-3.5 py-3.5", children: [index > 0 && _jsx(Separator, { className: "-mt-3.5 mb-0.5" }), _jsx("p", { className: "text-xs font-semibold text-[#091E42]", children: t(section.labelKey) }), _jsx("div", { className: "grid grid-cols-2 gap-2.5", children: section.fields.map(field => (_jsx(StyleFieldInput, { field: field, initial: declaredStyles[field.property] ?? '', onApply: onApply, onReset: onReset }, field.property))) })] }, section.id))) }), _jsx("footer", { className: "shrink-0 bg-[#F7F8F9] px-3.5 py-3 text-xs leading-5 text-[#6B778C]", children: t('inlineCanvas.style.footnote', '每次改动都会记入改动清单，可单条撤销') })] }));
+                }, className: "flex cursor-grab touch-none select-none h-11 shrink-0 items-center justify-between border-b\n                border-[#EBECF0] bg-[#F4F5F7] px-3.5", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("code", { className: "text-xs text-[#6B778C]", children: ["<", tag, ">"] }), _jsx("span", { className: "text-[13px] font-semibold text-[#091E42]", children: t(`taginfo.${tag.toUpperCase()}`, tag) })] }), _jsx(Button, { variant: "ghost", size: "icon", "aria-label": t('inlineCanvas.chrome.close', '关闭'), "data-testid": "inline-style-panel-close", onClick: onClose, children: _jsx(X, { className: "size-4" }) })] }), _jsx("div", { className: "min-h-0 flex-1 flex-col overflow-y-auto", children: sections.map((section, index) => (_jsxs("section", { "data-testid": `style-section-${section.id}`, className: "flex flex-col gap-3 px-3.5 py-3.5", children: [index > 0 && _jsx(Separator, { className: "-mt-3.5 mb-0.5" }), _jsx("p", { className: "text-xs font-semibold text-[#091E42]", children: t(section.labelKey) }), _jsx("div", { className: "grid grid-cols-2 gap-2.5", children: section.fields.map(field => (_jsx(StyleFieldInput, { field: field, initial: declaredStyles[field.property] ?? '', onApply: onApply, onReset: resettableProperties === undefined ||
+                                    resettableProperties.includes(field.property)
+                                    ? onReset
+                                    : undefined }, field.property))) })] }, section.id))) }), _jsx("footer", { className: "shrink-0 bg-[#F7F8F9] px-3.5 py-3 text-xs leading-5 text-[#6B778C]", children: t('inlineCanvas.style.footnote', '每次改动都会记入改动清单，可单条撤销') })] }));
 }
 function StyleFieldInput({ field, initial, onApply, onReset }) {
     const { t } = useTranslation();

package/dist/reviewLocales.d.ts

@@ -1,5 +1,8 @@
 export declare const reviewLocales: {
     readonly 'zh-CN': {
+        readonly pageLoadFailed: "目标页面无法加载";
+        readonly pageLoadHint: "请返回检查页面地址、网站访问权限和网络连接后重试。";
+        readonly backFromFailed: "返回修改";
         readonly generating: "正在生成截图…";
         readonly noLayers: "没有匹配的图层";
         readonly clearSearch: "清除搜索";
@@ -46,6 +49,9 @@ export declare const reviewLocales: {
         readonly align_justify: "两端对齐";
     };
     readonly 'en-US': {
+        readonly pageLoadFailed: "Unable to load the target page";
+        readonly pageLoadHint: "Go back to check the page URL, site permissions and network connection, then retry.";
+        readonly backFromFailed: "Go back";
         readonly generating: "Generating screenshot…";
         readonly noLayers: "No matching layers";
         readonly clearSearch: "Clear search";
@@ -92,6 +98,9 @@ export declare const reviewLocales: {
         readonly align_justify: "Justify";
     };
     readonly 'ja-JP': {
+        readonly pageLoadFailed: "対象ページを読み込めません";
+        readonly pageLoadHint: "戻ってページ URL、サイトへのアクセス権限、ネットワーク接続を確認して再試行してください。";
+        readonly backFromFailed: "戻って修正";
         readonly generating: "スクリーンショットを生成中…";
         readonly noLayers: "一致するレイヤーがありません";
         readonly clearSearch: "検索をクリア";

package/dist/reviewLocales.js

@@ -1,5 +1,8 @@
 export const reviewLocales = {
     'zh-CN': {
+        pageLoadFailed: '目标页面无法加载',
+        pageLoadHint: '请返回检查页面地址、网站访问权限和网络连接后重试。',
+        backFromFailed: '返回修改',
         generating: '正在生成截图…',
         noLayers: '没有匹配的图层', clearSearch: '清除搜索', searchLayers: '搜索图层',
         linkCopied: '链接已复制',
@@ -44,6 +47,9 @@ export const reviewLocales = {
         align_justify: '两端对齐'
     },
     'en-US': {
+        pageLoadFailed: 'Unable to load the target page',
+        pageLoadHint: 'Go back to check the page URL, site permissions and network connection, then retry.',
+        backFromFailed: 'Go back',
         generating: 'Generating screenshot…',
         noLayers: 'No matching layers', clearSearch: 'Clear search', searchLayers: 'Search layers',
         linkCopied: 'Link copied',
@@ -88,6 +94,9 @@ export const reviewLocales = {
         align_justify: 'Justify'
     },
     'ja-JP': {
+        pageLoadFailed: '対象ページを読み込めません',
+        pageLoadHint: '戻ってページ URL、サイトへのアクセス権限、ネットワーク接続を確認して再試行してください。',
+        backFromFailed: '戻って修正',
         generating: 'スクリーンショットを生成中…',
         noLayers: '一致するレイヤーがありません', clearSearch: '検索をクリア', searchLayers: 'レイヤーを検索',
         linkCopied: 'リンクをコピーしました',

package/dist/useInlineEditor.d.ts

@@ -42,8 +42,11 @@ export interface InlineEditorSelection {
     declaredStyles: Record<string, string>;
 }
 export interface UseInlineEditorInput {
+    onHistoryShortcut?: (direction: 'undo' | 'redo') => void;
     url: string;
     device: CanvasDevice;
+    /** 递增即按同一 url/device 重建画布会话（见 `useCanvasSession` 的同名参数）。 */
+    reloadKey?: number;
     /** change list 变化时回调 —— 宿主自己决定存哪（本 hook 不做持久化）。 */
     onChangesChange?: (changes: InlineChange[]) => void;
     /**
@@ -109,6 +112,18 @@ export interface UseInlineEditorResult {
      */
     mobileFit: MobileFitState;
     changeList: ReturnType<typeof useChangeList>;
+    /**
+     * 交互模式：画布上的拾取关掉，点击/悬停/输入原样交给客户页（打开弹窗、切换页签、展开折叠
+     * 之后再改那些「交互后才看得见」的内容）。对应老编辑器（engage-editor）顶栏的「交互模式」。
+     */
+    interactive: boolean;
+    /**
+     * 进出交互模式。退出时返回 `navigated`：交互期间画布整页跳走过（点了链接 / 提交了表单）。
+     * 跳走的文档不是编辑对象，调用方应重建会话（`reloadKey`）回到实验页，而不是在新页上继续编辑。
+     */
+    setInteractive: (on: boolean) => Promise<{
+        navigated: boolean;
+    }>;
     commands: {
         /** 选中某个元素（点路径选择器的某一级、或程序化选中）。空串 = 清空。 */
         select: (selector: string) => Promise<void>;

package/dist/useInlineEditor.js

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { CANVAS_MSG_NAMESPACE } from '@ptengine/inline-core/protocol';
 import { useCanvasSession } from './kernel/useCanvasSession.js';
 import { useCanvasStream } from './kernel/useCanvasStream.js';
 import { useMobileFit } from './kernel/useMobileFit.js';
@@ -37,7 +38,12 @@ export function useInlineEditor(input) {
         });
     }, []);
     const [readySessionId, setReadySessionId] = useState(null);
+    const [interactive, setInteractiveState] = useState(false);
+    const interactiveRef = useRef(false);
+    const navigatedRef = useRef(false);
     const onLifecycle = useCallback((payload, eventSessionId) => {
+        if (payload.phase === 'navAway' && interactiveRef.current)
+            navigatedRef.current = true;
         if (payload.phase !== 'domReady' && payload.phase !== 'loaded')
             return;
         if (!eventSessionId)
@@ -49,10 +55,24 @@ export function useInlineEditor(input) {
         documentSizeRef.current?.(payload);
     }, []);
     const stream = useCanvasStream(undefined, geometry.onGeometry, onTextEditCommit, onLifecycle, onDocumentSize);
+    const historyShortcutRef = useRef(input.onHistoryShortcut);
+    historyShortcutRef.current = input.onHistoryShortcut;
+    const onStreamEvent = useCallback((msg) => {
+        if (msg.namespace === CANVAS_MSG_NAMESPACE && msg.event === 'historyShortcut') {
+            if (interactiveRef.current)
+                return;
+            const direction = msg.payload?.direction;
+            if (direction === 'undo' || direction === 'redo')
+                historyShortcutRef.current?.(direction);
+        }
+        else
+            stream.onStreamEvent(msg);
+    }, [stream.onStreamEvent]);
     const session = useCanvasSession({
         url: input.url,
         device: input.device,
-        onStreamEvent: stream.onStreamEvent
+        onStreamEvent,
+        reloadKey: input.reloadKey
     });
     const sessionId = session.frameProps?.sessionId;
     const changeList = useChangeList(sessionId, {
@@ -109,6 +129,9 @@ export function useInlineEditor(input) {
     const geometryReset = geometry.reset;
     const streamReset = stream.reset;
     useEffect(() => {
+        interactiveRef.current = false;
+        navigatedRef.current = false;
+        setInteractiveState(false);
         setSelection_(null);
         setTree(null);
         treeForRef.current = null;
@@ -147,6 +170,35 @@ export function useInlineEditor(input) {
             ? graftSubtree(prev, anchorId, root, { renderIcon: renderIconRef.current })
             : prev);
     }, [sessionId]);
+    const treeLoaded = tree !== null;
+    const [treeEpoch, setTreeEpoch] = useState(0);
+    const contentRevision = changeList.list
+        .filter(record => ['elementContent', 'elementText', 'elementMove'].includes(record.change.type))
+        .map(record => record.changeId)
+        .join('|')
+        .concat(`#${treeEpoch}`);
+    const refreshedContent = useRef('#0');
+    useEffect(() => {
+        if (!wantTree ||
+            !domReady ||
+            !sessionId ||
+            !treeRef.current ||
+            refreshedContent.current === contentRevision)
+            return;
+        let cancelled = false;
+        const loaded = Object.values(treeRef.current.nodes);
+        void getDomTree(sessionId, { maxDepth: 16, maxNodes: Math.max(1500, loaded.length) })
+            .then(root => {
+            if (!cancelled) {
+                refreshedContent.current = contentRevision;
+                setTree(adaptDomTree(root, { renderIcon: renderIconRef.current }));
+            }
+        })
+            .catch(() => { });
+        return () => {
+            cancelled = true;
+        };
+    }, [contentRevision, domReady, sessionId, wantTree, treeLoaded]);
     const revealAttemptedRef = useRef(new Set());
     const selectedSelector = selection?.selector ?? null;
     const selectionChain = selection?.chain;
@@ -332,6 +384,41 @@ export function useInlineEditor(input) {
             }));
         }
     }), [graftAt, input.iframeRef, preserveScroll, refresh, sessionId]);
+    const setInteractive = useCallback(async (on) => {
+        if (!sessionId)
+            return { navigated: false };
+        if (on) {
+            if (interactiveRef.current)
+                return { navigated: false };
+            interactiveRef.current = true;
+            navigatedRef.current = false;
+            setInteractiveState(true);
+            setMove(null);
+            setSelection_(null);
+            await setHoverTarget(sessionId, '').catch(() => { });
+            await setSelection(sessionId, '').catch(() => { });
+            try {
+                await setPickMode(sessionId, false);
+            }
+            catch (e) {
+                interactiveRef.current = false;
+                setInteractiveState(false);
+                throw e;
+            }
+            return { navigated: false };
+        }
+        if (!interactiveRef.current)
+            return { navigated: false };
+        const navigated = navigatedRef.current;
+        interactiveRef.current = false;
+        navigatedRef.current = false;
+        setInteractiveState(false);
+        if (!navigated) {
+            await setPickMode(sessionId, true);
+            setTreeEpoch(n => n + 1);
+        }
+        return { navigated };
+    }, [sessionId]);
     return useMemo(() => ({
         session,
         frameProps: session.frameProps,
@@ -345,6 +432,8 @@ export function useInlineEditor(input) {
         geometry,
         mobileFit: mobileFit.state,
         changeList,
+        interactive,
+        setInteractive,
         commands
     }), [
         session,
@@ -358,6 +447,8 @@ export function useInlineEditor(input) {
         geometry,
         mobileFit.state,
         changeList,
+        interactive,
+        setInteractive,
         commands
     ]);
 }