@ptengine/inline-editor 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,89 @@
+import type { ElementContentModeName, ElementMoveModeName, InlineActionChange, InlineAttributeChange, InlineContentChange, InlineMoveChange, InlineScriptChange, InlineStyleChange, InlineTextChange, StyleChangeFlag } from '@ptengine/inline-core/change-format';
+/**
+ * 7 类 change 的 builder —— 产出**明文形态**（DEC-22）。
+ *
+ * 明文化之后本文件很薄：它只做「默认值 + 条件字段收敛」，值包装与 mode 数值映射
+ * 全在 `@ptengine/inline-core/change-format` 的转译器里。
+ * **契约风险因此从 7 个 builder 收缩到 1 个转译器** —— 这是 DEC-22 除可读性外的实际收益。
+ *
+ * 字段语义的权威来源仍是 engage-editor 的 7 个 `$create`
+ * （见设计稿 §2.6 的「7 类 × 全字段对照表」），只是形态换成了明文。
+ */
+interface CommonInput {
+    identifier: string;
+    selector: string;
+    /** 默认 false。undo 分组语义，7 类的 isValidTagData 都不校验它。 */
+    continueUndo?: boolean;
+    /**
+     * 省略 = **不写这个键**，交给 SDK 按类型的默认表（存量数据就是这个形态）。
+     * 只在需要**显式关闭**时才传 false —— 见 `InlineChangeBase.enableObserver`。
+     */
+    enableObserver?: boolean;
+    /**
+     * 作用元素的祖先 selector。**只给编辑器内存用**（落盘收敛，见 `mergeForSave`），
+     * builder 不会把它写进 change 本身。
+     */
+    ancestors?: string[];
+}
+export interface StyleChangeInput extends CommonInput {
+    property: string;
+    value: string;
+    cssRule?: boolean;
+    important?: boolean;
+    cssConditional?: string;
+}
+export declare function buildStyleChange(input: StyleChangeInput): InlineStyleChange;
+export interface ContentChangeInput extends CommonInput {
+    html: string;
+    mode: ElementContentModeName;
+    isFromAddPtElement?: boolean;
+    isTextChange?: boolean;
+    isStyleChange?: StyleChangeFlag;
+}
+export declare function buildContentChange(input: ContentChangeInput): InlineContentChange;
+export interface AttributeChangeInput extends CommonInput {
+    attribute: string;
+    /** 省略 = 删除该属性。空串 = 设为空值。 */
+    value?: string;
+}
+export declare function buildAttributeChange(input: AttributeChangeInput): InlineAttributeChange;
+export interface ActionChangeInput extends CommonInput {
+    action: unknown;
+}
+export declare function buildActionChange(input: ActionChangeInput): InlineActionChange;
+export interface MoveChangeInput extends CommonInput {
+    targetIdentifier: string;
+    targetSelector: string;
+    /**
+     * ⚠️ move 自己的词表（`top`/`bottom`/`before`/`after`），**不是** content 那套。
+     * 两套都有 before/after 但映射到不同数值（content before=3、move before=2）。
+     */
+    mode: ElementMoveModeName;
+}
+export declare function buildMoveChange(input: MoveChangeInput): InlineMoveChange;
+export interface TextChangeInput extends CommonInput {
+    text: string;
+    /** **childNode 下标（含文本节点！）**，不是元素下标。 */
+    childIndex: number;
+    mode: ElementContentModeName;
+}
+/**
+ * DEC-17：生成侧**不使用**本函数 —— 选中态的「编辑文字」走
+ * `elementContent` + `isTextChange: true`（现役 `inlineText.service.js:24-31`
+ * 里 `changeText` 的调用已被注释掉，改走 content）。
+ *
+ * 它存在的理由是反序列化路径需要能重建 57，以及「手工新增自定义 change」的历史入口
+ * （`EditTextDialog.vue:72` / `SidErrorDialog.vue:60` 仍在调 `TextChange$create`）。
+ */
+export declare function buildTextChange(input: TextChangeInput): InlineTextChange;
+export interface ScriptChangeInput {
+    identifier: string;
+    /** 空串 = 全局 JS。 */
+    selector: string;
+    continueUndo?: boolean;
+    script: string;
+    requiresContent: boolean;
+}
+/** DEC-7：画布不支持 script 编辑（现役也没有选中态入口）。本函数只服务反序列化。 */
+export declare function buildScriptChange(input: ScriptChangeInput): InlineScriptChange;
+export {};

package/dist/kernel/changelist/builders.js

@@ -0,0 +1,81 @@
+function common(input) {
+    return {
+        identifier: input.identifier,
+        selector: input.selector,
+        continueUndo: input.continueUndo ?? false,
+        enableObserver: input.enableObserver
+    };
+}
+export function buildStyleChange(input) {
+    const change = {
+        type: 'elementStyle',
+        ...common(input),
+        property: input.property,
+        value: input.value
+    };
+    if (input.cssRule != null)
+        change.cssRule = input.cssRule;
+    if (input.important != null)
+        change.important = input.important;
+    if (input.cssConditional != null)
+        change.cssConditional = input.cssConditional;
+    return change;
+}
+export function buildContentChange(input) {
+    const change = {
+        type: 'elementContent',
+        ...common(input),
+        html: input.html,
+        mode: input.mode
+    };
+    if (input.isFromAddPtElement !== undefined) {
+        change.isFromAddPtElement = input.isFromAddPtElement;
+    }
+    if (input.isTextChange !== undefined)
+        change.isTextChange = input.isTextChange;
+    if (input.isStyleChange !== undefined)
+        change.isStyleChange = input.isStyleChange;
+    return change;
+}
+export function buildAttributeChange(input) {
+    const change = {
+        type: 'changeElementAttribute',
+        ...common(input),
+        attribute: input.attribute
+    };
+    if (input.value != null)
+        change.value = input.value;
+    return change;
+}
+export function buildActionChange(input) {
+    return { type: 'changeElementAction', ...common(input), action: input.action };
+}
+export function buildMoveChange(input) {
+    return {
+        type: 'elementMove',
+        ...common(input),
+        path: '',
+        targetIdentifier: input.targetIdentifier,
+        targetSelector: input.targetSelector,
+        mode: input.mode
+    };
+}
+export function buildTextChange(input) {
+    return {
+        type: 'elementText',
+        ...common(input),
+        text: input.text,
+        childIndex: input.childIndex,
+        mode: input.mode
+    };
+}
+export function buildScriptChange(input) {
+    return {
+        type: 'elementScript',
+        identifier: input.identifier,
+        selector: input.selector,
+        continueUndo: input.continueUndo ?? false,
+        script: input.script,
+        requiresContent: input.requiresContent
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+/**
+ * 把一条 change 翻译成人能读的摘要。
+ *
+ * ⚠️ **不是给机器看的**：JSON 那一份仍然保留(切「数值」形态)，那是与存量数据逐字段
+ * 比对用的。这里解决的是另一个问题 —— 列表里一眼看不出「我到底改了什么」。
+ * `elementStyle · div.RectangleCopy3` 这种展示，改了 5 处之后完全分不清哪条是哪条。
+ */
+export interface ChangeSummary {
+    /** 动作名，如「改样式」「删除」「编辑文字」。 */
+    action: string;
+    /** 改动详情，如 `font-size: 18px`。删除类没有详情。 */
+    detail: string;
+    /** 用于定位元素。 */
+    selector: string;
+    /** 图标标识，渲染层自行映射。 */
+    icon: 'style' | 'delete' | 'text' | 'code' | 'image' | 'link' | 'move' | 'insert';
+}
+export declare function summarizeChange(change: InlineChange): ChangeSummary;

package/dist/kernel/changelist/changeSummary.js

@@ -0,0 +1,85 @@
+function isDeleteChange(change) {
+    return (change.type === 'elementStyle' &&
+        change.property === 'display' &&
+        change.value === 'none');
+}
+export function summarizeChange(change) {
+    const selector = 'selector' in change ? change.selector : '';
+    switch (change.type) {
+        case 'elementStyle':
+            if (isDeleteChange(change)) {
+                return { action: '删除元素', detail: '', selector, icon: 'delete' };
+            }
+            return {
+                action: '改样式',
+                detail: `${change.property}: ${shorten(change.value)}`,
+                selector,
+                icon: 'style'
+            };
+        case 'elementContent': {
+            if (change.isTextChange) {
+                return {
+                    action: '编辑文字',
+                    detail: textPreview(change.html),
+                    selector,
+                    icon: 'text'
+                };
+            }
+            if (change.mode === 'replace') {
+                return { action: '编辑 HTML', detail: htmlPreview(change.html), selector, icon: 'code' };
+            }
+            return {
+                action: '插入元素',
+                detail: `${modeLabel(change.mode)} · ${htmlPreview(change.html)}`,
+                selector,
+                icon: 'insert'
+            };
+        }
+        case 'changeElementAttribute':
+            if (change.attribute === 'src') {
+                return { action: '替换图片', detail: shorten(change.value ?? ''), selector, icon: 'image' };
+            }
+            return {
+                action: '改属性',
+                detail: change.value == null
+                    ? `移除 ${change.attribute}`
+                    : `${change.attribute}: ${shorten(change.value)}`,
+                selector,
+                icon: 'style'
+            };
+        case 'changeElementAction':
+            return { action: '点击动作', detail: actionDetail(change.action), selector, icon: 'link' };
+        case 'elementMove':
+            return {
+                action: '移动元素',
+                detail: `${moveModeLabel(change.mode)} ${change.targetSelector}`,
+                selector,
+                icon: 'move'
+            };
+        case 'elementText':
+            return { action: '改文本', detail: textPreview(change.text), selector, icon: 'text' };
+        case 'elementScript':
+            return { action: '自定义脚本', detail: '', selector, icon: 'code' };
+    }
+}
+function modeLabel(mode) {
+    return ({ insert: '内部开头', append: '内部末尾', before: '之前', after: '之后' }[mode] ?? mode);
+}
+function moveModeLabel(mode) {
+    return { top: '移入开头', bottom: '移入末尾', before: '移到前面', after: '移到后面' }[mode] ?? mode;
+}
+function textPreview(html) {
+    const text = html.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+    return shorten(text);
+}
+function htmlPreview(html) {
+    const tag = html.trim().match(/^<\s*([a-zA-Z][\w-]*)/)?.[1];
+    return tag ? `<${tag.toLowerCase()}> …` : shorten(html);
+}
+function actionDetail(action) {
+    const type = action?.clickActionType;
+    return type ? String(type) : '';
+}
+function shorten(text, max = 42) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 复制粘贴的剪贴板内容处理。
+ *
+ * ⚠️ **粘贴前必须重写防撞号**（`pt-element-XXXXXXXX`）。
+ *
+ * 那个 id 会被选择器生成**优先当锚点**用（`#id`）。原样粘贴的话页面上就有两个同 id
+ * 元素 —— identifier 不再唯一，第二份的所有后续 change 会全部错打到第一份上。
+ * 而且这件事在粘贴当下**看不出任何异常**：两个元素长得一模一样，直到用户去改第二份
+ * 才发现改的是第一份。
+ */
+export interface PasteSource {
+    /** 复制下来的 outerHTML（已剥 script/noscript —— `getOuterHtml` 做的）。 */
+    html: string;
+}
+/** 粘贴用的 HTML：重写全部防撞号。 */
+export declare function pasteHtml(source: PasteSource, randomId?: () => string): string;

package/dist/kernel/changelist/clipboard.js

@@ -0,0 +1,4 @@
+import { rewritePtElementIds } from '../../dialogs/imageEdit.js';
+export function pasteHtml(source, randomId) {
+    return rewritePtElementIds(source.html, randomId);
+}

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

@@ -0,0 +1,30 @@
+import { type InlineChange } from '@ptengine/inline-core/change-format';
+import { type MergeOutcome } from './mergeForSave.js';
+import type { ChangeRecord } from './useChangeList.js';
+/**
+ * 把编辑器里的**明文** change list 转成落盘形态。
+ *
+ * change list 跟随 experience 配置一起存库，包本身不碰存储 —— 宿主在保存 experience
+ * 时调这个函数，把结果放进配置里。
+ *
+ * ⚠️ **不要直接存 `editor.changeList.changes`**（那是明文形态，DEC-22）。直接存不会
+ * 报任何错，要等发布后 SDK 读到 `type: 'elementStyle'` 而不是 `53` 才暴露 ——
+ * 那时候排查要从「实验不生效」一路倒推回保存那一刻。
+ *
+ * 单独给一个具名函数而不是让宿主自己 `changes.map(toWireFormat)`：这一步太容易被漏，
+ * 而漏了没有任何信号。有了它，README 那句「落盘前必经 toWireFormat」才有着落。
+ */
+export declare function exportChangesForSave(changes: InlineChange[]): unknown[];
+/**
+ * 从 change list 的**记录**落盘 —— 比上面那个多做一步：按祖先关系收敛
+ * （见 `mergeForSave`：祖先后来被隐藏 / 整体替换时，子树里的改动不必存）。
+ *
+ * 为什么另给一个函数而不是改上面那个：上面那个只吃 `InlineChange[]`，没有祖先信息，
+ * 而祖先只活在 `ChangeRecord` 上。宿主手里就是记录，用这个。
+ *
+ * 返回 `dropped` 而不是静默筛掉：界面上要能回答「我明明改了 C 的文字，为什么没存」。
+ */
+export declare function exportRecordsForSave(records: ChangeRecord[]): {
+    tagData: unknown[];
+    dropped: MergeOutcome['dropped'];
+};

package/dist/kernel/changelist/exportForSave.js

@@ -0,0 +1,11 @@
+import { toWireFormat } from '@ptengine/inline-core/change-format';
+import { mergeForSave } from './mergeForSave.js';
+import { disableObserverAroundMoves } from './moveObserverSafety.js';
+export function exportChangesForSave(changes) {
+    return changes.map(toWireFormat);
+}
+export function exportRecordsForSave(records) {
+    const guarded = disableObserverAroundMoves(records.map(r => ({ change: r.change, ancestors: r.ancestors })));
+    const { kept, dropped } = mergeForSave(guarded);
+    return { tagData: kept.map(toWireFormat), dropped };
+}

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

@@ -0,0 +1,79 @@
+/**
+ * 落盘前的收敛 —— 只做**祖先关系**那两条，不建树、不读活 DOM。
+ *
+ * ## 与现役 `useInline.ts:getInlineRenderList` 的关系
+ *
+ * 那份实现做七件事，我们只需要其中两件。差别的根源是**它必须从活 DOM 反推最终状态**：
+ *
+ *  - 它的 `undo/redo` 会让 `insertedNodes` 变游离（它自己的注释写的），所以只能在保存时
+ *    `updateContentChangeNewHtml` 从活 DOM 重新序列化；一旦这么做，后代的 content change
+ *    就必须丢（否则重复应用，且刷新后的 html 里那个子元素可能已不存在）。
+ *    「丢后代」是那个选择的**后果**，不是独立需求。
+ *  - 我们的 `revert` 是**把那一行从清单里删掉**，所以清单永远是一条干净的、只往前的序列；
+ *    顺序重放即得最终状态，不需要反推。
+ *  - 它建树的另一半价值是算 `__enableObserver`（尽量开成 true，只对 move 参与的子树关掉）。
+ *    我们改成「默认不写、交给 SDK 那张按类型的默认表」，所以这一半也不需要建树。
+ *
+ * 剩下这两条是真有价值的，而且都只需要**祖先 selector 列表**（采集时就知道，见
+ * `ChangeRecord.ancestors`），不需要 DOM：
+ *
+ *  1. 祖先被隐藏（`elementStyle display:none`）→ 子树内的改动全丢。它们在一个不可见的
+ *     子树里，视觉上等于不存在，但 SDK 会为每条**空转轮询最长 3 分 20 秒**
+ *     （`_observeTextChange` 在「已是目标值」时返回 false，早停要靠成功计数推进，
+ *     所以它一直轮到 1000 次上限）。
+ *  2. 祖先的内容被整体替换（`elementContent` 的 `replace`，含 `isTextChange`）→
+ *     子树内**内容类**改动丢掉，`elementStyle` / `changeElementAction` 留着。
+ *     现役同一条规则；理由是那两类不写在 html 串里（action 靠运行时绑定，style 走样式表
+ *     规则或内联+找元素重试），而 content / attribute 会被序列化进祖先的 html。
+ *
+ * ## ⚠️ 必须带顺序，这是与现役的实质差异
+ *
+ * 只有当祖先的替换**在后**时才丢后代 —— 因为我们存的祖先 html 是「打开 HTML 弹框那一刻
+ * 的活 DOM 快照」，已经含了先前的后代改动。反过来（先改祖先、后改后代）后代才是更晚的
+ * 意图，**必须留**。现役不需要区分顺序，因为它读活 DOM 拿最终态；我们不读，所以要区分。
+ *
+ * ## 刻意不抄的一条
+ *
+ * 现役的 `isParentAdded`（新增元素的后代也丢）对我们不成立：我们存的 insert html 是当时
+ * 给的那份，后来在新元素里改的文字**没被烤进去**，丢了就真丢了。所以 `insert` / `append`
+ * 不触发规则 2，只有 `replace` 触发。
+ *
+ * ## ⚠️ 输出顺序绝不能变
+ *
+ * SDK 的 `_applyContentBefore` 只能清掉**在它之前注册**的监听（它在每次 content replace
+ * 前把子树里的监听收走）。我们的时间顺序正是让这套清理落在该清的那条上的原因。
+ * 为了「整洁」重排会让先后关系错位，症状是「偶尔某条被还原回旧值」。
+ */
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+/** 一条改动 + 它的祖先 selector（采集时记下，不进落盘 payload）。 */
+export interface ChangeWithAncestors {
+    change: InlineChange;
+    /** 由近及远或反序都行，只做集合判断。空 = 不知道祖先（则本条不参与筛除）。 */
+    ancestors: string[];
+}
+export interface MergeOutcome {
+    kept: InlineChange[];
+    /** 被筛掉的，连原因 —— 界面上要能说清「为什么这条没进存库」。 */
+    dropped: Array<{
+        change: InlineChange;
+        reason: 'ancestor-hidden' | 'ancestor-replaced';
+        /** 那个祖先的 selector。 */
+        by: string;
+    }>;
+}
+/** 一条被压制的判定：为什么、被哪条压的。`null` = 不被压制。 */
+export interface Suppression {
+    reason: 'ancestor-hidden' | 'ancestor-replaced';
+    /** 压制它的那条改动的 selector。 */
+    by: string;
+}
+/**
+ * 判断 `entries[index]` 是否被后面某条改动压制。
+ *
+ * ⚠️ **这是唯一的判定处，清单徽章与落盘收敛都必须调它。**
+ *
+ * 分成两份实现的后果不是「代码重复」，是**徽章会撒谎** —— 用户看到「会提交」结果
+ * 没存进去，比压根没有徽章更糟：他会以为自己改的东西丢了，而清单明明写着没问题。
+ */
+export declare function classifySuppression(entries: ChangeWithAncestors[], index: number): Suppression | null;
+export declare function mergeForSave(entries: ChangeWithAncestors[]): MergeOutcome;

package/dist/kernel/changelist/mergeForSave.js

@@ -0,0 +1,40 @@
+function isHide(change) {
+    return (change.type === 'elementStyle' &&
+        change.property === 'display' &&
+        change.value === 'none');
+}
+function isReplace(change) {
+    return change.type === 'elementContent' && change.mode === 'replace';
+}
+function isBakedIntoHtml(change) {
+    return change.type === 'elementContent' || change.type === 'changeElementAttribute';
+}
+export function classifySuppression(entries, index) {
+    const entry = entries[index];
+    if (!entry)
+        return null;
+    const ancestors = new Set(entry.ancestors);
+    for (let later = index + 1; later < entries.length; later++) {
+        const other = entries[later].change;
+        if (!ancestors.has(other.selector))
+            continue;
+        if (isHide(other))
+            return { reason: 'ancestor-hidden', by: other.selector };
+        if (isReplace(other) && isBakedIntoHtml(entry.change)) {
+            return { reason: 'ancestor-replaced', by: other.selector };
+        }
+    }
+    return null;
+}
+export function mergeForSave(entries) {
+    const kept = [];
+    const dropped = [];
+    entries.forEach((entry, index) => {
+        const verdict = classifySuppression(entries, index);
+        if (verdict)
+            dropped.push({ change: entry.change, ...verdict });
+        else
+            kept.push(entry.change);
+    });
+    return { kept, dropped };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * move 与 observer 的互锁 —— 列表里有移动时，把**位置可能失效**的那些改动的
+ * `enableObserver` 显式设成 `false`。
+ *
+ * ## 为什么必须关
+ *
+ * SDK 的 observer 是「隔一会儿按 selector 重新找元素、再把改动套上去」
+ * （`ptengine-sdk/src/modules/experience/inline/`，200ms 轮询）。而我们的 selector 是
+ * 位置型的（`nth-of-type` / 子序号），移动元素会让**同一条 selector 指向另一个元素** ——
+ * 观察者于是把改动套到错的元素上。
+ *
+ * 两种错的方向代价完全不对等：
+ * - 不该关而关了 → 客户端重渲染后这条改动不再被写回，可能被页面自己覆盖掉；
+ * - 该关而没关 → 改动落到**错误的元素**上，页面当场是花的。
+ *
+ * 所以宁可多关，但也不能一刀切全关（见下）。
+ *
+ * ## 关谁：位置失效的真实范围
+ *
+ * `nth-of-type` / 子序号只在**元素离开的那个容器**和**它进入的那个容器**里发生偏移。
+ * 于是受影响的恰好是这四类：
+ *
+ * 1. 被移动的元素自己；
+ * 2. 被移动元素**内部**的改动（子树整体换了位置，路径前缀变了）；
+ * 3. 被移动元素的**祖先**（子树内容变了，祖先的 html 序列化随之变）；
+ * 4. **源容器与目标容器子树内的一切** —— 任何路径穿过这两个容器的 selector 都会
+ *    因为兄弟序号偏移而指错。
+ *
+ * 第 4 条是自适应的：如果移动发生在顶层（源/目标容器就是 `body`），那么 `body` 出现在
+ * 所有改动的祖先链里，于是全部关闭 —— 正确，因为此时 `body > :nth-child(n)` 这类
+ * 路径确实全都偏了。
+ *
+ * ## ⚠️ 与现役的差异（刻意）
+ *
+ * 现役 `useInline.ts:checkMoveOperation` 的判据是「节点自身或任一后代有 move →
+ * 该节点整个子树关闭」，而 traverse 在 `body` 根节点直接跳过判定（`:445`），净效果是
+ * **「与某个 move 共享同一个顶层容器的改动全部关闭」**。那是树遍历形状的副产物，不是
+ * 位置失效的实际边界：同一顶层容器里另一条分支上的改动其实没受影响，却被关掉了。
+ *
+ * 另外现役那半「move 之前的路径」（`movePaths`）**是死代码**：`movePaths.push` 前有
+ * `change.elementMove?.path?.string &&` 守卫，而 `path` 全文件零赋值（DEC-19 的依据
+ * 正是这个），所以那个数组恒为空、`originPathHasMoveOperation` 恒 false。没有照抄。
+ *
+ * ## ⚠️ 为什么在**落盘时**算，不在采集时
+ *
+ * 移动可能是**后**加的：先改了 C 的文字，再把 C 的祖先移走 —— 那条文字改动在采集时
+ * 完全正常，是后来的移动让它的 selector 失效的。采集时决定就必然漏掉这种，
+ * 而漏掉的表现是「线上偶尔某个改动出现在错误的元素上」。
+ */
+import type { ChangeWithAncestors } from './mergeForSave.js';
+/**
+ * 返回一份新的 entries：受影响的改动 `enableObserver` 被显式设成 `false`。
+ *
+ * ⚠️ **写显式 `false`，不是留 undefined。** `undefined` 的含义是「不写这个 key、交给
+ * SDK 按类型的默认表决定」，而那张表里 attribute / textChange 是「缺省即监听」——
+ * 正是我们要关掉的两类。
+ *
+ * 列表里没有移动时原样返回（不产生新对象，调用方可以按引用判断有没有动过）。
+ *
+ * ## ⚠️ 已知降级：回显的存量改动没有祖先信息
+ *
+ * `hydrate` 填进来的记录 `ancestors: []`（存库是扁平数组、没有层级）。对这些改动：
+ * - 它们**自己**若正是被移动的元素 / 源容器 / 目标容器，仍会被关掉（按 selector 命中）；
+ * - 但「在被移动子树内部」这一条判不出来 —— 那需要它的祖先链。
+ *
+ * 也就是说「上次保存的改动 + 本次新加一个移动」这种组合下，保护是不完整的。
+ * 不用 selector 字符串前缀去猜层级：v2 selector 不保证是可截断的路径串，猜错的方向是
+ * **误关**（丢掉本该有的 observer），而那种丢失在编辑器里完全看不出来。
+ */
+export declare function disableObserverAroundMoves(entries: ChangeWithAncestors[]): ChangeWithAncestors[];

package/dist/kernel/changelist/moveObserverSafety.js

@@ -0,0 +1,39 @@
+function collectRegions(entries) {
+    const subtree = new Set();
+    const selfOnly = new Set();
+    for (const entry of entries) {
+        const change = entry.change;
+        if (change.type !== 'elementMove')
+            continue;
+        subtree.add(change.selector);
+        if (change.targetSelector)
+            subtree.add(change.targetSelector);
+        const sourceParent = entry.ancestors[0];
+        if (sourceParent)
+            subtree.add(sourceParent);
+        for (const ancestor of entry.ancestors)
+            selfOnly.add(ancestor);
+    }
+    return { subtree, selfOnly };
+}
+function isAffected(entry, regions) {
+    const selector = entry.change.selector;
+    if (regions.subtree.has(selector) || regions.selfOnly.has(selector))
+        return true;
+    return entry.ancestors.some(a => regions.subtree.has(a));
+}
+export function disableObserverAroundMoves(entries) {
+    const regions = collectRegions(entries);
+    if (regions.subtree.size === 0 && regions.selfOnly.size === 0)
+        return entries;
+    return entries.map(entry => {
+        const change = entry.change;
+        if (change.type === 'elementScript')
+            return entry;
+        if (!isAffected(entry, regions))
+            return entry;
+        if (change.enableObserver === false)
+            return entry;
+        return { ...entry, change: { ...change, enableObserver: false } };
+    });
+}

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

@@ -0,0 +1,22 @@
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+/**
+ * 返回可被 `incoming` 覆盖的下标，无则 -1。
+ *
+ * ⚠️ `affectsSelectors` 的 break 不可省，且**必须在 `overrides` 判断之前**：
+ * 顺序反了会让 attribute 之类「既有覆盖键又改选择器」的 change 被错误覆盖。
+ */
+export declare function findOverrideIndex(list: InlineChange[], incoming: InlineChange): number;
+/**
+ * 加入 `incoming` 的结果，**同时报出被丢弃的是哪些**。
+ *
+ * ⚠️ `dropped` 不是可选信息，是正确性所必需的：被覆盖的旧 change 只是从**列表**里
+ * 消失了，它在客户页 DOM 上**仍然生效**、agent 侧的撤销闭包也还挂着没人调。
+ * 调用方必须先把它们撤销掉再应用新的 —— 否则新 change 捕获到的「原始现场」其实是
+ * 上一条改过之后的状态，撤销它只会回退一步，用户看到的就是「撤销了但没恢复」。
+ */
+export declare function overrideOutcome(list: InlineChange[], incoming: InlineChange): {
+    next: InlineChange[];
+    dropped: InlineChange[];
+};
+/** 只要结果数组的薄封装。新代码请用 `overrideOutcome` —— 它同时报出被丢弃的条目。 */
+export declare function applyOverride(list: InlineChange[], incoming: InlineChange): InlineChange[];

package/dist/kernel/changelist/overrides.js

@@ -0,0 +1,63 @@
+function affectsSelectors(change) {
+    return change.type !== 'elementStyle' && change.type !== 'elementText';
+}
+function selectorOf(change) {
+    return change.selector;
+}
+function isAction(change) {
+    return change.type === 'changeElementAction';
+}
+function overrides(incoming, existing) {
+    if (incoming.type !== existing.type)
+        return false;
+    if (selectorOf(incoming) !== selectorOf(existing))
+        return false;
+    if (incoming.type === 'elementStyle' && existing.type === 'elementStyle') {
+        return (incoming.property === existing.property &&
+            incoming.cssConditional === existing.cssConditional);
+    }
+    if (incoming.type === 'elementText' && existing.type === 'elementText') {
+        return (incoming.mode === 'replace' &&
+            existing.mode === 'replace' &&
+            incoming.childIndex === existing.childIndex);
+    }
+    if (incoming.type === 'changeElementAttribute' &&
+        existing.type === 'changeElementAttribute') {
+        return incoming.attribute === existing.attribute;
+    }
+    return false;
+}
+export function findOverrideIndex(list, incoming) {
+    for (let i = list.length - 1; i >= 0; i--) {
+        const existing = list[i];
+        if (affectsSelectors(existing))
+            break;
+        if (overrides(incoming, existing))
+            return i;
+    }
+    return -1;
+}
+export function overrideOutcome(list, incoming) {
+    if (isAction(incoming)) {
+        const selector = selectorOf(incoming);
+        const dropped = list.filter(c => isAction(c) && selectorOf(c) === selector);
+        return { next: [...list.filter(c => !dropped.includes(c)), incoming], dropped };
+    }
+    const index = findOverrideIndex(list, incoming);
+    if (index < 0)
+        return { next: [...list, incoming], dropped: [] };
+    return {
+        next: [...list.slice(0, index), ...list.slice(index + 1), incoming],
+        dropped: [list[index]]
+    };
+}
+export function applyOverride(list, incoming) {
+    if (isAction(incoming)) {
+        const selector = selectorOf(incoming);
+        return [...list.filter(c => !(isAction(c) && selectorOf(c) === selector)), incoming];
+    }
+    const index = findOverrideIndex(list, incoming);
+    if (index < 0)
+        return [...list, incoming];
+    return [...list.slice(0, index), ...list.slice(index + 1), incoming];
+}