@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/InlineEditor.d.ts

@@ -0,0 +1,349 @@
+import type { CanvasDevice } from '@ptengine/inline-core/protocol';
+import { type ChromeVariant } from './chrome/EditorChrome.js';
+import type { PageModelBlock } from './kernel/blocks/resolveBlocks.js';
+import type { AdaptDomTreeOptions } from './tree/domTreeAdapter.js';
+import { type AnchorShot, type ElementAiContext } from './kernel/selection/elementAiContext.js';
+import { type InlinePlanAnchor } from './kernel/selection/resolveAnchors.js';
+import { type AiApplyOutcome, type AiScopeGrant, type AiWireChange } from './kernel/ai/aiInlineApply.js';
+import { type LibraryComponent } from './assets/componentLibrary.js';
+import { type UseInlineEditorResult } from './useInlineEditor.js';
+import type { ChangeRecord, HydrateOutcome } from './kernel/changelist/useChangeList.js';
+import type { InlineChange } from '@ptengine/inline-core/change-format';
+/**
+ * 成品编辑器 —— 外壳 + 画布 + 选中层 + 编辑入口的**默认拼装**。
+ *
+ * 需要不一样的外壳时**不要改这里加开关**，直接用 `useInlineEditor()` 自己拼
+ * （见 README 的两层 API）。这个组件存在的意义是「大多数入口不用从零拼」，
+ * 不是「所有入口都必须用它」。
+ *
+ * 目标视口宽度按设备固定：客户页按 1440 设计，画布用 `zoom` 缩放去适应面板宽度，
+ * 而不是把 iframe 做窄 —— 做窄会触发客户页的响应式断点，看到的就不是 PC 版了。
+ */
+export interface InlineEditorProps {
+    url: string;
+    device: CanvasDevice;
+    onDeviceChange: (device: CanvasDevice) => void;
+    title: string;
+    /** 单版本入口的静态版本名。传了 `versions` 时不再展示它（顶栏换成选择器）。 */
+    versionLabel?: string;
+    /**
+     * 可切换的版本列表。**宿主持有数据，包只负责切换机制** —— 包里不存多版本状态，
+     * 每次切换都是「把当前清单整体换成另一份」。
+     *
+     * 不传（或空数组）= 与今天完全一致：顶栏还是 `versionLabel` 那个静态标签，
+     * 下面这一组回调一个都不会触发。
+     */
+    versions?: {
+        id: string;
+        name: string;
+    }[];
+    /** 当前版本。**由宿主决定**：包切换成功后只是回调通知，不自己改这个值。 */
+    activeVersionId?: string;
+    /**
+     * 各版本的**明文**改动，key = versionId。宿主持有（它才知道哪些版本、存过什么）。
+     *
+     * ⚠️ 切到某个版本时包读的是这里的**当前值**，不是切换那一刻的快照 ——
+     * 宿主在 `onVersionLeave` 里把 live 清单写回来之后，下次切回去拿到的才是最新那份。
+     */
+    versionChanges?: Record<string, InlineChange[]>;
+    /**
+     * 版本变了（用户在顶栏选了另一个，或 AI 的这一批指名了另一个版本）。
+     * 宿主据此更新 `activeVersionId` —— 包不自己改，单一数据源仍在宿主手里。
+     */
+    onVersionChange?: (id: string) => void;
+    /**
+     * **离开某个版本前**把它的 live 清单交还宿主。⚠️ 不接这个回调 = 用户在这个版本上
+     * 做的改动会在切走时被撤光且再也拿不回来（包不留副本）。
+     */
+    onVersionLeave?: (id: string, records: ChangeRecord[]) => void;
+    /**
+     * 进入某个版本、改动回放完之后的**别名表**（旧 changeId → 本次新铸的 id）。
+     *
+     * 为什么必须有这个出口：回放每次都铸新 changeId（撤销闭包活在 agent 侧、随 iframe
+     * 重建而丢，见 `hydrate` 的注释），而 AI 卡片上记的是**旧** id。宿主拿这张表维护
+     * `resolveChangeId`，否则切走再切回来之后，卡片上的「撤销这一批」会一条都找不到。
+     */
+    onVersionEnter?: (id: string, idMap: Map<string, string>) => void;
+    /**
+     * 卡片上的旧 changeId → 当前会话里的新 id（宿主用 `onVersionEnter` 的 `idMap` 维护）。
+     * 不传 = 不做映射（单版本入口本来就不需要）。
+     */
+    resolveChangeId?: (id: string) => string;
+    /**
+     * `CHANGE_IMAGE` 的 origin 白名单（图片上传域等）。客户页自身的 origin 由包自动加上。
+     *
+     * 不传 = 只允许换成与客户页同源的图。**这是有意的 fail closed**：模型凭记忆敲出来的
+     * 域名会被每一个真实访客加载，等于我们替客户往他页面上挂了个第三方请求。
+     */
+    allowedImageOrigins?: string[];
+    /**
+     * 本会话在这个页面上读到过的图片地址（宿主从发给 agent 的 `anchor-image:` / `element-image:`
+     * 行与 html 里的 `<img src>` 攒）。origin 白名单之外的第二条放行路，整串相等才算 ——
+     * 换图、整块重写、插入模块三处共用（见 `kernel/ai/imageSource.ts`）。不传 = 这一路不放行。
+     */
+    allowedImageUrls?: string[];
+    /**
+     * `SET_LINK` 允许的**站外**地址 —— 用户在对话里逐字给过的那些（宿主从会话里攒）。
+     * 同源地址不需要进这张表。整串逐字相等，不是 origin 相等。
+     */
+    allowedLinkUrls?: string[];
+    chrome?: ChromeVariant;
+    onExit: () => void;
+    onSave?: (editor: UseInlineEditorResult) => void;
+    /**
+     * 打开**已有实验**时要回显的改动（明文形态；存库的数值 tagData 由宿主经
+     * `fromWireFormat` 转过来）。画布就绪后逐条回放，清单也一并填好。
+     *
+     * 不传 = 空白新建。
+     */
+    initialChanges?: InlineChange[];
+    /**
+     * 回显结果。**有失败项时宿主必须告诉用户** —— 客户页会改版，selector 不再命中是
+     * 常态；失败的条目仍留在清单里（不丢用户的数据），但页面上看不见它们的效果，
+     * 不说明的话用户会以为编辑器坏了。
+     */
+    onHydrated?: (outcome: HydrateOutcome) => void;
+    /**
+     * 「问 AI」入口。**不传则工具条上不出现这个按钮** —— 包不知道产品里有没有 AI 面板，
+     * 渲染出来点了没反应比没有更让人困惑。
+     *
+     * 上下文里**不含截图**。第二个参数是绑定到该元素的**延迟**截图函数，宿主在用户真的
+     * 发送时才调它 —— 点按钮那刻就拍的话，用户如果接着又改了这个元素，图就对不上了。
+     *
+     * `capture()` 内部串起「抓图 → 宿主 uploadImage → URL」。返回 `null` 的三种情况：
+     * 宿主没注入 uploadImage、画布会话已失效（编辑器被关掉）、抓图或上传失败。
+     * **调用方不该因为它返回 null 就阻断发送** —— 一次网络抖动不该让用户发不出消息。
+     */
+    onAskAi?: (ctx: ElementAiContext, capture: () => Promise<string | null>) => void;
+    /**
+     * **整页**上下文（以 `body` 为根）—— 给「AI 自己挑改哪儿」的首版生成用，
+     * 与 `onAskAi` 的元素级上下文是两件事：那份是用户已经选好了一个元素。
+     *
+     * `domReady` 且图层树拉到之后算一次。**只在传了这个 prop 时才算** ——
+     * 它要多一次跨域往返（整页 DOM 树 + body 的 outerHTML），没人用的话是纯浪费。
+     *
+     * ⚠️ **不改选中态**：这一步是背景采集，用户可能正看着自己刚点中的元素。
+     * `capture()` 与元素级同一支（对 body 就是整屏），失败回 `null`，别因此阻断发送。
+     *
+     * `captureAnchors()`（有 resolved 锚点时才给）：每个锚点区块一张裁切截图。整页图告诉 agent
+     * 区块在哪，裁切图才看得清区块内文字的颜色、字重、按钮圆角 —— 首版要"融进去"的东西。
+     * 同样在发送那一刻才拍，失败的那块就少一张，不阻断。
+     */
+    onPageContextReady?: (ctx: ElementAiContext, capture: () => Promise<string | null>, captureAnchors?: () => Promise<AnchorShot[]>) => void;
+    /**
+     * **方案锚点** —— 这条实验诞生时那份方案点名的页面区块（`InlinePlan.anchors`）。
+     *
+     * 存在的理由：假设是「B2 首屏的徽章」这么写的，而包交给 agent 的整页货架是一张扁平的
+     * selector 表，上面没有区块身份 —— agent 只能按关键词猜，猜错了也没有任何一道闸会拦
+     * （真机 trace：首屏那条被静默重锚到了页底另一个提到同样关键词的段落上）。
+     *
+     * 传了之后包会在**活页面上重新解析**它们（selector 优先，失效按 `label` 找回来），
+     * 把命中的锚点连同**它们的子树**排在整页货架最前 —— 于是 agent 既知道该改哪个容器，
+     * 也真的能改到容器里的孩子（货架是授权清单，不在货架里的 selector 一律 `OUT_OF_SCOPE`）。
+     *
+     * ⚠️ 只在 `onPageContextReady` 那条路上生效，且**每个会话读一次**（与整页货架同一次采集）。
+     * 不传 = 与今天完全一致。
+     */
+    anchors?: InlinePlanAnchor[];
+    /**
+     * 编辑器可用了（画布就绪、命令能发了）——**每个会话交一次**把手。
+     *
+     * 换会话（切设备 / 重载）会再交一次：新会话里那些命令要带新的 sessionId，
+     * 宿主留着上一次那份也不会报错，只是发出去的命令没人应答。
+     */
+    onEditorReady?: (handle: InlineEditorHandle) => void;
+    /**
+     * 画布会话就绪 → 交出 sessionId。**每个会话一次**，时机与 `onEditorReady` 相同
+     * （agent 报了 domReady）：这是 frame 命令（`resolveHeatmapSelector` 等）保证有人
+     * 应答的最早时刻 —— 早于它发命令会 `FRAME_NOT_READY`。切设备 / 重载开新会话时再交一次。
+     *
+     * 宿主要它是为了调 `resolveBlocks(sessionId, …)`（`useInlineEditor()` 的内部状态不外露，
+     * 此前只能从 iframe 的 `name` 里反解 —— 那是 hack）。
+     */
+    onSessionReady?: (sessionId: string) => void;
+    /**
+     * 按设备覆盖目标视口宽（只对**这一个实例**生效，合在 `TARGET_VIEWPORT_WIDTH` 之上）。
+     *
+     * 分析画布用：热图区块的 `yStart/yEnd` 是按 375 宽（mobile）量的，画布默认 390 ——
+     * 差 15px 足以让响应式断点换一套布局，区块框与页面对不上。
+     */
+    viewportWidthOverride?: Partial<Record<CanvasDevice, number>>;
+    /**
+     * 分析画布的区块框层（`resolveBlocks` 的产出）。传了就画在画布之上，随几何帧走；
+     * `activeId` 那块高亮；`onHover` 报芯片的悬浮（宿主据此高亮聊天里对应的段）。
+     * 不传 = 没有这一层（普通编辑器）。
+     */
+    blockOverlay?: {
+        blocks: PageModelBlock[];
+        activeId?: string | null;
+        onHover?: (id: string | null) => void;
+    };
+    /**
+     * 选中变化 → 新的 AI 上下文。`null` = 选中被清空。
+     *
+     * **只在 `trackAiSelection` 为真时触发**，因为算一次上下文要多一次跨域往返
+     * （取 outerHTML）—— AI 面板没开着的时候那次往返是纯浪费。
+     *
+     * 与 `onAskAi` 的分工：这个只**更新**上下文，宿主不该顺手把面板打开；
+     * `onAskAi` 是用户点了 ✨，那时才开面板。
+     */
+    onAiContextChange?: (ctx: ElementAiContext | null, capture: () => Promise<string | null>) => void;
+    /**
+     * 把「应用 AI 改动」的入口交给宿主。`null` = 画布会话不可用（此时不该也无法应用）。
+     *
+     * 为什么是回调而不是宿主直接调：AI 面板在**另一棵组件树**里（dock 挂在 AppShell 上），
+     * 拿不到编辑器内部的 change list —— 与 `capture` 同一套分工，宿主把它存进 store。
+     *
+     * ⚠️ 这个 apply **自带作用域**：只允许改「注册这一刻选中的那个元素」。宿主不需要、
+     * 也不应该自己传 selector 进来 —— agent 编的 selector 正是这道闸要拦的东西。
+     */
+    onAiApplyReady?: (api: AiApplyApi | null) => void;
+    /**
+     * 用户撤销（单条 / 整批 / 换版本）拿掉了 AI 插入的元素 → 回报它们的 selector。宿主据此把这些行
+     * 从 AI 的货架 / 授权票里删掉；包自己同时把它们从作用域里剔除。没有插入类时不调用。
+     */
+    onAiInsertedRemoved?: (selectors: string[]) => void;
+    /** 回放把 AI 插入的元素放回画布（切版本 / 切设备）→ 回报它们的 selector；宿主把它们并回货架。 */
+    onAiInsertedRestored?: (selectors: string[]) => void;
+    /**
+     * 是否跟着选中实时刷新 AI 上下文。宿主在**右侧 AI 面板已打开**时给 true。
+     *
+     * 面板关着还刷的话，每点一个元素都白花一次往返；而面板开着不刷的话，用户以为
+     * 自己换了选中、AI 却还在聊上一个元素 —— 这种错位不会有任何提示。
+     */
+    trackAiSelection?: boolean;
+    /**
+     * 组件库数据。宿主注入（包里不碰后端）—— **不传则左侧不出现「组件」页签**，
+     * 而不是出现一个空页签让用户以为库是空的。Task 6 填充。
+     */
+    libraryComponents?: LibraryComponent[];
+    libraryLoading?: boolean;
+    /**
+     * 新增版本。**不传则顶栏不渲染那个入口** —— 版本是 experience 级状态
+     * （每个版本一份 change list），不归编辑器管。
+     */
+    onAddVersion?: () => void;
+    /**
+     * 版本改名。**不传则下拉行里没有铅笔**（同 `onAddVersion`）。包只做交互与校验，
+     * 名字是 experience 级状态（保存时作为 `summary` 落库），改不改得成由宿主说了算。
+     */
+    onRenameVersion?: (id: string, name: string) => void;
+    /**
+     * 真实页面预览。**不传则顶栏不渲染那个入口** —— 预览链接由后端按 experience + 版本
+     * 签发（同详情页的「真实页面预览」），包里没有 experience 的概念，也不知道
+     * uid / sid，所以整件事归宿主。创建流程里 experience 还没落库，就别渲染。
+     */
+    onPreview?: () => void;
+    /**
+     * 开/关宿主的右侧 AI 面板。**不传则顶栏不渲染那个按钮** —— 同 `onPreview` 的处理。
+     *
+     * 包里没有 AI 面板，它是宿主布局的一部分（apps/x 的 `layout` store `aiVisible`）。
+     * apps/x 的宿主（`InlineEditorHost`，详情页与创建空白体验共用）接了；宿主没有 dock 可召唤时就别接。
+     *
+     * ⚠️ 纯开关：宿主实现里**不要**顺手切 agent 或开新会话（那是 `onAskAi` 的语义）。
+     */
+    onToggleAi?: () => void;
+    /** 宿主的右侧 AI 面板当前开着 —— 顶栏按钮据此高亮。 */
+    aiOpen?: boolean;
+    /**
+     * 把截图字节换成一条 URL。
+     *
+     * **包里不碰后端端点** —— 包不知道 `VITE_BACKEND_URL`、不知道 `sid`，那些是宿主的事
+     * （与 README 的两层 API 分工一致）。不传则只在界面上显示截图结果，不上传。
+     */
+    uploadImage?: (blob: Blob) => Promise<string>;
+    /**
+     * 图层树行首图标渲染器。**不传则树里不出图标**（不是出个占位方块）。
+     *
+     * 为什么由宿主给：lucide 字形表是「三代编辑器共用的唯一真值表」，住在
+     * `apps/x/src/components/landing-pages/editor/icons/` —— 包不能反向依赖 app。
+     * 包只交出事实（标签名 + 有没有子节点），挑哪个字形是宿主的事。
+     */
+    renderNodeIcon?: AdaptDomTreeOptions['renderIcon'];
+}
+/**
+ * 交给宿主的编辑器把手 —— **每个画布会话交一次**（`onEditorReady`）。
+ *
+ * 为什么不是「把 `useInlineEditor()` 的结果整个交出去」：那是内核的全部内部状态，
+ * 交出去等于把包的实现细节变成契约。这里只开三件宿主真的做不到的事。
+ */
+export interface InlineEditorHandle {
+    /**
+     * 清空选中（等价于 `commands.select('')`）。
+     *
+     * 宿主要它是为了**回到整页作用域**：有选中时 AI 的 apply 闸只认那一个元素与它的货架，
+     * 而首版生成（AI 自己挑改哪儿）必须在没有选中的状态下跑 —— 用户点过一个元素之后，
+     * 只有宿主知道「现在要换成整页那档了」。
+     */
+    clearSelection: () => Promise<void>;
+    /**
+     * **同步**读当前改动清单（不是渲染期那份 state）。
+     *
+     * 宿主保存时要的就是这一刻的清单；读渲染期那份会漏掉刚写进去、还没重渲染的那条。
+     */
+    peekList: () => ChangeRecord[];
+    /** 有没有未保存的改动 —— 离开确认、保存按钮的禁用态用它。 */
+    hasUnsavedChanges: () => boolean;
+    /**
+     * 整页截图 → PNG Blob（分析画布：标注区块后切瓦片给模型）。
+     *
+     * = `captureSelectedElement('body')`：走现成的编排（先滚动测量 → 藏 fixed/sticky 与
+     * 产品页浮层 → 分屏抓 → 恢复），**不另写一套**。fixed/sticky 由既有的 `setFixedHidden`
+     * 全部藏掉 —— 吸顶导航在长图里重复三四次比少一条导航更误导模型。
+     */
+    capturePage: () => Promise<Blob>;
+    /**
+     * 「定位」：把 selector 指向的元素滚进视野（= `commands.reveal`）。
+     * 分析画布点聊天里的某块 → 画布滚到那块。未命中不抛（agent 回 found:false）。
+     */
+    scrollToSelector: (selector: string) => Promise<void>;
+    /**
+     * 当前**就绪**的画布会话 id；`null` = 画布还没起来（含切设备后新 frame 尚未报 domReady
+     * 的窗口 —— 此刻发 frame 命令没人应答，所以不给旧 id）。
+     */
+    getSessionId: () => string | null;
+    /** 画布当前施加在 `<html>` 上的缩放比例（移动端超宽缩小；不缩为 1）。语义同 `PagePreviewHandle`。 */
+    getMobileFitScale: () => number;
+}
+/** 宿主拿到的 AI 改动入口。 */
+export interface AiApplyApi {
+    /**
+     * 应用一批改动。
+     *
+     * `opts.versionId` 指名了另一个版本时**先切过去再应用**（切换与应用共用同一个串行
+     * 队列，所以 agent 连着给两个版本的两批不会交错）。切换失败则整批 reject，
+     * reason `VERSION_SWITCH_FAILED`，并停留在当前版本 —— 半批落在错版本上比不落更糟。
+     *
+     * 返回里的 `versionId` 是这一批**实际落在**哪个版本上，宿主拿它给卡片记账。
+     *
+     * `opts.grant` 是**发这条消息时交给 agent 的那份作用域**（见 `AiScopeGrant`）：一轮要
+     * 60-120 秒，中途选中丢了的话包这边的实时作用域已经不是当时那个了。宿主自己记得当时
+     * 给出去的是什么，所以由它交回来 —— 与实时作用域取并集，不传则行为与今天逐字一致。
+     */
+    apply: (changes: AiWireChange[], opts?: {
+        versionId?: string;
+        grant?: AiScopeGrant;
+    }) => Promise<AiApplyOutcome & {
+        versionId: string;
+    }>;
+    /**
+     * 撤销**指定的**几条（卡片上的「撤销这一批」）。
+     *
+     * ⚠️ 不能用 `revertAll` —— 那会把用户自己手改的一起撤掉。
+     * ⚠️ **倒序撤**：后面的 change 可能作用在前面那条造出来的现场上，顺序撤会让它基于
+     * 已被撤掉的状态还原（与 `revertAll` 同一个理由）。
+     *
+     * 先经 `resolveChangeId` 映射（切过版本之后 id 都换过了）；映射完仍不在当前清单里，
+     * 说明这一批属于另一个版本 —— 返回 `VERSION_NOT_ACTIVE` 而不是硬撤：那些 id 在
+     * agent 侧早就没有闭包了，硬撤是静默的 no-op，用户只会看到「点了没反应」。
+     */
+    revert: (changeIds: string[]) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'VERSION_NOT_ACTIVE' | 'EDITOR_CLOSED';
+    }>;
+    /** 当前版本 —— 宿主把 agent 给的版本**名**映射成 id 时要知道现在在哪一版。 */
+    readonly activeVersionId?: string;
+}
+export declare function InlineEditor({ url, device, onDeviceChange, title, versionLabel, chrome, onExit, onSave, libraryComponents, libraryLoading, onAddVersion, onRenameVersion, onPreview, onToggleAi, aiOpen, uploadImage, initialChanges, onHydrated, onAskAi, onPageContextReady, anchors, onEditorReady, onSessionReady, onAiContextChange, onAiApplyReady, onAiInsertedRemoved, onAiInsertedRestored, trackAiSelection, renderNodeIcon, versions, activeVersionId, versionChanges, onVersionChange, onVersionLeave, onVersionEnter, resolveChangeId, allowedImageOrigins, allowedImageUrls, allowedLinkUrls, viewportWidthOverride, blockOverlay }: InlineEditorProps): import("react").JSX.Element;