@ptengine/inline-editor 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.8
+
+依赖不变（`@ptengine/inline-core` ~0.2.1），可以直接发。
+
+**新增**
+
+- 交互模式（对应 engage-editor 画布工具条上的「交互模式」）：画布条右侧新增开关，进入后关掉拾取，点击、悬停、输入都交给客户页，
+  用来打开弹窗、切换页签、展开折叠，再改那些交互之后才看得见的内容。
+  - 进入时清掉选中与悬停，收起选中框、工具条、样式面板、移动条与区块框；顶栏整条被「您当前正在交互模式 / 返回编辑模式」提示条盖住，
+    图层面板盖一层不可点的遮罩，设备切换禁用，画布发来的与宿主页的 Cmd/Ctrl+Z 都不再触发编辑器撤销；挂 beforeunload 防止页面把产品页带走。
+  - 退出时开回拾取、重拉图层树，并把当前改动按原 changeId 撤了重放一遍（页面脚本可能把改过的元素重渲染掉了；id 不变，AI 卡片的撤销仍对得上）。
+  - 交互中画布整页跳走过（点了链接 / 提交了表单，SW 派生的 `navAway`），退出时按实验地址重建会话，改动走与切设备相同的快照回放，不往跳走后的页面上放。
+  - 切版本、文字编辑、移动拾取、截图进行中时按钮禁用；关拾取失败则不进入。
+  - `InlineEditor` 新增 `interactiveMode`（默认 `true`，只读画布可传 `false`）与 `onInteractiveChange`；headless 层 `useInlineEditor` 新增
+    `interactive` / `setInteractive(on)`（退出返回 `{ navigated }`）与入参 `reloadKey`；`useChangeList` 新增 `reapplyAll()`。
+
 ## 0.1.7
 
 依赖 `@ptengine/inline-core` ~0.2.1（新增 `historyShortcut` 流事件）：**先发 inline-core 0.2.1，再发本版**。

package/dist/InlineEditor.d.ts

@@ -184,6 +184,15 @@ export interface InlineEditorProps {
         activeId?: string | null;
         onHover?: (id: string | null) => void;
     };
+    /**
+     * 「交互模式」按钮。默认 `true`。分析画布这类只看不改的宿主传 `false` 关掉。
+     *
+     * 交互模式 = 拾取关掉、页面原样可点（打开弹窗 / 切页签 / 展开折叠后再改那些交互后才
+     * 看得见的内容），对应老编辑器（engage-editor）画布工具条上的同名开关。
+     */
+    interactiveMode?: boolean;
+    /** 进出交互模式时通知宿主（宿主自己的浮层要不要让路由它决定）。 */
+    onInteractiveChange?: (on: boolean) => void;
     /**
      * 选中变化 → 新的 AI 上下文。`null` = 选中被清空。
      *
@@ -354,4 +363,4 @@ export interface AiApplyApi {
     /** 当前版本 —— 宿主把 agent 给的版本**名**映射成 id 时要知道现在在哪一版。 */
     readonly activeVersionId?: string;
 }
-export declare function InlineEditor({ url, device, onDeviceChange, title, versionLabel, chrome, onExit, onSave, libraryComponents, libraryLoading, onAddVersion, onRenameVersion, removableVersionIds, onRemoveVersion, onPreview, onToggleAi, aiOpen, uploadImage, initialChanges, onHydrated, onAskAi, onPageContextReady, anchors, pageBlocks, onEditorReady, onSessionReady, onAiContextChange, onAiApplyReady, onAiInsertedRemoved, onAiInsertedRestored, trackAiSelection, renderNodeIcon, versions, activeVersionId, versionChanges, onVersionChange, onVersionLeave, onVersionEnter, resolveChangeId, allowedLinkUrls, viewportWidthOverride, blockOverlay }: InlineEditorProps): import("react").JSX.Element;
+export declare function InlineEditor({ url, device, onDeviceChange, title, versionLabel, chrome, onExit, onSave, libraryComponents, libraryLoading, onAddVersion, onRenameVersion, removableVersionIds, onRemoveVersion, onPreview, onToggleAi, aiOpen, uploadImage, initialChanges, onHydrated, onAskAi, onPageContextReady, anchors, pageBlocks, onEditorReady, onSessionReady, onAiContextChange, onAiApplyReady, onAiInsertedRemoved, onAiInsertedRestored, trackAiSelection, renderNodeIcon, versions, activeVersionId, versionChanges, onVersionChange, onVersionLeave, onVersionEnter, resolveChangeId, allowedLinkUrls, viewportWidthOverride, blockOverlay, interactiveMode, onInteractiveChange }: InlineEditorProps): import("react").JSX.Element;

package/dist/InlineEditor.js

@@ -56,14 +56,16 @@ function imageTargetOf(caps) {
     return branch === 'background' ? 'background' : undefined;
 }
 const AI_ELEMENT_IMAGE_LIMIT = 4;
-export function InlineEditor({ url, device, onDeviceChange, title, versionLabel = 'V1', chrome = 'full', onExit, onSave, libraryComponents, libraryLoading, onAddVersion, onRenameVersion, removableVersionIds, onRemoveVersion, onPreview, onToggleAi, aiOpen, uploadImage, initialChanges, onHydrated, onAskAi, onPageContextReady, anchors, pageBlocks, onEditorReady, onSessionReady, onAiContextChange, onAiApplyReady, onAiInsertedRemoved, onAiInsertedRestored, trackAiSelection, renderNodeIcon, versions, activeVersionId, versionChanges, onVersionChange, onVersionLeave, onVersionEnter, resolveChangeId, allowedLinkUrls, viewportWidthOverride, blockOverlay }) {
+export function InlineEditor({ url, device, onDeviceChange, title, versionLabel = 'V1', chrome = 'full', onExit, onSave, libraryComponents, libraryLoading, onAddVersion, onRenameVersion, removableVersionIds, onRemoveVersion, onPreview, onToggleAi, aiOpen, uploadImage, initialChanges, onHydrated, onAskAi, onPageContextReady, anchors, pageBlocks, onEditorReady, onSessionReady, onAiContextChange, onAiApplyReady, onAiInsertedRemoved, onAiInsertedRestored, trackAiSelection, renderNodeIcon, versions, activeVersionId, versionChanges, onVersionChange, onVersionLeave, onVersionEnter, resolveChangeId, allowedLinkUrls, viewportWidthOverride, blockOverlay, interactiveMode = true, onInteractiveChange }) {
     const { t } = useTranslation();
     const canvasAreaRef = useRef(null);
     const canvasIframeRef = useRef(null);
     const insertedRemovedRef = useRef(null);
     const insertedRestoredRef = useRef(null);
     const historyShortcutRef = useRef(() => { });
+    const [reloadKey, setReloadKey] = useState(0);
     const editor = useInlineEditor({
+        reloadKey,
         onHistoryShortcut: direction => historyShortcutRef.current(direction),
         onInsertedRemoved: selectors => insertedRemovedRef.current?.(selectors),
         onInsertedRestored: selectors => insertedRestoredRef.current?.(selectors),
@@ -72,7 +74,7 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
         iframeRef: canvasIframeRef,
         renderNodeIcon
     });
-    const { selection, tree, clipboard, move, capturing, textEditing, geometry, changeList, commands, frameProps, domReady } = editor;
+    const { selection, tree, clipboard, move, capturing, textEditing, geometry, changeList, commands, frameProps, domReady, interactive } = editor;
     const selectAndReveal = useCallback(async (selector) => {
         await commands.select(selector);
         await commands.reveal(selector);
@@ -197,7 +199,7 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
         void run().catch(e => setCommandError(describeCanvasError(e)));
     }, [t]);
     historyShortcutRef.current = direction => {
-        if (!domReady || textEditing || switchingRef.current)
+        if (!domReady || textEditing || switchingRef.current || interactive)
             return;
         uiWrite(() => enqueue(() => direction === 'undo' ? changeListRef.current.undo() : changeListRef.current.redo()));
     };
@@ -248,17 +250,20 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
     const hydratedSessionRef = useRef(null);
     const sessionIdForHydrate = frameProps?.sessionId;
     const deviceSnapshot = useRef(null);
+    const snapshotForRebuild = async () => {
+        await changeListRef.current.whenIdle();
+        const live = changeListRef.current.peekList();
+        deviceSnapshot.current = { version: activeVersionId, changes: live.map(r => r.change) };
+        if (activeVersionId)
+            versionCallbacksRef.current.onVersionLeave?.(activeVersionId, live);
+    };
     const changeDevice = (next) => {
-        if (next === device || switchingRef.current)
+        if (next === device || switchingRef.current || interactive)
             return;
         switchingRef.current = true;
         setSwitching(true);
         void enqueue(async () => {
-            await changeListRef.current.whenIdle();
-            const live = changeListRef.current.peekList();
-            deviceSnapshot.current = { version: activeVersionId, changes: live.map(r => r.change) };
-            if (activeVersionId)
-                versionCallbacksRef.current.onVersionLeave?.(activeVersionId, live);
+            await snapshotForRebuild();
             onDeviceChange(next);
         })
             .catch(error => setCommandError(describeCanvasError(error)))
@@ -267,6 +272,41 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
             setSwitching(false);
         });
     };
+    const interactiveChangeRef = useRef(onInteractiveChange);
+    interactiveChangeRef.current = onInteractiveChange;
+    const canEnterInteractive = interactiveMode && domReady && !switching && !capturing && textEditing === null && !move;
+    const enterInteractive = () => {
+        if (!canEnterInteractive || switchingRef.current)
+            return;
+        setStylePanelOpen(false);
+        setShowChangeList(false);
+        setPasteDialog(false);
+        void enqueue(() => editor.setInteractive(true))
+            .then(() => interactiveChangeRef.current?.(true))
+            .catch(error => setCommandError(describeCanvasError(error)));
+    };
+    const exitInteractive = () => {
+        void enqueue(async () => {
+            const { navigated } = await editor.setInteractive(false);
+            interactiveChangeRef.current?.(false);
+            if (navigated) {
+                await snapshotForRebuild();
+                setReloadKey(n => n + 1);
+                return;
+            }
+            await changeListRef.current.reapplyAll();
+        }).catch(error => setCommandError(describeCanvasError(error)));
+    };
+    useEffect(() => {
+        if (!interactive)
+            return;
+        const onBeforeUnload = (event) => {
+            event.preventDefault();
+            event.returnValue = '';
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        return () => window.removeEventListener('beforeunload', onBeforeUnload);
+    }, [interactive]);
     const bootChanges = deviceSnapshot.current?.version === activeVersionId && deviceSnapshot.current
         ? deviceSnapshot.current.changes
         : hasVersions && activeVersionId && versionChanges?.[activeVersionId]
@@ -990,13 +1030,13 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
         }
     }, [clipboard, commands, depsOf, frameProps?.sessionId, selection, t, uploadImage]);
     const self = selection?.chain[0];
-    return (_jsxs("div", { className: `${CANVAS_UI_SCOPE} flex h-full min-h-0 flex-col bg-[#F5F7FC]`, children: [_jsx(EditorChrome, { slotRight: capturing ? (_jsx("span", { role: "status", className: "text-xs text-muted-foreground", children: t('inlineCanvas.review.generating', '正在生成截图…') })) : undefined, variant: chrome, title: title, versionLabel: versionLabel, versions: versions, activeVersionId: activeVersionId, versionSwitching: switching, onVersionChange: onVersionChange, canUndo: !switching && textEditing === null && changeList.canUndo, canRedo: !switching && textEditing === null && changeList.canRedo, onUndo: () => uiWrite(() => enqueue(() => changeListRef.current.undo())), onRedo: () => uiWrite(() => enqueue(() => changeListRef.current.redo())), changeCount: changeList.list.length, onExit: onExit, onSave: () => {
-                    if (switchingRef.current) {
-                        setCommandError(t('inlineCanvas.version.switching', '正在切换版本，请稍候'));
-                        return;
-                    }
-                    onSave?.(editor);
-                }, onAddVersion: onAddVersion, onRenameVersion: onRenameVersion, removableVersionIds: removableVersionIds, onRemoveVersion: onRemoveVersion, onPreview: onPreview, onToggleChangeList: () => setShowChangeList(v => !v), changeListOpen: showChangeList, onToggleAi: onToggleAi, aiOpen: aiOpen }), _jsxs("div", { className: "relative flex min-h-0 flex-1", children: [_jsxs(ResizablePanelGroup, { direction: "horizontal", autoSaveId: "inline-editor-panes-v2", className: "flex min-h-0 w-full flex-1", children: [showLeftPanel && (_jsxs(_Fragment, { children: [_jsx(ResizablePanel, { id: "left", order: 1, defaultSize: 18, minSize: 12, maxSize: 40, className: "flex min-h-0 flex-col", children: _jsxs("aside", { "data-testid": "inline-editor-left-panel", className: "inline-editor-left flex h-full min-h-0 flex-col bg-white", children: [!!libraryComponents && (_jsx("div", { className: "flex h-9 shrink-0 items-center gap-1 border-b\n                            border-[#EBECF0] px-2", children: [
+    return (_jsxs("div", { className: `${CANVAS_UI_SCOPE} flex h-full min-h-0 flex-col bg-[#F5F7FC]`, children: [_jsxs("div", { className: "relative shrink-0", children: [interactive && (_jsxs("div", { role: "status", "data-testid": "inline-editor-interactive-bar", className: "absolute inset-0 z-20 flex items-center justify-center gap-3\n                        border-b border-[#ececef] bg-white text-[13px] text-[#1a1a1a]\n                        shadow-[0_4px_12px_0_rgba(9,30,66,0.12)]", children: [_jsx("span", { children: t('inlineCanvas.interactive.active', '您当前正在交互模式') }), _jsx(Button, { size: "sm", variant: "secondary", "data-testid": "inline-editor-interactive-exit", onClick: exitInteractive, children: t('inlineCanvas.interactive.exit', '返回编辑模式') })] })), _jsx(EditorChrome, { slotRight: capturing ? (_jsx("span", { role: "status", className: "text-xs text-muted-foreground", children: t('inlineCanvas.review.generating', '正在生成截图…') })) : undefined, variant: chrome, title: title, versionLabel: versionLabel, versions: versions, activeVersionId: activeVersionId, versionSwitching: switching, onVersionChange: onVersionChange, canUndo: !switching && textEditing === null && changeList.canUndo, canRedo: !switching && textEditing === null && changeList.canRedo, onUndo: () => uiWrite(() => enqueue(() => changeListRef.current.undo())), onRedo: () => uiWrite(() => enqueue(() => changeListRef.current.redo())), changeCount: changeList.list.length, onExit: onExit, onSave: () => {
+                            if (switchingRef.current) {
+                                setCommandError(t('inlineCanvas.version.switching', '正在切换版本，请稍候'));
+                                return;
+                            }
+                            onSave?.(editor);
+                        }, onAddVersion: onAddVersion, onRenameVersion: onRenameVersion, removableVersionIds: removableVersionIds, onRemoveVersion: onRemoveVersion, onPreview: onPreview, onToggleChangeList: () => setShowChangeList(v => !v), changeListOpen: showChangeList, onToggleAi: onToggleAi, aiOpen: aiOpen })] }), _jsxs("div", { className: "relative flex min-h-0 flex-1", children: [_jsxs(ResizablePanelGroup, { direction: "horizontal", autoSaveId: "inline-editor-panes-v2", className: "flex min-h-0 w-full flex-1", children: [showLeftPanel && (_jsxs(_Fragment, { children: [_jsx(ResizablePanel, { id: "left", order: 1, defaultSize: 18, minSize: 12, maxSize: 40, className: "flex min-h-0 flex-col", children: _jsxs("aside", { "data-testid": "inline-editor-left-panel", className: "inline-editor-left relative flex h-full min-h-0 flex-col bg-white", children: [interactive && (_jsx("div", { "data-testid": "inline-editor-left-veil", className: "absolute inset-0 z-10 cursor-not-allowed bg-white/60" })), !!libraryComponents && (_jsx("div", { className: "flex h-9 shrink-0 items-center gap-1 border-b\n                            border-[#EBECF0] px-2", children: [
                                                         ['layers', '图层'],
                                                         ['assets', '组件']
                                                     ].map(([tab, label]) => (_jsx("button", { type: "button", "data-testid": `left-tab-${tab}`, "aria-pressed": leftTab === tab, onClick: () => setLeftTab(tab), className: `rounded px-2 py-1 text-[12px] ${leftTab === tab
@@ -1007,7 +1047,15 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
                                                             targetIdentifier: targetSelector,
                                                             targetSelector,
                                                             mode: moveModeFromDropPos(pos)
-                                                        })) })) })] }) }), _jsx(ResizableHandle, { withHandle: true })] })), _jsx(ResizablePanel, { id: "canvas", order: 2, minSize: 30, children: _jsxs("div", { className: "flex h-full min-h-0 min-w-0 flex-col", children: [_jsx(CanvasContextBar, { url: url, device: device, onDeviceChange: changeDevice }), _jsxs("div", { ref: canvasAreaRef, className: "relative min-h-0 flex-1 overflow-hidden p-3", children: [editor.session.state === 'failed' && (_jsxs("div", { role: "alert", "data-testid": "inline-editor-session-failed", className: "absolute inset-3 z-20 flex flex-col items-center justify-center gap-3 rounded-lg bg-white p-6 text-center text-sm", children: [_jsx("p", { className: "font-semibold", children: t('inlineCanvas.review.pageLoadFailed', '目标页面无法加载') }), _jsx("p", { children: [
+                                                        })) })) })] }) }), _jsx(ResizableHandle, { withHandle: true })] })), _jsx(ResizablePanel, { id: "canvas", order: 2, minSize: 30, children: _jsxs("div", { className: "flex h-full min-h-0 min-w-0 flex-col", children: [_jsx(CanvasContextBar, { url: url, device: device, onDeviceChange: changeDevice, deviceDisabled: interactive, interactive: interactiveMode
+                                                ? {
+                                                    active: interactive,
+                                                    disabled: !interactive && !canEnterInteractive,
+                                                    onToggle: () => interactive
+                                                        ? exitInteractive()
+                                                        : enterInteractive()
+                                                }
+                                                : undefined }), _jsxs("div", { ref: canvasAreaRef, className: "relative min-h-0 flex-1 overflow-hidden p-3", children: [editor.session.state === 'failed' && (_jsxs("div", { role: "alert", "data-testid": "inline-editor-session-failed", className: "absolute inset-3 z-20 flex flex-col items-center justify-center gap-3 rounded-lg bg-white p-6 text-center text-sm", children: [_jsx("p", { className: "font-semibold", children: t('inlineCanvas.review.pageLoadFailed', '目标页面无法加载') }), _jsx("p", { children: [
                                                                 'NO_EXTENSION',
                                                                 'EXTENSION_ID_MISSING',
                                                                 'CONTRACT_MISMATCH'
@@ -1015,7 +1063,7 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
                                                                 ? describeCanvasError(editor.session.reason)
                                                                 : t('inlineCanvas.review.pageLoadHint', '请返回检查页面地址、网站访问权限和网络连接后重试。') }), _jsx("code", { className: "text-xs text-muted-foreground", children: editor.session.reason }), _jsx(Button, { variant: "secondary", onClick: onExit, children: t('inlineCanvas.review.backFromFailed', '返回修改') })] })), frameProps && (_jsx(CanvasFrame, { url: frameProps.url, sessionId: frameProps.sessionId, device: frameProps.device, panelWidth: panelWidth, targetViewportWidth: targetViewportWidth[frameProps.device], onFrameLoad: () => { }, domReady: domReady, iframeRef: canvasIframeRef }, frameProps.sessionId))] })] }) })] }), !capturing && shot && (_jsx(ScreenshotCard, { dataUrl: shot.dataUrl, truncated: shot.truncated, scale: shot.scale, uploadImage: uploadImage, onClose: () => {
                             setShot(null);
-                        } }, shot.dataUrl)), _jsx(ChangeListPopover, { open: showChangeList && !capturing, onClose: () => setShowChangeList(false), children: _jsx(ChangeListPanel, { list: changeList.list, onRevert: id => uiWrite(() => writes.revert(id)), onRevertAll: () => uiWrite(() => writes.revertAll()), lastError: changeList.lastError, onHover: s => void commands.hover(s), onSelect: s => void selectAndReveal(s) }) })] }), !capturing && (_jsx(SelectionOverlay, { geometry: geometry.latest, context: overlayContext, selectedLabel: self ? `<${self.tag}>` : undefined })), !capturing && blockOverlay && (_jsx(BlockOverlay, { blocks: blockOverlay.blocks, activeId: blockOverlay.activeId, onHover: blockOverlay.onHover, geometry: geometry.latest, context: overlayContext, scale: editor.mobileFit.scale })), !capturing && commandError && (_jsxs(EditorStatus, { tone: "error", "data-testid": "inline-editor-command-error", style: { left: `${area.x + area.width / 2}px`, top: `${area.y + 8}px` }, children: [_jsx("span", { children: commandError }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setCommandError(null), children: t('inlineCanvas.chrome.close', '关闭') })] })), !capturing && aiApplyNote && (_jsxs(EditorStatus, { "data-testid": "inline-editor-ai-apply-note", style: { left: `${area.x + area.width / 2}px`, top: `${area.y + 8}px` }, children: [_jsx("span", { role: "status", children: aiApplyNote }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setAiApplyNote(null), children: t('inlineCanvas.chrome.close', '关闭') })] })), !capturing && move && (_jsx("div", { role: "toolbar", "aria-label": t('inlineCanvas.move.title'), "data-testid": "inline-editor-move-bar", className: "fixed z-[903] -translate-x-1/2 rounded-lg border bg-popover p-3 text-xs text-popover-foreground shadow-md", style: {
+                        } }, shot.dataUrl)), _jsx(ChangeListPopover, { open: showChangeList && !capturing, onClose: () => setShowChangeList(false), children: _jsx(ChangeListPanel, { list: changeList.list, onRevert: id => uiWrite(() => writes.revert(id)), onRevertAll: () => uiWrite(() => writes.revertAll()), lastError: changeList.lastError, onHover: s => void commands.hover(s), onSelect: s => void selectAndReveal(s) }) })] }), !capturing && !interactive && (_jsx(SelectionOverlay, { geometry: geometry.latest, context: overlayContext, selectedLabel: self ? `<${self.tag}>` : undefined })), !capturing && !interactive && blockOverlay && (_jsx(BlockOverlay, { blocks: blockOverlay.blocks, activeId: blockOverlay.activeId, onHover: blockOverlay.onHover, geometry: geometry.latest, context: overlayContext, scale: editor.mobileFit.scale })), !capturing && commandError && (_jsxs(EditorStatus, { tone: "error", "data-testid": "inline-editor-command-error", style: { left: `${area.x + area.width / 2}px`, top: `${area.y + 8}px` }, children: [_jsx("span", { children: commandError }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setCommandError(null), children: t('inlineCanvas.chrome.close', '关闭') })] })), !capturing && aiApplyNote && (_jsxs(EditorStatus, { "data-testid": "inline-editor-ai-apply-note", style: { left: `${area.x + area.width / 2}px`, top: `${area.y + 8}px` }, children: [_jsx("span", { role: "status", children: aiApplyNote }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setAiApplyNote(null), children: t('inlineCanvas.chrome.close', '关闭') })] })), !capturing && !interactive && move && (_jsx("div", { role: "toolbar", "aria-label": t('inlineCanvas.move.title'), "data-testid": "inline-editor-move-bar", className: "fixed z-[903] -translate-x-1/2 rounded-lg border bg-popover p-3 text-xs text-popover-foreground shadow-md", style: {
                     width: 'min(600px, calc(100vw - 32px))',
                     left: `clamp(min(316px, 50vw), ${area.x + area.width / 2}px, max(calc(100vw - 316px), 50vw))`,
                     top: `${area.y + 8}px`
@@ -1024,7 +1072,8 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
                                 : t('inlineCanvas.move.pickTarget') }), _jsx(Button, { size: "default", variant: "secondary", type: "button", "data-testid": "move-cancel", onClick: () => commands.cancelMove(), children: t('inlineCanvas.move.cancel') })] })) : (_jsx(MovePositionControls, { onConfirm: commands.confirmMove, onCancel: commands.cancelMove, onError: e => setCommandError(describeCanvasError(e)) }, move.target)) })), !capturing && textEditing !== null && (_jsx(EditorStatus, { "data-testid": "inline-editor-text-editing-hint", style: {
                     left: `${area.x + area.width / 2}px`,
                     top: `${area.y + 8}px`
-                }, children: "\u6B63\u5728\u7F16\u8F91\u6587\u5B57 \u00B7 \u56DE\u8F66\u63D0\u4EA4 \u00B7 Esc \u53D6\u6D88" })), !capturing && !switching && !move && textEditing === null && (_jsx(SelectionToolbar, { selectedRect: selectedRect, area: area, capabilities: selection?.capabilities ?? null, isScrolling: geometry.isScrolling, onAction: onToolbarAction, host: { askAi: !!onAskAi } })), stylePanelOpen &&
+                }, children: "\u6B63\u5728\u7F16\u8F91\u6587\u5B57 \u00B7 \u56DE\u8F66\u63D0\u4EA4 \u00B7 Esc \u53D6\u6D88" })), !capturing && !interactive && !switching && !move && textEditing === null && (_jsx(SelectionToolbar, { selectedRect: selectedRect, area: area, capabilities: selection?.capabilities ?? null, isScrolling: geometry.isScrolling, onAction: onToolbarAction, host: { askAi: !!onAskAi } })), stylePanelOpen &&
+                !interactive &&
                 !switching &&
                 selectedRect &&
                 self &&

package/dist/kernel/CanvasContextBar.d.ts

@@ -19,5 +19,18 @@ export interface CanvasContextBarProps {
     url: string;
     device: CanvasDevice;
     onDeviceChange: (device: CanvasDevice) => void;
+    /** 交互模式下切设备会重建画布、把用户点出来的页面状态整个丢掉，所以一并禁用。 */
+    deviceDisabled?: boolean;
+    /**
+     * 「交互模式」开关，靠右。不传 = 没有这个按钮。
+     *
+     * 放在画布条而不是顶栏：它改变的是**画布**的行为（点击交给页面），与设备切换同属
+     * 「我在怎么看这一页」；老编辑器也是挨着设备切换放的。
+     */
+    interactive?: {
+        active: boolean;
+        disabled?: boolean;
+        onToggle: () => void;
+    };
 }
-export declare function CanvasContextBar({ url, device, onDeviceChange }: CanvasContextBarProps): import("react").JSX.Element;
+export declare function CanvasContextBar({ url, device, onDeviceChange, deviceDisabled, interactive }: CanvasContextBarProps): import("react").JSX.Element;

package/dist/kernel/CanvasContextBar.js

@@ -1,12 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useTranslation } from 'react-i18next';
-import { Link2, Monitor, Smartphone } from 'lucide-react';
-import { ChromeSegment, ChromeSegmented } from '../chrome/topbarPrimitives.js';
-export function CanvasContextBar({ url, device, onDeviceChange }) {
+import { Link2, Monitor, MousePointerClick, Smartphone } from 'lucide-react';
+import { ChromeSegment, ChromeSegmented, ChromeTextButton } from '../chrome/topbarPrimitives.js';
+export function CanvasContextBar({ url, device, onDeviceChange, deviceDisabled, interactive }) {
     const { t } = useTranslation();
     const items = [
         ['pc', Monitor, t('inlineCanvas.chrome.pc', 'PC')],
         ['mobile', Smartphone, t('inlineCanvas.chrome.mobile', '移动')]
     ];
-    return (_jsxs("div", { "data-testid": "canvas-context-bar", className: "relative flex h-9 shrink-0 items-center border-b border-[#EBECF0]\n                bg-white px-3", children: [url && (_jsxs("a", { "data-testid": "canvas-context-url", href: url, target: "_blank", rel: "noopener noreferrer", title: url, className: "flex max-w-[calc(50%-60px)] items-center gap-1.5 truncate text-xs\n                        text-[#8a8f98] hover:text-[#52525b] hover:underline", children: [_jsx(Link2, { className: "size-3.5 shrink-0" }), _jsx("span", { className: "truncate", children: url })] })), _jsx(ChromeSegmented, { "data-testid": "device-switch", className: "absolute left-1/2 -translate-x-1/2", children: items.map(([value, Icon, label]) => (_jsxs(ChromeSegment, { "data-testid": `device-${value}`, active: device === value, onClick: () => onDeviceChange(value), children: [_jsx(Icon, { className: "size-3.5" }), label] }, value))) })] }));
+    return (_jsxs("div", { "data-testid": "canvas-context-bar", className: "relative flex h-9 shrink-0 items-center border-b border-[#EBECF0]\n                bg-white px-3", children: [url && (_jsxs("a", { "data-testid": "canvas-context-url", href: url, target: "_blank", rel: "noopener noreferrer", title: url, className: "flex max-w-[calc(50%-60px)] items-center gap-1.5 truncate text-xs\n                        text-[#8a8f98] hover:text-[#52525b] hover:underline", children: [_jsx(Link2, { className: "size-3.5 shrink-0" }), _jsx("span", { className: "truncate", children: url })] })), _jsx(ChromeSegmented, { "data-testid": "device-switch", className: "absolute left-1/2 -translate-x-1/2", children: items.map(([value, Icon, label]) => (_jsxs(ChromeSegment, { "data-testid": `device-${value}`, active: device === value, disabled: deviceDisabled, onClick: () => onDeviceChange(value), children: [_jsx(Icon, { className: "size-3.5" }), label] }, value))) }), interactive && (_jsxs(ChromeTextButton, { "data-testid": "canvas-interactive-toggle", className: "ml-auto h-7 gap-1.5 px-2 text-xs", active: interactive.active, disabled: interactive.disabled, title: t('inlineCanvas.interactive.tips', '切换到交互模式可以对页面进行交互，以修改需要交互后才能看到的内容。'), onClick: interactive.onToggle, children: [_jsx(MousePointerClick, { className: "size-3.5" }), interactive.active
+                        ? t('inlineCanvas.interactive.exit', '返回编辑模式')
+                        : t('inlineCanvas.interactive.enter', '交互模式')] }))] }));
 }

package/dist/kernel/changelist/useChangeList.d.ts

@@ -82,6 +82,8 @@ export interface UseChangeListResult {
         outcome: HydrateOutcome;
         idMap: Map<string, string>;
     }>;
+    /** 当前清单原样重放（changeId 不变、不进撤销历史）。交互模式退出时用。 */
+    reapplyAll: () => Promise<void>;
     whenIdle: () => Promise<unknown>;
     canUndo: boolean;
     canRedo: boolean;

package/dist/kernel/changelist/useChangeList.js

@@ -174,6 +174,7 @@ export function useChangeList(sessionId, options = {}) {
         target.push(entry);
         refreshHistory(n => n + 1);
     }, false), [guard, restoreSnapshot]);
+    const reapplyAll = useCallback(() => guard(() => restoreSnapshot(listRef.current), false), [guard, restoreSnapshot]);
     const undo = useCallback(() => travelHistory('undo'), [travelHistory]);
     const redo = useCallback(() => travelHistory('redo'), [travelHistory]);
     const addStyle = useCallback((input) => guard(() => push(buildStyleChange(input), input.ancestors)), [guard, push]);
@@ -249,6 +250,7 @@ export function useChangeList(sessionId, options = {}) {
         clear,
         hydrate,
         replaceAll,
+        reapplyAll,
         whenIdle: () => mutationQueue.current,
         peekList,
         canUndo: past.current.length > 0,

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

@@ -90,6 +90,12 @@ export declare const zhCN: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -271,6 +277,12 @@ export declare const enUS: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -452,6 +464,12 @@ export declare const jaJP: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
         version: {
             switching: string;
         };
@@ -683,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;
             };
@@ -913,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;
             };
@@ -1143,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

@@ -80,6 +80,12 @@ export const zhCN = {
             pc: 'PC',
             mobile: '移动'
         },
+        interactive: {
+            enter: '交互模式',
+            tips: '切换到交互模式可以对页面进行交互，以修改需要交互后才能看到的内容。',
+            active: '您当前正在交互模式',
+            exit: '返回编辑模式'
+        },
         version: {
             switching: '正在切换版本，请稍候'
         },
@@ -261,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'
         },
@@ -442,6 +454,12 @@ export const jaJP = {
             pc: 'PC',
             mobile: 'モバイル'
         },
+        interactive: {
+            enter: '画面操作モード',
+            tips: '画面操作できるようになります。表示されていない要素を開き、その後編集モードに切り替えることで隠れた要素を変更することが可能です。',
+            active: '現在、画面操作モードです',
+            exit: '編集モードに戻る'
+        },
         version: {
             switching: 'バージョンを切り替えています。しばらくお待ちください'
         },

package/dist/useInlineEditor.d.ts

@@ -45,6 +45,8 @@ export interface UseInlineEditorInput {
     onHistoryShortcut?: (direction: 'undo' | 'redo') => void;
     url: string;
     device: CanvasDevice;
+    /** 递增即按同一 url/device 重建画布会话（见 `useCanvasSession` 的同名参数）。 */
+    reloadKey?: number;
     /** change list 变化时回调 —— 宿主自己决定存哪（本 hook 不做持久化）。 */
     onChangesChange?: (changes: InlineChange[]) => void;
     /**
@@ -110,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

@@ -38,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)
@@ -54,6 +59,8 @@ export function useInlineEditor(input) {
     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);
@@ -64,7 +71,8 @@ export function useInlineEditor(input) {
     const session = useCanvasSession({
         url: input.url,
         device: input.device,
-        onStreamEvent
+        onStreamEvent,
+        reloadKey: input.reloadKey
     });
     const sessionId = session.frameProps?.sessionId;
     const changeList = useChangeList(sessionId, {
@@ -121,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;
@@ -160,11 +171,13 @@ export function useInlineEditor(input) {
             : 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('|');
-    const refreshedContent = useRef('');
+        .join('|')
+        .concat(`#${treeEpoch}`);
+    const refreshedContent = useRef('#0');
     useEffect(() => {
         if (!wantTree ||
             !domReady ||
@@ -371,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,
@@ -384,6 +432,8 @@ export function useInlineEditor(input) {
         geometry,
         mobileFit: mobileFit.state,
         changeList,
+        interactive,
+        setInteractive,
         commands
     }), [
         session,
@@ -397,6 +447,8 @@ export function useInlineEditor(input) {
         geometry,
         mobileFit.state,
         changeList,
+        interactive,
+        setInteractive,
         commands
     ]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptengine/inline-editor",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Ptengine Inline 编辑器：画布会话编排、图层树、属性面板与组件库（含内部 canvas-ui）",
   "license": "UNLICENSED",
   "private": false,