@ptengine/inline-editor 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.1.9
+
+依赖不变（`@ptengine/inline-core` ~0.2.1），可以直接发。
+
+**新增**
+
+- 自定义代码（老编辑器的「追加代码」/ code mode）：画布条新增「追加代码」按钮，打开面板给当前版本追加 CSS 与 JavaScript。
+  - `InlineEditor` 新增受控属性 `code`（当前版本的 `ExperienceCode[]`）与 `onCodeChange(code, versionId)`（带上代码所属版本：切版本时面板卸载补交的输入属于旧版本）；不传 `onCodeChange` 则没有按钮（对照组、只读画布），已有代码照样注入。
+  - 改即生效：输入停顿约 400ms 后整份交给宿主，关面板 / 换版本时立即交出；空白段不写。Tab 键插两个空格。
+  - CSS 经 `setCode` 实时注入画布，与组件库资产合并发送（全量替换语义，只发一边会清掉另一边）；会话就绪 / 重建后重新注入。
+  - JavaScript 只保存不在画布执行（与老编辑器一致），面板里提示通过预览 / 发布查看，并说明 ptKit 工具函数。
+  - 有代码时改动清单计数 +1，清单顶上显示「自定义代码」行，点它打开面板；按钮上带圆点提示。代码不进撤销历史。
+  - 交互模式中按钮禁用、面板收起。
+
+## 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

@@ -6,6 +6,7 @@ import { type AnchorShot, type ElementAiContext } from './kernel/selection/eleme
 import { type ShelfBlockHint } from './kernel/selection/buildRootShelf.js';
 import { type InlinePlanAnchor } from './kernel/selection/resolveAnchors.js';
 import { type AiApplyOutcome, type AiScopeGrant, type AiWireChange } from './kernel/ai/aiInlineApply.js';
+import type { ExperienceCode } from '@ptengine/inline-core/protocol';
 import { type LibraryComponent } from './assets/componentLibrary.js';
 import { type UseInlineEditorResult } from './useInlineEditor.js';
 import type { ChangeRecord, HydrateOutcome } from './kernel/changelist/useChangeList.js';
@@ -184,6 +185,27 @@ export interface InlineEditorProps {
         activeId?: string | null;
         onHover?: (id: string | null) => void;
     };
+    /**
+     * 「交互模式」按钮。默认 `true`。分析画布这类只看不改的宿主传 `false` 关掉。
+     *
+     * 交互模式 = 拾取关掉、页面原样可点（打开弹窗 / 切页签 / 展开折叠后再改那些交互后才
+     * 看得见的内容），对应老编辑器（engage-editor）画布工具条上的同名开关。
+     */
+    interactiveMode?: boolean;
+    /** 进出交互模式时通知宿主（宿主自己的浮层要不要让路由它决定）。 */
+    onInteractiveChange?: (on: boolean) => void;
+    /**
+     * 当前版本的自定义代码（老编辑器的「追加代码」/ code mode），**受控**：宿主按版本持有，
+     * 切版本时换成那一版的。CSS 实时注入画布，JavaScript 只存不执行（见 `CodePanel`）。
+     */
+    code?: ExperienceCode[];
+    /**
+     * 自定义代码改了（输入停顿后整份交出），带上**这份代码属于哪一版**。⚠️ 宿主要按这个 id 存，
+     * 不能按「当前版本」存：切版本时面板卸载会把停顿窗口里没交出的那一下补交出来，那一刻宿主的
+     * 当前版本已经是新的了。**不传 = 这一版不能加代码**：画布条上没有「追加代码」
+     * 按钮（对照组、只读画布）；已有的 `code` 仍会注入画布。
+     */
+    onCodeChange?: (code: ExperienceCode[], versionId: string | undefined) => void;
     /**
      * 选中变化 → 新的 AI 上下文。`null` = 选中被清空。
      *
@@ -354,4 +376,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, code, onCodeChange }: InlineEditorProps): import("react").JSX.Element;

package/dist/InlineEditor.js

@@ -39,6 +39,7 @@ import { StylePanel } from './panels/StylePanel.js';
 import { STYLE_SECTIONS } from './panels/styleFields.js';
 import { HtmlEditDialog } from './dialogs/HtmlEditDialog.js';
 import { setCode } from './kernel/canvasCommands.js';
+import { CodePanel } from './panels/CodePanel.js';
 import { describeCanvasError } from './kernel/canvasErrors.js';
 import { LayersPanel } from './tree/LayersPanel.js';
 import { AssetsPanel } from './assets/AssetsPanel.js';
@@ -56,14 +57,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, code, onCodeChange }) {
     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 +75,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 +200,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 +251,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 +273,42 @@ 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);
+        setCodePanelOpen(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]
@@ -368,6 +410,29 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
         addAction: writes.addAction
     }), [writes, selection]);
     const injectedAssetsRef = useRef([]);
+    const userCode = useMemo(() => (Array.isArray(code) ? code : []), [code]);
+    const userCodeRef = useRef(userCode);
+    userCodeRef.current = userCode;
+    const userCodeKey = JSON.stringify(userCode);
+    const codeSyncedRef = useRef(null);
+    useEffect(() => {
+        const sessionId = frameProps?.sessionId;
+        if (!domReady || !sessionId)
+            return;
+        const last = codeSyncedRef.current;
+        if (last && last.sessionId === sessionId && last.key === userCodeKey)
+            return;
+        if ((!last || last.sessionId !== sessionId) &&
+            userCode.length === 0 &&
+            !injectedAssetsRef.current.length) {
+            codeSyncedRef.current = { sessionId, key: userCodeKey };
+            return;
+        }
+        codeSyncedRef.current = { sessionId, key: userCodeKey };
+        void setCode(sessionId, [...injectedAssetsRef.current, ...userCode]).catch(error => setCommandError(describeCanvasError(error)));
+    }, [domReady, frameProps?.sessionId, userCodeKey]);
+    const hasUserCode = userCode.some(c => c.code.trim() !== '');
+    const [codePanelOpen, setCodePanelOpen] = useState(false);
     const insertComponent = useCallback(async (component) => {
         const target = selection?.chain[0];
         const sessionId = frameProps?.sessionId;
@@ -382,7 +447,10 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
             const { html, codeList } = componentInsertPayload(component);
             if (codeList.length > 0) {
                 injectedAssetsRef.current = [...injectedAssetsRef.current, ...codeList];
-                await setCode(sessionId, injectedAssetsRef.current);
+                await setCode(sessionId, [
+                    ...injectedAssetsRef.current,
+                    ...userCodeRef.current
+                ]);
             }
             await writes.addContent({
                 identifier: target.selector,
@@ -990,13 +1058,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 + (hasUserCode ? 1 : 0), 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,15 +1075,42 @@ 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, code: onCodeChange
+                                                ? {
+                                                    active: codePanelOpen,
+                                                    hasCode: hasUserCode,
+                                                    disabled: interactive,
+                                                    onToggle: () => setCodePanelOpen(v => !v)
+                                                }
+                                                : 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'
                                                             ].includes(editor.session.reason ?? '')
                                                                 ? 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: () => {
+                                                                : 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', '返回修改') })] })), codePanelOpen && onCodeChange && !interactive && (_jsx(CodePanel, { code: userCode, onChange: next => onCodeChange(next, activeVersionId), onClose: () => setCodePanelOpen(false) }, activeVersionId ?? 'single')), 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), customCode: hasUserCode
+                                ? {
+                                    types: userCode
+                                        .filter(c => c.code.trim() !== '')
+                                        .map(c => c.type),
+                                    onOpen: onCodeChange
+                                        ? () => {
+                                            setShowChangeList(false);
+                                            setCodePanelOpen(true);
+                                        }
+                                        : undefined
+                                }
+                                : undefined }) })] }), !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 +1119,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,28 @@ export interface CanvasContextBarProps {
     url: string;
     device: CanvasDevice;
     onDeviceChange: (device: CanvasDevice) => void;
+    /** 交互模式下切设备会重建画布、把用户点出来的页面状态整个丢掉，所以一并禁用。 */
+    deviceDisabled?: boolean;
+    /**
+     * 「交互模式」开关，靠右。不传 = 没有这个按钮。
+     *
+     * 放在画布条而不是顶栏：它改变的是**画布**的行为（点击交给页面），与设备切换同属
+     * 「我在怎么看这一页」；老编辑器也是挨着设备切换放的。
+     */
+    interactive?: {
+        active: boolean;
+        disabled?: boolean;
+        onToggle: () => void;
+    };
+    /**
+     * 「追加代码」开关（自定义 CSS / JS 面板），挨着交互模式。不传 = 没有这个按钮（对照组、只读画布）。
+     * `hasCode` 时按钮上带个点，提示这一版已经有代码 —— 面板关着时代码是看不见的。
+     */
+    code?: {
+        active: boolean;
+        hasCode: 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, code }: 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 { Code2, Link2, Monitor, MousePointerClick, Smartphone } from 'lucide-react';
+import { ChromeSegment, ChromeSegmented, ChromeTextButton } from '../chrome/topbarPrimitives.js';
+export function CanvasContextBar({ url, device, onDeviceChange, deviceDisabled, interactive, code }) {
     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))) }), code && (_jsxs(ChromeTextButton, { "data-testid": "canvas-code-toggle", className: "ml-auto h-7 gap-1.5 px-2 text-xs", active: code.active, disabled: code.disabled, title: t('inlineCanvas.code.desc', '可以追加 CSS / JavaScript 代码，更自由地编辑您的网页。'), onClick: code.onToggle, children: [_jsx(Code2, { className: "size-3.5" }), t('inlineCanvas.code.button', '追加代码'), code.hasCode && (_jsx("span", { "data-testid": "canvas-code-dot", "aria-hidden": true, className: "size-1.5 rounded-full bg-[#0052CC]" }))] })), interactive && (_jsxs(ChromeTextButton, { "data-testid": "canvas-interactive-toggle", className: `${code ? 'ml-1.5' : '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/ChangeListPanel.d.ts

@@ -9,5 +9,13 @@ export interface ChangeListPanelProps {
     onSelect?: (selector: string) => void;
     /** 全部撤销。省略则不显示该入口。 */
     onRevertAll?: () => void;
+    /**
+     * 这一版有自定义代码时在清单顶上占一行（老编辑器同款，计数也 +1）。它不是一条 change：
+     * 不能单独撤销，点它打开代码面板（`onOpen` 不传则不可点）。
+     */
+    customCode?: {
+        types: Array<'css' | 'javascript'>;
+        onOpen?: () => void;
+    };
 }
-export declare function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll }: ChangeListPanelProps): import("react").JSX.Element;
+export declare function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll, customCode }: ChangeListPanelProps): import("react").JSX.Element;

package/dist/kernel/changelist/ChangeListPanel.js

@@ -15,7 +15,7 @@ const ICONS = {
     move: Move,
     insert: Plus
 };
-export function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll }) {
+export function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll, customCode }) {
     const [confirmRevert, setConfirmRevert] = useState(false);
     const [view, setView] = useState('summary');
     const entries = useMemo(() => list.map(r => ({ change: r.change, ancestors: r.ancestors })), [list]);
@@ -23,14 +23,16 @@ export function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect,
     return (_jsxs("section", { "data-testid": "change-list-panel", className: "flex min-h-0 flex-1 flex-col", onMouseLeave: () => onHover?.(''), children: [confirmRevert && (_jsxs("div", { role: "alert", className: "border-b p-3 text-xs", children: ["\u786E\u5B9A\u64A4\u9500\u6B64\u7248\u672C\u7684\u5168\u90E8\u6539\u52A8\uFF1F", _jsxs("div", { className: "mt-2 flex justify-end gap-2", children: [_jsx(Button, { size: "sm", variant: "secondary", onClick: () => setConfirmRevert(false), children: "\u53D6\u6D88" }), _jsx(Button, { size: "sm", variant: "destructive", onClick: () => {
                                     setConfirmRevert(false);
                                     onRevertAll?.();
-                                }, children: "\u64A4\u9500\u5168\u90E8\u6539\u52A8" })] })] })), _jsxs("header", { className: "flex h-10 shrink-0 items-center justify-between gap-2 border-b\n                border-[#f1f2f3] pl-3 pr-2", children: [_jsxs("span", { className: "truncate text-[13px] font-medium text-[#1a1a1a]", children: ["\u6539\u52A8\u6E05\u5355", _jsx("span", { "data-testid": "change-list-count", className: "ml-1.5 text-xs font-normal tabular-nums text-[#8a8f98]", children: list.length })] }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx("div", { className: "flex items-center gap-px rounded-md bg-[#f3f4f4] p-0.5", children: [
+                                }, children: "\u64A4\u9500\u5168\u90E8\u6539\u52A8" })] })] })), _jsxs("header", { className: "flex h-10 shrink-0 items-center justify-between gap-2 border-b\n                border-[#f1f2f3] pl-3 pr-2", children: [_jsxs("span", { className: "truncate text-[13px] font-medium text-[#1a1a1a]", children: ["\u6539\u52A8\u6E05\u5355", _jsx("span", { "data-testid": "change-list-count", className: "ml-1.5 text-xs font-normal tabular-nums text-[#8a8f98]", children: list.length + (customCode ? 1 : 0) })] }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx("div", { className: "flex items-center gap-px rounded-md bg-[#f3f4f4] p-0.5", children: [
                                     ['summary', '摘要', undefined],
                                     [
                                         'wire',
                                         '高级数据',
                                         '查看此版本的高级修改数据'
                                     ]
-                                ].map(([v, label, hint]) => (_jsx(Button, { type: "button", "data-testid": `change-list-view-${v}`, "aria-pressed": view === v, title: hint, onClick: () => setView(v), size: "sm", variant: view === v ? 'secondary' : 'ghost', children: label }, v))) }), onRevertAll && list.length > 0 && (_jsx(Button, { type: "button", "data-testid": "change-list-revert-all", onClick: () => setConfirmRevert(true), size: "sm", variant: "ghost", children: "\u5168\u90E8\u64A4\u9500" }))] })] }), lastError && (_jsx("p", { "data-testid": "change-list-error", className: "px-3 py-2 text-xs text-[#DE350B]", children: lastError })), list.length === 0 ? (_jsx("p", { "data-testid": "change-list-empty", className: "px-3 py-8 text-center text-xs text-[#8a8f98]", children: "\u8FD8\u6CA1\u6709\u6539\u52A8\u3002\u5728\u753B\u5E03\u91CC\u9009\u4E2D\u5143\u7D20\u5F00\u59CB\u7F16\u8F91\u3002" })) : view === 'summary' ? (_jsx("ul", { className: "min-h-0 flex-1 overflow-y-auto", children: list.map((record, index) => (_jsx(ChangeRow, { record: record, summary: summarizeChange(record.change), suppression: classifySuppression(entries, index), onRevert: onRevert, onHover: onHover, onSelect: onSelect }, record.changeId))) })) : (_jsx("pre", { "data-testid": "change-list-json", className: "min-h-0 flex-1 overflow-auto bg-[#FAFAFA] px-3 py-2 text-[11px]\n                        leading-4 text-[#344563]", children: json }))] }));
+                                ].map(([v, label, hint]) => (_jsx(Button, { type: "button", "data-testid": `change-list-view-${v}`, "aria-pressed": view === v, title: hint, onClick: () => setView(v), size: "sm", variant: view === v ? 'secondary' : 'ghost', children: label }, v))) }), onRevertAll && list.length > 0 && (_jsx(Button, { type: "button", "data-testid": "change-list-revert-all", onClick: () => setConfirmRevert(true), size: "sm", variant: "ghost", children: "\u5168\u90E8\u64A4\u9500" }))] })] }), lastError && (_jsx("p", { "data-testid": "change-list-error", className: "px-3 py-2 text-xs text-[#DE350B]", children: lastError })), customCode && (_jsxs("button", { type: "button", "data-testid": "change-list-custom-code", disabled: !customCode.onOpen, onClick: customCode.onOpen, className: "flex shrink-0 items-center gap-2 border-b border-[#f1f2f3] px-3 py-2 text-left\n                        text-xs text-[#1a1a1a] enabled:hover:bg-[#f7f8f9]", children: [_jsx("span", { className: "font-medium", children: "\u81EA\u5B9A\u4E49\u4EE3\u7801" }), _jsx("span", { className: "text-[#8a8f98]", children: customCode.types
+                            .map(t => (t === 'css' ? 'CSS' : 'JavaScript'))
+                            .join(' / ') })] })), list.length === 0 && customCode ? null : list.length === 0 ? (_jsx("p", { "data-testid": "change-list-empty", className: "px-3 py-8 text-center text-xs text-[#8a8f98]", children: "\u8FD8\u6CA1\u6709\u6539\u52A8\u3002\u5728\u753B\u5E03\u91CC\u9009\u4E2D\u5143\u7D20\u5F00\u59CB\u7F16\u8F91\u3002" })) : view === 'summary' ? (_jsx("ul", { className: "min-h-0 flex-1 overflow-y-auto", children: list.map((record, index) => (_jsx(ChangeRow, { record: record, summary: summarizeChange(record.change), suppression: classifySuppression(entries, index), onRevert: onRevert, onHover: onHover, onSelect: onSelect }, record.changeId))) })) : (_jsx("pre", { "data-testid": "change-list-json", className: "min-h-0 flex-1 overflow-auto bg-[#FAFAFA] px-3 py-2 text-[11px]\n                        leading-4 text-[#344563]", children: json }))] }));
 }
 const SUPPRESSION_TEXT = {
     'ancestor-hidden': {

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,19 @@ export declare const zhCN: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
+        code: {
+            button: string;
+            title: string;
+            desc: string;
+            cssHint: string;
+            jsHint: string;
+        };
         version: {
             switching: string;
         };
@@ -271,6 +284,19 @@ export declare const enUS: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
+        code: {
+            button: string;
+            title: string;
+            desc: string;
+            cssHint: string;
+            jsHint: string;
+        };
         version: {
             switching: string;
         };
@@ -452,6 +478,19 @@ export declare const jaJP: {
             pc: string;
             mobile: string;
         };
+        interactive: {
+            enter: string;
+            tips: string;
+            active: string;
+            exit: string;
+        };
+        code: {
+            button: string;
+            title: string;
+            desc: string;
+            cssHint: string;
+            jsHint: string;
+        };
         version: {
             switching: string;
         };
@@ -683,6 +722,19 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
+            readonly code: {
+                button: string;
+                title: string;
+                desc: string;
+                cssHint: string;
+                jsHint: string;
+            };
             readonly version: {
                 switching: string;
             };
@@ -913,6 +965,19 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
+            readonly code: {
+                button: string;
+                title: string;
+                desc: string;
+                cssHint: string;
+                jsHint: string;
+            };
             readonly version: {
                 switching: string;
             };
@@ -1143,6 +1208,19 @@ export declare const inlineEditorLocales: {
                 pc: string;
                 mobile: string;
             };
+            readonly interactive: {
+                enter: string;
+                tips: string;
+                active: string;
+                exit: string;
+            };
+            readonly code: {
+                button: string;
+                title: string;
+                desc: string;
+                cssHint: string;
+                jsHint: string;
+            };
             readonly version: {
                 switching: string;
             };

package/dist/locales.js

@@ -80,6 +80,19 @@ export const zhCN = {
             pc: 'PC',
             mobile: '移动'
         },
+        interactive: {
+            enter: '交互模式',
+            tips: '切换到交互模式可以对页面进行交互，以修改需要交互后才能看到的内容。',
+            active: '您当前正在交互模式',
+            exit: '返回编辑模式'
+        },
+        code: {
+            button: '追加代码',
+            title: '自定义代码',
+            desc: '可以追加 CSS / JavaScript 代码，更自由地编辑您的网页。',
+            cssHint: 'CSS 会实时应用到画布。',
+            jsHint: 'JavaScript 不会在编辑器画布里执行，请通过预览或发布后查看效果。可使用 ptKit 工具函数（如 ptKit.query）等待元素出现。'
+        },
         version: {
             switching: '正在切换版本，请稍候'
         },
@@ -261,6 +274,19 @@ 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'
+        },
+        code: {
+            button: 'Custom code',
+            title: 'Custom code',
+            desc: 'Add CSS / JavaScript to customize your page more freely.',
+            cssHint: 'CSS is applied to the canvas in real time.',
+            jsHint: 'JavaScript does not run in the editor canvas. Use preview or publish to see its effect. ptKit helpers (e.g. ptKit.query) can wait for elements to appear.'
+        },
         version: {
             switching: 'Switching version, please wait'
         },
@@ -442,6 +468,19 @@ export const jaJP = {
             pc: 'PC',
             mobile: 'モバイル'
         },
+        interactive: {
+            enter: '画面操作モード',
+            tips: '画面操作できるようになります。表示されていない要素を開き、その後編集モードに切り替えることで隠れた要素を変更することが可能です。',
+            active: '現在、画面操作モードです',
+            exit: '編集モードに戻る'
+        },
+        code: {
+            button: 'コード追加',
+            title: 'カスタムコード',
+            desc: 'CSS / JavaScript を追加して、ページをより自由に編集できます。',
+            cssHint: 'CSS はキャンバスにリアルタイムで反映されます。',
+            jsHint: 'JavaScript はエディタのキャンバスでは実行されません。プレビューまたは公開後に効果を確認してください。ptKit のヘルパー（例: ptKit.query）で要素の表示を待つことができます。'
+        },
         version: {
             switching: 'バージョンを切り替えています。しばらくお待ちください'
         },

package/dist/panels/CodePanel.d.ts

@@ -0,0 +1,20 @@
+import type { ExperienceCode } from '@ptengine/inline-core/protocol';
+/**
+ * 自定义代码面板（老编辑器的「追加代码」/ code mode）：给当前版本追加 CSS 与 JavaScript。
+ *
+ * - **改即生效，没有「应用」按钮**（与老编辑器一致）：输入停顿 `FLUSH_MS` 后把整份代码交给宿主，
+ *   宿主写回 `code` 属性，编辑器据此把 CSS 注入画布。关面板 / 换版本时立即交出未落的那一下。
+ * - JavaScript **只保存、画布里不执行**（老编辑器同样关掉了：编辑器里的页面环境不对、
+ *   客户页也没有 SDK 的 `ptKit`），预览或发布后才生效 —— 面板里说清楚。
+ * - 不进撤销历史（老编辑器也不进）。
+ *
+ * 编辑控件用包里现成的等宽文本框，不引代码编辑器库（体积）；Tab 键插两个空格而不是跳走焦点。
+ */
+export interface CodePanelProps {
+    code: ExperienceCode[];
+    onChange: (code: ExperienceCode[]) => void;
+    onClose: () => void;
+}
+/** 两段文本 → 存储形状。空白段不写（与后端 normalize 同口径）。 */
+export declare function toExperienceCode(css: string, js: string): ExperienceCode[];
+export declare function CodePanel({ code, onChange, onClose }: CodePanelProps): import("react").JSX.Element;

package/dist/panels/CodePanel.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { X } from 'lucide-react';
+import { Button } from '@ptengine/design-components';
+import { ChromeSegment, ChromeSegmented } from '../chrome/topbarPrimitives.js';
+import { CodeField } from '../dialogs/CodeField.js';
+const FLUSH_MS = 400;
+function textOf(code, type) {
+    return code
+        .filter(c => c.type === type)
+        .map(c => c.code)
+        .join('\n');
+}
+export function toExperienceCode(css, js) {
+    const out = [];
+    if (css.trim())
+        out.push({ type: 'css', code: css });
+    if (js.trim())
+        out.push({ type: 'javascript', code: js });
+    return out;
+}
+export function CodePanel({ code, onChange, onClose }) {
+    const { t } = useTranslation();
+    const [tab, setTab] = useState('css');
+    const [draft, setDraft] = useState(() => ({
+        css: textOf(code, 'css'),
+        javascript: textOf(code, 'javascript')
+    }));
+    const draftRef = useRef(draft);
+    draftRef.current = draft;
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const timerRef = useRef(null);
+    const dirtyRef = useRef(false);
+    const flush = () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = null;
+        if (!dirtyRef.current)
+            return;
+        dirtyRef.current = false;
+        onChangeRef.current(toExperienceCode(draftRef.current.css, draftRef.current.javascript));
+    };
+    useEffect(() => flush, []);
+    const cssProp = textOf(code, 'css');
+    const jsProp = textOf(code, 'javascript');
+    useEffect(() => {
+        if (dirtyRef.current)
+            return;
+        const cur = draftRef.current;
+        if (cur.css.trim() === cssProp.trim() && cur.javascript.trim() === jsProp.trim())
+            return;
+        const next = { css: cssProp, javascript: jsProp };
+        draftRef.current = next;
+        setDraft(next);
+    }, [cssProp, jsProp]);
+    const update = (type, value) => {
+        setDraft(prev => ({ ...prev, [type]: value }));
+        draftRef.current = { ...draftRef.current, [type]: value };
+        dirtyRef.current = true;
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(flush, FLUSH_MS);
+    };
+    const onKeyDown = (event) => {
+        if (event.key !== 'Tab' || event.shiftKey)
+            return;
+        event.preventDefault();
+        const el = event.currentTarget;
+        const { selectionStart, selectionEnd, value } = el;
+        const next = `${value.slice(0, selectionStart)}  ${value.slice(selectionEnd)}`;
+        update(tab, next);
+        requestAnimationFrame(() => {
+            el.selectionStart = el.selectionEnd = selectionStart + 2;
+        });
+    };
+    return (_jsxs("aside", { "data-testid": "inline-editor-code-panel", className: "absolute bottom-3 right-3 top-3 z-30 flex w-[420px] max-w-[calc(100%-24px)] flex-col\n                rounded-lg border border-[#EBECF0] bg-white shadow-[0_8px_24px_rgba(9,30,66,0.16)]", children: [_jsxs("header", { className: "flex h-11 shrink-0 items-center justify-between border-b border-[#f1f2f3] pl-3 pr-1.5", children: [_jsx("span", { className: "text-[13px] font-medium text-[#1a1a1a]", children: t('inlineCanvas.code.title', '自定义代码') }), _jsx(Button, { size: "sm", variant: "ghost", "data-testid": "inline-editor-code-close", "aria-label": t('inlineCanvas.chrome.close', '关闭'), onClick: () => {
+                            flush();
+                            onClose();
+                        }, children: _jsx(X, { className: "size-4" }) })] }), _jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-3", children: [_jsx("p", { className: "text-xs leading-5 text-[#6B778C]", children: t('inlineCanvas.code.desc', '可以追加 CSS / JavaScript 代码，更自由地编辑您的网页。') }), _jsx(ChromeSegmented, { "data-testid": "inline-editor-code-tabs", className: "self-start", children: [
+                            ['css', 'CSS'],
+                            ['javascript', 'JavaScript']
+                        ].map(([value, label]) => (_jsx(ChromeSegment, { "data-testid": `inline-editor-code-tab-${value}`, active: tab === value, onClick: () => setTab(value), children: label }, value))) }), _jsx(CodeField, { "data-testid": `inline-editor-code-input-${tab}`, "aria-label": tab === 'css' ? 'CSS' : 'JavaScript', className: "min-h-0 flex-1 resize-none", value: draft[tab], placeholder: tab === 'css'
+                            ? '.hero-title { color: #e60012; }'
+                            : "ptKit.query('.cta').then(function (el) { el.textContent = '…'; });", onChange: event => update(tab, event.target.value), onKeyDown: onKeyDown, onBlur: flush }, tab), _jsx("p", { "data-testid": "inline-editor-code-hint", className: "text-xs leading-5 text-[#6B778C]", children: tab === 'css'
+                            ? t('inlineCanvas.code.cssHint', 'CSS 会实时应用到画布。')
+                            : t('inlineCanvas.code.jsHint', 'JavaScript 不会在编辑器画布里执行，请通过预览或发布后查看效果。可使用 ptKit 工具函数（如 ptKit.query）等待元素出现。') })] })] }));
+}

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.9",
   "description": "Ptengine Inline 编辑器：画布会话编排、图层树、属性面板与组件库（含内部 canvas-ui）",
   "license": "UNLICENSED",
   "private": false,