@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/kernel/canvasCommands.d.ts

@@ -0,0 +1,126 @@
+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 type { InlineChange } from '@ptengine/inline-core/change-format';
+/**
+ * 六条 frame 命令（含 D9 的 setCode）的产品侧封装。全部走既有的 `sendCanvasCommand`（`chrome.runtime.sendMessage`
+ * 回调链）——SW 会 await agent 的回复后再 resolve 这一次调用，所以这里天然是 Promise
+ * 语义，**不需要自己发明 requestId 或超时**（D2）。失败原样抛出，message 就是
+ * FRAME_ROUTE_ERRORS 里的错误码，UI 直接展示即可。
+ */
+export declare function setPickMode(sessionId: string, enabled: boolean): Promise<{
+    ok: true;
+}>;
+export declare function getDomTree(sessionId: string, opts?: Omit<GetDomTreeParams, 'command' | 'sessionId'>): Promise<DomTreeNode>;
+/**
+ * 设置页面级自定义 CSS / JS（P10 → D9，§4.4）。**全量替换**语义，不是增量合并——传入的
+ * `codeList` 就是画布上要生效的完整集合，agent 侧会先清掉上一次 `setCode` 注入的
+ * `<style>` 再按顺序重新注入。因此天然幂等，不需要 operationId 做去重。
+ *
+ * 画布内行为不对称，这是硬约束不是策略选择：`css` 条目实时生效（agent 注入 `<style>`
+ * 到目标文档 `<head>`）；`javascript` 条目**不执行**，只被 agent 存起来——用户写的 JS
+ * 依赖 `ptKit`（SDK 运行时 API），画布场景下客户页很可能没装 SDK，`ptKit` 不存在，
+ * 执行了也只会报错。回执 `cssInjectedCount` / `jsStoredCount` 供调用方直接展示，
+ * 不用自己在前端重新数一遍 `codeList`。
+ */
+export declare function setCode(sessionId: string, codeList: ExperienceCode[]): Promise<SetCodeResult>;
+/** 度量文档。`excludeLayers` 让 agent 在同一任务内摘层-回流-测量-复原（不闪），见契约注释。 */
+export declare function measureDocument(sessionId: string, opts?: Omit<MeasureDocumentParams, 'command' | 'sessionId'>): Promise<MeasureDocumentResult>;
+/** 按名字分层注入 CSS；`css` 为空串 = 删除该层。 */
+export declare function setStyleLayer(sessionId: string, layer: string, css: string, order?: number): Promise<SetStyleLayerResult>;
+/** 打开 / 关闭文档尺寸观察；变化经 `documentSize` 事件到 `useCanvasStream` 的 `onDocumentSize`。 */
+export declare function observeDocumentSize(sessionId: string, opts: Omit<ObserveDocumentSizeParams, 'command' | 'sessionId'>): Promise<ObserveDocumentSizeResult>;
+/** 批量 selector 查询，agent 只回原始事实（按 `fields`）。 */
+export declare function queryElements(sessionId: string, selectors: string[], opts?: Omit<QueryElementsParams, 'command' | 'sessionId' | 'selectors'>): Promise<QueryElementsResult>;
+/** 按文档坐标取元素及祖先；采样网格与打分由调用方决定。 */
+export declare function elementsAtPoints(sessionId: string, points: Array<{
+    x: number;
+    y: number;
+}>, opts?: Omit<ElementsAtPointsParams, 'command' | 'sessionId' | 'points'>): Promise<ElementsAtPointsResult>;
+/** 会话级可调项（只覆盖传入的键）。 */
+export declare function configureCanvas(sessionId: string, options: Omit<ConfigureParams, 'command' | 'sessionId'>): Promise<ConfigureResult>;
+export { ELEMENT_CONTENT_MODE };
+export declare function getElementCapabilities(sessionId: string, selector?: string): Promise<ElementCapabilities>;
+export declare function getAncestorChain(sessionId: string, selector?: string): Promise<GetAncestorChainResult>;
+/**
+ * ⚠️ **未命中不是错误**：agent 会 resolve 一个 `{ matched: false }`，而不是 reject
+ * （DEC-16 的正常分支 —— 客户改版后老 selector 失效，选中态恢复不了就清空，不该弹错）。
+ */
+export declare function resolveCanvasSelector(sessionId: string, selector: string): Promise<ResolveSelectorResult>;
+/** 空串 = 清空选中。 */
+export declare function setSelection(sessionId: string, selector: string): Promise<{
+    ok: true;
+}>;
+/**
+ * DEC-23：悬浮路径选择器节点时预览高亮。
+ * ⚠️ **空串必须发**（鼠标移出路径条时），否则画布里高亮残留。
+ */
+export declare function setHoverTarget(sessionId: string, selector: string): Promise<{
+    ok: true;
+}>;
+/**
+ * 「定位」：把 selector 指向的元素滚进视野。
+ *
+ * ⚠️ **不能用 `scrollFrame` 代替** —— 那条吃文档 y，而定位时产品页压根不知道目标的
+ * 文档坐标（几何流只推**当前选中**元素的矩形，且是异步的，跟这次点击竞态）。
+ * 算坐标只有 agent 侧摸得到 DOM。
+ */
+export declare function scrollToSelector(sessionId: string, selector: string): Promise<ScrollToSelectorResult>;
+/** 把一条**明文形态**的 change 应用到画布（DEC-22：转译只发生在落盘那一步）。 */
+export declare function applyChange(sessionId: string, changeId: string, change: InlineChange): Promise<ApplyChangeResult>;
+export declare function revertChange(sessionId: string, changeId: string): Promise<{
+    ok: true;
+}>;
+/** `</>` 的 seed：**outerHTML**（不是 innerHTML），且已剥 script/noscript。 */
+export declare function getOuterHtml(sessionId: string, selector?: string): Promise<GetOuterHtmlResult>;
+/**
+ * 区块里真实图片的 URL：`<img src>` + **计算样式**里的 `background-image`（v10）。
+ * outerHTML 里看不到 CSS 类设的背景图，首版给 agent 当 generate-image 参考图的 URL 只能从这里来。
+ * 老扩展不认识这条命令 → SW 回 `AGENT_STALE`，调用方按"没有图片行"降级。
+ */
+export declare function getElementImages(sessionId: string, selector?: string, limit?: number): Promise<GetElementImagesResult>;
+/**
+ * 页面内实时改文字（问题 3）。
+ *
+ * 结束**不走返回值**：用户可能按 Esc、可能点到别处，两条路都不是「产品侧发了 disable
+ * 命令」。结果统一由 agent 的 `textEditCommit` 事件回报。
+ */
+export declare function setTextEditing(sessionId: string, enabled: boolean, selector?: string): Promise<{
+    ok: true;
+}>;
+/** 截图前滚动进视口并测量（**视口**坐标，不是文档坐标）。 */
+export declare function prepareElementCapture(sessionId: string, selector?: string): Promise<PrepareElementCaptureResult>;
+/**
+ * 抓屏 + 裁剪。**由 SW 自处理**（不转发给 agent），`rect` 是屏幕物理像素坐标。
+ */
+export declare function captureElement(sessionId: string, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, 
+/** 元素比可视区高时的分屏方案；省略/单屏则直接截一次。 */
+slices?: CaptureSlice[]): Promise<CaptureElementResult>;
+/**
+ * 截图期间临时藏起 fixed/sticky。
+ *
+ * ⚠️ agent 侧只改 `visibility` 不改 `position`（改 position 会让元素重回文档流，
+ * 下面内容整体上移，图与真实页面对不上）。
+ */
+export declare function setFixedHidden(sessionId: string, hidden: boolean): Promise<SetFixedHiddenResult>;
+/**
+ * 热图 / SDK 的 jQuery 方言 selector（`body>#wrapper>div:eq(0)`，可能带 `v2>`）→ 在活页面上
+ * 试命中。**一次带全部**：一页十几个区块、每块若干条，逐条往返太慢。
+ *
+ * ⚠️ 未命中 / 多命中不是错误（客户改版后老 selector 失效是常态），看 `results[].matchCount`；
+ * 只有 `matchCount === 1` 的才带 `kernelSelector`（内核方言，画布闸门唯一认的那种）。
+ */
+export declare function resolveHeatmapSelector(sessionId: string, selectors: string[]): Promise<ResolveHeatmapSelectorResult>;
+/**
+ * 几何映射：文档 y 区间 → 最贴合的容器候选（按 1-D IoU 降序，最多 3 条）。
+ * agent 会滚动取样再恢复 scrollY；`minIou` 不传时 agent 用默认 0.3（这里不补默认，
+ * 免得两边各写一份数字）。
+ */
+export declare function elementsInBand(sessionId: string, band: {
+    yStart: number;
+    yEnd: number;
+    minIou?: number;
+}): Promise<ElementsInBandResult>;

package/dist/kernel/canvasCommands.js

@@ -0,0 +1,146 @@
+import { ELEMENT_CONTENT_MODE } from '@ptengine/inline-core/protocol';
+import { sendCanvasCommand } from './useCanvasBridge.js';
+export function setPickMode(sessionId, enabled) {
+    return sendCanvasCommand({ command: 'setPickMode', sessionId, enabled });
+}
+export function getDomTree(sessionId, opts = {}) {
+    return sendCanvasCommand({
+        command: 'getDomTree',
+        sessionId,
+        ...opts
+    });
+}
+export function setCode(sessionId, codeList) {
+    return sendCanvasCommand({ command: 'setCode', sessionId, codeList });
+}
+export function measureDocument(sessionId, opts = {}) {
+    return sendCanvasCommand({ command: 'measureDocument', sessionId, ...opts });
+}
+export function setStyleLayer(sessionId, layer, css, order) {
+    return sendCanvasCommand({
+        command: 'setStyleLayer',
+        sessionId,
+        layer,
+        css,
+        ...(order !== undefined ? { order } : {})
+    });
+}
+export function observeDocumentSize(sessionId, opts) {
+    return sendCanvasCommand({ command: 'observeDocumentSize', sessionId, ...opts });
+}
+export function queryElements(sessionId, selectors, opts = {}) {
+    return sendCanvasCommand({ command: 'queryElements', sessionId, selectors, ...opts });
+}
+export function elementsAtPoints(sessionId, points, opts = {}) {
+    return sendCanvasCommand({ command: 'elementsAtPoints', sessionId, points, ...opts });
+}
+export function configureCanvas(sessionId, options) {
+    return sendCanvasCommand({ command: 'configure', sessionId, ...options });
+}
+export { ELEMENT_CONTENT_MODE };
+export function getElementCapabilities(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'getElementCapabilities',
+        sessionId,
+        selector
+    });
+}
+export function getAncestorChain(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'getAncestorChain',
+        sessionId,
+        selector
+    });
+}
+export function resolveCanvasSelector(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'resolveSelector',
+        sessionId,
+        selector
+    });
+}
+export function setSelection(sessionId, selector) {
+    return sendCanvasCommand({ command: 'setSelection', sessionId, selector });
+}
+export function setHoverTarget(sessionId, selector) {
+    return sendCanvasCommand({ command: 'setHoverTarget', sessionId, selector });
+}
+export function scrollToSelector(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'scrollToSelector',
+        sessionId,
+        selector
+    });
+}
+export function applyChange(sessionId, changeId, change) {
+    return sendCanvasCommand({
+        command: 'applyChange',
+        sessionId,
+        changeId,
+        change
+    });
+}
+export function revertChange(sessionId, changeId) {
+    return sendCanvasCommand({ command: 'revertChange', sessionId, changeId });
+}
+export function getOuterHtml(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'getOuterHtml',
+        sessionId,
+        selector
+    });
+}
+export function getElementImages(sessionId, selector, limit) {
+    return sendCanvasCommand({
+        command: 'getElementImages',
+        sessionId,
+        selector,
+        limit
+    });
+}
+export function setTextEditing(sessionId, enabled, selector) {
+    return sendCanvasCommand({
+        command: 'setTextEditing',
+        sessionId,
+        enabled,
+        selector
+    });
+}
+export function prepareElementCapture(sessionId, selector) {
+    return sendCanvasCommand({
+        command: 'prepareElementCapture',
+        sessionId,
+        selector
+    });
+}
+export function captureElement(sessionId, rect, slices) {
+    return sendCanvasCommand({
+        command: 'captureElement',
+        sessionId,
+        rect,
+        slices
+    });
+}
+export function setFixedHidden(sessionId, hidden) {
+    return sendCanvasCommand({
+        command: 'setFixedHidden',
+        sessionId,
+        hidden
+    });
+}
+export function resolveHeatmapSelector(sessionId, selectors) {
+    return sendCanvasCommand({
+        command: 'resolveHeatmapSelector',
+        sessionId,
+        selectors
+    });
+}
+export function elementsInBand(sessionId, band) {
+    return sendCanvasCommand({
+        command: 'elementsInBand',
+        sessionId,
+        yStart: band.yStart,
+        yEnd: band.yEnd,
+        ...(band.minIou !== undefined ? { minIou: band.minIou } : {})
+    });
+}

package/dist/kernel/canvasErrors.d.ts

@@ -0,0 +1 @@
+export declare function describeCanvasError(error: unknown): string;

package/dist/kernel/canvasErrors.js

@@ -0,0 +1,14 @@
+import { FRAME_ROUTE_ERROR } from '@ptengine/inline-core/protocol';
+const MESSAGES = {
+    [FRAME_ROUTE_ERROR.NO_SESSION]: '画布会话已失效，请重新打开编辑器',
+    [FRAME_ROUTE_ERROR.FRAME_NOT_READY]: '画布还没就绪，请稍候重试',
+    [FRAME_ROUTE_ERROR.FRAME_UNREACHABLE]: '画布已失联，请刷新页面重试',
+    [FRAME_ROUTE_ERROR.AGENT_ERROR]: '这一步在页面里执行失败了',
+    [FRAME_ROUTE_ERROR.AGENT_STALE]: '插件版本过旧：请重新加载扩展并刷新画布页',
+    EXTENSION_ID_MISSING: '插件 ID 未配置（构建配置问题，不是没装插件）',
+    NO_EXTENSION: '未检测到 Ptengine 插件，请先安装并启用'
+};
+export function describeCanvasError(error) {
+    const code = error instanceof Error ? error.message : String(error ?? '');
+    return MESSAGES[code] ?? code;
+}

package/dist/kernel/captureGeometry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 把「元素在客户页视口里的矩形」换算成「整屏截图位图里的矩形」。
+ *
+ * 三步，缺一不可：
+ * 1. **×zoom** —— iframe 上有 CSS `zoom`（把 1440 宽的客户页缩进面板）。
+ *    漏乘的症状是「元素越靠右下、框偏得越多」，看起来像随机偏移。
+ * 2. **+iframe 位置** —— `getBoundingClientRect()` 返回的**已经是缩放后**的视觉盒
+ *    （CSS zoom 改的是布局盒尺寸），所以它**不要再乘一次 zoom**。
+ * 3. **×devicePixelRatio** —— `captureVisibleTab` 出的是物理像素位图。
+ *    漏乘的症状是在 Retina 上「只截到左上角四分之一」。
+ *
+ * 最后钳进 iframe 可视区：不钳的话 `drawImage` 会在位图边界外取样，得到透明边。
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CaptureGeometryInput {
+    /** 元素在客户页**视口**坐标系的矩形（agent 滚动之后测的）。 */
+    elementViewportRect: Rect;
+    /** iframe 元素在产品页视口坐标系的矩形（`getBoundingClientRect()`）。 */
+    iframeRect: Rect;
+    /** iframe 上的 CSS zoom。 */
+    zoom: number;
+    devicePixelRatio: number;
+}
+export type ScreenRect = Rect;
+export declare function toScreenRect(input: CaptureGeometryInput): ScreenRect;
+/**
+ * 元素在可视区里被切掉了吗。产品页据此回报 `truncated`（E-C5：截不全必须告知）。
+ * 用 1px 容差吸收取整误差 —— 不加容差的话，正常元素也会因为四舍五入被误报截断。
+ */
+export declare function isTruncated(input: CaptureGeometryInput): boolean;

package/dist/kernel/captureGeometry.js

@@ -0,0 +1,25 @@
+export function toScreenRect(input) {
+    const { elementViewportRect: el, iframeRect, zoom, devicePixelRatio: dpr } = input;
+    const left = iframeRect.x + el.x * zoom;
+    const top = iframeRect.y + el.y * zoom;
+    const right = left + el.width * zoom;
+    const bottom = top + el.height * zoom;
+    const clampedLeft = Math.max(left, iframeRect.x);
+    const clampedTop = Math.max(top, iframeRect.y);
+    const clampedRight = Math.min(right, iframeRect.x + iframeRect.width);
+    const clampedBottom = Math.min(bottom, iframeRect.y + iframeRect.height);
+    const x = Math.round(clampedLeft * dpr);
+    const y = Math.round(clampedTop * dpr);
+    return {
+        x,
+        y,
+        width: Math.max(0, Math.round(clampedRight * dpr) - x),
+        height: Math.max(0, Math.round(clampedBottom * dpr) - y)
+    };
+}
+export function isTruncated(input) {
+    const { elementViewportRect: el, zoom, devicePixelRatio: dpr } = input;
+    const full = { width: el.width * zoom * dpr, height: el.height * zoom * dpr };
+    const actual = toScreenRect(input);
+    return actual.width < full.width - 1 || actual.height < full.height - 1;
+}

package/dist/kernel/captureOrchestration.d.ts

@@ -0,0 +1,48 @@
+import { type Rect } from './captureGeometry.js';
+/**
+ * 元素截图的编排。**顺序就是它的全部价值**：
+ * 先滚动测量 → 再隐藏浮层 → 再抓屏 → 最后恢复浮层。
+ *
+ * 隐藏放在抓屏之后 = 高亮框和工具条被截进客户页的图里（E-C4）。
+ * 恢复没放在 finally = 抓屏一失败，编辑器从此没有高亮框和工具条，只能刷新页面。
+ *
+ * 依赖注入而不是直接调命令：这样这段顺序逻辑能在没有插件、没有浏览器的环境里测。
+ */
+export interface CaptureOutcome {
+    dataUrl: string;
+    width: number;
+    height: number;
+    /** 元素被可视区切掉了（E-C5：截不全必须告知）。 */
+    truncated: boolean;
+    /** 实际采样倍率 = zoom × devicePixelRatio。低于 1 表示比 1:1 糊。 */
+    scale: number;
+}
+export interface RunCaptureDeps {
+    prepare: (selector: string) => Promise<{
+        viewportRect: Rect;
+        viewportWidth: number;
+        viewportHeight: number;
+        docRect: Rect;
+        documentHeight: number;
+        scrollY: number;
+    }>;
+    capture: (rect: Rect, slices?: Array<{
+        scrollTo: number;
+        sourceTop: number;
+        height: number;
+        destTop: number;
+    }>) => Promise<{
+        dataUrl: string;
+        width: number;
+        height: number;
+    }>;
+    /** 隐藏浮层并**等到画面真的更新**（两帧）。 */
+    hideOverlays: () => Promise<void>;
+    showOverlays: () => void;
+    readViewport: () => {
+        iframeRect: Rect;
+        zoom: number;
+        devicePixelRatio: number;
+    };
+}
+export declare function runCapture(selector: string, deps: RunCaptureDeps): Promise<CaptureOutcome>;

package/dist/kernel/captureOrchestration.js

@@ -0,0 +1,43 @@
+import { isTruncated, toScreenRect } from './captureGeometry.js';
+import { planSlices } from './captureSlices.js';
+export async function runCapture(selector, deps) {
+    const prepared = await deps.prepare(selector);
+    const { iframeRect, zoom, devicePixelRatio } = deps.readViewport();
+    const geometry = {
+        elementViewportRect: prepared.viewportRect,
+        iframeRect,
+        zoom,
+        devicePixelRatio
+    };
+    const slices = planSlices({
+        elementTop: prepared.docRect.y,
+        elementHeight: prepared.docRect.height,
+        viewportHeight: prepared.viewportHeight,
+        documentHeight: prepared.documentHeight
+    });
+    const multi = slices.length > 1;
+    const scale = zoom * devicePixelRatio;
+    const screenRect = toScreenRect(geometry);
+    const wireSlices = multi
+        ? slices.map(s => ({
+            scrollTo: Math.round(s.scrollTo),
+            sourceTop: Math.round(iframeRect.y * devicePixelRatio + s.sourceTop * scale),
+            height: Math.round(s.height * scale),
+            destTop: Math.round(s.destTop * scale)
+        }))
+        : undefined;
+    try {
+        await deps.hideOverlays();
+        const shot = await deps.capture(screenRect, wireSlices);
+        return {
+            dataUrl: shot.dataUrl,
+            width: shot.width,
+            height: shot.height,
+            truncated: multi ? false : isTruncated(geometry),
+            scale
+        };
+    }
+    finally {
+        deps.showOverlays();
+    }
+}

package/dist/kernel/captureSlices.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 把「一个比可视区高的元素」切成若干屏，供滚动 + 拼接。
+ *
+ * `captureVisibleTab` 只能抓到**屏幕上看得见的那一块**，所以高元素必须分几次滚过去各截
+ * 一次再拼。这里只算「滚到哪、这一屏取哪一段」，不碰任何浏览器 API。
+ *
+ * ⚠️ **最后一屏几乎必然滚不满。** 页面滚到底之后 `scrollY` 会被夹住，再要求它多滚一点
+ * 也不动 —— 这时那一屏的可见内容和上一屏是**重叠**的。直接把每屏整块往下拼会得到一张
+ * 中间重复一段的图，而且重复的量随页面剩余高度变化，看起来像「拼歪了」。
+ * 正确做法是：滚不动的那一屏只取**没被上一屏覆盖过**的那一段（见 `sourceTop`）。
+ */
+export interface SlicePlan {
+    /** 要把 frame 滚到的文档 y。可能被页面夹住，实际值由 agent 回报。 */
+    scrollTo: number;
+    /** 这一屏里，从元素可见区域的第几像素开始取（用于处理滚不动导致的重叠）。 */
+    sourceTop: number;
+    /** 这一屏取多高。 */
+    height: number;
+    /** 拼到成品图的第几像素。 */
+    destTop: number;
+}
+export interface SliceInput {
+    /** 元素在**文档**坐标里的顶端。 */
+    elementTop: number;
+    /** 元素完整高度。 */
+    elementHeight: number;
+    /** frame 可视区高度。 */
+    viewportHeight: number;
+    /** 文档总高度 —— 用来算滚动能到的极限。 */
+    documentHeight: number;
+}
+/**
+ * 算出分屏方案。返回的每一项都是「滚到 scrollTo，然后从可视区的 sourceTop 取 height 高，
+ * 放到成品图的 destTop」。
+ */
+export declare function planSlices(input: SliceInput): SlicePlan[];

package/dist/kernel/captureSlices.js

@@ -0,0 +1,20 @@
+export function planSlices(input) {
+    const { elementTop, elementHeight, viewportHeight, documentHeight } = input;
+    if (elementHeight <= 0 || viewportHeight <= 0)
+        return [];
+    const maxScroll = Math.max(0, documentHeight - viewportHeight);
+    const plans = [];
+    let covered = 0;
+    while (covered < elementHeight) {
+        const wantScroll = elementTop + covered;
+        const scrollTo = Math.min(wantScroll, maxScroll);
+        const sourceTop = wantScroll - scrollTo;
+        const available = viewportHeight - sourceTop;
+        if (available <= 0)
+            break;
+        const height = Math.min(available, elementHeight - covered);
+        plans.push({ scrollTo, sourceTop, height, destTop: covered });
+        covered += height;
+    }
+    return plans;
+}

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

@@ -0,0 +1,13 @@
+import type { ChangeRecord } from './useChangeList.js';
+export interface ChangeListPanelProps {
+    list: ChangeRecord[];
+    onRevert: (changeId: string) => void;
+    lastError?: string | null;
+    /** 悬浮某条时在画布里高亮该元素。传空串表示清除。 */
+    onHover?: (selector: string) => void;
+    /** 点某条时选中该元素。 */
+    onSelect?: (selector: string) => void;
+    /** 全部撤销。省略则不显示该入口。 */
+    onRevertAll?: () => void;
+}
+export declare function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll }: ChangeListPanelProps): import("react").JSX.Element;

package/dist/kernel/changelist/ChangeListPanel.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { toWireFormat } from '@ptengine/inline-core/change-format';
+import { Code2, Crosshair, EyeOff, Image, Link2, Move, Plus, Trash2, Type, Undo2, Wand } from 'lucide-react';
+import { Button } from '@ptengine/design-components';
+import { summarizeChange } from './changeSummary.js';
+import { classifySuppression } from './mergeForSave.js';
+const ICONS = {
+    style: Wand,
+    delete: Trash2,
+    text: Type,
+    code: Code2,
+    image: Image,
+    link: Link2,
+    move: Move,
+    insert: Plus
+};
+export function ChangeListPanel({ list, onRevert, lastError, onHover, onSelect, onRevertAll }) {
+    const [view, setView] = useState('summary');
+    const entries = useMemo(() => list.map(r => ({ change: r.change, ancestors: r.ancestors })), [list]);
+    const json = useMemo(() => JSON.stringify(list.map(r => toWireFormat(r.change)), null, 2), [list]);
+    return (_jsxs("section", { "data-testid": "change-list-panel", className: "flex min-h-0 flex-1 flex-col", onMouseLeave: () => onHover?.(''), children: [_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: [
+                                    ['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), className: `rounded px-2 py-[3px] text-[11px] transition-colors ${view === v
+                                        ? 'bg-white font-medium text-[rgba(16,28,31,0.9)] shadow-[0_1px_2px_rgba(16,28,31,0.08)]'
+                                        : 'text-[#707779] hover:text-[rgba(16,28,31,0.7)]'}`, children: label }, v))) }), onRevertAll && list.length > 0 && (_jsx("button", { type: "button", "data-testid": "change-list-revert-all", onClick: onRevertAll, className: "rounded px-2 py-1 text-xs text-[#52525b] transition-colors\n                                hover:bg-[rgba(16,28,31,0.06)] hover:text-[rgba(16,28,31,0.9)]", 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 }))] }));
+}
+const SUPPRESSION_TEXT = {
+    'ancestor-hidden': {
+        badge: '不会提交',
+        hint: '所在元素已被后面的「删除」改动隐藏。这条改动在画布上仍然生效，但保存时不会提交'
+    },
+    'ancestor-replaced': {
+        badge: '不会提交',
+        hint: '所在元素的 HTML 已被后面的改动整体替换（新 HTML 里已含这条改动的结果）。保存时不会提交'
+    }
+};
+function ChangeRow({ record, summary, suppression, onRevert, onHover, onSelect }) {
+    const Icon = ICONS[summary.icon];
+    const text = suppression ? SUPPRESSION_TEXT[suppression.reason] : null;
+    return (_jsxs("li", { "data-testid": "change-list-item", "data-suppressed": suppression ? suppression.reason : undefined, className: "group flex items-center gap-2.5 border-b border-[#f1f2f3] px-3 py-2.5\n                last:border-b-0 hover:bg-[rgba(16,28,31,0.04)]", onMouseEnter: () => onHover?.(summary.selector), children: [_jsx(Icon, { className: `size-4 shrink-0 ${suppression ? 'text-[#B3BAC5]' : 'text-[#6B778C]'}` }), _jsxs("button", { type: "button", "data-testid": "change-list-locate", onClick: () => onSelect?.(summary.selector), className: "flex min-w-0 flex-1 flex-col items-start gap-0.5 text-left", title: summary.selector, children: [_jsxs("span", { className: `flex items-center gap-1.5 text-[13px] font-medium ${suppression ? 'text-[#8993A4]' : 'text-[#1a1a1a]'}`, children: [summary.action, onSelect && (_jsx(Crosshair, { className: "size-3 text-[#8993A4] opacity-0 group-hover:opacity-100" }))] }), text && (_jsxs("span", { "data-testid": "change-list-suppressed-badge", className: "flex items-center gap-1 rounded bg-[#FFF7E6] px-1.5 py-0.5\n                            text-[11px] leading-4 text-[#974F0C]", title: `${text.hint}（${suppression?.by}）`, children: [_jsx(EyeOff, { className: "size-3 shrink-0" }), text.badge] })), summary.detail && (_jsx("span", { className: `w-full truncate font-mono text-[11px] ${suppression ? 'text-[#8993A4] line-through' : 'text-[#344563]'}`, children: summary.detail })), _jsx("span", { className: "w-full truncate font-mono text-[11px] text-[#8993A4]", children: summary.selector })] }), _jsx(Button, { variant: "ghost", size: "icon", "data-testid": `change-list-revert-${record.changeId}`, "aria-label": "\u64A4\u9500", onClick: () => onRevert(record.changeId), children: _jsx(Undo2, { className: "size-4" }) })] }));
+}

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

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+/**
+ * 改动清单的悬浮外壳 —— **点顶栏入口才出现**，锚在入口正下方、右对齐，浮在画布之上。
+ *
+ * 此前清单是右侧那条可拖宽的 `ResizablePanel`，默认常驻、占掉 22% 宽。它的问题不是
+ * 占地方，而是**大部分时间是空的**：用户进编辑器的头几分钟一条改动都没有，那一栏就是
+ * 一块白，而画布被挤窄到要横向滚。
+ *
+ * 开合规则（ESC 关 / 点外部关 / 点触发器不算点外部 / 点画布不关）全部归
+ * `useDismissOnOutside`，那里有每一条的理由。
+ *
+ * 关着时**整块不在 DOM 里**，也不挂任何监听 —— 不是 `display:none`。清单里每行都带
+ * hover→高亮画布元素的回调，留在 DOM 里会被别处的合成事件误触。
+ */
+export interface ChangeListPopoverProps {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+}
+export declare function ChangeListPopover({ open, onClose, children }: ChangeListPopoverProps): import("react").JSX.Element | null;

package/dist/kernel/changelist/ChangeListPopover.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { useDismissOnOutside } from '../../chrome/useDismissOnOutside.js';
+export function ChangeListPopover({ open, onClose, children }) {
+    const ref = useRef(null);
+    useDismissOnOutside(open, ref, onClose, 'changelist-trigger');
+    if (!open)
+        return null;
+    return (_jsx("div", { ref: ref, "data-testid": "changelist-popover", className: "absolute right-4 top-2 z-30 flex max-h-[calc(100%-1rem)] w-[360px]\n                flex-col overflow-hidden rounded-lg border border-[#ececef] bg-white\n                shadow-[0_8px_24px_rgba(16,28,31,0.14),0_2px_8px_rgba(16,28,31,0.08)]", children: children }));
+}