@ptengine/inline-editor 0.0.0-stage → 0.1.0

package/dist/kernel/ai/insertHtmlGate.js

@@ -0,0 +1,123 @@
+import { imageSourceAllowed } from './imageSource.js';
+export const INSERT_HTML_BUDGET_BYTES = 8192;
+const ALLOWED_TAGS = new Set([
+    'div',
+    'span',
+    'p',
+    'a',
+    'button',
+    'strong',
+    'em',
+    'b',
+    'i',
+    'small',
+    'br',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'ul',
+    'ol',
+    'li',
+    'u',
+    'img',
+    'table',
+    'thead',
+    'tbody',
+    'tfoot',
+    'tr',
+    'td',
+    'th'
+]);
+const ALLOWED_ATTRS = new Set([
+    'class',
+    'style',
+    'href',
+    'target',
+    'rel',
+    'role',
+    'title',
+    'aria-label',
+    'aria-hidden',
+    'src',
+    'alt',
+    'width',
+    'height',
+    'loading'
+]);
+const STRIPPED_ATTRS = ['srcset', 'imagesrcset'];
+function isSafeHref(value) {
+    const v = value.trim().toLowerCase();
+    if (v.startsWith('#') || v.startsWith('/') || v.startsWith('./') || v.startsWith('../')) {
+        return true;
+    }
+    return v.startsWith('http://') || v.startsWith('https://') || v.startsWith('mailto:') || v.startsWith('tel:');
+}
+function isSafeStyleAttr(value) {
+    const v = value.toLowerCase();
+    return (!v.includes('javascript:') &&
+        !v.includes('expression(') &&
+        !v.includes('url('));
+}
+export function sanitizeInsertHtml(raw, images = { allowedImageOrigins: [] }) {
+    const html = (raw ?? '').trim();
+    if (!html)
+        return { ok: false, problem: { reason: 'EMPTY' } };
+    const bytes = new TextEncoder().encode(html).length;
+    if (bytes > INSERT_HTML_BUDGET_BYTES) {
+        return { ok: false, problem: { reason: 'TOO_LARGE', bytes } };
+    }
+    if (typeof DOMParser === 'undefined') {
+        return {
+            ok: false,
+            problem: { reason: 'UNSAFE_ATTR_VALUE', detail: 'no DOMParser to inspect markup' }
+        };
+    }
+    const doc = new DOMParser().parseFromString(`<div id="__ai_root">${html}</div>`, 'text/html');
+    const root = doc.getElementById('__ai_root');
+    if (!root) {
+        return { ok: false, problem: { reason: 'EMPTY' } };
+    }
+    for (const el of Array.from(root.querySelectorAll('*'))) {
+        const tag = el.tagName.toLowerCase();
+        if (!ALLOWED_TAGS.has(tag)) {
+            return { ok: false, problem: { reason: 'TAG_NOT_ALLOWED', detail: tag } };
+        }
+        for (const name of STRIPPED_ATTRS)
+            el.removeAttribute(name);
+        for (const attr of Array.from(el.attributes)) {
+            const name = attr.name.toLowerCase();
+            if (name.startsWith('on')) {
+                return { ok: false, problem: { reason: 'ATTR_NOT_ALLOWED', detail: `${tag}[${name}]` } };
+            }
+            if (!ALLOWED_ATTRS.has(name)) {
+                return { ok: false, problem: { reason: 'ATTR_NOT_ALLOWED', detail: `${tag}[${name}]` } };
+            }
+            if (name === 'href' && !isSafeHref(attr.value)) {
+                return {
+                    ok: false,
+                    problem: { reason: 'UNSAFE_ATTR_VALUE', detail: `href=${attr.value.slice(0, 40)}` }
+                };
+            }
+            if (name === 'style' && !isSafeStyleAttr(attr.value)) {
+                return {
+                    ok: false,
+                    problem: { reason: 'UNSAFE_ATTR_VALUE', detail: `style=${attr.value.slice(0, 40)}` }
+                };
+            }
+        }
+        if (tag === 'img' && !imageSourceAllowed(el.getAttribute('src'), images)) {
+            const src = el.getAttribute('src');
+            return {
+                ok: false,
+                problem: {
+                    reason: 'UNSAFE_IMAGE_SRC',
+                    detail: src ? `source not allowed: ${src.slice(0, 60)}` : 'img without src'
+                }
+            };
+        }
+    }
+    return { ok: true, html: root.innerHTML };
+}

package/dist/kernel/ai/postApplyCheck.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AI 改动落地后的**几何自检**（P2a，2026-09-30）。
+ *
+ * 为什么要有它：`propose_inline_changes` 的返回只是一个 ack，编辑器应用完既不量也不报 ——
+ * 两次真机都是同一种走样：把东西 `after` 到了一个横排容器的孩子上（首屏信任线跑到标题右边、
+ * 购买盒变成评价轮播的第六张 slide），页面上一眼就能看出来，链路里却没有任何一层会说话。
+ *
+ * 这里只做**确定性**判定，不看图、不问模型：输入是改前 / 改后的视口矩形，输出是几个标记 + 数字。
+ * 回执卡据此标 ⚠，后面（P2b）再把它送回模型让它自己修。
+ *
+ * 判定都带容差：客户页常有 transform 动画（`animate-bob` / `pulse`），矩形会抖一两个像素。
+ */
+import type { ViewportRect } from '@ptengine/inline-core/protocol';
+export type ApplyCheckFlag = 
+/** before/after 插入的新元素与锚点**并排**了（竖向重叠过半、水平不相交）：父级是横排。 */
+'SIDE_BY_SIDE'
+/** 锚点被挤窄（宽度缩了一成以上）：新元素挤进了同一行。 */
+ | 'ANCHOR_SQUEEZED'
+/** 新元素（或改后的目标）超出视口宽度：被推到屏幕外 / 横向滚动容器里。 */
+ | 'OVERFLOW_X'
+/** 新元素（或改后的目标）宽或高为 0：插进了隐藏区域，或被样式折叠。 */
+ | 'ZERO_SIZE'
+/** 改后的目标高度翻了倍以上：文案溢出、样式把布局撑开（只供核对，不一定是错）。 */
+ | 'HEIGHT_JUMP';
+export interface ApplyCheckInserted {
+    selector: string;
+    rect: ViewportRect | null;
+}
+export interface ApplyCheck {
+    flags: ApplyCheckFlag[];
+    /** 目标（锚点）改前 / 改后的视口矩形；量不到为 null。 */
+    targetBefore: ViewportRect | null;
+    targetAfter: ViewportRect | null;
+    /** 这条改动插入的新元素（INSERT 的根、EDIT_HTML 的新根）。 */
+    inserted: ApplyCheckInserted[];
+    /** 给回执卡 / 日志用的数字：`widthBefore` / `widthAfter` / `heightBefore` / `heightAfter` / `side`。 */
+    detail: Partial<{
+        widthBefore: number;
+        widthAfter: number;
+        heightBefore: number;
+        heightAfter: number;
+        side: 'left' | 'right';
+    }>;
+}
+export type ApplyCheckOp = 'INSERT_ELEMENT' | 'EDIT_TEXT' | 'CHANGE_STYLE' | 'EDIT_HTML' | 'CHANGE_IMAGE';
+export type ApplyCheckMode = 'insert' | 'append' | 'before' | 'after';
+/** 落地后、量之前等多久：让 transition（PageFly 按钮常见 `transition: all .3s`）与图片加载跑完。 */
+export declare const APPLY_CHECK_SETTLE_MS = 400;
+export declare function evaluateApplyCheck(input: {
+    op: ApplyCheckOp;
+    mode?: ApplyCheckMode;
+    targetBefore: ViewportRect | null;
+    targetAfter: ViewportRect | null;
+    inserted: ApplyCheckInserted[];
+    viewportWidth?: number;
+}): ApplyCheck;

package/dist/kernel/ai/postApplyCheck.js

@@ -0,0 +1,74 @@
+export const APPLY_CHECK_SETTLE_MS = 400;
+const PX_TOLERANCE = 2;
+const SQUEEZE_RATIO = 0.9;
+const OVERLAP_RATIO = 0.5;
+const HEIGHT_JUMP_RATIO = 2;
+const HEIGHT_JUMP_MIN_PX = 20;
+function zeroSize(r) {
+    return r.width <= 0 || r.height <= 0;
+}
+function overflowsX(r, viewportWidth) {
+    if (!viewportWidth || viewportWidth <= 0)
+        return false;
+    return r.x >= viewportWidth - PX_TOLERANCE || r.x + r.width <= PX_TOLERANCE;
+}
+function sideBySide(anchor, other) {
+    const overlap = Math.min(anchor.y + anchor.height, other.y + other.height) - Math.max(anchor.y, other.y);
+    const shorter = Math.min(anchor.height, other.height);
+    if (shorter <= 0 || overlap / shorter < OVERLAP_RATIO)
+        return null;
+    if (other.x >= anchor.x + anchor.width - PX_TOLERANCE)
+        return 'right';
+    if (other.x + other.width <= anchor.x + PX_TOLERANCE)
+        return 'left';
+    return null;
+}
+export function evaluateApplyCheck(input) {
+    const flags = new Set();
+    const detail = {};
+    const { op, mode, targetBefore, targetAfter, inserted, viewportWidth } = input;
+    const sibling = op === 'INSERT_ELEMENT' && (mode === 'before' || mode === 'after');
+    for (const item of inserted) {
+        const r = item.rect;
+        if (!r)
+            continue;
+        if (zeroSize(r)) {
+            flags.add('ZERO_SIZE');
+            continue;
+        }
+        if (overflowsX(r, viewportWidth))
+            flags.add('OVERFLOW_X');
+        if (sibling && targetAfter && !zeroSize(targetAfter)) {
+            const side = sideBySide(targetAfter, r);
+            if (side) {
+                flags.add('SIDE_BY_SIDE');
+                detail.side = side;
+            }
+        }
+    }
+    if (sibling && targetBefore && targetAfter && targetBefore.width > 0) {
+        if (targetAfter.width < targetBefore.width * SQUEEZE_RATIO) {
+            flags.add('ANCHOR_SQUEEZED');
+            detail.widthBefore = Math.round(targetBefore.width);
+            detail.widthAfter = Math.round(targetAfter.width);
+        }
+    }
+    if (op !== 'INSERT_ELEMENT') {
+        const after = targetAfter ?? inserted.find(i => i.rect)?.rect ?? null;
+        if (after) {
+            if (zeroSize(after))
+                flags.add('ZERO_SIZE');
+            else if (overflowsX(after, viewportWidth))
+                flags.add('OVERFLOW_X');
+            if (targetBefore &&
+                targetBefore.height > 0 &&
+                after.height > targetBefore.height * HEIGHT_JUMP_RATIO &&
+                after.height - targetBefore.height >= HEIGHT_JUMP_MIN_PX) {
+                flags.add('HEIGHT_JUMP');
+                detail.heightBefore = Math.round(targetBefore.height);
+                detail.heightAfter = Math.round(after.height);
+            }
+        }
+    }
+    return { flags: [...flags], targetBefore, targetAfter, inserted, detail };
+}

package/dist/kernel/ai/replaceHtmlGate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AI **整块重写**（`EDIT_HTML`）那段 HTML 的闸。
+ *
+ * ## 与 `insertHtmlGate` 的关系
+ *
+ * 同一套审查思路（真解析器、拒绝而非清洗、重新序列化），但**不能共用一份实现** ——
+ * 插入是「往页面上加一个小东西」，替换是「把一个既有元素整个换掉」，由此来三条硬差异：
+ *
+ * 1. **必须单根。** 被替换的一个元素变成 N 个，后续所有基于 `:nth-of-type` 的 selector
+ *    全部错位，而且是**上线之后**才暴露。人写 `</>` 那条路早就显式挡住了
+ *    （`dialogs/htmlValidation.ts`），AI 这条只会更需要。
+ * 2. **必须能带 `img`。** 整块重写要把块里原有的图再吐一遍；不允许 `img` 等于说
+ *    「含图的区块永远重写不了」——而首屏、商品展示这些最想改的块恰恰都含图。
+ *    放开的代价用 **origin 白名单**兜住（与 `CHANGE_IMAGE` 同一张表、同一套 origin 比较），
+ *    并且把 `srcset` 整条剥掉：那是第二条 URL 通道，白名单管不到它。
+ * 3. **预算更大。** 2048B 是按「一个小新元素」定的，真实区块的 outerHTML 不是那个量级。
+ *
+ * ⚠️ 用 `<template>` 解析而不是 `<div>`：`<div>` 会把 `<td>` / `<tr>` / `<option>` 这类
+ * **需要正确宿主**的标签当成错误内容丢掉 —— 于是「审查通过」了，应用后结构却塌掉。
+ * 这一条与 `dialogs/htmlValidation.ts` 同源，理由也一样。
+ *
+ * ⚠️ `url()` 仍然禁止。允许 `img` 不等于允许任意对外请求：`img[src]` 过 origin 白名单，
+ * 而 `style="background:url(...)"` 绕开那张表。
+ */
+import { type ImageSourcePolicy } from './imageSource.js';
+/** 一段替换 HTML 的字节上限。比插入那份宽，但模型偶尔会吐一整屏 markup，仍要封顶。 */
+export declare const REPLACE_HTML_BUDGET_BYTES = 8192;
+export type ReplaceHtmlReject = {
+    reason: 'EMPTY';
+} | {
+    reason: 'TOO_LARGE';
+    bytes: number;
+} | {
+    reason: 'NO_ROOT_ELEMENT';
+} | {
+    reason: 'MULTI_ROOT_HTML';
+    detail: string;
+} | {
+    reason: 'TAG_NOT_ALLOWED';
+    detail: string;
+} | {
+    reason: 'ATTR_NOT_ALLOWED';
+    detail: string;
+} | {
+    reason: 'UNSAFE_ATTR_VALUE';
+    detail: string;
+} | {
+    reason: 'UNSAFE_IMAGE_SRC';
+    detail: string;
+};
+export type ReplaceHtmlOutcome = 
+/** `html` 是**重新序列化后**的那份 —— 写进页面用它，不要用原串。 */
+{
+    ok: true;
+    html: string;
+} | {
+    ok: false;
+    problem: ReplaceHtmlReject;
+};
+/**
+ * `img[src]` 的来源规则：与 `CHANGE_IMAGE`、`INSERT_ELEMENT` 同一份（见 `imageSource.ts`）——
+ * origin 白名单（客户页自身 + 上传 / 生图域），或本页已出现过的图片地址（整串相等）。
+ */
+export type ReplaceHtmlOptions = ImageSourcePolicy;
+/**
+ * 审查并规整一段将**替换掉某个既有元素**的 HTML。
+ *
+ * 依赖 `DOMParser`（产品页与 jsdom 都有）。拿不到解析器时**一律拒绝** ——
+ * 「审不了就放过」是这类闸最糟的降级。
+ */
+export declare function sanitizeReplaceHtml(raw: string, opts: ReplaceHtmlOptions): ReplaceHtmlOutcome;

package/dist/kernel/ai/replaceHtmlGate.js

@@ -0,0 +1,147 @@
+import { imageSourceAllowed } from './imageSource.js';
+export const REPLACE_HTML_BUDGET_BYTES = 8192;
+const ALLOWED_TAGS = new Set([
+    'div',
+    'span',
+    'p',
+    'a',
+    'button',
+    'strong',
+    'em',
+    'b',
+    'i',
+    'u',
+    'small',
+    'br',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'ul',
+    'ol',
+    'li',
+    'img',
+    'table',
+    'thead',
+    'tbody',
+    'tfoot',
+    'tr',
+    'td',
+    'th'
+]);
+const ALLOWED_ATTRS = new Set([
+    'class',
+    'style',
+    'href',
+    'target',
+    'rel',
+    'role',
+    'title',
+    'aria-label',
+    'aria-hidden',
+    'src',
+    'alt',
+    'width',
+    'height',
+    'loading'
+]);
+const STRIPPED_ATTRS = ['srcset', 'imagesrcset'];
+function isSafeHref(value) {
+    const v = value.trim().toLowerCase();
+    if (v.startsWith('#') || v.startsWith('/') || v.startsWith('./') || v.startsWith('../')) {
+        return true;
+    }
+    return (v.startsWith('http://') ||
+        v.startsWith('https://') ||
+        v.startsWith('mailto:') ||
+        v.startsWith('tel:'));
+}
+function isSafeStyleAttr(value) {
+    const v = value.toLowerCase();
+    return !v.includes('javascript:') && !v.includes('expression(') && !v.includes('url(');
+}
+export function sanitizeReplaceHtml(raw, opts) {
+    const html = (raw ?? '').trim();
+    if (!html)
+        return { ok: false, problem: { reason: 'EMPTY' } };
+    const bytes = new TextEncoder().encode(html).length;
+    if (bytes > REPLACE_HTML_BUDGET_BYTES) {
+        return { ok: false, problem: { reason: 'TOO_LARGE', bytes } };
+    }
+    if (typeof DOMParser === 'undefined') {
+        return {
+            ok: false,
+            problem: { reason: 'UNSAFE_ATTR_VALUE', detail: 'no DOMParser to inspect markup' }
+        };
+    }
+    const doc = new DOMParser().parseFromString('<!doctype html><body></body>', 'text/html');
+    const template = doc.createElement('template');
+    template.innerHTML = html;
+    const roots = template.content.children;
+    if (roots.length === 0)
+        return { ok: false, problem: { reason: 'NO_ROOT_ELEMENT' } };
+    if (roots.length > 1) {
+        return {
+            ok: false,
+            problem: {
+                reason: 'MULTI_ROOT_HTML',
+                detail: `${roots.length} root elements, expected 1`
+            }
+        };
+    }
+    const root = roots[0];
+    for (const el of [root, ...Array.from(root.querySelectorAll('*'))]) {
+        const tag = el.tagName.toLowerCase();
+        if (!ALLOWED_TAGS.has(tag)) {
+            return { ok: false, problem: { reason: 'TAG_NOT_ALLOWED', detail: tag } };
+        }
+        for (const name of STRIPPED_ATTRS)
+            el.removeAttribute(name);
+        for (const attr of Array.from(el.attributes)) {
+            const name = attr.name.toLowerCase();
+            if (name.startsWith('on')) {
+                return {
+                    ok: false,
+                    problem: { reason: 'ATTR_NOT_ALLOWED', detail: `${tag}[${name}]` }
+                };
+            }
+            if (!ALLOWED_ATTRS.has(name)) {
+                return {
+                    ok: false,
+                    problem: { reason: 'ATTR_NOT_ALLOWED', detail: `${tag}[${name}]` }
+                };
+            }
+            if (name === 'href' && !isSafeHref(attr.value)) {
+                return {
+                    ok: false,
+                    problem: {
+                        reason: 'UNSAFE_ATTR_VALUE',
+                        detail: `href=${attr.value.slice(0, 40)}`
+                    }
+                };
+            }
+            if (name === 'style' && !isSafeStyleAttr(attr.value)) {
+                return {
+                    ok: false,
+                    problem: {
+                        reason: 'UNSAFE_ATTR_VALUE',
+                        detail: `style=${attr.value.slice(0, 40)}`
+                    }
+                };
+            }
+        }
+        if (tag === 'img' && !imageSourceAllowed(el.getAttribute('src'), opts)) {
+            const src = el.getAttribute('src');
+            return {
+                ok: false,
+                problem: {
+                    reason: 'UNSAFE_IMAGE_SRC',
+                    detail: src ? `origin not allowed: ${src.slice(0, 60)}` : 'img without src'
+                }
+            };
+        }
+    }
+    return { ok: true, html: root.outerHTML };
+}

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

@@ -0,0 +1,16 @@
+import type { CanvasGeometryPayload } from '@ptengine/inline-core/protocol';
+import { type FrameToProductContext } from '../selection/geometry.js';
+import type { PageModelBlock } from './resolveBlocks.js';
+export interface BlockOverlayProps {
+    blocks: PageModelBlock[];
+    activeId?: string | null;
+    onHover?: (id: string | null) => void;
+    geometry: CanvasGeometryPayload | null;
+    context: FrameToProductContext;
+    /**
+     * 画布当前施加在 `<html>` 上的缩放比例（移动端超宽缩小），默认 1。区块 `top/height` 是
+     * 自然文档坐标，几何帧的 `scrollY` 是缩放后页面的 —— 乘上比例两者才在同一空间里。
+     */
+    scale?: number;
+}
+export declare function BlockOverlay({ blocks, activeId, onHover, geometry, context, scale }: BlockOverlayProps): import("react").JSX.Element | null;

package/dist/kernel/blocks/BlockOverlay.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { frameRectToProductRect } from '../selection/geometry.js';
+const Z_INDEX = 2147482990;
+const CHIP_HEIGHT = 18;
+const COLORS = { base: '#1D4ED8', active: '#DB2777', none: '#94A3B8' };
+function boxStyle(rect, color, active, none) {
+    return {
+        position: 'absolute',
+        left: `${rect.x}px`,
+        top: `${rect.y}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        boxSizing: 'border-box',
+        border: `${active ? 3 : 2}px ${none ? 'dashed' : 'solid'} ${color}`,
+        background: active ? 'rgba(219, 39, 119, 0.06)' : 'transparent',
+        pointerEvents: 'none'
+    };
+}
+export function BlockOverlay({ blocks, activeId, onHover, geometry, context, scale = 1 }) {
+    if (!geometry)
+        return null;
+    const clip = frameRectToProductRect({ x: 0, y: 0, width: geometry.viewportWidth, height: geometry.viewportHeight }, context);
+    return (_jsx("div", { "data-testid": "block-overlay-root", style: {
+            position: 'fixed',
+            left: `${clip.x}px`,
+            top: `${clip.y}px`,
+            width: `${clip.width}px`,
+            height: `${clip.height}px`,
+            overflow: 'hidden',
+            pointerEvents: 'none',
+            zIndex: Z_INDEX
+        }, children: blocks.map(block => {
+            const active = block.id === activeId;
+            const none = block.resolved === 'none';
+            const color = active ? COLORS.active : none ? COLORS.none : COLORS.base;
+            const abs = frameRectToProductRect({
+                x: 0,
+                y: block.top * scale - geometry.scrollY,
+                width: geometry.viewportWidth,
+                height: block.height * scale
+            }, context);
+            const rect = { ...abs, x: abs.x - clip.x, y: abs.y - clip.y };
+            const chipTop = Math.min(Math.max(0, -rect.y), Math.max(0, rect.height - CHIP_HEIGHT));
+            return (_jsx("div", { "data-testid": `block-box-${block.id}`, "data-resolved": block.resolved, "data-active": active ? 'true' : undefined, style: boxStyle(rect, color, active, none), children: _jsxs("div", { "data-testid": `block-chip-${block.id}`, onMouseEnter: () => onHover?.(block.id), onMouseLeave: () => onHover?.(null), style: {
+                        position: 'absolute',
+                        left: 0,
+                        top: `${chipTop}px`,
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        gap: '4px',
+                        maxWidth: '100%',
+                        padding: '1px 6px',
+                        background: color,
+                        color: '#fff',
+                        fontSize: '11px',
+                        lineHeight: '16px',
+                        fontWeight: 600,
+                        whiteSpace: 'nowrap',
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        borderRadius: '0 0 2px 0',
+                        pointerEvents: 'auto',
+                        cursor: 'default'
+                    }, children: [_jsx("span", { children: block.id }), _jsx("span", { style: { fontWeight: 400, opacity: 0.9 }, children: block.label ?? block.name })] }) }, block.id));
+        }) }));
+}

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

@@ -0,0 +1,106 @@
+import type { DecodedImage } from '../shrinkImageForUpload.js';
+/**
+ * 整页截图 → 画上区块编号框 → 切成若干瓦片给模型看。
+ *
+ * 为什么切：整页图 375×8000+ 一张塞给模型，纵向被压到看不清文字；切成 2000 高的瓦片，
+ * 每片都是可读的。为什么标注：模型要把「B3 那块」与 `resolveBlocks` 给的 `B3` 对上号，
+ * 编号框就是两边共用的坐标系。
+ *
+ * 页太高时（> tileHeight × maxTiles）整体缩小到正好放下，下限 0.5 —— 再小文字就糊了；
+ * 到下限仍放不下就只留前 maxTiles 片并标 `truncated`（模型图片数有上限，与其发不出去
+ * 不如少看底部）。
+ *
+ * canvas / createImageBitmap 在 jsdom 里没有实现 → 解码 / 渲染经 `deps` 注入，规划本身
+ * （缩放决定、瓦片边界、框与标签位置）是纯函数单独测。与 `shrinkImageForUpload.ts` 同一套写法。
+ */
+export declare const ANNOTATE_DEFAULTS: {
+    readonly tileHeight: 2000;
+    readonly maxTiles: 6;
+};
+/** 整体缩小的下限：再小文字就不可读了。 */
+export declare const MIN_DOWNSCALE = 0.5;
+/** 两色交替：相邻区块颜色不同，边界一眼可辨。 */
+export declare const BLOCK_COLORS: readonly [string, string];
+export declare const TILE_JPEG_QUALITY = 0.82;
+export interface AnnotateBlock {
+    id: string;
+    /** 页面 CSS px（文档坐标）。 */
+    top: number;
+    height: number;
+}
+export interface AnnotateOptions {
+    /** 每片高度（输出 px），默认 2000。 */
+    tileHeight?: number;
+    /** 最多几片，默认 6。 */
+    maxTiles?: number;
+    /**
+     * 截图时页面的 CSS 宽（mobile 375 / pc 1440）。DPR > 1 时图宽是它的整数倍，框要按
+     * `imageWidth / pageWidthPx` 放大才对得上。默认 = 图宽（不做 DPR 换算）。
+     */
+    pageWidthPx?: number;
+}
+export interface AnnotateBox {
+    id: string;
+    /** 输出 px。 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: string;
+    label: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        text: string;
+    };
+}
+export interface AnnotateTile {
+    index: number;
+    /** 输出 px，相对整张（已缩放的）标注图。 */
+    top: number;
+    height: number;
+}
+export interface AnnotatePlan {
+    /** 输出 px / **源图** px（≤ 1；1 = 没缩）。 */
+    downscale: number;
+    /** 输出 px / **页面 CSS** px = (imageWidth / pageWidthPx) × downscale。页 px → 瓦片 px 用它。 */
+    pxPerPagePx: number;
+    /** 输出图尺寸。 */
+    width: number;
+    height: number;
+    /** 页高，**页面 CSS px**。 */
+    pageHeight: number;
+    tileHeight: number;
+    tiles: AnnotateTile[];
+    boxes: AnnotateBox[];
+    /** 到缩放下限仍放不下，底部几片被丢了。 */
+    truncated: boolean;
+}
+export declare function planAnnotateAndTile(input: {
+    imageWidth: number;
+    imageHeight: number;
+    pageWidthPx?: number;
+    blocks: AnnotateBlock[];
+    tileHeight?: number;
+    maxTiles?: number;
+}): AnnotatePlan;
+export interface AnnotateDeps {
+    decode: (blob: Blob) => Promise<DecodedImage>;
+    /** 把源图按 plan 缩放、画框、切片，每片一个 JPEG Blob（顺序与 `plan.tiles` 一致）。 */
+    render: (image: DecodedImage, plan: AnnotatePlan) => Promise<Blob[]>;
+}
+export interface AnnotateResult {
+    tiles: Blob[];
+    /** 输出 px / 页面 CSS px（= `plan.pxPerPagePx`）：页 px 的 y 落在第 `floor(y×scale / tileHeight)` 片。 */
+    scale: number;
+    /** 页高，页面 CSS px。 */
+    pageHeight: number;
+    tileHeight: number;
+    truncated: boolean;
+}
+/**
+ * 解码 → 规划 → 渲染。解码 / 渲染失败**原样抛**：调用方（apps/x）决定退回不标注的整图
+ * 还是不发图 —— 这里不知道哪种对当前对话更好。
+ */
+export declare function annotateAndTile(fullPage: Blob, blocks: AnnotateBlock[], opts?: AnnotateOptions, deps?: AnnotateDeps): Promise<AnnotateResult>;