@ptengine/inline-editor 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.5
+
+**变更**
+- 截图之后把画布滚回截图前的位置。截图只能拍可视区（元素截图先滚过去、整页图一屏屏滚到底），此前 agent 拍完不滚回来 ——
+  进编辑器首版自动拍整页图 + 锚点近景后，页面停在最后一张近景那里。`captureSelectedElement`、`InlineEditorHandle.capturePage`、
+  `PagePreviewHandle.capturePage` 都会滚回；锚点近景几张连拍，只在最后滚回一次。
+
+**新增**
+- `useInlineEditor().commands.preserveScroll(run)`：跑完 `run` 把画布滚回开始前的位置（取几何帧的 `scrollY`）。
+  嵌套时只有最外层还原；几何帧还没到（不知道原位置）就不滚；滚回失败不抛。
+
 ## 0.1.4
 
 **变更**

package/dist/InlineEditor.js

@@ -561,20 +561,21 @@ export function InlineEditor({ url, device, onDeviceChange, title, versionLabel
                     fragments.push(links);
             }
             const captureAnchors = anchorBlocks.length
-                ? async () => {
-                    const shots = [];
-                    for (const { anchor, selector } of anchorBlocks) {
-                        const shotSelector = anchor.blockSelectors?.[0] ?? selector;
-                        const shot = await captureAiShot(shotSelector);
-                        const base = {
-                            ...(anchor.blockId ? { blockId: anchor.blockId } : {}),
-                            label: anchor.label,
-                            selector: shotSelector
-                        };
-                        shots.push('url' in shot ? { ...base, url: shot.url } : { ...base, error: shot.error });
-                    }
-                    return shots;
-                }
+                ?
+                    () => commandsRef.current.preserveScroll(async () => {
+                        const shots = [];
+                        for (const { anchor, selector } of anchorBlocks) {
+                            const shotSelector = anchor.blockSelectors?.[0] ?? selector;
+                            const shot = await captureAiShot(shotSelector);
+                            const base = {
+                                ...(anchor.blockId ? { blockId: anchor.blockId } : {}),
+                                label: anchor.label,
+                                selector: shotSelector
+                            };
+                            shots.push('url' in shot ? { ...base, url: shot.url } : { ...base, error: shot.error });
+                        }
+                        return shots;
+                    })
                 : undefined;
             const frame = geometryRef.current;
             onPageContextReady(buildElementAiContext({

package/dist/kernel/canvasCommands.d.ts

@@ -1,4 +1,4 @@
-import { ELEMENT_CONTENT_MODE, type ApplyChangeResult, type CaptureElementResult, type CaptureSlice, type PrepareElementCaptureResult, type SetFixedHiddenResult, type ScrollToSelectorResult, type DomTreeNode, type GetDomTreeParams, type ElementCapabilities, type GetAncestorChainResult, type GetOuterHtmlResult, type ResolveSelectorResult, type ExperienceCode, type SetCodeResult, type MeasureDocumentParams, type MeasureDocumentResult, type SetStyleLayerResult, type ObserveDocumentSizeParams, type ObserveDocumentSizeResult, type QueryElementsParams, type QueryElementsResult, type ElementsAtPointsParams, type ElementsAtPointsResult, type ConfigureParams, type ConfigureResult, type ResolveHeatmapSelectorResult, type ElementsInBandResult, type GetElementImagesResult } from '@ptengine/inline-core/protocol';
+import { ELEMENT_CONTENT_MODE, type ApplyChangeResult, type CaptureElementResult, type CaptureSlice, type PrepareElementCaptureResult, type SetFixedHiddenResult, type ScrollFrameResult, type ScrollToSelectorResult, type DomTreeNode, type GetDomTreeParams, type ElementCapabilities, type GetAncestorChainResult, type GetOuterHtmlResult, type ResolveSelectorResult, type ExperienceCode, type SetCodeResult, type MeasureDocumentParams, type MeasureDocumentResult, type SetStyleLayerResult, type ObserveDocumentSizeParams, type ObserveDocumentSizeResult, type QueryElementsParams, type QueryElementsResult, type ElementsAtPointsParams, type ElementsAtPointsResult, type ConfigureParams, type ConfigureResult, type ResolveHeatmapSelectorResult, type ElementsInBandResult, type GetElementImagesResult } from '@ptengine/inline-core/protocol';
 import type { InlineChange } from '@ptengine/inline-core/change-format';
 /**
  * 六条 frame 命令（含 D9 的 setCode）的产品侧封装。全部走既有的 `sendCanvasCommand`（`chrome.runtime.sendMessage`
@@ -64,6 +64,12 @@ export declare function setHoverTarget(sessionId: string, selector: string): Pro
  * 算坐标只有 agent 侧摸得到 DOM。
  */
 export declare function scrollToSelector(sessionId: string, selector: string): Promise<ScrollToSelectorResult>;
+/**
+ * 把画布 frame 滚到文档 y（agent 回报实际滚到哪，到底会被夹住）。
+ *
+ * 截图分屏由 SW 直接发这条；产品页用它在截图之后把页面滚回截图前的位置（见 `preserveScroll`）。
+ */
+export declare function scrollFrame(sessionId: string, y: number): Promise<ScrollFrameResult>;
 /** 把一条**明文形态**的 change 应用到画布（DEC-22：转译只发生在落盘那一步）。 */
 export declare function applyChange(sessionId: string, changeId: string, change: InlineChange): Promise<ApplyChangeResult>;
 export declare function revertChange(sessionId: string, changeId: string): Promise<{

package/dist/kernel/canvasCommands.js

@@ -72,6 +72,9 @@ export function scrollToSelector(sessionId, selector) {
         selector
     });
 }
+export function scrollFrame(sessionId, y) {
+    return sendCanvasCommand({ command: 'scrollFrame', sessionId, y });
+}
 export function applyChange(sessionId, changeId, change) {
     return sendCanvasCommand({
         command: 'applyChange',

package/dist/useInlineEditor.d.ts

@@ -131,8 +131,19 @@ export interface UseInlineEditorResult {
          * 由 agent 的 `textEditCommit` 事件回报，本 hook 收到后自动落一条 change。
          */
         startTextEdit: (selector?: string) => Promise<void>;
-        /** 截选中元素并返回图像字节。**不上传** —— 上传是宿主的事（包里不碰后端端点）。 */
+        /**
+         * 截选中元素并返回图像字节。**不上传** —— 上传是宿主的事（包里不碰后端端点）。
+         * 截完把页面滚回截图前的位置（自带 `preserveScroll`）。
+         */
         captureSelectedElement: (selector: string) => Promise<CaptureOutcome>;
+        /**
+         * 跑完 `run` 把画布滚回开始前的位置。截图只能拍可视区，所以要滚过去拍、整页图要一屏屏滚到底，
+         * 而 agent 拍完不滚回来 —— 进编辑器首版自动拍图时，用户看到页面自己跑到了别处（2026-10-20）。
+         *
+         * 嵌套时**只有最外层还原**：连拍几张（锚点近景）包一层，页面只在最后滚回一次，不在每张之间来回跳。
+         * 几何帧还没到（不知道原位置）就不还原；还原失败不抛。
+         */
+        preserveScroll: <T>(run: () => Promise<T>) => Promise<T>;
         /** 复制元素（存 outerHTML 到剪贴板，不产生 change）。 */
         copyElement: (selector: string) => Promise<void>;
         /** 粘贴到某个元素的指定位置。**粘贴前会重写防撞号**。 */

package/dist/useInlineEditor.js

@@ -9,7 +9,7 @@ import { runCapture } from './kernel/captureOrchestration.js';
 import { adaptDomTree, findIdBySelector, graftSubtree } from './tree/domTreeAdapter.js';
 import { pasteHtml } from './kernel/changelist/clipboard.js';
 import { isReady, pickTarget, shouldCapturePick, startMove as startMove_ } from './kernel/moveState.js';
-import { setPickMode, getAncestorChain, getDomTree, getElementCapabilities, getOuterHtml, captureElement, prepareElementCapture, setFixedHidden, setHoverTarget, scrollToSelector, setSelection, setTextEditing } from './kernel/canvasCommands.js';
+import { setPickMode, getAncestorChain, getDomTree, getElementCapabilities, getOuterHtml, captureElement, prepareElementCapture, scrollFrame, setFixedHidden, setHoverTarget, scrollToSelector, setSelection, setTextEditing } from './kernel/canvasCommands.js';
 const PICK_MODE_MAX_RETRIES = 2;
 const PICK_MODE_RETRY_MS = 400;
 export function useInlineEditor(input) {
@@ -214,7 +214,24 @@ export function useInlineEditor(input) {
     useEffect(() => {
         onChangesChange?.(changes);
     }, [changes, onChangesChange]);
+    const latestGeometryRef = useRef(geometry.latest);
+    latestGeometryRef.current = geometry.latest;
+    const scrollKeepRef = useRef({ depth: 0, y: null });
+    const preserveScroll = useCallback(async (run) => {
+        const keep = scrollKeepRef.current;
+        if (keep.depth++ === 0)
+            keep.y = latestGeometryRef.current?.scrollY ?? null;
+        try {
+            return await run();
+        }
+        finally {
+            if (--keep.depth === 0 && sessionId && keep.y !== null) {
+                await scrollFrame(sessionId, keep.y).catch(() => { });
+            }
+        }
+    }, [sessionId]);
     const commands = useMemo(() => ({
+        preserveScroll,
         select: async (selector) => {
             if (!sessionId)
                 return;
@@ -292,7 +309,7 @@ export function useInlineEditor(input) {
             const iframe = input.iframeRef?.current;
             if (!iframe)
                 throw new Error('no canvas iframe');
-            return runCapture(selector, {
+            return preserveScroll(() => runCapture(selector, {
                 prepare: s => prepareElementCapture(sessionId, s),
                 capture: (rect, slices) => captureElement(sessionId, rect, slices),
                 hideOverlays: async () => {
@@ -312,9 +329,9 @@ export function useInlineEditor(input) {
                         devicePixelRatio: window.devicePixelRatio || 1
                     };
                 }
-            });
+            }));
         }
-    }), [graftAt, input.iframeRef, refresh, sessionId]);
+    }), [graftAt, input.iframeRef, preserveScroll, refresh, sessionId]);
     return useMemo(() => ({
         session,
         frameProps: session.frameProps,

package/package.json

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