@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/kernel/blocks/annotateAndTile.js

@@ -0,0 +1,122 @@
+export const ANNOTATE_DEFAULTS = { tileHeight: 2000, maxTiles: 6 };
+export const MIN_DOWNSCALE = 0.5;
+export const BLOCK_COLORS = ['#1D4ED8', '#DB2777'];
+const STROKE_PX = 3;
+const LABEL_PAD = 4;
+const LABEL_FONT_PX = 16;
+const LABEL_H = LABEL_FONT_PX + 8;
+export const TILE_JPEG_QUALITY = 0.82;
+export function planAnnotateAndTile(input) {
+    const tileHeight = Math.max(1, Math.trunc(input.tileHeight ?? ANNOTATE_DEFAULTS.tileHeight));
+    const maxTiles = Math.max(1, Math.trunc(input.maxTiles ?? ANNOTATE_DEFAULTS.maxTiles));
+    const pageWidthPx = input.pageWidthPx && input.pageWidthPx > 0 ? input.pageWidthPx : input.imageWidth;
+    const dpr = input.imageWidth / pageWidthPx;
+    const budget = tileHeight * maxTiles;
+    const downscale = input.imageHeight > budget ? Math.max(MIN_DOWNSCALE, budget / input.imageHeight) : 1;
+    const width = Math.max(1, Math.round(input.imageWidth * downscale));
+    const height = Math.max(1, Math.round(input.imageHeight * downscale));
+    const pxPerPagePx = dpr * downscale;
+    const tiles = [];
+    for (let top = 0, index = 0; top < height; top += tileHeight, index++) {
+        tiles.push({ index, top, height: Math.min(tileHeight, height - top) });
+    }
+    const truncated = tiles.length > maxTiles;
+    const boxes = [];
+    input.blocks.forEach((b, i) => {
+        const rawY = b.top * pxPerPagePx;
+        const rawBottom = (b.top + b.height) * pxPerPagePx;
+        const y = Math.max(0, Math.round(rawY));
+        const bottom = Math.min(height, Math.round(rawBottom));
+        if (bottom <= y)
+            return;
+        const color = BLOCK_COLORS[i % 2];
+        boxes.push({
+            id: b.id,
+            x: 0,
+            y,
+            width,
+            height: bottom - y,
+            color,
+            label: {
+                x: LABEL_PAD,
+                y: y + LABEL_PAD,
+                width: Math.round(LABEL_FONT_PX * 0.62 * b.id.length + LABEL_PAD * 2),
+                height: LABEL_H,
+                text: b.id
+            }
+        });
+    });
+    return {
+        downscale,
+        pxPerPagePx,
+        width,
+        height,
+        pageHeight: Math.round(input.imageHeight / dpr),
+        tileHeight,
+        tiles: tiles.slice(0, maxTiles),
+        boxes,
+        truncated
+    };
+}
+function toBlob(canvas, type, quality) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob(b => (b ? resolve(b) : reject(new Error('toBlob returned null'))), type, quality);
+    });
+}
+const browserDeps = {
+    async decode(blob) {
+        const bitmap = await createImageBitmap(blob);
+        return { width: bitmap.width, height: bitmap.height, source: bitmap };
+    },
+    async render(image, plan) {
+        const full = document.createElement('canvas');
+        full.width = plan.width;
+        full.height = plan.height;
+        const ctx = full.getContext('2d');
+        if (!ctx)
+            throw new Error('canvas 2d context unavailable');
+        ctx.drawImage(image.source, 0, 0, plan.width, plan.height);
+        ctx.lineWidth = STROKE_PX;
+        ctx.font = `bold ${LABEL_FONT_PX}px system-ui, -apple-system, sans-serif`;
+        ctx.textBaseline = 'middle';
+        for (const box of plan.boxes) {
+            ctx.strokeStyle = box.color;
+            ctx.strokeRect(box.x + STROKE_PX / 2, box.y + STROKE_PX / 2, Math.max(0, box.width - STROKE_PX), Math.max(0, box.height - STROKE_PX));
+            ctx.fillStyle = box.color;
+            ctx.fillRect(box.label.x, box.label.y, box.label.width, box.label.height);
+            ctx.fillStyle = '#FFFFFF';
+            ctx.fillText(box.label.text, box.label.x + LABEL_PAD, box.label.y + box.label.height / 2);
+        }
+        const out = [];
+        for (const tile of plan.tiles) {
+            const c = document.createElement('canvas');
+            c.width = plan.width;
+            c.height = tile.height;
+            const tctx = c.getContext('2d');
+            if (!tctx)
+                throw new Error('canvas 2d context unavailable');
+            tctx.drawImage(full, 0, tile.top, plan.width, tile.height, 0, 0, plan.width, tile.height);
+            out.push(await toBlob(c, 'image/jpeg', TILE_JPEG_QUALITY));
+        }
+        return out;
+    }
+};
+export async function annotateAndTile(fullPage, blocks, opts = {}, deps = browserDeps) {
+    const image = await deps.decode(fullPage);
+    const plan = planAnnotateAndTile({
+        imageWidth: image.width,
+        imageHeight: image.height,
+        pageWidthPx: opts.pageWidthPx,
+        blocks,
+        tileHeight: opts.tileHeight,
+        maxTiles: opts.maxTiles
+    });
+    const tiles = await deps.render(image, plan);
+    return {
+        tiles,
+        scale: plan.pxPerPagePx,
+        pageHeight: plan.pageHeight,
+        tileHeight: plan.tileHeight,
+        truncated: plan.truncated
+    };
+}

package/dist/kernel/blocks/resolveBlocks.d.ts

@@ -0,0 +1,153 @@
+import type { DomTreeNode, ElementsInBandResult, GetDomTreeParams, ResolveHeatmapSelectorResult } from '@ptengine/inline-core/protocol';
+/**
+ * 分析画布：把热图的**区块配置**（MySQL 里那份，apps/x 读来）画到客户活页面上，
+ * 并给每块找一个锚点元素 + 一份 AI 能读的摘要（标题 / 文案 / CTA）。
+ *
+ * ## 框来自配置，锚点来自页面
+ *
+ * **区块框恒等于配置的 `yStart/yEnd`**，与老热图 `CommonBlockMap.vue` 同一个契约
+ * （那边 `top: yStart*scale` / `height: (yEnd-yStart)*scale`，从不问 DOM）。这里解析出来的
+ * 元素**只决定锚点**（`members[].selector`：点进哪个元素、给 agent 交哪条 selector），
+ * 不回头改写框的位置。
+ *
+ * 曾经不是这样：框由解析到的元素矩形首尾相接推出来。实测（vivaia margot-walker，16 块配置）
+ * 的结果是 B2 吞掉 B3 上半段、B6 塌成 15px 细条**并排到了 B5 前面**、边界整体漂 300-500px ——
+ * 因为那页配置里的 selector 全都断在一个已被站点删掉的 `#wrapper` 祖先上，16 块全部退到几何
+ * 兜底，而几何只要 IoU ≥ 0.3 就认。职责一分开，解析失败就从「画错框」降级成「少个锚点」。
+ *
+ * 三条路（只影响锚点与摘要），按优先级：
+ * 1. **selector** —— 配置里的 jQuery 方言 selector 翻译后在活页面上唯一命中（`resolveHeatmapSelector`）。
+ *    命中的每条是一个 member；区块矩形 = 所有 member 的并（min top → max bottom）。
+ * 2. **geometry** —— selector 全失效时（客户改版，vivaia.jp 实测 0/33），拿 `yStart/yEnd`
+ *    去活页面上找最贴合的容器（`elementsInBand`，1-D IoU），取最佳一个当 member，记下 `iou`。
+ *    刻意**只在 selector 失败时才跑**：它要滚动取样，一块几十毫秒，十几块就是一秒多。
+ * 3. **none** —— 都没有：members 空。区块框照画（位置本来就来自配置，一样准），
+ *    只是点不进任何元素、也没有 selector 可以交给 agent。
+ *
+ * 编号 `B1..Bn` 按输入的 `yStart` 升序，与模型看到的瓦片标注一致（`annotateAndTile`）。
+ *
+ * 三条跨域命令经 `deps` 注入：编排逻辑不需要插件也不需要浏览器就能测。任何一条失败都
+ * **降级而不是抛**（老 agent 不认新命令 → AGENT_STALE；frame 失联 → FRAME_UNREACHABLE）：
+ * 分析画布宁可少几块摘要，也不能因为一块失败让整页黑掉。
+ */
+export interface HeatmapBlockConfig {
+    id: string | number;
+    name: string;
+    /** 文档 px，按热图量测时的视口宽（mobile 375 / pc 1440）。 */
+    yStart: number;
+    yEnd: number;
+    /** 热图 / SDK 的 jQuery 方言（`body>#wrapper>div:eq(0)…`，可能带 `v2>` 前缀）。 */
+    selectors: string[];
+}
+export interface PageModelBlockMember {
+    /** 内核方言（`buildSelector`）—— 画布闸门唯一认的那种。 */
+    selector: string;
+    tag: string;
+    /** 该 member 子树的文案摘要（折叠空白、≤80）。拉树失败为空串。 */
+    text: string;
+    hasChildren: boolean;
+}
+export interface PageModelBlock {
+    /** `'B1'`,`'B2'`… 按 `yStart` 升序。 */
+    id: string;
+    /**
+     * 热图配置里的块名。**原样保留**——`page_block_metrics` 的 `blockName` 靠它对上号。
+     * 自动识别常常拿图片文件名凑（`Frame 2007695980.png__PID:…`），给人看的那份在 `label`。
+     */
+    name: string;
+    /**
+     * 给人看的名字：`name` 像自动生成的、且这一块解析出了标题时 = 该标题。
+     * 缺省 = `name` 本身就能读。画布芯片、`<page-model>`、假设卡都显示它。
+     */
+    label?: string;
+    /**
+     * 文档 px，**恒等于配置的 `yStart`**（不随解析结果变）。
+     * 与 `<page-model>` / 截图编号框 / 老热图共用同一套坐标，三处永远对得上。
+     */
+    top: number;
+    /** 文档 px，**恒等于配置的 `yEnd - yStart`**。 */
+    height: number;
+    members: PageModelBlockMember[];
+    /** 根节点的 heading（agent 侧 h1-h4 → 首段 ≥4 字直属文本的兜底）。 */
+    heading?: string;
+    /** a / button / 链接节点的短文案（整棵子树的文字，≤20 字），最多 4 条，去重。 */
+    ctas: string[];
+    /**
+     * 这一块里可点的链接（`<a href>` 与 PageFly 图片链接 / 商品卡的 `data-href`）：`count` 个元素，
+     * 按去向（`linkPath`，查询串去掉）聚合、次数多的在前。**没有链接时不写这个键**（老扩展的树也没有）。
+     *
+     * 与 `ctas` 是两件事：图片链接没有文字，是导线但进不了 cta。真机 2026-10-15（vivaia allday）只有
+     * cta 一栏时，agent 把「没有 cta」读成了「全页没有购买导线」，而那页几乎每张图都链到商品页。
+     */
+    links?: BlockLinks;
+    /** 全部 member 子树文案拼接、折叠空白、≤80。 */
+    text: string;
+    resolved: 'selector' | 'geometry' | 'none';
+    /** 只有 `resolved === 'geometry'` 时有：最佳候选的 1-D IoU。 */
+    iou?: number;
+}
+export interface BlockLinks {
+    count: number;
+    targets: Array<{
+        path: string;
+        count: number;
+    }>;
+}
+export interface ResolveBlocksDeps {
+    resolveHeatmapSelector: (sessionId: string, selectors: string[]) => Promise<ResolveHeatmapSelectorResult>;
+    elementsInBand: (sessionId: string, band: {
+        yStart: number;
+        yEnd: number;
+        minIou?: number;
+    }) => Promise<ElementsInBandResult>;
+    getDomTree: (sessionId: string, opts: Omit<GetDomTreeParams, 'command' | 'sessionId'>) => Promise<DomTreeNode>;
+}
+export declare const BLOCK_TEXT_MAX = 80;
+export declare const CTA_TEXT_MAX = 20;
+export declare const CTA_LIMIT = 4;
+/**
+ * 摘要子树的总节点数封顶。真机（vivaia allday）一个 PageFly section 的可见节点只有 8-51 个，
+ * 留足余量；它只是防一块异常巨大的区块把整次 kickoff 拖慢。
+ */
+export declare const SUMMARY_TREE_MAX_NODES = 400;
+export interface TreeSummary {
+    heading?: string;
+    text: string;
+    ctas: string[];
+    /** 子树里每个链接节点的去向（`linkPath`），前序 DFS 顺序、不去重 —— 计数要用。 */
+    links: string[];
+    hasChildren: boolean;
+}
+/**
+ * 从一棵子树派生摘要。纯函数。
+ *
+ * - `heading`：根节点的 `heading`（agent 已做 h1-h4 → 直属文本兜底），空串视作没有；
+ * - `text`：前序 DFS 拼接每个节点的 `textSummary`（那是**直属**文本，所以拼起来不重复），
+ *   折叠空白、截到 80；
+ * - `ctas`：a / button / 带 `href` 的节点，取**整棵子树**的文字（`a>u>strong>span>span` 的直属
+ *   文本在最里层，`<a>` 自己是空的），≤20 字的非空文案，去重，最多 4 条；
+ * - `links`：带 `href` 的节点（`<a href>`、PageFly 的 `<img data-href>`），链接里面的链接不重复计。
+ *
+ * `hidden` 的节点连同子树整棵跳过：看不见的文字与链接不是这块的内容（取树时已 `visibleOnly`，
+ * 这里兜不带它的老调用方）。
+ */
+export declare function summarizeTree(root: DomTreeNode): TreeSummary;
+export interface ResolveBlocksOptions {
+    /**
+     * 画布当前施加在 `<html>` 上的缩放比例（`useInlineEditor().mobileFit.scale`），默认 1。
+     *
+     * 热图配置的 `yStart/yEnd` 是客户页**自然**文档坐标，而 agent 在缩放后的页面上量到的
+     * 元素位置是**视觉**坐标 —— `elementsInBand` 的 IoU 两边口径必须一致，所以 band 乘上
+     * 比例再发。产出的 `top/height` **不变**（仍是配置原值）：`<page-model>`、截图标注、老热图
+     * 三处共用这套坐标，由各自的消费者在画的时候乘比例。
+     */
+    scale?: number;
+}
+export declare function resolveBlocks(sessionId: string, blocks: HeatmapBlockConfig[], deps?: ResolveBlocksDeps, opts?: ResolveBlocksOptions): Promise<PageModelBlock[]>;
+/**
+ * 块名是不是自动识别凑出来的（图片文件名 / 设计稿图层名 / uuid / 占位名）。
+ *
+ * 判据只认**明确像机器生成**的形状，宁可漏判也不误判：真人写的名字被换掉，用户会以为
+ * 区块对错了。
+ */
+export declare function isAutoGeneratedBlockName(name: string): boolean;

package/dist/kernel/blocks/resolveBlocks.js

@@ -0,0 +1,233 @@
+import { elementsInBand as elementsInBandCommand, getDomTree as getDomTreeCommand, resolveHeatmapSelector as resolveHeatmapSelectorCommand } from '../canvasCommands.js';
+import { linkPath } from '../linkHref.js';
+import { SHELF_TREE_MAX_DEPTH } from '../selection/elementAiContext.js';
+const defaultDeps = {
+    resolveHeatmapSelector: resolveHeatmapSelectorCommand,
+    elementsInBand: elementsInBandCommand,
+    getDomTree: getDomTreeCommand
+};
+export const BLOCK_TEXT_MAX = 80;
+export const CTA_TEXT_MAX = 20;
+export const CTA_LIMIT = 4;
+export const SUMMARY_TREE_MAX_NODES = 400;
+const TREE_OPTS = {
+    maxDepth: SHELF_TREE_MAX_DEPTH,
+    maxChildren: 20,
+    maxNodes: SUMMARY_TREE_MAX_NODES,
+    visibleOnly: true,
+    includeRect: true
+};
+const CTA_TAGS = new Set(['a', 'button']);
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function clamp(text, max) {
+    return text.length > max ? text.slice(0, max) : text;
+}
+function subtreeText(n) {
+    if (n.hidden)
+        return '';
+    return [n.textSummary ?? '', ...(n.children ?? []).map(subtreeText)].join(' ');
+}
+export function summarizeTree(root) {
+    const texts = [];
+    const ctas = [];
+    const links = [];
+    const seen = new Set();
+    const walk = (n, insideCta) => {
+        if (n.hidden)
+            return;
+        const t = collapse(n.textSummary ?? '');
+        if (t)
+            texts.push(t);
+        const isCta = !insideCta && (!!n.href || CTA_TAGS.has(n.tag));
+        if (isCta) {
+            if (n.href)
+                links.push(linkPath(n.href));
+            const label = collapse(subtreeText(n));
+            if (label && label.length <= CTA_TEXT_MAX && !seen.has(label) && ctas.length < CTA_LIMIT) {
+                seen.add(label);
+                ctas.push(label);
+            }
+        }
+        for (const c of n.children ?? [])
+            walk(c, insideCta || isCta);
+    };
+    walk(root, false);
+    const heading = collapse(root.heading ?? '');
+    return {
+        heading: heading || undefined,
+        text: clamp(collapse(texts.join(' ')), BLOCK_TEXT_MAX),
+        ctas,
+        links,
+        hasChildren: (root.childCount ?? 0) > 0 || (root.children?.length ?? 0) > 0
+    };
+}
+function aggregateLinks(paths) {
+    if (paths.length === 0)
+        return undefined;
+    const counts = new Map();
+    for (const p of paths)
+        counts.set(p, (counts.get(p) ?? 0) + 1);
+    const targets = Array.from(counts, ([path, count]) => ({ path, count })).sort((a, b) => b.count - a.count);
+    return { count: paths.length, targets };
+}
+function geometryOf(cfg) {
+    return { top: cfg.yStart, height: Math.max(0, cfg.yEnd - cfg.yStart) };
+}
+function idOf(index) {
+    return `B${index + 1}`;
+}
+function bestCandidate(candidates) {
+    let best = null;
+    for (const c of candidates)
+        if (!best || c.iou > best.iou)
+            best = c;
+    return best;
+}
+export async function resolveBlocks(sessionId, blocks, deps = defaultDeps, opts = {}) {
+    if (blocks.length === 0)
+        return [];
+    const scale = opts.scale && opts.scale > 0 ? opts.scale : 1;
+    const ordered = blocks
+        .map((b, i) => ({ b, i }))
+        .sort((x, y) => x.b.yStart - y.b.yStart || x.i - y.i)
+        .map(x => x.b);
+    const allSelectors = Array.from(new Set(ordered.flatMap(b => (b.selectors ?? []).filter(s => typeof s === 'string' && s.length > 0))));
+    const matches = new Map();
+    if (allSelectors.length > 0) {
+        try {
+            const { results } = await deps.resolveHeatmapSelector(sessionId, allSelectors);
+            for (const r of results ?? [])
+                matches.set(r.input, r);
+        }
+        catch {
+        }
+    }
+    const out = [];
+    for (let i = 0; i < ordered.length; i++) {
+        const cfg = ordered[i];
+        const base = { id: idOf(i), name: cfg.name };
+        const hits = [];
+        const seen = new Set();
+        for (const s of cfg.selectors ?? []) {
+            const m = matches.get(s);
+            if (!m || m.matchCount !== 1 || !m.kernelSelector || !m.rect)
+                continue;
+            if (seen.has(m.kernelSelector))
+                continue;
+            seen.add(m.kernelSelector);
+            hits.push({ selector: m.kernelSelector, tag: m.tag ?? '', rect: m.rect });
+        }
+        if (hits.length > 0) {
+            out.push(await enrich(sessionId, deps, {
+                ...base,
+                ...geometryOf(cfg),
+                members: hits.map(h => ({
+                    selector: h.selector,
+                    tag: h.tag,
+                    text: '',
+                    hasChildren: false
+                })),
+                ctas: [],
+                text: '',
+                resolved: 'selector'
+            }));
+            continue;
+        }
+        let candidate = null;
+        try {
+            const { candidates } = await deps.elementsInBand(sessionId, {
+                yStart: cfg.yStart * scale,
+                yEnd: cfg.yEnd * scale
+            });
+            candidate = bestCandidate(candidates ?? []);
+        }
+        catch {
+            candidate = null;
+        }
+        if (candidate) {
+            out.push(await enrich(sessionId, deps, {
+                ...base,
+                ...geometryOf(cfg),
+                members: [
+                    {
+                        selector: candidate.kernelSelector,
+                        tag: candidate.tag,
+                        text: '',
+                        hasChildren: false
+                    }
+                ],
+                ctas: [],
+                text: '',
+                resolved: 'geometry',
+                iou: candidate.iou
+            }));
+            continue;
+        }
+        out.push({
+            ...base,
+            ...geometryOf(cfg),
+            members: [],
+            ctas: [],
+            text: '',
+            resolved: 'none'
+        });
+    }
+    return out;
+}
+export function isAutoGeneratedBlockName(name) {
+    const n = name.trim();
+    if (!n)
+        return true;
+    if (/\.(png|jpe?g|webp|gif|svg|avif)\b/i.test(n))
+        return true;
+    if (/__PID:/i.test(n))
+        return true;
+    if (/^(frame|group|rectangle|image|img|component|layer)[\s_-]*\d+$/i.test(n))
+        return true;
+    if (/^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}/i.test(n))
+        return true;
+    if (/^unnamed\b/i.test(n))
+        return true;
+    return false;
+}
+async function enrich(sessionId, deps, block) {
+    const summaries = await Promise.all(block.members.map(async (m) => {
+        try {
+            const tree = await deps.getDomTree(sessionId, {
+                rootSelector: m.selector,
+                ...TREE_OPTS
+            });
+            return summarizeTree(tree);
+        }
+        catch {
+            return null;
+        }
+    }));
+    const members = block.members.map((m, i) => {
+        const s = summaries[i];
+        return s ? { ...m, text: s.text, hasChildren: s.hasChildren } : m;
+    });
+    const heading = summaries.find(s => s?.heading)?.heading;
+    const ctas = [];
+    const seen = new Set();
+    for (const s of summaries) {
+        for (const c of s?.ctas ?? []) {
+            if (seen.has(c) || ctas.length >= CTA_LIMIT)
+                continue;
+            seen.add(c);
+            ctas.push(c);
+        }
+    }
+    const text = clamp(collapse(summaries.map(s => s?.text ?? '').join(' ')), BLOCK_TEXT_MAX);
+    const enriched = { ...block, members, ctas, text };
+    if (heading)
+        enriched.heading = heading;
+    const links = aggregateLinks(summaries.flatMap(s => s?.links ?? []));
+    if (links)
+        enriched.links = links;
+    if (heading && isAutoGeneratedBlockName(block.name))
+        enriched.label = heading;
+    return enriched;
+}

package/dist/kernel/canvasCapabilities.d.ts

@@ -0,0 +1,31 @@
+import { type HandshakeResult, type ReadyPayload } from '@ptengine/inline-core/protocol';
+/**
+ * 画布能力协商（契约 v11，设计见 inline-core `docs/contract-v11-design.md` §3）。
+ *
+ * 门禁不再按「产品页版本 ≤ 插件版本」整页拦截，而是：
+ * - 插件回报的能力集（v11+ 的 `capabilities`；旧插件按 SINCE 表由版本推导）；
+ * - 减去产品页侧**关掉**的能力（`configureInlineEditor` 的 `disabledCapabilities`）—— 插件发出去收不回，
+ *   v11 的任何 bug 都要能在产品页侧关掉对应能力、退回旧行为，而不是等下一次插件发版；
+ * - 只有缺 CORE 才整页拦截，其余能力由各消费方 `hasCanvasCapability()` 逐项启用 / 降级。
+ */
+/** 解析能力名列表（命令名或 `feature:*`）：逗号分隔字符串或字符串数组，trim、去空。 */
+export declare function parseDisabledCapabilities(raw: unknown): Set<string>;
+/** 消费方经 `configureInlineEditor({ disabledCapabilities })` 配置的「即使插件支持也不启用」的能力。 */
+export declare function disabledCapabilities(): Set<string>;
+/**
+ * 握手 → 本会话可用的能力集。
+ *
+ * CORE 能力**不能被关掉**：关掉它们等于整页关闭画布，那应该用别的开关明确做，而不是
+ * 借能力开关让门禁在一个看起来无关的配置下报 CONTRACT_MISMATCH。
+ */
+export declare function capabilitiesFromHandshake(handshake: Pick<HandshakeResult, 'contractVersion' | 'capabilities'>, disabled?: Set<string>): Set<string>;
+/**
+ * 按 agent 自报的能力收窄。SW 与 agent 可能版本不一致（已打开 tab 里残留旧 content script）：
+ * 产品页以 `handshake ∩ ready` 为准。agent 不会回报 SW 命令，所以 SW 命令恒保留。
+ * 旧 agent 不带 `capabilities` → 原样返回（SW 侧的 AGENT_STALE 机制继续兜底）。
+ */
+export declare function narrowByReady(caps: Set<string>, ready: Pick<ReadyPayload, 'capabilities'> | undefined): Set<string>;
+/** 缺了哪些 CORE 能力；非空即整页拦截。 */
+export declare function missingCoreCapabilities(caps: Set<string>): string[];
+/** 消费方按此逐项启用 / 降级。能力集还没就绪（门禁前）一律按不可用。 */
+export declare function hasCanvasCapability(caps: Set<string> | undefined, name: string): boolean;

package/dist/kernel/canvasCapabilities.js

@@ -0,0 +1,39 @@
+import { CANVAS_CORE_CAPABILITIES, CANVAS_SW_COMMANDS, resolveCapabilities } from '@ptengine/inline-core/protocol';
+import { getInlineEditorConfig } from './config.js';
+export function parseDisabledCapabilities(raw) {
+    const items = typeof raw === 'string' ? raw.split(',') : Array.isArray(raw) ? raw : [];
+    return new Set(items
+        .filter((s) => typeof s === 'string')
+        .map(s => s.trim())
+        .filter(Boolean));
+}
+export function disabledCapabilities() {
+    return parseDisabledCapabilities(getInlineEditorConfig().disabledCapabilities);
+}
+export function capabilitiesFromHandshake(handshake, disabled = disabledCapabilities()) {
+    const caps = resolveCapabilities(handshake);
+    const core = new Set(CANVAS_CORE_CAPABILITIES);
+    for (const name of disabled) {
+        if (!core.has(name))
+            caps.delete(name);
+    }
+    return caps;
+}
+export function narrowByReady(caps, ready) {
+    if (!ready || !Array.isArray(ready.capabilities))
+        return caps;
+    const agent = new Set(ready.capabilities);
+    const sw = new Set(CANVAS_SW_COMMANDS);
+    const out = new Set();
+    for (const c of caps) {
+        if (agent.has(c) || sw.has(c))
+            out.add(c);
+    }
+    return out;
+}
+export function missingCoreCapabilities(caps) {
+    return CANVAS_CORE_CAPABILITIES.filter(c => !caps.has(c));
+}
+export function hasCanvasCapability(caps, name) {
+    return !!caps && caps.has(name);
+}