@ptengine/inline-editor 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,185 @@
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+import { type ActionChangeInput, type AttributeChangeInput, type ContentChangeInput, type MoveChangeInput, type StyleChangeInput } from './builders.js';
+/**
+ * change list 状态 + 「应用到画布」的编排。
+ *
+ * ⚠️ **顺序是硬要求：先 `applyChange` 命令、成功后才入列。**
+ * 反过来会出现「列表里有、页面上没有」—— 用户看到 change 已记录，但画布毫无变化，
+ * 且没有任何报错。这是最难排查的一类不一致。
+ *
+ * 每条 change 带一个产品页分配的 `changeId`（**不进落盘 payload**），
+ * agent 侧靠它定位撤销闭包。
+ */
+export interface ChangeRecord {
+    changeId: string;
+    change: InlineChange;
+    /**
+     * 这条改动作用元素的**祖先 selector**。落盘前按祖先关系收敛要用它
+     * （见 `mergeForSave`）—— 例如「祖先后来被隐藏/整体替换了，本条就不必存」。
+     *
+     * ⚠️ **不进落盘 payload**，只活在编辑器内存里。
+     *
+     * 为什么在这里记：祖先关系在**加入 change 那一刻**是已知的（选中态里就有
+     * `selection.chain`）。现役是在保存时从 `renderPath` 逐段截字符串反推
+     * （`useInline.ts:getParentNode`），既要活 DOM 也更容易错。
+     *
+     * 缺省空数组 = 不知道祖先（程序化加入、回显的存量数据）→ 该条不参与收敛。
+     */
+    ancestors: string[];
+    /**
+     * 这条改动插入的新元素 selector（扩展 `applyChange` 回报的 `insertedSelectors`：INSERT 的根、
+     * EDIT_HTML 的新根）。**只活在内存里、不进落盘 payload**，AI 落地后的几何自检要量它们，
+     * 宿主也要把它们并进授权范围。没有插入（样式 / 文案 / 回显数据）就没有这个键。
+     */
+    insertedSelectors?: string[];
+}
+export interface UseChangeListResult {
+    list: ChangeRecord[];
+    /** 明文 change 数组（落盘前经 toWireFormat 转数值形态）。 */
+    changes: InlineChange[];
+    addStyle: (input: StyleChangeInput) => Promise<string>;
+    addContent: (input: ContentChangeInput) => Promise<string>;
+    addAttribute: (input: AttributeChangeInput) => Promise<string>;
+    addAction: (input: ActionChangeInput) => Promise<string>;
+    addMove: (input: MoveChangeInput) => Promise<string>;
+    revert: (changeId: string) => Promise<void>;
+    /**
+     * **同步**读当前清单（`listRef`），不是渲染期那份 `list`。
+     *
+     * 为什么必须有：`list` 是 state，而写入是异步的 —— 「刚 `await` 完一次 apply 就要知道
+     * 清单里有什么」这种调用（AI 应用完立刻撤销、改完最后一条立刻切版本）发生在 React
+     * flush 之前，读 `list` 拿到的是**上一次渲染**的值。少一条的后果是静默的：
+     * 切版本时交还给宿主的清单漏掉那条改动（它就此消失），或者刚铸出来的 changeId
+     * 被判成「不属于当前版本」而一条都撤不掉。
+     */
+    peekList: () => ChangeRecord[];
+    /** 全部撤销。**倒序**撤 —— 顺序撤会让后面的 change 基于已被撤掉的现场还原。 */
+    revertAll: () => Promise<void>;
+    clear: () => void;
+    /**
+     * 把**已存在的**改动载入本次会话：逐条回放到画布，并填进清单（撤销/覆盖照常可用）。
+     *
+     * 用在「打开已有实验的编辑器」——清单和画布都得回到上次保存的样子。
+     */
+    hydrate: (changes: InlineChange[]) => Promise<HydrateOutcome>;
+    /**
+     * 把清单**整体换成另一批**改动：撤光当前的，再回放新的。用在**切换实验版本**
+     * （每个版本一份清单，宿主持有数据、包只负责换）。
+     *
+     * = 快照 → `revertAll()` → `hydrate(next)`。拆成两步调用方自己做也行，但那样每个
+     * 调用点都要重复「先快照、必须倒序撤、撤完才能 hydrate」这三件事，漏一件都不报错：
+     * 不快照就把上一个版本的清单丢了（用户的改动凭空消失），不撤就把两个版本的改动
+     * 叠在同一个页面上。
+     *
+     * @param prevIds 与 `next` **等长且同序**的旧 changeId（宿主上次从
+     *   `onVersionLeave` 拿到的那份 `records` 的 id）。给了就能拿到 `idMap`
+     *   （旧 id → 本次新铸的 id）—— `hydrate` 每次都铸新 id（撤销闭包随 iframe 重建而丢，
+     *   见它的注释），而 AI 卡片上记的是**旧** id，没有这张别名表，切回来之后
+     *   「撤销这一批」会找不到任何一条。不给则 `idMap` 为空。
+     */
+    replaceAll: (next: InlineChange[], prevIds?: string[]) => Promise<{
+        previous: ChangeRecord[];
+        outcome: HydrateOutcome;
+        idMap: Map<string, string>;
+    }>;
+    lastError: string | null;
+}
+export interface HydrateOutcome {
+    /** 成功回放到画布的条数。 */
+    applied: number;
+    /**
+     * 应用失败的条目（selector 在当前页面上不再命中、元素已被改版删掉等）。
+     *
+     * ⚠️ **它们仍然留在清单里**，不会被丢掉。三种做法里只有这种是诚实的：
+     *   · 静默丢掉 → 用户上次保存的改动凭空消失，再一保存就真没了（数据丢失）；
+     *   · 静默留着不报 → 清单说有 5 项改动，页面上只看得见 2 项，用户以为编辑器坏了；
+     *   · 留着 + 报出来 → 用户能看到「这 3 项在当前页面上失效了」，自己决定删还是留。
+     * 客户页是活的、会改版，这条路径不是异常而是常态。
+     */
+    failed: Array<{
+        change: InlineChange;
+        reason: string;
+    }>;
+}
+export declare function useChangeList(sessionId: string | undefined): UseChangeListResult;
+export interface ButtonActionDeps {
+    identifier: string;
+    selector: string;
+    /**
+     * 作用元素的祖先 selector —— 落盘收敛要用（`mergeForSave`）。
+     *
+     * ⚠️ **每个工具函数都必须把它转发进 `add*` 的 input**。漏了不会报错，
+     * 只是那条 change 的祖先链是空的、永远不参与收敛 —— 症状是「按理该被收掉的条目
+     * 还留在存库数据里」。加进来时 tsc 抓到了 delete / insert 两处漏转发。
+     */
+    ancestors?: string[];
+    addStyle: (input: StyleChangeInput) => Promise<string>;
+    addContent: (input: ContentChangeInput) => Promise<string>;
+}
+/**
+ * 「删除」—— ⚠️ **不是真删**，是 `display: none`
+ * （`edit.service.js:332-339` 第一行就是 `changeStyle('display','none')`）。
+ *
+ * 现役随后还会把选中态上移到父元素；那一步由调用方做（它才拿得到祖先链）。
+ */
+export declare function deleteElement(deps: ButtonActionDeps): Promise<string>;
+/** 「编辑样式」—— 一条 `elementStyle`。 */
+export declare function editStyle(deps: ButtonActionDeps, property: string, value: string, opts?: {
+    cssRule?: boolean;
+    important?: boolean;
+    cssConditional?: string;
+}): Promise<string>;
+/**
+ * 「`</>` 编辑 HTML」—— `elementContent` + `mode: 'replace'`，**不传 `isTextChange`**。
+ * 编辑的是整个元素（outerHTML），seed 来自 `getOuterHtml`。
+ */
+export declare function editHtml(deps: ButtonActionDeps, html: string): Promise<string>;
+/**
+ * 「编辑文字」—— `elementContent` + `mode: 'replace'` + **`isTextChange: true`**。
+ *
+ * ⚠️ `isTextChange` 是与 `</>` 唯一的区别（两者共用 `mode: 'replace'`）：
+ * 它让 agent 走「换 innerHTML、外壳保留」，而 `</>` 走「换元素本身」。
+ * 传错的后果是 `#target` 这个锚点一侧存在一侧不存在，后续 selector 全部错位。
+ */
+export declare function editText(deps: ButtonActionDeps, html: string): Promise<string>;
+/**
+ * 插入位置。**刻意不用 `ElementContentModeName`** —— 那个类型含 `'replace'`，
+ * 而「插一张新图」永远不该是 replace（那会把目标元素整个换掉）。tsc 已经拦过一次。
+ */
+export type InsertMode = 'insert' | 'append' | 'before' | 'after';
+export interface ImageActionDeps extends ButtonActionDeps {
+    addAttribute: (input: AttributeChangeInput) => Promise<string>;
+}
+/**
+ * 「替换图片」—— **同一个按钮，三种完全不同的 change**（分支判定见 `dialogs/imageEdit.ts`）。
+ *
+ * 判错不报错，只是「点了替换图片、图没变」：比如对背景图 div 产出
+ * `changeElementAttribute src`，属性确实设上了，但 div 根本不吃 src。
+ */
+export declare function replaceImage(deps: ImageActionDeps, input: {
+    branch: 'img-src' | 'background' | 'insert';
+    url: string;
+    mode?: InsertMode;
+}): Promise<string>;
+/** 「图片设置」—— 本期只有 alt。**空串 = 移除属性**（`value` 省略）。 */
+export declare function setImageAlt(deps: ImageActionDeps, alt: string): Promise<string>;
+/** 「点击动作」—— action 对象由 `dialogs/actionTypes.ts` 的 `buildActionObject` 组装。 */
+export declare function setClickAction(deps: ButtonActionDeps & {
+    addAction: (input: ActionChangeInput) => Promise<string>;
+}, action: Record<string, unknown>): Promise<string>;
+/**
+ * 「替换视频」—— `<video>` 与 YouTube 内嵌 iframe 都是改 `src`，只有一条分支
+ * （不像替换图片要分 img / 背景图 / 插入三种）。
+ */
+export declare function replaceVideo(deps: ImageActionDeps, url: string): Promise<string>;
+/**
+ * 「插入元素」—— 用户手写的 HTML **原样插入，不加包装**。
+ *
+ * 与 `replaceImage` 的 insert 分支刻意不同：那里插的是我们生成的 `<img>`，包一层带防撞号
+ * 的 `div` 是为了给它稳定的选择器锚点；用户手写的 HTML 该落成什么样就是什么样，
+ * 凭空多一层 `div` 会把他的布局改坏，而且他不知道那层是哪来的。
+ */
+export declare function insertElement(deps: ButtonActionDeps, input: {
+    html: string;
+    mode: InsertMode;
+}): Promise<string>;

package/dist/kernel/changelist/useChangeList.js

@@ -0,0 +1,259 @@
+import { useCallback, useRef, useState } from 'react';
+import { applyChange, revertChange } from '../canvasCommands.js';
+import { overrideOutcome } from './overrides.js';
+import { backgroundImageValue, buildInsertImageHtml, randomPtElementId } from '../../dialogs/imageEdit.js';
+import { buildActionChange, buildAttributeChange, buildContentChange, buildMoveChange, buildStyleChange } from './builders.js';
+function newChangeId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `cid-${Math.random().toString(36).slice(2)}-${performance.now()}`;
+}
+function withResolvedStyleMode(change, applied) {
+    return change.type === 'elementStyle' && applied?.resolvedStyleMode
+        ? { ...change, ...applied.resolvedStyleMode }
+        : change;
+}
+export function useChangeList(sessionId) {
+    const [list, setList] = useState([]);
+    const [lastError, setLastError] = useState(null);
+    const listRef = useRef([]);
+    listRef.current = list;
+    const push = useCallback(async (change, ancestors = []) => {
+        if (!sessionId)
+            throw new Error('no canvas session');
+        const changeId = newChangeId();
+        const prev = listRef.current;
+        const { next: nextChanges, dropped } = overrideOutcome(prev.map(r => r.change), change);
+        const byChange = new Map(prev.map(r => [r.change, r.changeId]));
+        for (const old of dropped) {
+            const oldId = byChange.get(old);
+            if (!oldId)
+                continue;
+            await revertChange(sessionId, oldId).catch(() => { });
+        }
+        const applied = await applyChange(sessionId, changeId, change);
+        const stored = withResolvedStyleMode(change, applied);
+        const ancestorsByChange = new Map(prev.map(r => [r.change, r.ancestors]));
+        const insertedByChange = new Map(prev.map(r => [r.change, r.insertedSelectors]));
+        const insertedNow = applied.insertedSelectors?.length ? applied.insertedSelectors : undefined;
+        const nextRecords = nextChanges.map(c => {
+            const inserted = c === change ? insertedNow : insertedByChange.get(c);
+            return {
+                change: c === change ? stored : c,
+                changeId: byChange.get(c) ?? changeId,
+                ancestors: ancestorsByChange.get(c) ?? ancestors,
+                ...(inserted?.length ? { insertedSelectors: inserted } : {})
+            };
+        });
+        listRef.current = nextRecords;
+        setList(nextRecords);
+        setLastError(null);
+        return changeId;
+    }, [sessionId]);
+    const hydrate = useCallback(async (changes) => {
+        if (!sessionId)
+            throw new Error('no canvas session');
+        if (listRef.current.length > 0) {
+            return { applied: 0, failed: [] };
+        }
+        const records = [];
+        const failed = [];
+        for (const change of changes) {
+            const changeId = newChangeId();
+            let applied;
+            try {
+                applied = await applyChange(sessionId, changeId, change);
+            }
+            catch (e) {
+                failed.push({ change, reason: String(e?.message ?? e) });
+                records.push({ changeId, change, ancestors: [] });
+                continue;
+            }
+            records.push({
+                changeId,
+                change: withResolvedStyleMode(change, applied),
+                ancestors: []
+            });
+        }
+        listRef.current = records;
+        setList(records);
+        setLastError(null);
+        return { applied: records.length - failed.length, failed };
+    }, [sessionId]);
+    const guard = useCallback(async (run) => {
+        try {
+            return await run();
+        }
+        catch (e) {
+            setLastError(String(e?.message ?? e));
+            throw e;
+        }
+    }, []);
+    const addStyle = useCallback((input) => guard(() => push(buildStyleChange(input), input.ancestors)), [guard, push]);
+    const addContent = useCallback((input) => guard(() => push(buildContentChange(input), input.ancestors)), [guard, push]);
+    const addAttribute = useCallback((input) => guard(() => push(buildAttributeChange(input), input.ancestors)), [guard, push]);
+    const addAction = useCallback((input) => guard(() => push(buildActionChange(input), input.ancestors)), [guard, push]);
+    const addMove = useCallback((input) => guard(() => push(buildMoveChange(input), input.ancestors)), [guard, push]);
+    const revert = useCallback((changeId) => guard(async () => {
+        if (!sessionId)
+            throw new Error('no canvas session');
+        await revertChange(sessionId, changeId);
+        const next = listRef.current.filter(r => r.changeId !== changeId);
+        listRef.current = next;
+        setList(next);
+    }), [guard, sessionId]);
+    const revertAll = useCallback(() => guard(async () => {
+        if (!sessionId)
+            throw new Error('no canvas session');
+        for (const record of [...listRef.current].reverse()) {
+            await revertChange(sessionId, record.changeId).catch(() => { });
+        }
+        listRef.current = [];
+        setList([]);
+    }), [guard, sessionId]);
+    const replaceAll = useCallback(async (next, prevIds) => {
+        if (!sessionId)
+            throw new Error('no canvas session');
+        const previous = listRef.current;
+        await revertAll();
+        let outcome;
+        try {
+            outcome = await hydrate(next);
+        }
+        catch (e) {
+            listRef.current = previous;
+            setList(previous);
+            throw e;
+        }
+        const nextRecords = listRef.current;
+        const idMap = new Map();
+        if (prevIds) {
+            for (let i = 0; i < nextRecords.length; i++) {
+                const old = prevIds[i];
+                if (old)
+                    idMap.set(old, nextRecords[i].changeId);
+            }
+        }
+        return { previous, outcome, idMap };
+    }, [hydrate, revertAll, sessionId]);
+    const peekList = useCallback(() => listRef.current, []);
+    const clear = useCallback(() => {
+        listRef.current = [];
+        setList([]);
+        setLastError(null);
+    }, []);
+    return {
+        list,
+        changes: list.map(r => r.change),
+        addStyle,
+        addContent,
+        addAttribute,
+        addAction,
+        addMove,
+        revert,
+        revertAll,
+        clear,
+        hydrate,
+        replaceAll,
+        peekList,
+        lastError
+    };
+}
+export function deleteElement(deps) {
+    return deps.addStyle({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        property: 'display',
+        value: 'none'
+    });
+}
+export function editStyle(deps, property, value, opts = {}) {
+    return deps.addStyle({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        property,
+        value,
+        ...opts
+    });
+}
+export function editHtml(deps, html) {
+    return deps.addContent({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        html,
+        mode: 'replace'
+    });
+}
+export function editText(deps, html) {
+    return deps.addContent({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        html,
+        mode: 'replace',
+        isTextChange: true
+    });
+}
+export function replaceImage(deps, input) {
+    if (input.branch === 'img-src') {
+        return deps.addAttribute({
+            identifier: deps.identifier,
+            selector: deps.selector,
+            attribute: 'src',
+            value: input.url
+        });
+    }
+    if (input.branch === 'background') {
+        return deps.addStyle({
+            identifier: deps.identifier,
+            selector: deps.selector,
+            property: 'background-image',
+            value: backgroundImageValue(input.url)
+        });
+    }
+    return deps.addContent({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        html: buildInsertImageHtml(input.url, input.mode ?? 'append', randomPtElementId),
+        mode: input.mode ?? 'append'
+    });
+}
+export function setImageAlt(deps, alt) {
+    return deps.addAttribute({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        attribute: 'alt',
+        value: alt.length > 0 ? alt : undefined
+    });
+}
+export function setClickAction(deps, action) {
+    return deps.addAction({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        action
+    });
+}
+export function replaceVideo(deps, url) {
+    return deps.addAttribute({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        attribute: 'src',
+        value: url
+    });
+}
+export function insertElement(deps, input) {
+    return deps.addContent({
+        identifier: deps.identifier,
+        selector: deps.selector,
+        ancestors: deps.ancestors,
+        html: input.html,
+        mode: input.mode
+    });
+}

package/dist/kernel/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * inline-editor 的显式运行时配置。
+ *
+ * 本包以**预构建 ESM** 发布，产物里不能再依赖消费方 Vite 替换构建期环境变量
+ * （预构建后那些表达式要么原样留在产物里读不到值，要么被消费方的构建误处理）。
+ * 所以两个原本读构建期环境变量的配置项，改成由消费方在应用启动时显式传入。
+ * （为此有测试扫描源码、禁止再出现对 Vite 环境变量对象的读取，注释里也不要写那个字面量。）
+ *
+ * Vite 消费方在入口调用一次 `configureInlineEditor`，把自己的两个 `VITE_*` 变量传进来，
+ * 具体写法见包 README「配置扩展 ID」。
+ */
+export interface InlineEditorConfig {
+    /**
+     * 扩展 id。**非空 = 严格模式**：只认这一个 id（正式上线填商店 id）。
+     * 不配（或空串）= 内测模式：id 改读插件在 `<html data-ptengine-kit-id>` 上报的值。
+     */
+    extensionId?: string;
+    /**
+     * 即使插件支持也不启用的能力：逗号分隔字符串，或字符串数组。
+     * 两种形式走同一套规范化（trim、去空）。
+     */
+    disabledCapabilities?: string | readonly string[];
+}
+/** 浅合并进模块级配置，可多次调用；后调用的字段覆盖先前的同名字段。 */
+export declare function configureInlineEditor(config: InlineEditorConfig): void;
+/** 当前生效的配置（只读快照：返回的是副本，改它不会影响模块级配置）。 */
+export declare function getInlineEditorConfig(): Readonly<InlineEditorConfig>;
+/** 清空配置。仅测试用（也从包入口导出，方便消费方的测试隔离）。 */
+export declare function resetInlineEditorConfig(): void;

package/dist/kernel/config.js

@@ -0,0 +1,10 @@
+let current = {};
+export function configureInlineEditor(config) {
+    current = { ...current, ...config };
+}
+export function getInlineEditorConfig() {
+    return { ...current };
+}
+export function resetInlineEditorConfig() {
+    current = {};
+}

package/dist/kernel/dataUrlToBlob.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `data:` URL → Blob，不经 `fetch`。
+ *
+ * `captureElement` 回的是 PNG dataURL（图像数据全程留在 SW 里，只有成品一张过通道）。
+ * 现役 `captureAiScreenshot` 用 `fetch(dataUrl).blob()` 转，那依赖宿主的网络栈对 `data:`
+ * 方案的支持（jsdom / 某些 CSP 下不可用）；这里纯解码，哪儿都能跑。
+ */
+export declare function dataUrlToBlob(dataUrl: string): Blob;

package/dist/kernel/dataUrlToBlob.js

@@ -0,0 +1,17 @@
+export function dataUrlToBlob(dataUrl) {
+    const comma = dataUrl.indexOf(',');
+    if (!dataUrl.startsWith('data:') || comma < 0)
+        throw new Error('not a data URL');
+    const meta = dataUrl.slice(5, comma);
+    const payload = dataUrl.slice(comma + 1);
+    const [mime = 'application/octet-stream', ...params] = meta.split(';');
+    const isBase64 = params.includes('base64');
+    if (isBase64) {
+        const bin = atob(payload);
+        const bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            bytes[i] = bin.charCodeAt(i);
+        return new Blob([bytes], { type: mime });
+    }
+    return new Blob([decodeURIComponent(payload)], { type: mime });
+}

package/dist/kernel/linkHref.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 树节点上的链接（`DomTreeNode.href`）—— 类型补丁 + 给 AI 看的去向写法。
+ *
+ * 扩展从 `<a href>` 与 PageFly 这类构建器的 `data-href`（图片链接 / 商品卡：外面没有 `<a>`，JS 跳转）
+ * 读出这个字段：同站是 `pathname + search + hash`（以 `/` 开头），外站是完整地址。
+ * 真机 2026-10-15（vivaia allday）：整页 41 个 `data-href` 图片，树里没有链接信息时 agent 把
+ * 「page-model 没列 cta」读成了「全页没有购买导线」。
+ */
+import '@ptengine/inline-core/protocol';
+declare module '@ptengine/inline-core/protocol' {
+    interface DomTreeNode {
+        /**
+         * 仅 `includeRect: true` 时出现：这个节点**自己**点下去会去哪。同站给路径（含查询串），
+         * 外站给完整地址，≤200 字符。不是链接时不发；老扩展永远不发。
+         */
+        href?: string;
+    }
+}
+/** 去向写法的长度上限：够认出是哪个页面就行。 */
+export declare const LINK_PATH_MAX = 60;
+/**
+ * 给 AI 看的去向：查询串去掉（`?variant=46629727863040` 是噪音，同一个商品不同变体应算一个去向），
+ * hash 留着（页内锚点 `#buy` 本身就是导线）；外站去掉协议、留域名；`mailto:` 这类原样。截到上限。
+ */
+export declare function linkPath(href: string): string;

package/dist/kernel/linkHref.js

@@ -0,0 +1,16 @@
+import '@ptengine/inline-core/protocol';
+export const LINK_PATH_MAX = 60;
+export function linkPath(href) {
+    const raw = href.trim();
+    let out = raw;
+    const hashAt = raw.indexOf('#');
+    const hash = hashAt >= 0 ? raw.slice(hashAt) : '';
+    const beforeHash = hashAt >= 0 ? raw.slice(0, hashAt) : raw;
+    const queryAt = beforeHash.indexOf('?');
+    const path = queryAt >= 0 ? beforeHash.slice(0, queryAt) : beforeHash;
+    if (raw.startsWith('/'))
+        out = `${path}${hash}`;
+    else if (/^https?:\/\//i.test(raw))
+        out = `${path.replace(/^https?:\/\//i, '')}${hash}`;
+    return out.length > LINK_PATH_MAX ? out.slice(0, LINK_PATH_MAX) : out;
+}

package/dist/kernel/mobileFit.d.ts

@@ -0,0 +1,46 @@
+import type { MeasureDocumentResult } from '@ptengine/inline-core/protocol';
+/**
+ * 移动端超宽缩小（契约 v11 设计稿 §8）—— **纯计算**，不碰画布。
+ *
+ * 客户页写死 `<meta name="viewport" content="width=750">` 之类时，375 宽的画布里页面会横向溢出。
+ * 算法照搬 engage-editor 线上版（`page.store.ts` 的 `updateFrameSize` + `OriginalPageIframe.vue`
+ * 的 `setFrameScaleStyle`）：量出自然宽度 W，`s = min(1, 视口宽 / W)`，把 `transform: scale(s)`
+ * 加在 `<html>` 上，宽度钉成 W、高度钉成 H·s。
+ *
+ * 为什么是**产品页**算而不是插件：缩多少、要不要缩、加哪几条渲染修正，都是会随客户页反馈
+ * 反复调的策略；插件只提供 `measureDocument` / `setStyleLayer` / `observeDocumentSize` 三个原语，
+ * 这里改阈值不用发插件。
+ */
+/** 缩放层。`measureDocument` / `observeDocumentSize` 都要把它摘掉再量，否则量到的是缩放后的尺寸。 */
+export declare const MOBILE_FIT_LAYER = "mobile-fit";
+/** 渲染修正层（滚动行为 / 防闪烁隐藏 / body 高度写死）。不参与排除 —— 修正后的布局才是我们要量的。 */
+export declare const RENDER_FIXES_LAYER = "render-fixes";
+/** 两层的叠放顺序：修正在前、缩放在后（数字大的后插入、优先级高）。 */
+export declare const RENDER_FIXES_ORDER = 10;
+export declare const MOBILE_FIT_ORDER = 20;
+export interface NaturalSize {
+    /** 自然宽度 W：body 横向 overflow hidden 时取 body.clientWidth（溢出部分本来就看不见，不该按它缩）。 */
+    width: number;
+    /** 自然高度 H = max(html.scrollHeight, body.scrollHeight)。 */
+    height: number;
+    /** 未经 overflow 修正的原始宽度 max(html.scrollWidth, body.scrollWidth)。`documentSize` 事件只有这个口径，用它判「宽度变了没」。 */
+    rawWidth: number;
+}
+export interface MobileFitPlan extends NaturalSize {
+    /** `min(1, innerWidth / W)`；W 为 0（文档还没布局）时为 1。 */
+    scale: number;
+    /** 写入 `mobile-fit` 层的 CSS；不用缩时为空串（= 删层）。 */
+    css: string;
+}
+export declare function naturalSize(m: MeasureDocumentResult): NaturalSize;
+export declare function computeScale(viewportWidth: number, naturalWidth: number): number;
+/** 缩放层 CSS。`transform-origin: 0 0` 与 engage-editor 的 `left top` 等价。 */
+export declare function buildFitCss(naturalWidth: number, naturalHeight: number, scale: number): string;
+export declare function planMobileFit(m: MeasureDocumentResult): MobileFitPlan;
+/**
+ * 渲染修正层 CSS，只在命中条件时加（engage-editor `frameStateChange` 里的三条）：
+ * - `scroll-behavior: smooth` 会吞掉程序化滚动（定位、截图分片）→ 强制 auto；
+ * - 防闪烁脚本把 html/body 隐藏了 → 强制显示，否则量到的宽高全是 0；
+ * - body 高度被写死且内容更高 → 解开，避免 html/body 各一条滚动条。
+ */
+export declare function buildRenderFixesCss(m: MeasureDocumentResult): string;

package/dist/kernel/mobileFit.js

@@ -0,0 +1,44 @@
+export const MOBILE_FIT_LAYER = 'mobile-fit';
+export const RENDER_FIXES_LAYER = 'render-fixes';
+export const RENDER_FIXES_ORDER = 10;
+export const MOBILE_FIT_ORDER = 20;
+export function naturalSize(m) {
+    const rawWidth = Math.max(m.html.scrollWidth, m.body?.scrollWidth ?? 0);
+    const width = m.body && m.body.computed.overflowX === 'hidden' ? m.body.clientWidth : rawWidth;
+    const height = Math.max(m.html.scrollHeight, m.body?.scrollHeight ?? 0);
+    return { width, height, rawWidth };
+}
+export function computeScale(viewportWidth, naturalWidth) {
+    if (naturalWidth <= 0 || viewportWidth <= 0)
+        return 1;
+    return Math.min(1, viewportWidth / naturalWidth);
+}
+export function buildFitCss(naturalWidth, naturalHeight, scale) {
+    if (scale >= 1)
+        return '';
+    const scaledHeight = Math.round(naturalHeight * scale);
+    return (`html{transform:scale(${scale}) !important;transform-origin:0 0 !important;` +
+        `width:${naturalWidth}px !important;height:${scaledHeight}px !important;}`);
+}
+export function planMobileFit(m) {
+    const size = naturalSize(m);
+    const scale = computeScale(m.innerWidth, size.width);
+    return { ...size, scale, css: buildFitCss(size.width, size.height, scale) };
+}
+export function buildRenderFixesCss(m) {
+    const rules = [];
+    if (m.html.computed.scrollBehavior && m.html.computed.scrollBehavior !== 'auto') {
+        rules.push('html{scroll-behavior:auto !important;}');
+    }
+    if (m.html.computed.display === 'none' || m.body?.computed.display === 'none') {
+        rules.push('html,body{display:block !important;}');
+    }
+    if (m.body) {
+        const h = m.body.computed.height;
+        const fixed = h !== '' && h !== 'auto' && h !== 'unset';
+        if (fixed && m.body.scrollHeight > m.body.offsetHeight) {
+            rules.push('body{height:unset !important;}');
+        }
+    }
+    return rules.join('');
+}