@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/panels/styleFields.js

@@ -0,0 +1,91 @@
+export const STYLE_SECTIONS = [
+    {
+        id: 'size',
+        labelKey: 'inlineCanvas.style.size',
+        fields: [
+            { property: 'width', labelKey: 'inlineCanvas.style.width', kind: 'length', unit: 'px' },
+            { property: 'height', labelKey: 'inlineCanvas.style.height', kind: 'length', unit: 'px' }
+        ]
+    },
+    {
+        id: 'typography',
+        labelKey: 'inlineCanvas.style.typography',
+        visible: caps => caps.hasText,
+        fields: [
+            { property: 'font-family', labelKey: 'inlineCanvas.style.fontFamily', kind: 'text' },
+            {
+                property: 'font-size',
+                labelKey: 'inlineCanvas.style.fontSize',
+                kind: 'length',
+                unit: 'px'
+            },
+            {
+                property: 'font-weight',
+                labelKey: 'inlineCanvas.style.fontWeight',
+                kind: 'select',
+                options: ['300', '400', '500', '600', '700', '800', '900']
+            },
+            {
+                property: 'line-height',
+                labelKey: 'inlineCanvas.style.lineHeight',
+                kind: 'length',
+                unit: 'px'
+            },
+            {
+                property: 'text-align',
+                labelKey: 'inlineCanvas.style.textAlign',
+                kind: 'select',
+                options: ['left', 'center', 'right', 'justify']
+            },
+            { property: 'color', labelKey: 'inlineCanvas.style.color', kind: 'color' }
+        ]
+    },
+    {
+        id: 'background',
+        labelKey: 'inlineCanvas.style.background',
+        fields: [
+            {
+                property: 'background-color',
+                labelKey: 'inlineCanvas.style.backgroundColor',
+                kind: 'color'
+            }
+        ]
+    },
+    {
+        id: 'spacing',
+        labelKey: 'inlineCanvas.style.spacing',
+        fields: [
+            { property: 'padding', labelKey: 'inlineCanvas.style.padding', kind: 'text' },
+            { property: 'margin', labelKey: 'inlineCanvas.style.margin', kind: 'text' }
+        ]
+    },
+    {
+        id: 'border',
+        labelKey: 'inlineCanvas.style.border',
+        fields: [
+            { property: 'border', labelKey: 'inlineCanvas.style.borderAll', kind: 'text' },
+            {
+                property: 'border-radius',
+                labelKey: 'inlineCanvas.style.borderRadius',
+                kind: 'length',
+                unit: 'px'
+            }
+        ]
+    }
+];
+export function visibleSections(caps) {
+    if (!caps)
+        return [];
+    return STYLE_SECTIONS.filter(s => (s.visible ? s.visible(caps) : true));
+}
+const HAS_UNIT_OR_KEYWORD = /[a-z%)]$/i;
+export function composeStyleValue(field, raw) {
+    const value = raw.trim();
+    if (!value)
+        return value;
+    if (field.kind !== 'length' || !field.unit)
+        return value;
+    if (HAS_UNIT_OR_KEYWORD.test(value))
+        return value;
+    return `${value}${field.unit}`;
+}

package/dist/tree/LayersPanel.d.ts

@@ -0,0 +1,30 @@
+import { type DropPos } from '../canvas-ui/index.js';
+import { type AdaptedTree } from './domTreeAdapter.js';
+/**
+ * inline editor 的图层面板。
+ *
+ * ⚠️ **对客户页只读**：点=选中、悬浮=高亮、拖=移动。**没有重命名** ——
+ * 客户页元素没有 `data-pt-name` 可写，写了就是在改客户页的属性。
+ *
+ * id 与 selector 的转换只在这一层做：`TreePanel` 只认 id，画布命令只认 selector，
+ * 中间那层撞号后缀（`#dup2`）绝不能漏到命令上去（见 `domTreeAdapter`）。
+ */
+export interface LayersPanelProps {
+    tree: AdaptedTree | null;
+    selectedSelector: string | null;
+    hoverSelector?: string | null;
+    onSelect: (selector: string) => void;
+    /** 空串 = 清除高亮。 */
+    onHover: (selector: string) => void;
+    /** 拖拽重排 → `elementMove`。省略则不可拖。 */
+    onMove?: (dragSelector: string, targetSelector: string, pos: DropPos) => void;
+    /**
+     * 展开一个被截断的节点（去把它的子树拉回来）。省略则截断节点不出箭头。
+     *
+     * ⚠️ **唯一交出内部 id 而不是 selector 的回调，而且必须如此**：回填的目标是
+     * 「树上这一行」，撞号时多行共享同一个 selector —— 交 selector 出去，宿主只能
+     * 回查到第一行，于是点第 2 个同名节点会把子树接到第 1 个身上，**且不报错**。
+     */
+    onExpand?: (id: string) => void;
+}
+export declare function LayersPanel({ tree, selectedSelector, hoverSelector, onSelect, onHover, onMove, onExpand }: LayersPanelProps): import("react").JSX.Element;

package/dist/tree/LayersPanel.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Input } from '@ptengine/design-components';
+import { TreePanel } from '../canvas-ui/index.js';
+import { findIdBySelector } from './domTreeAdapter.js';
+export function LayersPanel({ tree, selectedSelector, hoverSelector, onSelect, onHover, onMove, onExpand }) {
+    const [query, setQuery] = useState('');
+    if (!tree) {
+        return (_jsx("p", { "data-testid": "layers-empty", className: "px-3 py-6 text-center text-xs text-[#8993A4]", children: "\u8FD8\u6CA1\u6709\u62FF\u5230\u9875\u9762\u7ED3\u6784" }));
+    }
+    const selectorOf = (id) => tree.nodes[id]?.selector ?? id;
+    const idOf = (selector) => selector ? findIdBySelector(tree, selector) : null;
+    return (_jsxs("div", { className: "flex h-full min-h-0 flex-col", "data-testid": "layers-panel", children: [_jsx("div", { className: "p-2", children: _jsx(Input, { "data-testid": "layers-search", placeholder: "\u641C\u7D22\u56FE\u5C42", value: query, onChange: e => setQuery(e.target.value) }) }), _jsx("div", { className: "min-h-0 flex-1 overflow-auto", children: _jsx(TreePanel, { nodes: tree.nodes, rootId: tree.rootId, selectedId: idOf(selectedSelector), hoverId: idOf(hoverSelector ?? null), query: query, onSelect: id => onSelect(selectorOf(id)), onHover: id => onHover(id ? selectorOf(id) : ''), onMove: onMove &&
+                        ((dragId, targetId, pos) => onMove(selectorOf(dragId), selectorOf(targetId), pos)), onExpand: onExpand }) })] }));
+}

package/dist/tree/domTreeAdapter.d.ts

@@ -0,0 +1,63 @@
+import type React from 'react';
+import type { DomTreeNode } from '@ptengine/inline-core/protocol';
+import type { ElementMoveModeName } from '@ptengine/inline-core/change-format';
+import type { TreePanelNode } from '../canvas-ui/index.js';
+export interface AdaptedTreeNode extends TreePanelNode {
+    /** 发给画布命令用的**原始** selector（不带撞号后缀）。 */
+    selector: string;
+}
+export interface AdaptedTree {
+    nodes: Record<string, AdaptedTreeNode>;
+    rootId: string;
+}
+/** 宿主渲染行首图标要的信息。**只给事实，不给结论** —— 图标怎么挑是宿主的事。 */
+export interface TreeNodeIconInput {
+    tag: string;
+    /**
+     * 有直接子元素。
+     *
+     * ⚠️ 用 `childCount` 而不是 `children.length`：DOM 树命令对超大页面会**截断**子节点，
+     * 截断处 `children` 是空数组而 `childCount > 0` —— 只看数组会把一个容器画成叶子。
+     */
+    hasChildren: boolean;
+}
+export interface AdaptDomTreeOptions {
+    /**
+     * 行首图标渲染器。省略则树里不出图标。
+     *
+     * 为什么要注入：glyph 真值表（三代编辑器唯一那份）在 `apps/x` 里，而本包在
+     * `packages/` —— 包不能反向依赖 app。同 `uploadImage` / `libraryComponents` 的分工。
+     */
+    renderIcon?: (input: TreeNodeIconInput) => React.ReactNode;
+}
+export declare function adaptDomTree(root: DomTreeNode, options?: AdaptDomTreeOptions): AdaptedTree;
+/**
+ * 把按需拉回来的子树接回原树 —— `getDomTree({ rootSelector })` 的返回，其**根就是**
+ * `atId` 这个节点自己。
+ *
+ * ⚠️ **原地替换那一个节点的子树，不重建整棵树。** 重建会换掉所有 id，于是折叠态、
+ * 选中态、滚动定位全部对不上 —— 而且是静默的：树看着没问题，点哪一行都不对。
+ * 同理 `atId` 这一行的 id 也保持原样，只更新它的 label / truncated / children。
+ *
+ * `atId` 已经不在树里（切过设备、树重拉过）时**原样返回同一个对象**，让调用方的
+ * `===` 比较能直接判出「什么都没变」。
+ */
+export declare function graftSubtree(tree: AdaptedTree, atId: string, subtree: DomTreeNode, options?: AdaptDomTreeOptions): AdaptedTree;
+/**
+ * selector → 行 id。撞号时多行共享同一个 selector，取第一行 —— 与「点第一行选中它」
+ * 自洽。查不到返回 `null`，**调用方必须把它当「这个元素还没加载进树」来处理**，
+ * 不能当成「没有这个元素」。
+ */
+export declare function findIdBySelector(tree: AdaptedTree, selector: string): string | null;
+/**
+ * 树的落点档位 → `elementMove` 的 mode。
+ *
+ * ⚠️ **两套词表不一样**，直接传会静默错位：
+ * 树只有 `before` / `after` / `inside`，而 `elementMove` 是
+ * `before` / `after` / `top`（移入开头）/ `bottom`（移入末尾）。
+ *
+ * `inside` 映射到 `bottom`（追加到末尾）—— 与「把一行拖进容器」的直觉一致：
+ * 用户看到的是它落在容器里已有内容的下面。映射到 `top` 会让它插到最前面，
+ * 现象是「拖进去了但位置不对」，而且用户完全无法预期。
+ */
+export declare function moveModeFromDropPos(pos: 'before' | 'after' | 'inside'): ElementMoveModeName;

package/dist/tree/domTreeAdapter.js

@@ -0,0 +1,90 @@
+const VOID_TAGS = new Set([
+    'img',
+    'br',
+    'hr',
+    'input',
+    'source',
+    'track',
+    'area',
+    'base',
+    'col',
+    'embed',
+    'link',
+    'meta',
+    'param',
+    'wbr'
+]);
+function labelOf(node) {
+    const text = node.textSummary.trim();
+    const suffix = node.truncated ? ` …(${node.childCount})` : '';
+    return text ? `${node.tag} · ${text}${suffix}` : `${node.tag}${suffix}`;
+}
+function makeUniqueId(used) {
+    return (selector) => {
+        if (!used.has(selector)) {
+            used.add(selector);
+            return selector;
+        }
+        let n = 2;
+        while (used.has(`${selector}#dup${n}`))
+            n += 1;
+        const id = `${selector}#dup${n}`;
+        used.add(id);
+        return id;
+    };
+}
+function rowOf(node, id, childIds, options) {
+    const hasChildren = node.childCount > 0 || childIds.length > 0;
+    return {
+        id,
+        selector: node.selector,
+        label: labelOf(node),
+        canContain: !VOID_TAGS.has(node.tag.toLowerCase()),
+        truncated: node.truncated,
+        children: childIds,
+        icon: options.renderIcon?.({ tag: node.tag, hasChildren })
+    };
+}
+function writeSubtree(node, nodes, uniqueId, options) {
+    const id = uniqueId(node.selector);
+    const childIds = node.children.map(child => writeSubtree(child, nodes, uniqueId, options));
+    nodes[id] = rowOf(node, id, childIds, options);
+    return id;
+}
+export function adaptDomTree(root, options = {}) {
+    const nodes = {};
+    const rootId = writeSubtree(root, nodes, makeUniqueId(new Set()), options);
+    return { nodes, rootId };
+}
+export function graftSubtree(tree, atId, subtree, options = {}) {
+    if (!tree.nodes[atId])
+        return tree;
+    const nodes = { ...tree.nodes };
+    const seen = new Set([atId]);
+    const drop = (id) => {
+        for (const child of nodes[id]?.children ?? []) {
+            if (seen.has(child))
+                continue;
+            seen.add(child);
+            drop(child);
+            delete nodes[child];
+        }
+    };
+    drop(atId);
+    const uniqueId = makeUniqueId(new Set(Object.keys(nodes)));
+    const childIds = subtree.children.map(child => writeSubtree(child, nodes, uniqueId, options));
+    nodes[atId] = rowOf(subtree, atId, childIds, options);
+    return { nodes, rootId: tree.rootId };
+}
+export function findIdBySelector(tree, selector) {
+    if (!selector)
+        return null;
+    if (tree.nodes[selector])
+        return selector;
+    return Object.keys(tree.nodes).find(id => tree.nodes[id].selector === selector) ?? null;
+}
+export function moveModeFromDropPos(pos) {
+    if (pos === 'inside')
+        return 'bottom';
+    return pos;
+}

package/dist/useInlineEditor.d.ts

@@ -0,0 +1,161 @@
+import type { AncestorNode, CanvasDevice, ElementCapabilities } from '@ptengine/inline-core/protocol';
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+import { useCanvasSession } from './kernel/useCanvasSession.js';
+import { type MobileFitState } from './kernel/useMobileFit.js';
+import { useCanvasGeometry } from './kernel/selection/useCanvasGeometry.js';
+import { useChangeList } from './kernel/changelist/useChangeList.js';
+import { type CaptureOutcome } from './kernel/captureOrchestration.js';
+import { type AdaptDomTreeOptions, type AdaptedTree } from './tree/domTreeAdapter.js';
+import type { InsertMode } from './kernel/changelist/useChangeList.js';
+import { type MovePosition, type MoveState } from './kernel/moveState.js';
+import { getOuterHtml } from './kernel/canvasCommands.js';
+/**
+ * 内联编辑器的 **headless 层**。
+ *
+ * 它把「会话编排 + 选中态 + 几何 + change list」收成一个对象，**不含任何 UI**。
+ *
+ * 为什么必须有这一层，而不是只提供成品 `<InlineEditor>`：
+ * 编辑器在不同入口下**外壳差异极大** —— experience 创建流程需要版本管理、设备切换、
+ * 保存/预览的双层顶栏；从 AI 对话里打开则只要一条极简顶栏。只封装成品组件的话，
+ * 后者要么被迫塞进它不需要的 UI，要么就得给组件加一堆 `showXxx` 布尔开关
+ * —— 那是组件复杂度失控的典型开端。
+ *
+ * 所以：**外壳是宿主的事，内核在这里**。`<InlineEditor>` 只是本 hook 的一个默认外壳。
+ */
+export interface InlineEditorSelection {
+    /** 匹配用 selector（可能命中多个，SDK 只作用第一个）。 */
+    selector: string;
+    /** 唯一定位串（强制 tagName + nth-of-type）。 */
+    identifier: string;
+    tag: string;
+    /** `[自己, 父, …, body]`，index 0 是自己。路径选择器用它。 */
+    chain: AncestorNode[];
+    /** DEC-14：一次往返批量拿到的能力位，决定工具条显示哪些按钮。 */
+    capabilities: ElementCapabilities | null;
+    /**
+     * 选中元素的 innerHTML（来自 `elementPicked` 的 `originalValue.html`）。
+     * 「编辑文字」的 seed 用它 —— 用 textContent 会把 `<br>`/`<strong>` 这类内联标记
+     * 悄悄抹掉。
+     */
+    declaredHtml: string;
+    /** author 层声明的样式，属性面板拿它作输入框初值。 */
+    declaredStyles: Record<string, string>;
+}
+export interface UseInlineEditorInput {
+    url: string;
+    device: CanvasDevice;
+    /** change list 变化时回调 —— 宿主自己决定存哪（本 hook 不做持久化）。 */
+    onChangesChange?: (changes: InlineChange[]) => void;
+    /**
+     * 画布 iframe 的 ref。元素截图要靠它拿 iframe 在产品页里的位置与 zoom ——
+     * 没有这两个值就没法把「元素在客户页视口里的坐标」换算成「屏幕位图里的坐标」。
+     */
+    iframeRef?: React.MutableRefObject<HTMLIFrameElement | null>;
+    /** 图层树行首图标渲染器（宿主注入，见 `adaptDomTree`）。 */
+    renderNodeIcon?: AdaptDomTreeOptions['renderIcon'];
+    /** 撤销拿掉了插入类 change → 回报它插入过的元素（见 `UseChangeListOptions.onInsertedRemoved`）。 */
+    onInsertedRemoved?: (selectors: string[]) => void;
+    onInsertedRestored?: (selectors: string[]) => void;
+    /**
+     * 是否在 `domReady` 后拉取页面结构树（图层面板的数据源）。默认 `true`。
+     *
+     * 给**不渲染图层面板**的外壳用（分析阶段的 `<PagePreview>`）：那一趟是跨三跳的
+     * 往返 + 整棵结构的序列化（现在是 depth 16 / maxNodes 1500），对一个从头到尾都不
+     * 显示树的壳纯属白花。关掉后 `tree` 恒为 `null`。
+     *
+     * ⚠️ **这不是「关掉一个功能」的开关模板**。包的 API 主张是「外壳差异靠 headless 层
+     * 自己拼」（见 `index.ts` 头部），所以这里只收**纯数据获取**的开关；任何「显示/不显示
+     * 某个部件」的诉求都该在外壳里解决，不要往这个 input 上加 `showXxx`。
+     *
+     * ⚠️ 尤其**不要**照这个样子再加一个「关掉拾取」的开关：`picker.ts` 的
+     * `onPointerDown`/`onClick` 正是在客户页上 `preventDefault`/`stopPropagation` 的地方，
+     * 关掉拾取等于让嵌进来的客户页**活过来** —— 点一个链接画布就导航走了，而 sessionId
+     * 不变，于是选中、几何、区块坐标全部对着一个已经不存在的页面，且零报错。
+     * 拾取开着才是这块板子「惰性」的成因；`elementPicked` 没人消费是无害的。
+     */
+    tree?: boolean;
+}
+export interface UseInlineEditorResult {
+    /** 会话状态：gating / opening / ready / failed + 失败原因。 */
+    session: ReturnType<typeof useCanvasSession>;
+    /** 供 `<CanvasFrame>` 直接展开的 props；`null` = 还没到可渲染画布的阶段。 */
+    frameProps: ReturnType<typeof useCanvasSession>['frameProps'];
+    /** DOM 解析完即为真 —— 不等 iframe 原生 load（那要等全部子资源，真实落地页好几秒）。 */
+    domReady: boolean;
+    selection: InlineEditorSelection | null;
+    /** 页面结构树（图层面板用）；`null` = 还没拿到。 */
+    tree: AdaptedTree | null;
+    /** 剪贴板里复制下来的 outerHTML；`null` = 空。 */
+    clipboard: string | null;
+    /** 「移动元素」的两步拾取状态；`null` = 没在移动。 */
+    move: MoveState | null;
+    /**
+     * 正在截图。为真时宿主**必须隐藏所有浮层**（高亮框 / 工具条 / 提示条）——
+     * `captureVisibleTab` 抓的是整屏，不隐藏就会把编辑器 UI 截进客户页的图里。
+     */
+    capturing: boolean;
+    /**
+     * 正在页面内原位改文字的元素 selector；`null` = 没在改。
+     *
+     * 必须有这个状态,不然编辑态**完全不可见** —— contentEditable 本身不带任何视觉
+     * 提示,用户点了「编辑文字」看到的和没点一模一样,分不清是没生效还是生效了。
+     */
+    textEditing: string | null;
+    geometry: ReturnType<typeof useCanvasGeometry>;
+    /**
+     * 移动端超宽缩小（契约 v11 §8）的当前状态。`scale < 1` 时 `<html>` 被整体缩放，
+     * agent 回报的几何（选中框、区块框）已经是缩放后的值，宿主**不用**换算；
+     * 只有拿外部数据（热图坐标）往画布上对时才需要除以 `scale`。
+     */
+    mobileFit: MobileFitState;
+    changeList: ReturnType<typeof useChangeList>;
+    commands: {
+        /** 选中某个元素（点路径选择器的某一级、或程序化选中）。空串 = 清空。 */
+        select: (selector: string) => Promise<void>;
+        /** 悬浮预览高亮。⚠️ **不改选中态**；空串 = 清除。 */
+        hover: (selector: string) => Promise<void>;
+        /**
+         * 「定位」：把元素滚进视野。**与 `select` 分开**，不合并进去 ——
+         * 画布内点选、恢复选中态、AI 应用改动都会产生选中，那些场景滚动是意外行为
+         * （尤其恢复：刷新后页面在顶部，自己跳走会让用户以为页面没加载完）。
+         *
+         * 未命中不抛错（客户改版后老 selector 失效是正常分支）。
+         */
+        reveal: (selector: string) => Promise<void>;
+        /** `</>` 的 seed：**outerHTML**，已剥 script/noscript。 */
+        readOuterHtml: (selector?: string) => ReturnType<typeof getOuterHtml>;
+        /**
+         * 在客户页**原位**开始改文字（问题 3）。
+         *
+         * 没有对应的「结束」命令给宿主调：用户按 Esc、按 Enter、点到别处都算结束，
+         * 由 agent 的 `textEditCommit` 事件回报，本 hook 收到后自动落一条 change。
+         */
+        startTextEdit: (selector?: string) => Promise<void>;
+        /** 截选中元素并返回图像字节。**不上传** —— 上传是宿主的事（包里不碰后端端点）。 */
+        captureSelectedElement: (selector: string) => Promise<CaptureOutcome>;
+        /** 复制元素（存 outerHTML 到剪贴板，不产生 change）。 */
+        copyElement: (selector: string) => Promise<void>;
+        /** 粘贴到某个元素的指定位置。**粘贴前会重写防撞号**。 */
+        pasteInto: (selector: string, mode: InsertMode) => Promise<void>;
+        /** 开始移动：记下源，等用户在画布里点目标。 */
+        startMove: (selector: string) => void;
+        /** 确认移动。目标未选时是 no-op。 */
+        confirmMove: (position: MovePosition) => Promise<void>;
+        cancelMove: () => void;
+        /**
+         * 展开图层树里某个被截断的节点：拉它的子树接回原树。
+         *
+         * 目标行不在树里（切过设备、树重拉过）时是 no-op。失败不抛 —— 树少一段，
+         * 但画布点选与路径选择器都还在。
+         */
+        expandTreeNode: (id: string) => Promise<void>;
+        /**
+         * 把清单整体换成另一批改动（切换实验版本）。转发 `changeList.replaceAll`。
+         *
+         * 也放在 `commands` 上，是因为自己拼外壳的宿主（headless 层）拿到的就是这一组
+         * 动作入口 —— 版本切换是「一个动作」，不该要求调用方先绕到 `changeList` 上去找。
+         */
+        replaceAll: ReturnType<typeof useChangeList>['replaceAll'];
+    };
+}
+export declare function useInlineEditor(input: UseInlineEditorInput): UseInlineEditorResult;