@ptengine/inline-editor 0.0.0-stage → 0.1.0

package/dist/kernel/selection/resolveAnchors.js

@@ -0,0 +1,173 @@
+import { buildDescendantShelfWithPaths } from './buildDescendantShelf.js';
+import { AI_DESCENDANT_LIMIT, AI_DESCENDANT_TEXT_CHARS } from './elementAiContext.js';
+export function blockContainerFor(anchor, shelf, ancestorsOf) {
+    const isBlockRow = (selector) => {
+        if (selector === 'body')
+            return false;
+        const row = shelf.find(r => r.selector === selector);
+        return !!row && row.hasChildren;
+    };
+    if (isBlockRow(anchor.selector))
+        return anchor.selector;
+    for (const up of ancestorsOf.get(anchor.selector) ?? []) {
+        if (isBlockRow(up))
+            return up;
+    }
+    return anchor.selector;
+}
+export function backgroundImageAncestorFor(selector, shelf, ancestorsOf) {
+    const withBackground = new Set(shelf.filter(r => r.image === 'background').map(r => r.selector));
+    if (withBackground.has(selector))
+        return null;
+    for (const up of ancestorsOf.get(selector) ?? []) {
+        if (up === 'body')
+            return null;
+        if (withBackground.has(up))
+            return up;
+    }
+    return null;
+}
+export function withImageRows(shelf, anchorRowCount, images) {
+    const kindOf = new Map();
+    for (const im of images)
+        if (!kindOf.has(im.selector))
+            kindOf.set(im.selector, im.kind);
+    if (!kindOf.size)
+        return { shelf, added: 0 };
+    const next = shelf.map(row => {
+        const kind = kindOf.get(row.selector);
+        return kind && !row.image ? { ...row, image: kind } : row;
+    });
+    const present = new Set(shelf.map(r => r.selector));
+    const extra = [];
+    for (const [selector, kind] of kindOf) {
+        if (present.has(selector))
+            continue;
+        extra.push({
+            selector,
+            tag: kind === 'img'
+                ? 'img'
+                : (/^([a-z][a-z0-9-]*)/i.exec(selector)?.[1] ?? 'div').toLowerCase(),
+            text: '',
+            hasChildren: kind === 'background',
+            image: kind
+        });
+    }
+    if (!extra.length)
+        return { shelf: next, added: 0 };
+    return {
+        shelf: [...next.slice(0, anchorRowCount), ...extra, ...next.slice(anchorRowCount)],
+        added: extra.length
+    };
+}
+function normalizeLabel(s) {
+    return s.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function indexAncestors(root) {
+    const map = new Map();
+    const walk = (n, ancestors) => {
+        for (const child of n.children) {
+            if (!map.has(child.selector))
+                map.set(child.selector, ancestors);
+            walk(child, [child.selector, ...ancestors]);
+        }
+    };
+    map.set(root.selector, []);
+    walk(root, [root.selector]);
+    return map;
+}
+function findUniqueByLabel(root, label) {
+    const want = normalizeLabel(label);
+    if (!want)
+        return null;
+    const found = [];
+    const walk = (n) => {
+        const heading = n.heading ? normalizeLabel(n.heading) : '';
+        const text = normalizeLabel(n.textSummary);
+        if (heading === want || text === want)
+            found.push(n);
+        for (const child of n.children)
+            walk(child);
+    };
+    walk(root);
+    return found.length === 1 ? found[0] : null;
+}
+function rowOf(n) {
+    const hasChildren = n.childCount > 0 || n.children.length > 0;
+    const row = {
+        selector: n.selector,
+        tag: n.tag,
+        text: n.textSummary.trim().slice(0, AI_DESCENDANT_TEXT_CHARS),
+        hasChildren
+    };
+    if (hasChildren && n.heading)
+        row.heading = n.heading;
+    if (n.rect)
+        row.top = n.rect.top;
+    if (n.image)
+        row.image = n.image;
+    return row;
+}
+export async function resolveInlinePlanAnchors(input) {
+    const { anchors, rootTree, resolveSelector, getSubtree } = input;
+    const limitPerAnchor = input.limitPerAnchor ?? AI_DESCENDANT_LIMIT;
+    const shelf = [];
+    const ancestorsOf = new Map();
+    const outcomes = [];
+    const seen = new Set();
+    const rootAncestors = indexAncestors(rootTree);
+    const push = (row, chain) => {
+        if (seen.has(row.selector))
+            return;
+        seen.add(row.selector);
+        shelf.push(row);
+        ancestorsOf.set(row.selector, chain);
+    };
+    for (const anchor of anchors) {
+        let resolvedSelector = null;
+        let via;
+        try {
+            const probe = await resolveSelector(anchor.selector);
+            if (probe.matched && probe.matchCount === 1) {
+                resolvedSelector = anchor.selector;
+                via = 'selector';
+            }
+        }
+        catch {
+        }
+        if (!resolvedSelector) {
+            const byLabel = findUniqueByLabel(rootTree, anchor.label);
+            if (byLabel) {
+                resolvedSelector = byLabel.selector;
+                via = 'label';
+            }
+        }
+        if (!resolvedSelector) {
+            outcomes.push({ ...anchor, resolved: false });
+            continue;
+        }
+        outcomes.push({ ...anchor, resolved: true, via });
+        const ownAncestors = rootAncestors.get(resolvedSelector) ?? [];
+        let subtree = null;
+        try {
+            subtree = await getSubtree(resolvedSelector);
+        }
+        catch {
+        }
+        if (!subtree) {
+            push({ selector: resolvedSelector, tag: '', text: '', hasChildren: true }, ownAncestors);
+            continue;
+        }
+        const anchorSelector = subtree.selector || resolvedSelector;
+        push(rowOf(subtree), ownAncestors);
+        const { shelf: rows, ancestorsOf: within } = buildDescendantShelfWithPaths(subtree, limitPerAnchor);
+        for (const row of rows) {
+            const chainWithin = within.get(row.selector) ?? [];
+            const chain = chainWithin.includes(anchorSelector)
+                ? [...chainWithin, ...ownAncestors]
+                : [...chainWithin, anchorSelector, ...ownAncestors];
+            push({ ...row, depth: (row.depth ?? 0) + 1 }, chain);
+        }
+    }
+    return { shelf, ancestorsOf, anchors: outcomes };
+}

package/dist/kernel/selection/shelfRow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 货架行 → prompt 里的一行文本。**唯一**的格式化出口。
+ *
+ * 此前 `apps/x` 里有两份逐字相同的实现（`pageModel.shelfLine` 与 `inlineElementAi` 的
+ * `editable-descendants` 循环）。agent 学的是一套读法（skill 里就写着这一种行形），两份实现
+ * 一漂移就是「同一个元素在 `<page-block>` 与 `<page-element>` 里长得不一样」，而它会按其中
+ * 一种去抄 selector。
+ *
+ * 行形：`  - selector <tag> [container] [image: …] [link→…] top:N "text"`，`depth` 每加一层在 `- ` 前
+ * 多两个空格。缩进是 2026-09-30 加的：平铺的货架看不出谁是谁的父级，agent 分不清
+ * 「after 容器」与「after 容器里的标题」落在哪 —— 真机里它 after 了一个 flex 横排里的 Column，
+ * 新加的一行跑到了标题右边。
+ */
+import type { AiDescendant } from './elementAiContext.js';
+/** 引用文本的长度上限。正文在 outerHtml 里，这里只要够认出是哪个元素。 */
+export declare const SHELF_TEXT_MAX = 60;
+/**
+ * 货架行上的图片位标记：` [image: background]` / ` [image: img]`，不是图片位时空串。
+ *
+ * 写成与 `<page-element>` 头部那行 `image: background` 同一个词：agent 在 skill 里学的是一套读法，
+ * 「这一行换图落在 background-image 上」。没有它时 CSS 背景图容器与普通 div 长得一模一样，
+ * agent 换首屏图就去找最近的 `<img>`（真机 2026-09-23：落到了下一个区块的商品图上）。
+ */
+export declare function imageTag(d: Pick<AiDescendant, 'image'>): string;
+/**
+ * 货架行上的链接位：` [link→/products/…]`（去向写法见 `linkPath`），不是链接时空串。
+ *
+ * 没有它时 PageFly 的图片链接（`<img data-href>`）与普通图片长得一模一样 —— 真机 2026-10-15，
+ * 方案卡据此断言「全页没有购买导线」，而那页几乎每张图都链到商品页。
+ */
+export declare function linkTag(d: Pick<AiDescendant, 'href'>): string;
+/** 叶子行优先写自己的直接文本；容器行（自己没有文本）才写 heading。 */
+export declare function formatShelfRow(d: AiDescendant): string;

package/dist/kernel/selection/shelfRow.js

@@ -0,0 +1,19 @@
+import { linkPath } from '../linkHref.js';
+export const SHELF_TEXT_MAX = 60;
+export function imageTag(d) {
+    return d.image ? ` [image: ${d.image}]` : '';
+}
+export function linkTag(d) {
+    return d.href ? ` [link→${linkPath(d.href)}]` : '';
+}
+function quote(text, max) {
+    const clean = text.replace(/\s+/g, ' ').replace(/"/g, "'").trim();
+    return `"${clean.length > max ? clean.slice(0, max) : clean}"`;
+}
+export function formatShelfRow(d) {
+    const indent = '  '.repeat(Math.max(0, d.depth ?? 0));
+    const tag = d.tag ? ` <${d.tag}>` : '';
+    const pos = typeof d.top === 'number' ? ` top:${Math.round(d.top)}` : '';
+    const label = d.text || d.heading;
+    return `  ${indent}- ${d.selector}${tag}${d.hasChildren ? ' [container]' : ''}${imageTag(d)}${linkTag(d)}${pos}${label ? ` ${quote(label, SHELF_TEXT_MAX)}` : ''}`;
+}

package/dist/kernel/selection/tagLabels.d.ts

@@ -0,0 +1,9 @@
+/** 该 tag 是否有友好名。大小写不敏感。 */
+export declare function hasTagLabel(tag: string): boolean;
+/**
+ * 该 tag 对应的 i18n key；无友好名时返回 `null`（**不是空串、也不是 tag 名**）。
+ * 返回空串会让调用方渲染出一个空标签；返回 tag 名会让「有没有友好名」这个信息丢失。
+ */
+export declare function tagLabelKey(tag: string): string | null;
+/** 供测试与非 i18n 场景使用：全部有友好名的 tag（升序）。 */
+export declare function tagsWithLabel(): string[];

package/dist/kernel/selection/tagLabels.js

@@ -0,0 +1,46 @@
+const TAGS_WITH_LABEL = new Set([
+    'A',
+    'B',
+    'BODY',
+    'BUTTON',
+    'CAPTION',
+    'DIV',
+    'FORM',
+    'H1',
+    'H2',
+    'H3',
+    'I',
+    'IFRAME',
+    'IMG',
+    'INPUT',
+    'LABEL',
+    'LI',
+    'NAV',
+    'OL',
+    'OPTION',
+    'P',
+    'PRE',
+    'SELECT',
+    'SPAN',
+    'TABLE',
+    'TBODY',
+    'TD',
+    'TEXTAREA',
+    'TFOOT',
+    'TH',
+    'THEAD',
+    'TR',
+    'U',
+    'UL',
+    'VIDEO'
+]);
+export function hasTagLabel(tag) {
+    return TAGS_WITH_LABEL.has(tag.toUpperCase());
+}
+export function tagLabelKey(tag) {
+    const upper = tag.toUpperCase();
+    return TAGS_WITH_LABEL.has(upper) ? `taginfo.${upper}` : null;
+}
+export function tagsWithLabel() {
+    return [...TAGS_WITH_LABEL].sort();
+}

package/dist/kernel/selection/toolbarButtons.d.ts

@@ -0,0 +1,60 @@
+import type { ElementCapabilities } from '@ptengine/inline-core/protocol';
+/**
+ * 工具条按钮**配置表** —— DEC-12 的核心收益在这里兑现。
+ *
+ * 现役 engage-editor 的 13 个按钮全部硬编码在模板里（`SelectMask.vue:14-286`，无配置表），
+ * 加一个按钮要改模板。而工具条 UI 移到产品页之后，加按钮**不需要过商店审核**
+ * —— 前提是它是**数据**而不是代码分支。
+ *
+ * 设计稿 §5 首期只实装 4 个（删除 / 编辑样式 / 编辑 HTML / 编辑文字），其余按需追加 ——
+ * 到 2026-08-10 已补齐现役 13 个里除「AI 助手」外的全部：替换图片、替换视频、点击动作、
+ * 移动、复制、粘贴、图片设置、插入，另加本项目特有的「截图」。
+ *
+ * 加一个按钮 = 这张表里加一行数据 + `InlineEditor` 里加一个分支 + 三语文案各一条，
+ * **不需要过商店审核**（工具条 UI 在产品页）—— 这正是 DEC-12 的收益。
+ */
+/**
+ * 图标标识；渲染层（SelectionToolbar 的 TOOLBAR_ICONS）映射到 lucide 图标。
+ * 写成联合类型而不是 string：新增一个标识却忘了在渲染层映射，类型检查就过不去。
+ */
+export type ToolbarIconName = 'image' | 'video' | 'plus' | 'setting' | 'click' | 'move' | 'copy' | 'paste' | 'text' | 'style' | 'code' | 'camera' | 'delete' | 'sparkles';
+export interface ToolbarButtonSpec {
+    id: string;
+    /** apps/x i18n 的 key。 */
+    labelKey: string;
+    icon: ToolbarIconName;
+    /** 返回 false 则不渲染这个按钮。 */
+    gate: (caps: ElementCapabilities) => boolean;
+    /**
+     * 这个按钮依赖宿主注入的哪项能力。宿主没提供就**不渲染** ——
+     * 渲染出来点了没反应比没有更让人困惑。
+     *
+     * 与 `gate` 分开：`gate` 判「这个元素能不能做」，这里判「这个产品入口有没有接」。
+     * 两者混在一起的话，`visibleButtons` 的单测就得为每个按钮都造一遍宿主状态。
+     */
+    requiresHost?: keyof ToolbarHostCapabilities;
+}
+/**
+ * 宿主注入的能力。缺省全 false —— 包不假设任何一项存在。
+ *
+ * `askAi` 只有产品里**真有右侧 AI 面板可召唤**的入口才该给 true：详情页给，
+ * 分步创建流程不给（那条路由上 dock 压根不渲染，见 apps/x 的 isAiDockRoute）。
+ */
+export interface ToolbarHostCapabilities {
+    askAi?: boolean;
+}
+/**
+ * 数组顺序就是工具条上的顺序：先编辑（内容 → 样式 → 点击动作 → HTML），再对元素的操作，
+ * 「问 AI」恒最右。删除排在元素操作末尾，和最右的 AI 胶囊挨着但不混在编辑按钮中间。
+ */
+export declare const TOOLBAR_BUTTONS: ToolbarButtonSpec[];
+export declare function visibleButtons(caps: ElementCapabilities, host?: ToolbarHostCapabilities): ToolbarButtonSpec[];
+/**
+ * 「插入 / 粘贴」可选的位置，按 tagName 白名单裁剪 —— 对齐现役
+ * `SelectMask.vue:426-449`：不能有子节点就去掉 insert/append，不能插同级就去掉
+ * before/after（`TD`/`TH`）。
+ *
+ * ⚠️ 返回空数组是**合法结果**（比如 `<td>` 里的 `<img>`）。调用方必须处理，
+ * 不能假设至少有一个位置可选 —— 否则会渲染出一个点了没反应的下拉。
+ */
+export declare function pasteModes(caps: ElementCapabilities): Array<'insert' | 'append' | 'before' | 'after'>;

package/dist/kernel/selection/toolbarButtons.js

@@ -0,0 +1,105 @@
+function notRoot(caps) {
+    return !caps.isRootLevel;
+}
+export const TOOLBAR_BUTTONS = [
+    {
+        id: 'edit-text',
+        labelKey: 'inlineCanvas.toolbar.editText',
+        icon: 'text',
+        gate: caps => notRoot(caps) && caps.hasText
+    },
+    {
+        id: 'replace-image',
+        labelKey: 'inlineCanvas.toolbar.replaceImage',
+        icon: 'image',
+        gate: caps => notRoot(caps) && (caps.isImg || caps.hasBackgroundImage)
+    },
+    {
+        id: 'replace-video',
+        labelKey: 'inlineCanvas.toolbar.replaceVideo',
+        icon: 'video',
+        gate: caps => notRoot(caps) && caps.isVideo
+    },
+    {
+        id: 'image-setting',
+        labelKey: 'inlineCanvas.toolbar.imageSetting',
+        icon: 'setting',
+        gate: caps => notRoot(caps) && caps.isImg
+    },
+    {
+        id: 'edit-style',
+        labelKey: 'inlineCanvas.toolbar.editStyle',
+        icon: 'style',
+        gate: notRoot
+    },
+    {
+        id: 'click-action',
+        labelKey: 'inlineCanvas.toolbar.clickAction',
+        icon: 'click',
+        gate: caps => notRoot(caps) && caps.canEditLink
+    },
+    {
+        id: 'edit-html',
+        labelKey: 'inlineCanvas.toolbar.editHtml',
+        icon: 'code',
+        gate: notRoot
+    },
+    {
+        id: 'insert',
+        labelKey: 'inlineCanvas.toolbar.insert',
+        icon: 'plus',
+        gate: caps => notRoot(caps) && (caps.canHaveChildren || caps.canInsertSibling)
+    },
+    {
+        id: 'move',
+        labelKey: 'inlineCanvas.toolbar.move',
+        icon: 'move',
+        gate: notRoot
+    },
+    {
+        id: 'copy',
+        labelKey: 'inlineCanvas.toolbar.copy',
+        icon: 'copy',
+        gate: caps => notRoot(caps) && caps.canHaveChildren
+    },
+    {
+        id: 'paste',
+        labelKey: 'inlineCanvas.toolbar.paste',
+        icon: 'paste',
+        gate: caps => notRoot(caps) && (caps.canHaveChildren || caps.canInsertSibling)
+    },
+    {
+        id: 'screenshot',
+        labelKey: 'inlineCanvas.toolbar.screenshot',
+        icon: 'camera',
+        gate: notRoot
+    },
+    {
+        id: 'delete',
+        labelKey: 'inlineCanvas.toolbar.delete',
+        icon: 'delete',
+        gate: notRoot
+    },
+    {
+        id: 'ask-ai',
+        labelKey: 'inlineCanvas.toolbar.askAi',
+        icon: 'sparkles',
+        gate: notRoot,
+        requiresHost: 'askAi'
+    }
+];
+export function visibleButtons(caps, host = {}) {
+    return TOOLBAR_BUTTONS.filter(b => {
+        if (b.requiresHost && !host[b.requiresHost])
+            return false;
+        return b.gate(caps);
+    });
+}
+export function pasteModes(caps) {
+    const modes = [];
+    if (caps.canHaveChildren)
+        modes.push('insert', 'append');
+    if (caps.canInsertSibling)
+        modes.push('before', 'after');
+    return modes;
+}

package/dist/kernel/selection/useAiSelectionContext.d.ts

@@ -0,0 +1,26 @@
+import type { ElementAiContext } from './elementAiContext.js';
+export interface AiSelectionContextInput<T> {
+    /**
+     * 是否跟随。宿主在**右侧 AI 面板已打开**时给 true。
+     *
+     * 关着还跟的话，每点一个元素都白花一次跨域往返（取 outerHTML），而那份上下文没人看；
+     * 开着不跟的话，用户换了选中而 AI 还在聊上一个元素 —— 这种错位没有任何提示。
+     */
+    enabled?: boolean;
+    /** 当前选中的元素；`null` / `undefined` = 没有选中。 */
+    picked: T | null | undefined;
+    /** 画布会话；没有会话时什么都不做（命令发不出去）。 */
+    sessionId: string | undefined;
+    /** 取 outerHTML —— 由调用方绑好 sessionId。 */
+    readOuterHtml: (selector: string) => Promise<{
+        html: string;
+    }>;
+    selectorOf: (picked: T) => string;
+    /** 由选中态 + HTML 组上下文。与点 ✨ 那条路**共用同一份**，避免两处口径漂移。 */
+    buildContext: (picked: T, outerHtml: string) => ElementAiContext;
+    /** 延迟截图函数的工厂（发送时才真的拍）。 */
+    captureFor: (selector: string) => () => Promise<string | null>;
+    /** 上下文变化。`null` = 选中被清空。 */
+    onChange?: (ctx: ElementAiContext | null, capture: () => Promise<string | null>) => void;
+}
+export declare function useAiSelectionContext<T>(input: AiSelectionContextInput<T>): void;

package/dist/kernel/selection/useAiSelectionContext.js

@@ -0,0 +1,26 @@
+import { useEffect } from 'react';
+const NO_CAPTURE = () => Promise.resolve(null);
+export function useAiSelectionContext(input) {
+    const { enabled, picked, sessionId, readOuterHtml, selectorOf, buildContext, captureFor, onChange } = input;
+    useEffect(() => {
+        if (!enabled || !onChange)
+            return;
+        if (!picked || !sessionId) {
+            onChange(null, NO_CAPTURE);
+            return;
+        }
+        const selector = selectorOf(picked);
+        let stale = false;
+        void readOuterHtml(selector)
+            .then(r => {
+            if (stale)
+                return;
+            onChange(buildContext(picked, r.html), captureFor(selector));
+        })
+            .catch(() => {
+        });
+        return () => {
+            stale = true;
+        };
+    }, [enabled, picked, sessionId, onChange, buildContext]);
+}

package/dist/kernel/selection/useCanvasGeometry.d.ts

@@ -0,0 +1,32 @@
+import type { CanvasGeometryPayload } from '@ptengine/inline-core/protocol';
+/**
+ * 消费 agent 推来的 `geometry` 事件（DEC-15）。
+ *
+ * 两件事：
+ * 1. **按 `frameSeq` 丢弃乱序到达的旧帧** —— agent → SW → Port → React 两跳不保证
+ *    顺序，旧帧会让高亮框来回跳。
+ * 2. **维护滚动态** —— DEC-15 采纳的缓解措施：滚动期间隐藏工具条（高亮框不隐藏，
+ *    它必须跟随），停止一小段时间后按最新几何重新显示。
+ */
+/** 滚动停止后多久认为「滚完了」。取值凭手感：太短会在惯性滚动里闪，太长显得迟钝。 */
+export declare const SCROLL_IDLE_MS = 150;
+/** ⚠️ TEMP-DEBUG（区块框不跟随滚动的排查用，定位完删掉）。 */
+export interface CanvasGeometryDebug {
+    /** agent 推来的原始帧数（过滤之前）。滚动时它不涨 = 通道断了，不是消费侧的问题。 */
+    received: number;
+    /** 被 frameSeq 乱序保护丢掉的帧数。滚动时它涨 = agent 的 seq 回退了（frame 重载）。 */
+    dropped: number;
+}
+export interface CanvasGeometry {
+    /** 最新一帧（已过乱序过滤）。`null` = 还没收到任何一帧。 */
+    latest: CanvasGeometryPayload | null;
+    /** ⚠️ TEMP-DEBUG，见 `CanvasGeometryDebug`。 */
+    debug: CanvasGeometryDebug;
+    /** 滚动中。工具条据此隐藏；高亮框**不要**用它。 */
+    isScrolling: boolean;
+    /** 供 stream 层把收到的 geometry 事件喂进来。 */
+    onGeometry: (payload: CanvasGeometryPayload) => void;
+    /** 切换会话 / iframe reload 时重置（frameSeq 会从 0 重新开始）。 */
+    reset: () => void;
+}
+export declare function useCanvasGeometry(): CanvasGeometry;

package/dist/kernel/selection/useCanvasGeometry.js

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+export const SCROLL_IDLE_MS = 150;
+export function useCanvasGeometry() {
+    const [latest, setLatest] = useState(null);
+    const [isScrolling, setIsScrolling] = useState(false);
+    const [debug, setDebug] = useState({ received: 0, dropped: 0 });
+    const maxSeqRef = useRef(-1);
+    const lastScrollRef = useRef(null);
+    const idleTimerRef = useRef(null);
+    const clearIdleTimer = useCallback(() => {
+        if (idleTimerRef.current !== null) {
+            clearTimeout(idleTimerRef.current);
+            idleTimerRef.current = null;
+        }
+    }, []);
+    const reset = useCallback(() => {
+        maxSeqRef.current = -1;
+        lastScrollRef.current = null;
+        clearIdleTimer();
+        setLatest(null);
+        setIsScrolling(false);
+        setDebug({ received: 0, dropped: 0 });
+    }, [clearIdleTimer]);
+    const onGeometry = useCallback((payload) => {
+        setDebug(d => ({ ...d, received: d.received + 1 }));
+        if (payload.frameSeq <= maxSeqRef.current) {
+            setDebug(d => ({ ...d, dropped: d.dropped + 1 }));
+            return;
+        }
+        maxSeqRef.current = payload.frameSeq;
+        const previous = lastScrollRef.current;
+        const scrolled = previous !== null &&
+            (previous.x !== payload.scrollX || previous.y !== payload.scrollY);
+        lastScrollRef.current = { x: payload.scrollX, y: payload.scrollY };
+        setLatest(payload);
+        if (scrolled) {
+            setIsScrolling(true);
+            clearIdleTimer();
+            idleTimerRef.current = setTimeout(() => {
+                idleTimerRef.current = null;
+                setIsScrolling(false);
+            }, SCROLL_IDLE_MS);
+        }
+    }, [clearIdleTimer]);
+    useEffect(() => clearIdleTimer, [clearIdleTimer]);
+    return useMemo(() => ({ latest, isScrolling, debug, onGeometry, reset }), [latest, isScrolling, debug, onGeometry, reset]);
+}

package/dist/kernel/selection/useSelectionRestore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DEC-16：iframe reload 后按 identifier 重新解析选中态。
+ *
+ * 为什么需要它：**我们切设备会 reload iframe**，而现役 engage-editor
+ * **没有任何选中态恢复机制**（`SelectionModule` 构造即重置为 `body.firstElementChild`，
+ * 恢复的只有 change list）。切设备是我们新引入的高频操作，每次丢选中态会让
+ * 「PC 改完看 Mobile」这个核心动作变得难用。
+ *
+ * ⚠️ **未命中是正常分支，不是错误**：客户改版后老 selector 失效很常见。
+ * 未命中就清空选中态，**不弹错、不打断用户**。
+ */
+export interface UseSelectionRestoreResult {
+    /** 每次选中变化时记下来，供下一次 domReady 恢复。空串 = 清空。 */
+    remember: (selector: string) => void;
+    /** `domReady` 之后调用。返回是否恢复成功。 */
+    restore: (sessionId: string) => Promise<boolean>;
+}
+export declare function useSelectionRestore(): UseSelectionRestoreResult;

package/dist/kernel/selection/useSelectionRestore.js

@@ -0,0 +1,25 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { resolveCanvasSelector, setSelection } from '../canvasCommands.js';
+export function useSelectionRestore() {
+    const lastSelectorRef = useRef('');
+    const remember = useCallback((selector) => {
+        lastSelectorRef.current = selector;
+    }, []);
+    const restore = useCallback(async (sessionId) => {
+        const selector = lastSelectorRef.current;
+        if (!selector)
+            return false;
+        const result = await resolveCanvasSelector(sessionId, selector);
+        if (!result.matched) {
+            lastSelectorRef.current = '';
+            await setSelection(sessionId, '');
+            return false;
+        }
+        if (result.matchCount > 1) {
+            console.debug(`[canvas] 恢复选中态时 selector 命中 ${result.matchCount} 个，按契约只作用第一个：${selector}`);
+        }
+        await setSelection(sessionId, selector);
+        return true;
+    }, []);
+    return useMemo(() => ({ remember, restore }), [remember, restore]);
+}

package/dist/kernel/shrinkImageForUpload.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 「问 AI」截图上传前的瘦身。
+ *
+ * 为什么需要：整页截图是扩展把多片拼成的**一张 PNG**（`cropImage.ts` 固定 `image/png`），
+ * 390×8000+ 的 PNG 轻松超过后端 `/imageUpload` 的 6 MiB 上限（`UPLOAD_IMAGE_MAX_SIZE`），
+ * 实测 413。截图给模型看的是布局不是像素，所以在宿主侧重编码成 JPEG、按宽高上限等比缩、
+ * 质量梯度往下走直到体积达标。
+ *
+ * 宽高上限也要管：模型侧任何一边超过 8000px 会让整次请求 400（image-inline 的注释），
+ * 与其让服务端切片再缩，不如上传前就落在安全范围内。
+ *
+ * canvas / createImageBitmap 在 jsdom 里没有实现 → 解码/编码通过 `deps` 注入，默认实现
+ * 用浏览器 API；任何一步失败都**原样返回**原图，让上传自己去成败 —— 为一张截图让用户
+ * 发不出消息是过度反应（与 captureAiScreenshot 的容错口径一致）。
+ */
+export interface ShrinkLimits {
+    /** 上传体积上限（留出 multipart 头的余量，比后端 6 MiB 小一截） */
+    maxBytes: number;
+    maxWidth: number;
+    maxHeight: number;
+}
+export declare const AI_UPLOAD_LIMITS: ShrinkLimits;
+/** JPEG 质量梯度：布局可辨即可，最后一档已经很糙，再低就看不清文字了。 */
+export declare const JPEG_QUALITY_LADDER: readonly number[];
+export interface ShrinkPlan {
+    scale: number;
+    width: number;
+    height: number;
+}
+/** 等比缩到宽高都不超限；永不放大。纯函数，单独测。 */
+export declare function planShrink(size: {
+    width: number;
+    height: number;
+}, limits: ShrinkLimits): ShrinkPlan;
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** 交给 encode 画到 canvas 上的源（浏览器里是 ImageBitmap）。 */
+    source: unknown;
+}
+export interface ShrinkDeps {
+    decode: (blob: Blob) => Promise<DecodedImage>;
+    encode: (image: DecodedImage, plan: ShrinkPlan, quality: number) => Promise<Blob>;
+}
+export declare function shrinkImageForUpload(blob: Blob, limits?: ShrinkLimits, deps?: ShrinkDeps): Promise<Blob>;