@ptengine/inline-editor 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,313 @@
+/**
+ * 「问 AI」交给宿主的元素上下文。
+ *
+ * 包只负责**采集**，怎么送进对话是宿主的事（包不知道产品里有没有 AI 面板、长什么样）——
+ * 与 `uploadImage` / `libraryComponents` 同一套分工。
+ */
+import type { CanvasDevice } from '@ptengine/inline-core/protocol';
+import type { ResolvedAnchor } from './resolveAnchors.js';
+/** outerHTML 进 prompt 的预算。 */
+export declare const AI_HTML_BUDGET_BYTES = 4096;
+/**
+ * 选中元素的几何。
+ *
+ * 存在的理由：没有它 agent 只能**盲猜布局** —— 真机上它要在 banner 上叠一个绝对定位的
+ * 覆盖层，只好说「如果和我预估的不一致，你告诉我微调偏移量」。有了宽高与视口，它能给出
+ * 合理的尺寸/字号，也能判断这是不是一条通栏（元素宽 ≈ 视口宽）。
+ *
+ * ⚠️ **不含 x**：横向位置对「改这个元素」没有信息量，而它在轮播/横滚容器里还会变。
+ * 纵向给的是 `topInPage`（文档坐标，不随滚动变），因为「在不在首屏」是个真会被问到的问题。
+ */
+export interface AiElementGeometry {
+    width: number;
+    height: number;
+    /** 元素顶边在**整页文档**里的位置（已加回 scrollY，不随滚动变）。 */
+    topInPage: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    device: CanvasDevice;
+}
+/** 货架的一项。字段刻意少 —— 它要进 prompt，多一个字段就是每次对话的固定开销。 */
+export interface AiDescendant {
+    /** 直接可用的 selector（逐字抄，不要改写）。 */
+    selector: string;
+    tag: string;
+    /** 直接文本的摘要（截断）。空 = 这一项自己不持有文字，只是层级。 */
+    text: string;
+    /** 有子元素 —— 决定 `EDIT_TEXT` 是否适用（容器上改文字会换掉整棵子树）。 */
+    hasChildren: boolean;
+    /**
+     * 这个区块里第一个 h1-h4 的文字（≤80 字符）。**只在容器行上、且新 agent 给了
+     * `heading` 时**出现——AI 靠它认「哪个区块是"雨の日も"那一段」，而不是靠 selector 猜。
+     * 老 agent（树上没 rect）产出的货架永远没有这个键。
+     */
+    heading?: string;
+    /**
+     * 文档坐标的顶边（px，取整）。同上，只有新 agent（`includeRect`）的树才有；
+     * AI 用它判断「这是页面上半部还是下半部的区块」、以及区块的先后顺序。
+     */
+    top?: number;
+    /**
+     * 这一行**自己**是可换的图片位：`'img'` = `<img>`，`'background'` = CSS 背景图（PageFly
+     * 首屏照片常是类名设的背景，html 里看不到）。来自树节点的 `image`（新扩展 + includeRect）；
+     * 都不是、或老扩展时没有这个键。宿主写成行尾的 `[image: …]`。
+     */
+    image?: 'img' | 'background';
+    /**
+     * 这一行**自己**是链接：点下去去哪（树节点的 `href`，新扩展 + includeRect；`<a href>` 或 PageFly
+     * 图片链接 / 商品卡的 `data-href`）。原样存，宿主写成行尾的 `[link→路径]`（`linkTag`，查询串去掉）。
+     * 不是链接、或老扩展时没有这个键。
+     */
+    href?: string;
+    /**
+     * 层级缩进：这一行上面有几个**出了行**的祖先（跳过的包装层不计）。只用来排版
+     * （`formatShelfRow`），不进授权判断。顶层行不写这个键（条件写入，与 `image` 同一条纪律）。
+     */
+    depth?: number;
+}
+/**
+ * 区块级货架取树的口径（`<page-block>`、方案锚点子树、选中元素货架三处共用）。
+ *
+ * `maxDepth` 用扩展的硬上限（`domTree.ts MAX_DEPTH_CEILING`），**不再按层截**：真实站点的标题
+ * 在第 5-10 层都常见（PageFly：Section > div > Row > .pf-c > Column > h1），按 4 截的结果是
+ * 货架里只剩容器（2026-09-30 真机）。真正的总量闸是 `maxNodes`；货架行数另有
+ * `AI_DESCENDANT_LIMIT` / 各调用方的上限，由 `buildDescendantShelf` 按「值不值得出行」挑。
+ */
+export declare const SHELF_TREE_MAX_DEPTH = 64;
+export declare const SHELF_TREE_MAX_NODES = 1000;
+export interface ElementAiContext {
+    /** 发命令用的 selector，也是 AI 定位这个元素的唯一凭据。 */
+    selector: string;
+    tag: string;
+    /**
+     * 有直接子元素 —— **纯显示用**：宿主按它决定芯片上的图标（有子节点=容器图标，
+     * 叶子才按类型给）。刻意**不进** `<page-element>` 块：AI 从 outerHtml 就能看出结构，
+     * 多一行是噪音。
+     *
+     * 来自 `ElementCapabilities.childElementCount`，老 agent 不发那个字段时为 false。
+     */
+    hasChildren: boolean;
+    /** 祖先选择器路径（由近及远的反序，即从 body 到自己）。只给 selector，不给它们的 HTML。 */
+    ancestors: string[];
+    /**
+     * **可编辑的后代货架** —— 选中元素子树里的元素，每项一个可直接使用的 selector。
+     *
+     * 存在的理由：用户常常选的是一个**容器**（一个 section），而真正要改的文字在它的某个
+     * 子元素里。只给容器的 selector 时 agent 只能回「请你重新点选那个按钮」——
+     * 而它手上明明有 outerHTML、看得见那个按钮。
+     *
+     * ⚠️ 货架是**授权清单**，不是参考资料：作用域闸只接受「选中元素本身」或货架里逐字
+     * 命中的某一项。agent 因此永远不需要、也不允许自己拼子选择器 —— 拼错的 selector
+     * 改错元素**不报错**，用户只看到页面花了。
+     */
+    descendants: AiDescendant[];
+    /**
+     * **方案锚点的解析结果** —— 只有整页上下文（宿主传了 `anchors`）才有。
+     *
+     * 存在的理由：AI 建的实验来自一条点名了区块的假设（「B2 首屏的徽章」），而货架是一张
+     * 扁平的 selector 表，没有区块身份 —— agent 只能按关键词猜，猜错了也没有任何一道闸会
+     * 拦（实测：把首屏那条改到了页底另一个提到同样关键词的段落上）。
+     *
+     * ⚠️ `resolved: false` 的那几条**也要交出来**。不交的话 agent 以为锚点还在页面上，
+     * 会拿一个已经失效的 selector 反复重试；交出来它才知道要在货架里按标题重新找。
+     */
+    anchors?: ResolvedAnchor[];
+    /**
+     * 选中元素的几何。**可能缺**：几何帧还没到（刚打开画布）、或元素已不在文档里。
+     * 缺的时候 agent 就该避免给绝对定位/固定尺寸的东西 —— 见 skill。
+     */
+    geometry?: AiElementGeometry;
+    /** 已剥 script/noscript 的 outerHTML，超预算则截断。 */
+    outerHtml: string;
+    /**
+     * `'anchors'` = `outerHtml` **不是这个元素本身**，而是方案锚点所在区块的 outerHTML +
+     * 页面链接清单的组合（见 `AiHtmlFragment`）。只在首版（body 为根、有锚点）出现；
+     * 元素级上下文没有这个键 —— 那份 `outerHtml` 就是选中元素自己。
+     * 宿主据此在 `<page-element>` 里写一行 `html-scope:`，agent 才不会把片段当整页读。
+     */
+    htmlScope?: 'anchors';
+    /**
+     * 区块 / 元素里的真实图片（见 `AiPageImage`）。宿主写成 `anchor-image:`（整页首版）或
+     * `element-image:`（元素级）行。老扩展不认识 `getElementImages`、或这一块里没有图时
+     * 这个键不存在。
+     */
+    images?: AiPageImage[];
+    /**
+     * **换图会落在哪一支** —— `'img'` = 改 `<img>` 的 src，`'background'` = 改
+     * `background-image`。两者都不是（普通文字元素）时**没有这个键**。
+     *
+     * ⚠️ 为什么必须给：块里只有 outerHTML，而 PageFly / styled-components 这类页面的照片是
+     * **CSS 类**设的背景图 —— html 里既没有 `<img>` 也没有内联样式，agent 只能猜自己的
+     * `CHANGE_IMAGE` 会不会被闸打回（真机 2026-09-22：它猜对了分支，但全程是在赌）。
+     * 这个值来自选中那一刻就已经在手上的能力位（`isImg` / `hasBackgroundImage`），
+     * 与闸判分支用的是**同一个函数**（`resolveImageBranch`），不会两边漂移。
+     */
+    imageTarget?: 'img' | 'background';
+    /**
+     * `true` = 上面那段被截断了。
+     *
+     * ⚠️ **必须一并送给 AI**。不说的话它会拿半截 HTML 当全部去下结论 —— 比如断言
+     * 「这个容器里只有一个按钮」，而其实后面还有十个被截掉了。
+     */
+    htmlTruncated: boolean;
+    /** 原始字节数（截断时才有意义，用于让 AI 知道少看了多少）。 */
+    htmlBytes: number;
+}
+/**
+ * 按预算截断 HTML。
+ *
+ * **从中间截**而不是只留开头：一个元素的开头是标签和属性、结尾是闭合与末尾子节点，
+ * 只留开头会让 AI 看到一个永远没有闭合的片段，更容易被误读成「结构不完整的坏 HTML」。
+ */
+export declare function truncateHtml(rawHtml: string, budget?: number): {
+    text: string;
+    truncated: boolean;
+    bytes: number;
+};
+/**
+ * **首版 html 片段**：方案锚点所在区块的 outerHTML、以及页面已有链接清单。
+ *
+ * 存在的理由（真机 2026-09-20，vivaia，243KB 的 PageFly 页）：首版上下文以 body 为根，整页
+ * outerHTML 按 4KB 从中间截，agent 拿到的是 `<div class="route-loader">…` 和页脚 ——
+ * 它要改的首屏一个字节都不在。结果是「无法确定购买链接」（CTA 落成不可点的 span）、
+ * 颜色/字号只能从截图猜。锚点区块的 outerHTML 才是它要改的东西；链接清单是它被允许
+ * 使用的 href 的唯一来源。
+ */
+export interface AiHtmlFragment {
+    /** 注释头里的名字：区块号（`B1`）或 `links on page`。 */
+    label: string;
+    /** 这段 HTML 来自哪个元素（链接清单写 `(scan)`）。 */
+    selector: string;
+    html: string;
+}
+/**
+ * 首版时每个锚点区块的裁切截图。与整页截图一起附上：整页图告诉 agent 区块在哪、周围是什么，
+ * 裁切图才看得清区块内文字的颜色、字重、按钮的圆角 —— 这些是它要"融进去"的东西。
+ */
+export type AnchorShot = {
+    blockId?: string;
+    label: string;
+    /** 实际截的元素（区块容器，见 `blockContainerFor`），不一定等于锚点 selector。 */
+    selector: string;
+} & ({
+    url: string;
+    error?: never;
+}
+/**
+ * 没截到：失败原因原文。宿主把它写进 `<page-element>`（`not captured: …`）——
+ * 真机 9/21、9/23 有锚点却没有近景图，原因只闪在编辑器提示条上，trace 里无处可查；
+ * agent 也因此知道这张图没有，而不是以为自己看全了。
+ */
+ | {
+    error: string;
+    url?: never;
+});
+/**
+ * 锚点区块里真实图片的 URL（首版专用）。`<img src>` 与 CSS 里的 `background-image` 都在——
+ * PageFly 页的首屏照片是类名设的背景，outerHTML 里根本没有，只有计算样式里有（`getElementImages`
+ * 命令）。agent 换图时用它当 `referenceImageUrl`（当前这张图的构图/色调），而不是叠着文字的区块截图。
+ */
+export interface AiPageImage {
+    blockId?: string;
+    /** 承载这张图的元素（`<img>` 自己，或设了 background-image 的容器）。 */
+    selector: string;
+    kind: 'img' | 'background';
+    url: string;
+}
+/** 每个片段的预算。一个首屏区块几十行标记通常 1-3KB；塞了 base64 图的会在块内截。 */
+export declare const AI_FRAGMENT_BUDGET_BYTES = 3072;
+/** 所有片段合计的预算 —— 首版是一次性的消息，可以比元素级的 4KB 大，但不能无上限。 */
+export declare const AI_FRAGMENTS_TOTAL_BUDGET_BYTES = 8192;
+/**
+ * 给 AI 看的 html 里，把 `srcset` 的值换成 `(N sizes, omitted)`。
+ *
+ * 那是**同一张图**的一串不同尺寸地址（浏览器按屏宽 / 像素密度挑一张），对 AI 没有信息量，却很占
+ * 预算 —— 真机 2026-09-24：B2 商品卡区块 4.6KB 里约 2/3 是 srcset，结构（「今すぐ購入」那段）被截掉。
+ * 实际显示的是哪张由 `anchor-image` / `element-image`（currentSrc）与截图给。**属性名保留**：AI 仍看得出这里是响应式图，
+ * `<picture><source media>` 这种「不同屏幕显示不同图」的结构与 media 条件也原样在（换图时编辑器与 SDK
+ * 都会清掉 srcset / source，所有屏宽统一显示新图 —— 这件事 AI 得看得出来）。只影响给 AI 的文本，
+ * 页面与换图行为不受影响。
+ */
+export declare function compactSrcsetForAi(html: string): string;
+/**
+ * 把片段组合成一段给 agent 读的 html：每块一行注释头（label / selector / 原始字节），块之间
+ * 空一行；单块超预算在**块内**从中间截（同 `truncateHtml` 的理由：头是标签和属性、尾是闭合，
+ * 只留头会被读成坏 HTML）；总预算用完后面的块整块不进，并写明省略了几块 —— 不说的话 agent
+ * 会以为方案点名的另一个区块"在页面上不存在"。
+ */
+export declare function composeAnchorHtml(fragments: AiHtmlFragment[], opts?: {
+    perFragment?: number;
+    total?: number;
+}): {
+    text: string;
+    truncated: boolean;
+    bytes: number;
+};
+/**
+ * 从整页 html 里抽"可指认的链接"：`<a href>` + 可见文本。这是 agent 被允许用于 `href` /
+ * `SET_LINK` 的唯一来源（它不许编 URL），而整页 html 本身进不了 prompt。
+ *
+ * 剔掉：`javascript:` / 纯锚点 `#…`（不是跳转）、没有文本的（只有图的 LINE 浮标之类，
+ * agent 认不出是什么）、文本过长的（文章标题不是 CTA）。按 href 去重，保留首次出现的文本。
+ */
+export declare function extractPageLinks(html: string, opts?: {
+    limit?: number;
+    maxTextChars?: number;
+}): Array<{
+    href: string;
+    text: string;
+}>;
+/** 链接清单 → 一个片段；没有链接就 null（别送一段空 html 让 agent 猜它是什么意思）。 */
+export declare function linksFragment(links: Array<{
+    href: string;
+    text: string;
+}>): AiHtmlFragment | null;
+/** 货架上限。放太多就是把整棵 DOM 树塞进每轮对话；30 项够覆盖一个区块的可改点。 */
+export declare const AI_DESCENDANT_LIMIT = 30;
+/**
+ * **整页**上下文（`onPageContextReady`，以 body 为根）的货架上限。
+ *
+ * 与元素级那档**刻意分开、也刻意更大**：元素级是「用户已经选好了一个区块，只要它里面的
+ * 可改点」；整页那份是 AI 自己挑改哪儿（首版生成），30 项连一个长落地页的区块标题都盖不全，
+ * agent 只能去编 selector —— 而编出来的 selector 会被作用域闸原样拒掉。
+ *
+ * 60 → 100：货架改成「区块优先」（`buildRootShelf`）之后，每个区块是 1 行容器 + 最多 6 行
+ * 可改点，一个 10 个区块的落地页就是 70 行；60 会把最后几个区块整段切掉，AI 又回到
+ * 「找不到要改的那一块」。100 = 约 13 个区块，长落地页也够；header/nav/footer 各封 5 行，
+ * 不会被它们吃掉。
+ *
+ * 也不能顺手把 `AI_DESCENDANT_LIMIT` 一起调大：那份是**每轮对话**的固定开销，
+ * 整页这份一次会话只算一次。
+ */
+export declare const ROOT_SHELF_LIMIT = 100;
+/** 货架里文字摘要的长度。够认出「是哪个元素」就行，正文在 outerHtml 里。 */
+export declare const AI_DESCENDANT_TEXT_CHARS = 40;
+export declare function buildElementAiContext(input: {
+    selector: string;
+    tag: string;
+    ancestors: string[];
+    outerHtml: string;
+    hasChildren?: boolean;
+    descendants?: AiDescendant[];
+    geometry?: AiElementGeometry;
+    budget?: number;
+    /**
+     * 货架上限。默认元素级那档；整页上下文传 `ROOT_SHELF_LIMIT`。
+     *
+     * ⚠️ 有锚点行时**必须把它们的条数加上去**：下面这一刀切的是 `descendants`，
+     * 锚点行落在刀口之后的话，它们仍然被授权、却在 prompt 里消失了 ——
+     * 这是一种不报错的错配（agent 手上没有那个 selector，只能自己编，然后整批被拒）。
+     */
+    descendantLimit?: number;
+    /** 方案锚点的解析结果（整页上下文才有）。空数组 = 宿主给了锚点但一条都没命中。 */
+    anchors?: ResolvedAnchor[];
+    /**
+     * 首版专用：锚点区块的 outerHTML + 链接清单。**非空时取代 `outerHtml`**（整页那段一个字节
+     * 都不进 prompt），并标 `htmlScope: 'anchors'`。空数组 = 没解析到任何锚点，等同没传。
+     */
+    fragments?: AiHtmlFragment[];
+    /** 锚点区块 / 选中元素里的真实图片。空数组 = 没有 / 老扩展不认识命令，等同没传。 */
+    images?: AiPageImage[];
+    /** 换图落在哪一支（见 `ElementAiContext.imageTarget`）。不是图片目标时不传。 */
+    imageTarget?: 'img' | 'background';
+}): ElementAiContext;

package/dist/kernel/selection/elementAiContext.js

@@ -0,0 +1,122 @@
+export const AI_HTML_BUDGET_BYTES = 4096;
+export const SHELF_TREE_MAX_DEPTH = 64;
+export const SHELF_TREE_MAX_NODES = 1000;
+export function truncateHtml(rawHtml, budget = AI_HTML_BUDGET_BYTES) {
+    const html = compactSrcsetForAi(rawHtml);
+    const bytes = new TextEncoder().encode(html).length;
+    if (bytes <= budget)
+        return { text: html, truncated: false, bytes };
+    const half = Math.floor(budget / 2);
+    const head = html.slice(0, half);
+    const tail = html.slice(-half);
+    return {
+        text: `${head}\n<!-- …已截断，原始 ${bytes} 字节… -->\n${tail}`,
+        truncated: true,
+        bytes
+    };
+}
+export const AI_FRAGMENT_BUDGET_BYTES = 3072;
+export const AI_FRAGMENTS_TOTAL_BUDGET_BYTES = 8192;
+const SRCSET_ATTR = /(\s(?:srcset|imagesrcset|data-srcset))\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+function countSrcsetCandidates(value) {
+    const described = value.match(/\S\s+\d+(?:\.\d+)?[wx]\b/g)?.length ?? 0;
+    if (described)
+        return described;
+    return value.split(',').filter(part => part.trim()).length || 1;
+}
+export function compactSrcsetForAi(html) {
+    return html.replace(SRCSET_ATTR, (_match, name, dq, sq) => {
+        const quote = dq !== undefined ? '"' : "'";
+        const n = countSrcsetCandidates(dq ?? sq ?? '');
+        return `${name}=${quote}(${n} ${n === 1 ? 'size' : 'sizes'}, omitted)${quote}`;
+    });
+}
+export function composeAnchorHtml(fragments, opts = {}) {
+    const perFragment = opts.perFragment ?? AI_FRAGMENT_BUDGET_BYTES;
+    const total = opts.total ?? AI_FRAGMENTS_TOTAL_BUDGET_BYTES;
+    const parts = [];
+    let used = 0;
+    let truncated = false;
+    let bytes = 0;
+    let omitted = 0;
+    for (const f of fragments) {
+        const cut = truncateHtml(f.html, perFragment);
+        bytes += cut.bytes;
+        if (cut.truncated)
+            truncated = true;
+        const block = `<!-- ${f.label}: ${f.selector} (${cut.bytes} bytes${cut.truncated ? ', truncated' : ''}) -->\n${cut.text}`;
+        const size = new TextEncoder().encode(block).length;
+        if (parts.length && used + size > total) {
+            omitted++;
+            continue;
+        }
+        parts.push(block);
+        used += size;
+    }
+    if (omitted) {
+        truncated = true;
+        parts.push(`<!-- …${omitted} more fragment${omitted > 1 ? 's' : ''} omitted (budget)… -->`);
+    }
+    return { text: parts.join('\n\n'), truncated, bytes };
+}
+const PAGE_LINK_TEXT_CHARS = 40;
+const PAGE_LINK_LIMIT = 8;
+export function extractPageLinks(html, opts = {}) {
+    const limit = opts.limit ?? PAGE_LINK_LIMIT;
+    const maxText = opts.maxTextChars ?? PAGE_LINK_TEXT_CHARS;
+    const out = [];
+    const seen = new Set();
+    const re = /<a\b([^>]*?)\bhref\s*=\s*(?:"([^"]*)"|'([^']*)')[^>]*>([\s\S]*?)<\/a>/gi;
+    let m;
+    while ((m = re.exec(html)) && out.length < limit) {
+        const href = (m[2] ?? m[3] ?? '').trim();
+        if (!href || href.startsWith('#') || /^javascript:/i.test(href) || /^data:/i.test(href))
+            continue;
+        if (seen.has(href))
+            continue;
+        const text = m[4]
+            .replace(/<[^>]*>/g, ' ')
+            .replace(/&nbsp;/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!text || text.length > maxText)
+            continue;
+        seen.add(href);
+        out.push({ href, text });
+    }
+    return out;
+}
+export function linksFragment(links) {
+    if (!links.length)
+        return null;
+    return {
+        label: 'links on page',
+        selector: '(scan)',
+        html: links.map(l => `<a href="${l.href}">${l.text}</a>`).join('\n')
+    };
+}
+export const AI_DESCENDANT_LIMIT = 30;
+export const ROOT_SHELF_LIMIT = 100;
+export const AI_DESCENDANT_TEXT_CHARS = 40;
+export function buildElementAiContext(input) {
+    const fragments = input.fragments ?? [];
+    const images = input.images ?? [];
+    const { text, truncated, bytes } = fragments.length
+        ? composeAnchorHtml(fragments)
+        : truncateHtml(input.outerHtml, input.budget);
+    return {
+        ...(fragments.length ? { htmlScope: 'anchors' } : {}),
+        ...(images.length ? { images } : {}),
+        ...(input.imageTarget ? { imageTarget: input.imageTarget } : {}),
+        selector: input.selector,
+        tag: input.tag,
+        hasChildren: input.hasChildren ?? false,
+        ancestors: input.ancestors,
+        descendants: (input.descendants ?? []).slice(0, input.descendantLimit ?? AI_DESCENDANT_LIMIT),
+        ...(input.anchors ? { anchors: input.anchors } : {}),
+        ...(input.geometry ? { geometry: input.geometry } : {}),
+        outerHtml: text,
+        htmlTruncated: truncated,
+        htmlBytes: bytes
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 几何帧 → AI 上下文里的几何。
+ *
+ * 单独一个纯函数而不是内联：这里有两处**容易写错且不报错**的判断 ——
+ * 「元素不可见时不给几何」与「纵向要换成文档坐标」。
+ */
+import type { CanvasDevice, CanvasGeometryPayload } from '@ptengine/inline-core/protocol';
+import type { AiElementGeometry } from './elementAiContext.js';
+export declare function elementGeometryForAi(payload: CanvasGeometryPayload | null | undefined, device: CanvasDevice): AiElementGeometry | undefined;

package/dist/kernel/selection/elementGeometryForAi.js

@@ -0,0 +1,15 @@
+export function elementGeometryForAi(payload, device) {
+    const rect = payload?.selectedViewportRect;
+    if (!payload || !rect)
+        return undefined;
+    if (rect.width <= 0 || rect.height <= 0)
+        return undefined;
+    return {
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        topInPage: Math.round(rect.y + payload.scrollY),
+        viewportWidth: Math.round(payload.viewportWidth),
+        viewportHeight: Math.round(payload.viewportHeight),
+        device
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { ViewportRect } from '@ptengine/inline-core/protocol';
+/**
+ * frame 视口坐标 → 产品页视口坐标。
+ *
+ * ⚠️ **必须从零写，engage-editor 没有可参考代码，而且它那几处都是坑**：
+ * - 它把缩放做在 iframe 内部 `<html>` 的 transform 上并显式设 `frameScale = 1`
+ *   （`PageIframe.vue:557,565`），overlay 侧**零补偿** —— 所以它根本没有这个问题；
+ * - `dom_utils_overlayProperties` 的 scale 分支**只乘 w/h 不乘 left/top**
+ *   （`goog$modules.util.js:446-455`），照搬会让缩放后位置整体偏移，缩放比越小偏得越多；
+ * - `getZoom()` 的终止条件用父页面 document（`:405-418`），跨文档时行为不对。
+ *
+ * 我们的做法：`zoom` 加在**父页面容器**上，agent 上报的是**未缩放的 frame 视口坐标**，
+ * 所以 x/y/w/h **四个都要乘 zoom**，然后叠加 iframe 自身在页面里的偏移
+ * （偏移是产品页坐标，**不参与缩放**）。
+ */
+export interface FrameToProductContext {
+    /** iframe 元素的 `getBoundingClientRect()`（产品页视口坐标）。 */
+    iframeRect: {
+        left: number;
+        top: number;
+    };
+    zoom: number;
+}
+/**
+ * 量出换算所需的上下文。
+ *
+ * ⚠️ **必须量 iframe 元素本身，不能量它的容器。** `CanvasFrame` 把 iframe 放在一个
+ * `justify-content: center` 的 flex 容器里，所以当渲染宽度小于容器宽度时，iframe 是
+ * **居中**的、左边留白 `(容器宽 − 渲染宽)/2`。
+ *
+ * PC 端看不出差别：`zoom = 面板宽 / 1440`，渲染宽恰好等于面板宽、没有留白。
+ * **SP 端 `zoom` 被「只缩不放」夹成 1**，渲染宽 390 < 面板宽，于是留白出现 ——
+ * 量容器就会让选中框整体左偏正好那么多。这个偏移只在移动端出现，且不报任何错。
+ *
+ * `zoom` 由调用方给（它与 `CanvasFrame` 内部用同一个公式，见 InlineEditor 的注释）。
+ */
+export declare function measureFrameContext(iframe: {
+    getBoundingClientRect(): {
+        left: number;
+        top: number;
+    };
+} | null | undefined, zoom: number): FrameToProductContext;
+export declare function frameRectToProductRect(rect: ViewportRect, ctx: FrameToProductContext): ViewportRect;
+/**
+ * 反向：产品页视口坐标 → frame 视口坐标。
+ * 目前没有消费方（命中测试在 frame 内做），但与正向成对定义能防止将来有人
+ * 只写一半、或把除法写成乘法。有 round-trip 测试守着。
+ */
+export declare function productPointToFramePoint(point: {
+    x: number;
+    y: number;
+}, ctx: FrameToProductContext): {
+    x: number;
+    y: number;
+};

package/dist/kernel/selection/geometry.js

@@ -0,0 +1,18 @@
+export function measureFrameContext(iframe, zoom) {
+    const rect = iframe?.getBoundingClientRect();
+    return { iframeRect: { left: rect?.left ?? 0, top: rect?.top ?? 0 }, zoom };
+}
+export function frameRectToProductRect(rect, ctx) {
+    return {
+        x: rect.x * ctx.zoom + ctx.iframeRect.left,
+        y: rect.y * ctx.zoom + ctx.iframeRect.top,
+        width: rect.width * ctx.zoom,
+        height: rect.height * ctx.zoom
+    };
+}
+export function productPointToFramePoint(point, ctx) {
+    return {
+        x: (point.x - ctx.iframeRect.left) / ctx.zoom,
+        y: (point.y - ctx.iframeRect.top) / ctx.zoom
+    };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * 方案锚点（宿主给的「这一版要改哪个区块」）→ 货架行 + 授权表。
+ *
+ * 为什么需要这一层：AI 建的 inline 实验来自一条**点名了区块**的假设（「B2 首屏的徽章」），
+ * 而编辑器交给 agent 的只有一张扁平的 selector 货架 —— 上面没有任何区块身份。真机 trace 里
+ * agent 把「首屏徽章（B2，top:78）」静默重锚到了 `div.pf-62_`（top:1231，B4），只因为那段
+ * 文字里出现了同样的关键词；没有任何一道闸会拒绝它，用户只看到改动落在了页面下半部。
+ *
+ * 这里做两件事：
+ * ① 把宿主存下来的锚点**在活页面上重新解析**（selector 优先，失败按 label 在树上找回来）；
+ * ② 把命中的锚点**连同它的子树**产出成货架行 —— 货架是授权清单，孩子不在货架里的话
+ *    agent 想改容器里的某个按钮就会整批 `OUT_OF_SCOPE`。
+ *
+ * ⚠️ 货架与 `ancestorsOf` **同一个出口**（与 `buildRootShelf` 同一条纪律）：每一行都在表里、
+ * 表里也只有货架里的行。两边一旦漂移就是「同一个 selector 有时能移有时不能，且不报错」。
+ */
+import type { DomTreeNode } from '@ptengine/inline-core/protocol';
+import { type AiDescendant, type AiPageImage } from './elementAiContext.js';
+/** 宿主存下来的一个锚点。与 backend `contracts.ts` 的 `InlinePlanAnchor` 逐字同形。 */
+export interface InlinePlanAnchor {
+    /** 作者写方案那一刻的内核 selector。 */
+    selector: string;
+    /** 区块标题 / 首句 —— selector 失效时按它找回来。 */
+    label: string;
+    /** 页面模型里的区块号（B2…）。纯展示：让 agent 与用户说的是同一个区块。 */
+    blockId?: string;
+    /**
+     * 方案卡上写下的**落法**（2026-09-30）：`op` 是编辑器要执行的那个 op；`mode` 只对
+     * INSERT_ELEMENT 有意义（before/after = 进锚点的父级、按父级的排法摆；insert/append = 进锚点
+     * 自己）；`placement` 是一句人话（「h1 正下方、同列」）。
+     *
+     * 此前锚点只有 selector，意图只活在模型二次转述的 brief 自由文本里 —— 首版把「标题下方」
+     * 做成了 after 一个 flex 横排里的 Column。三个都可选：老方案没有；宿主只原样打印给 agent。
+     */
+    op?: string;
+    mode?: string;
+    placement?: string;
+    /**
+     * 该区块（B{n}）在活页面上的 member 容器 selector，外层优先。**只在内存里**（宿主从页面模型
+     * 补进来），不落库、不与 backend 同形。
+     *
+     * 存在的理由：锚点常常是区块里的一个叶子/小列（真机：首屏 B1 的锚点是只有 h1+h2 的
+     * `div.pf-503_`，照片挂在旁边的 `div.pf-505_` 上）。真实图片与裁切截图要按**区块**取，
+     * 否则查到的是"这个文字列里没有图"。html 片段仍按锚点容器取（区块整段太大）。
+     */
+    blockSelectors?: string[];
+    /**
+     * 这是用户**最近一次选中的方案**的锚点（只在内存里，宿主补进来）。宿主写成 `latest pick`：打开编辑器
+     * 是为了把那个方案加成新版本时，模型要知道改的是这一块，而不是 `plan:` 里旧版本的区块。
+     */
+    latestPick?: boolean;
+}
+/** 解析结果。`resolved: false` 也要交给宿主 —— 不说的话 agent 以为它还在。 */
+export interface ResolvedAnchor extends InlinePlanAnchor {
+    resolved: boolean;
+    /** 哪条路成功的。`label` = 原 selector 已失效（客户改版），值得让 agent 知道。 */
+    via?: 'selector' | 'label';
+}
+export interface AnchorShelfResult {
+    /** 锚点容器行在前、其子树行在后，按锚点顺序。 */
+    shelf: AiDescendant[];
+    /** 每一行的祖先链，**绝对到 body**（由近及远，不含自己）。 */
+    ancestorsOf: Map<string, string[]>;
+    anchors: ResolvedAnchor[];
+}
+/**
+ * 首版 html 片段该取哪个元素的 outerHTML —— 锚点所在的**区块容器**，不是锚点自己。
+ *
+ * 锚点是叶子（`h2.pf-119_`，EDIT_TEXT 的落点）时，只给那个 `<h2>` agent 看不到旁边的
+ * 证言卡片和按钮，等于没给；锚点本身就是容器（INSERT_ELEMENT 进 `div.pf-23_`）时就是它。
+ * 上溯只认**货架里有的容器行**（被授权的区块），跳过中间那些包装 div；`body` 不算区块 ——
+ * 走到它就退回锚点自己（宁可给窄的，不给整页）。
+ */
+export declare function blockContainerFor(anchor: InlinePlanAnchor | ResolvedAnchor, shelf: AiDescendant[], ancestorsOf: Map<string, string[]>): string;
+/**
+ * 锚点往外最近一个**自身**带 CSS 背景图的元素（货架行 `image: 'background'`），到 body 为止。
+ *
+ * 用途：锚点没有区块容器（`blockSelectors` —— 页面模型没了：刷新过页面 / 不是从分析画布进的编辑器）
+ * 时，找真实图片也要够到它。PageFly 页的首屏照片是外层 section 的类名背景，锚点多是里面的文字列
+ * （真机 2026-09-24：vivaia 锚点 `div.pf-504_` / `h1.pf-502_`，照片在 `div.pf-505_`），只查锚点
+ * 子树就一张图都没有。锚点自己就带背景 → null（它本来就在查找范围里）。
+ */
+export declare function backgroundImageAncestorFor(selector: string, shelf: AiDescendant[], ancestorsOf: Map<string, string[]>): string | null;
+/**
+ * 把首版找到的真实图片元素（`anchor-image:` 那几行）并进授权货架。
+ *
+ * 为什么：编辑器只放行货架上**逐字出现**的 selector，而承载图片的元素常常不在货架里 ——
+ * PageFly 首屏照片是区块外层容器的 CSS 背景，锚点子树（4 层）与整页货架（按区块挑）都够不到。
+ * 首版照「新图：」brief 换首屏图时（2026-09-30 起首版允许生图），`CHANGE_IMAGE` 打在
+ * `anchor-image:` 点名的元素上会整条 `OUT_OF_SCOPE`，模型却以为给出的就是合法落点。
+ *
+ * - 货架里已有的行：补上 `image` 标记（没有才补，不覆盖树上读到的）；
+ * - 不在的：追加成一行，排在锚点行之后、整页货架之前 —— 与锚点行同一个理由，排在刀口
+ *   （`descendantLimit`）之后就是「授权了、prompt 里却看不到」。
+ *
+ * 纯函数、不碰祖先表：调用方先给每个新元素取真实祖先链（货架每一行都必须在表里），只把取到链的
+ * 图片交进来。返回 `added` = 新增行数，调用方据此把 `descendantLimit` 抬高同样的量。
+ */
+export declare function withImageRows(shelf: AiDescendant[], anchorRowCount: number, images: AiPageImage[]): {
+    shelf: AiDescendant[];
+    added: number;
+};
+export declare function resolveInlinePlanAnchors(input: {
+    anchors: InlinePlanAnchor[];
+    /** 已经拉到的整页树（锚点的绝对祖先链、label 回落都从它上面取，不再多一次往返）。 */
+    rootTree: DomTreeNode;
+    /** 探活。未命中是**正常分支**（resolve 一个 `matched:false`），不是异常。 */
+    resolveSelector: (selector: string) => Promise<{
+        matched: boolean;
+        matchCount: number;
+    }>;
+    /** 取锚点子树（宿主用 `getDomTree(rootSelector, …)` 包一层）。 */
+    getSubtree: (rootSelector: string) => Promise<DomTreeNode>;
+    /** 每个锚点最多产出几行子树（不含容器行）。 */
+    limitPerAnchor?: number;
+}): Promise<AnchorShelfResult>;