@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/dialogs/imageEdit.d.ts

@@ -0,0 +1,49 @@
+import type { ElementCapabilities } from '@ptengine/inline-core/protocol';
+/**
+ * 「替换图片」的分支判定 —— 移植现役 `ImageEditDialog.vue:93-130`。
+ *
+ * ⚠️ **同一个按钮，按元素类型产出三种完全不同的 change**：
+ *
+ * | 元素 | change | 说明 |
+ * |---|---|---|
+ * | `<img>` | `changeElementAttribute`(55) `src` | 顺带清 `srcset`（应用侧已自动做，见 applyChange） |
+ * | 有 computed 背景图 | `elementStyle`(53) `background-image` | 现役先 `undoStyle` 再 `changeStyle` |
+ * | 其它（可插入位置） | `elementContent`(54) 插一个新 `<img>` | 包一层带防撞号的 div |
+ *
+ * 判错的后果不是报错，是「点了替换图片、图没变」：比如对一个背景图 div 产出
+ * `changeElementAttribute src`，属性确实被设上了，但 div 根本不吃 src。
+ */
+export type ImageEditBranch = 'img-src' | 'background' | 'insert';
+/**
+ * ⚠️ 优先级：**先判 `<img>`，再判背景图**。
+ * 一个 `<img>` 完全可能同时带背景图（CSS 给它加了占位背景），这时用户要换的是 src，
+ * 不是背景。反过来判会让换图作用在看不见的背景层上。
+ */
+export declare function resolveImageBranch(caps: ElementCapabilities): ImageEditBranch;
+/** `background-image` 的值。现役是把旧 url 替换掉，这里直接产出完整值。 */
+export declare function backgroundImageValue(url: string): string;
+/**
+ * 插入新 `<img>` 时的 HTML —— 移植 `common.util.js:326-333` 的 `createPtElementDom`。
+ *
+ * ⚠️ 三件必须照做的事：
+ * 1. 外面包一层 `div`，`id` 是 `pt-element-` + **8 位**随机十六进制。
+ *    这个 id 会被选择器生成优先当锚点用（`#id`），复制粘贴时必须重新生成防撞号，
+ *    否则页面上出现两个同 id 元素 → identifier 不再唯一 → 第二份的所有后续 change
+ *    全部错打到第一份上。
+ * 2. `pt-element-name` 打大写 tagName —— `metadata.service.js:530` 靠它判定元素能力。
+ * 3. `mode` 为 insert/append（内部开头/结尾）时加 `display:inline-block`，
+ *    否则块级 div 会把行内布局撑坏。
+ */
+export declare function buildInsertImageHtml(url: string, mode: 'insert' | 'append' | 'before' | 'after', randomId: () => string): string;
+/** 8 位十六进制（与 `uuid_8bit()` 同形态）。 */
+export declare function randomPtElementId(): string;
+/**
+ * 复制粘贴时重写 HTML 里的防撞号 —— 移植 `common.util.js:340-349`
+ * 的 `updatePtCopyElementId`。
+ *
+ * ⚠️ 现役有一个**副作用**：它用无 `g` 标志的正则逐个替换，同一个 id 在 HTML 里出现
+ * N 次时会被换成 N 个**互不相同**的新 id，原有引用关系会断。
+ * **未确证**那是有意还是 bug。这里改成「同一个旧 id 映射到同一个新 id」——
+ * 保持引用关系，且不影响防撞这个目的本身。
+ */
+export declare function rewritePtElementIds(html: string, randomId?: () => string): string;

package/dist/dialogs/imageEdit.js

@@ -0,0 +1,30 @@
+export function resolveImageBranch(caps) {
+    if (caps.isImg)
+        return 'img-src';
+    if (caps.hasBackgroundImage)
+        return 'background';
+    return 'insert';
+}
+export function backgroundImageValue(url) {
+    return `url("${url}")`;
+}
+export function buildInsertImageHtml(url, mode, randomId) {
+    const inlineBlock = mode === 'insert' || mode === 'append' ? ' style="display:inline-block"' : '';
+    const img = `<img src="${url}" data-user-url="${url}">`;
+    return `<div id="pt-element-${randomId()}" pt-element-name="IMG"${inlineBlock}>${img}</div>`;
+}
+export function randomPtElementId() {
+    let out = '';
+    for (let i = 0; i < 8; i++) {
+        out += Math.floor(Math.random() * 16).toString(16);
+    }
+    return out;
+}
+export function rewritePtElementIds(html, randomId = randomPtElementId) {
+    const seen = new Map();
+    return html.replace(/pt-element-([A-Za-z0-9_]{8})/g, (_m, old) => {
+        if (!seen.has(old))
+            seen.set(old, randomId());
+        return `pt-element-${seen.get(old)}`;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 内联编辑器 —— 公开出口。
+ *
+ * **两层 API，按宿主的外壳需求选**：
+ * - `useInlineEditor()` —— headless。宿主完全自定义 UI（AI 对话那种极简壳走这条）。
+ * - `<EditorChrome>` + 各面板/弹框 —— 默认外壳与成品部件，按需拼装。
+ *
+ * ⚠️ 画布内核（会话/几何/选中/change list）目前物理位置仍在
+ * `./kernel/*`，这里统一再导出一次，
+ * 让消费方**只认这一个入口**。物理搬迁是后续单独一步，搬完这里的路径变、
+ * 对外的 API 不变 —— 这正是留这层再导出的目的。
+ */
+export { InlineEditor } from './InlineEditor.js';
+export type { InlineEditorProps } from './InlineEditor.js';
+/**
+ * 分析阶段的被动预览板（顶栏 + 画布 + 区块框，别的一概不渲染）。
+ * 它就是上面那条主张的样板：**用 headless 层拼一个极简外壳**，而不是给
+ * `<InlineEditor>` 加 `showXxx` 开关。
+ */
+export { PagePreview } from './PagePreview.js';
+export type { PagePreviewProps, PagePreviewHandle } from './PagePreview.js';
+export { useInlineEditor } from './useInlineEditor.js';
+export type { UseInlineEditorInput, UseInlineEditorResult, InlineEditorSelection } from './useInlineEditor.js';
+export { EditorChrome } from './chrome/EditorChrome.js';
+export type { EditorChromeProps, ChromeVariant } from './chrome/EditorChrome.js';
+export { StylePanel } from './panels/StylePanel.js';
+export type { StylePanelProps } from './panels/StylePanel.js';
+export { STYLE_SECTIONS, visibleSections, composeStyleValue } from './panels/styleFields.js';
+export type { StyleSection, StyleField } from './panels/styleFields.js';
+export { HtmlEditDialog } from './dialogs/HtmlEditDialog.js';
+export { validateHtml } from './dialogs/htmlValidation.js';
+export type { HtmlValidationResult } from './dialogs/htmlValidation.js';
+export { inlineEditorLocales, zhCN, enUS, jaJP } from './locales.js';
+export type { InlineEditorLocale } from './locales.js';
+export { useCanvasSession } from './kernel/useCanvasSession.js';
+export { useCanvasStream } from './kernel/useCanvasStream.js';
+export { checkCanvasGate } from './kernel/useCanvasGate.js';
+export type { GateResult } from './kernel/useCanvasGate.js';
+export { useCanvasGeometry } from './kernel/selection/useCanvasGeometry.js';
+export { useSelectionRestore } from './kernel/selection/useSelectionRestore.js';
+export { useChangeList } from './kernel/changelist/useChangeList.js';
+export { deleteElement, editStyle, editHtml, editText, replaceImage, setImageAlt, setClickAction } from './kernel/changelist/useChangeList.js';
+export * as canvasCommands from './kernel/canvasCommands.js';
+export { setPickMode, getDomTree, setCode, getElementCapabilities, getAncestorChain, resolveCanvasSelector, setSelection, setHoverTarget, applyChange, revertChange, getOuterHtml, resolveHeatmapSelector, elementsInBand, measureDocument, setStyleLayer, observeDocumentSize, queryElements, elementsAtPoints, configureCanvas } from './kernel/canvasCommands.js';
+export { capabilitiesFromHandshake, disabledCapabilities, hasCanvasCapability, missingCoreCapabilities, narrowByReady } from './kernel/canvasCapabilities.js';
+export { useMobileFit } from './kernel/useMobileFit.js';
+export type { MobileFitState, UseMobileFitInput, UseMobileFitResult } from './kernel/useMobileFit.js';
+export { MOBILE_FIT_LAYER, RENDER_FIXES_LAYER, planMobileFit, buildRenderFixesCss } from './kernel/mobileFit.js';
+export type { MobileFitPlan, NaturalSize } from './kernel/mobileFit.js';
+export { configureInlineEditor, getInlineEditorConfig, resetInlineEditorConfig } from './kernel/config.js';
+export type { InlineEditorConfig } from './kernel/config.js';
+export { EXTENSION_ID_ATTR, getExtensionId, isExtensionIdConfigured, hasExtensionChannel, sendCanvasCommand, probeExtension } from './kernel/useCanvasBridge.js';
+export type { UseChangeListResult, ChangeRecord, HydrateOutcome } from './kernel/changelist/useChangeList.js';
+export type { ToolbarButtonSpec } from './kernel/selection/toolbarButtons.js';
+export { tagLabelKey, hasTagLabel, tagsWithLabel } from './kernel/selection/tagLabels.js';
+export { buildStyleChange, buildContentChange, buildAttributeChange, buildActionChange, buildMoveChange, buildTextChange, buildScriptChange } from './kernel/changelist/builders.js';
+export { applyOverride, findOverrideIndex } from './kernel/changelist/overrides.js';
+export { CanvasFrame, TARGET_VIEWPORT_WIDTH, computeZoom } from './kernel/CanvasFrame.js';
+export { SelectionOverlay } from './kernel/selection/SelectionOverlay.js';
+export { SelectionToolbar } from './kernel/selection/SelectionToolbar.js';
+export { SelectorPathBar } from './kernel/selection/SelectorPathBar.js';
+export { ChangeListPanel } from './kernel/changelist/ChangeListPanel.js';
+export { TOOLBAR_BUTTONS, visibleButtons, pasteModes } from './kernel/selection/toolbarButtons.js';
+export { frameRectToProductRect } from './kernel/selection/geometry.js';
+export { describeCanvasError } from './kernel/canvasErrors.js';
+/** 落盘：明文 change list → 数值形态。**存库前必经这一步**（见该函数注释）。 */
+export { exportChangesForSave } from './kernel/changelist/exportForSave.js';
+export { buildElementAiContext, truncateHtml, AI_HTML_BUDGET_BYTES, AI_DESCENDANT_LIMIT, SHELF_TREE_MAX_DEPTH, SHELF_TREE_MAX_NODES, ROOT_SHELF_LIMIT, composeAnchorHtml, extractPageLinks, linksFragment } from './kernel/selection/elementAiContext.js';
+export type { ElementAiContext, AiDescendant, AiHtmlFragment, AiPageImage, AnchorShot } from './kernel/selection/elementAiContext.js';
+/**
+ * 方案锚点：宿主存下来的「这一版要改哪个区块」，包在活页面上重新解析并预授权它的子树。
+ * 形状与 backend `contracts.ts` 的 `InlinePlanAnchor` 逐字同形。
+ */
+export { resolveInlinePlanAnchors } from './kernel/selection/resolveAnchors.js';
+export type { InlinePlanAnchor, ResolvedAnchor, AnchorShelfResult } from './kernel/selection/resolveAnchors.js';
+export { buildDescendantShelf } from './kernel/selection/buildDescendantShelf.js';
+export { formatShelfRow, imageTag, linkTag, SHELF_TEXT_MAX } from './kernel/selection/shelfRow.js';
+export { linkPath } from './kernel/linkHref.js';
+export { buildRootShelf } from './kernel/selection/buildRootShelf.js';
+export { LayersPanel } from './tree/LayersPanel.js';
+export { adaptDomTree, moveModeFromDropPos } from './tree/domTreeAdapter.js';
+export type { AdaptDomTreeOptions, TreeNodeIconInput } from './tree/domTreeAdapter.js';
+export { exportRecordsForSave } from './kernel/changelist/exportForSave.js';
+export { mergeForSave } from './kernel/changelist/mergeForSave.js';
+export type { MergeOutcome } from './kernel/changelist/mergeForSave.js';
+export { applyAiChanges, AI_SAFE_OPS, AI_INSERT_MODES, AI_MOVE_MODES } from './kernel/ai/aiInlineApply.js';
+export type { AiApplyApi, InlineEditorHandle } from './InlineEditor.js';
+export type { AiApplyOutcome, AiAppliedChange, AiApplyReject, AiRejectReason, AiApplyDeps, AiScopeGrant, AiWireChange } from './kernel/ai/aiInlineApply.js';
+export { evaluateApplyCheck, APPLY_CHECK_SETTLE_MS } from './kernel/ai/postApplyCheck.js';
+export type { ApplyCheck, ApplyCheckFlag, ApplyCheckInserted } from './kernel/ai/postApplyCheck.js';
+export type { AdaptedTree, AdaptedTreeNode } from './tree/domTreeAdapter.js';
+export { AssetsPanel } from './assets/AssetsPanel.js';
+export { componentInsertPayload } from './assets/componentLibrary.js';
+export type { LibraryComponent } from './assets/componentLibrary.js';
+export { resolveBlocks, summarizeTree } from './kernel/blocks/resolveBlocks.js';
+export type { BlockLinks, HeatmapBlockConfig, PageModelBlock, PageModelBlockMember, ResolveBlocksDeps, ResolveBlocksOptions } from './kernel/blocks/resolveBlocks.js';
+export { annotateAndTile, planAnnotateAndTile } from './kernel/blocks/annotateAndTile.js';
+export type { AnnotateBlock, AnnotateOptions, AnnotatePlan, AnnotateResult, AnnotateDeps } from './kernel/blocks/annotateAndTile.js';
+export { BlockOverlay } from './kernel/blocks/BlockOverlay.js';
+export type { BlockOverlayProps } from './kernel/blocks/BlockOverlay.js';
+export { dataUrlToBlob } from './kernel/dataUrlToBlob.js';

package/dist/index.js

@@ -0,0 +1,53 @@
+export { InlineEditor } from './InlineEditor.js';
+export { PagePreview } from './PagePreview.js';
+export { useInlineEditor } from './useInlineEditor.js';
+export { EditorChrome } from './chrome/EditorChrome.js';
+export { StylePanel } from './panels/StylePanel.js';
+export { STYLE_SECTIONS, visibleSections, composeStyleValue } from './panels/styleFields.js';
+export { HtmlEditDialog } from './dialogs/HtmlEditDialog.js';
+export { validateHtml } from './dialogs/htmlValidation.js';
+export { inlineEditorLocales, zhCN, enUS, jaJP } from './locales.js';
+export { useCanvasSession } from './kernel/useCanvasSession.js';
+export { useCanvasStream } from './kernel/useCanvasStream.js';
+export { checkCanvasGate } from './kernel/useCanvasGate.js';
+export { useCanvasGeometry } from './kernel/selection/useCanvasGeometry.js';
+export { useSelectionRestore } from './kernel/selection/useSelectionRestore.js';
+export { useChangeList } from './kernel/changelist/useChangeList.js';
+export { deleteElement, editStyle, editHtml, editText, replaceImage, setImageAlt, setClickAction } from './kernel/changelist/useChangeList.js';
+export * as canvasCommands from './kernel/canvasCommands.js';
+export { setPickMode, getDomTree, setCode, getElementCapabilities, getAncestorChain, resolveCanvasSelector, setSelection, setHoverTarget, applyChange, revertChange, getOuterHtml, resolveHeatmapSelector, elementsInBand, measureDocument, setStyleLayer, observeDocumentSize, queryElements, elementsAtPoints, configureCanvas } from './kernel/canvasCommands.js';
+export { capabilitiesFromHandshake, disabledCapabilities, hasCanvasCapability, missingCoreCapabilities, narrowByReady } from './kernel/canvasCapabilities.js';
+export { useMobileFit } from './kernel/useMobileFit.js';
+export { MOBILE_FIT_LAYER, RENDER_FIXES_LAYER, planMobileFit, buildRenderFixesCss } from './kernel/mobileFit.js';
+export { configureInlineEditor, getInlineEditorConfig, resetInlineEditorConfig } from './kernel/config.js';
+export { EXTENSION_ID_ATTR, getExtensionId, isExtensionIdConfigured, hasExtensionChannel, sendCanvasCommand, probeExtension } from './kernel/useCanvasBridge.js';
+export { tagLabelKey, hasTagLabel, tagsWithLabel } from './kernel/selection/tagLabels.js';
+export { buildStyleChange, buildContentChange, buildAttributeChange, buildActionChange, buildMoveChange, buildTextChange, buildScriptChange } from './kernel/changelist/builders.js';
+export { applyOverride, findOverrideIndex } from './kernel/changelist/overrides.js';
+export { CanvasFrame, TARGET_VIEWPORT_WIDTH, computeZoom } from './kernel/CanvasFrame.js';
+export { SelectionOverlay } from './kernel/selection/SelectionOverlay.js';
+export { SelectionToolbar } from './kernel/selection/SelectionToolbar.js';
+export { SelectorPathBar } from './kernel/selection/SelectorPathBar.js';
+export { ChangeListPanel } from './kernel/changelist/ChangeListPanel.js';
+export { TOOLBAR_BUTTONS, visibleButtons, pasteModes } from './kernel/selection/toolbarButtons.js';
+export { frameRectToProductRect } from './kernel/selection/geometry.js';
+export { describeCanvasError } from './kernel/canvasErrors.js';
+export { exportChangesForSave } from './kernel/changelist/exportForSave.js';
+export { buildElementAiContext, truncateHtml, AI_HTML_BUDGET_BYTES, AI_DESCENDANT_LIMIT, SHELF_TREE_MAX_DEPTH, SHELF_TREE_MAX_NODES, ROOT_SHELF_LIMIT, composeAnchorHtml, extractPageLinks, linksFragment } from './kernel/selection/elementAiContext.js';
+export { resolveInlinePlanAnchors } from './kernel/selection/resolveAnchors.js';
+export { buildDescendantShelf } from './kernel/selection/buildDescendantShelf.js';
+export { formatShelfRow, imageTag, linkTag, SHELF_TEXT_MAX } from './kernel/selection/shelfRow.js';
+export { linkPath } from './kernel/linkHref.js';
+export { buildRootShelf } from './kernel/selection/buildRootShelf.js';
+export { LayersPanel } from './tree/LayersPanel.js';
+export { adaptDomTree, moveModeFromDropPos } from './tree/domTreeAdapter.js';
+export { exportRecordsForSave } from './kernel/changelist/exportForSave.js';
+export { mergeForSave } from './kernel/changelist/mergeForSave.js';
+export { applyAiChanges, AI_SAFE_OPS, AI_INSERT_MODES, AI_MOVE_MODES } from './kernel/ai/aiInlineApply.js';
+export { evaluateApplyCheck, APPLY_CHECK_SETTLE_MS } from './kernel/ai/postApplyCheck.js';
+export { AssetsPanel } from './assets/AssetsPanel.js';
+export { componentInsertPayload } from './assets/componentLibrary.js';
+export { resolveBlocks, summarizeTree } from './kernel/blocks/resolveBlocks.js';
+export { annotateAndTile, planAnnotateAndTile } from './kernel/blocks/annotateAndTile.js';
+export { BlockOverlay } from './kernel/blocks/BlockOverlay.js';
+export { dataUrlToBlob } from './kernel/dataUrlToBlob.js';

package/dist/kernel/CanvasContextBar.d.ts

@@ -0,0 +1,23 @@
+import type { CanvasDevice } from '@ptengine/inline-core/protocol';
+/**
+ * 画布列顶部的上下文条 —— **「我在看哪台设备上的哪一页」**。
+ *
+ * 顶栏收敛成一行时这两样从顶栏搬了下来：它们说的是画布的状态，不是 experience 的动作，
+ * 混在退出/保存/改动清单那一排里读不出归属。放在画布正上方，它们指向的东西就在眼皮底下。
+ *
+ * ## 设备切换是**绝对居中**的
+ *
+ * 与三代落地页编辑器同一条口径（`.editor-toolbar-center`）：脱离 flex 流，永远落在
+ * 这一列的几何正中 —— 也就是画布的中轴。不居中的话它会随 URL 长度左右漂。
+ *
+ * ⚠️ 代价是它**不会把 URL 推开**（绝对定位的东西不参与流）。所以 URL 必须自己设上限：
+ * `max-width: calc(50% - 60px)`，60 ≈ 分段控件半宽 + 一点余量。不设的话长 URL 会从
+ * 设备切换底下穿过去，两段文字叠在一起。
+ */
+export interface CanvasContextBarProps {
+    /** 目标页地址。空串时整条仍然渲染（设备切换要在），只是不显示地址。 */
+    url: string;
+    device: CanvasDevice;
+    onDeviceChange: (device: CanvasDevice) => void;
+}
+export declare function CanvasContextBar({ url, device, onDeviceChange }: CanvasContextBarProps): import("react").JSX.Element;

package/dist/kernel/CanvasContextBar.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
+import { Link2, Monitor, Smartphone } from 'lucide-react';
+import { ChromeSegment, ChromeSegmented } from '../chrome/topbarPrimitives.js';
+export function CanvasContextBar({ url, device, onDeviceChange }) {
+    const { t } = useTranslation();
+    const items = [
+        ['pc', Monitor, t('inlineCanvas.chrome.pc', 'PC')],
+        ['mobile', Smartphone, t('inlineCanvas.chrome.mobile', '移动')]
+    ];
+    return (_jsxs("div", { "data-testid": "canvas-context-bar", className: "relative flex h-9 shrink-0 items-center border-b border-[#EBECF0]\n                bg-white px-3", children: [url && (_jsxs("a", { "data-testid": "canvas-context-url", href: url, target: "_blank", rel: "noopener noreferrer", title: url, className: "flex max-w-[calc(50%-60px)] items-center gap-1.5 truncate text-xs\n                        text-[#8a8f98] hover:text-[#52525b] hover:underline", children: [_jsx(Link2, { className: "size-3.5 shrink-0" }), _jsx("span", { className: "truncate", children: url })] })), _jsx(ChromeSegmented, { "data-testid": "device-switch", className: "absolute left-1/2 -translate-x-1/2", children: items.map(([value, Icon, label]) => (_jsxs(ChromeSegment, { "data-testid": `device-${value}`, active: device === value, onClick: () => onDeviceChange(value), children: [_jsx(Icon, { className: "size-3.5" }), label] }, value))) })] }));
+}

package/dist/kernel/CanvasFrame.d.ts

@@ -0,0 +1,56 @@
+import { type CanvasDevice } from '@ptengine/inline-core/protocol';
+/**
+ * 目标逻辑视口宽的默认表（宿主可按实例覆盖）。
+ *
+ * 客户页按 1440 设计，画布用 `zoom` 缩放去适应面板宽度，而不是把 iframe 做窄 ——
+ * 做窄会触发客户页的响应式断点，看到的就不是 PC 版了。
+ *
+ * ⚠️ **放在这里是为了让所有外壳共用同一份**：`<InlineEditor>` 与 `<PagePreview>`
+ * 都要用它算 `zoom`，而 `zoom` 同时决定「画面怎么缩」与「区块框/选中框怎么换算」。
+ * 各写一份的结果是框与画面错位，且错位量随设备与面板宽变化 —— 看起来像高亮框在飘。
+ */
+export declare const TARGET_VIEWPORT_WIDTH: Record<CanvasDevice, number>;
+/**
+ * zoom = 面板宽 ÷ 目标逻辑视口宽；只缩不放，避免小面板把页面放大。
+ *
+ * 截断（而非四舍五入）到 4 位小数：`toFixed(4)` 会四舍五入，对
+ * 685.08/1063 = 0.64447789... 舍入成 0.6445，与规格值 0.6444 不符。
+ */
+export declare function computeZoom(panelWidth: number, targetViewportWidth: number): number;
+interface Props {
+    url: string;
+    /** 画布会话 id（不是本仓惯用的 `sid`/profile id）—— 与契约 canvasFrameName 的第 2 段一致。 */
+    sessionId: string;
+    device: CanvasDevice;
+    panelWidth: number;
+    targetViewportWidth: number;
+    /**
+     * 把真实 iframe 元素交出去。目前只有一个用途:**页面内改文字前要先让焦点进入
+     * 画布 frame**。agent 在客户页里调 `el.focus()` 只是在那个文档内部选中元素,
+     * 浏览器的活动 frame 仍停在产品页 —— 用户敲的字会打到产品页上,表现是
+     * 「点了编辑文字,什么都没发生」。必须由产品侧 `iframe.focus()` 把焦点送进去。
+     */
+    iframeRef?: React.MutableRefObject<HTMLIFrameElement | null>;
+    /**
+     * 只表示 iframe 的 `load` 事件发生了——**不等于**画布真的加载成功。Chrome 的
+     * XFO/CSP 拦截页本身也会正常触发 `load`（它是一个真实渲染出来的内建错误页），
+     * 所以这里绝不能把它当成「成功」上报给业务。真正的成功信号要等扩展侧的
+     * `ready` 事件打通（下一个任务），本次只用它来解除 visibility:hidden 避免白屏。
+     */
+    onFrameLoad: () => void;
+    /**
+     * agent 的 `domReady`（DOMContentLoaded）是否已到。用来**提前**解除
+     * `visibility: hidden`。
+     *
+     * 为什么需要它：iframe 的原生 `load` 要等**全部子资源**（图片、字体、嵌套
+     * iframe、广告位）都加载完，真实落地页往往好几秒；在那之前画布区是空白的，
+     * 而 DOM 其实早就解析完、可以看也可以编辑了。有了扩展侧的生命周期上报之后
+     * 就不必再等 `load`。
+     *
+     * 取「两者谁先到」而不是只看 `domReady`：没装插件 / 通道不通时不会有任何
+     * 生命周期事件，此时仍要靠原生 `load` 兜底，否则画布永远不可见。
+     */
+    domReady?: boolean;
+}
+export declare function CanvasFrame({ url, sessionId, device, panelWidth, targetViewportWidth, onFrameLoad, domReady, iframeRef }: Props): import("react").JSX.Element;
+export {};

package/dist/kernel/CanvasFrame.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
+import { canvasFrameName } from '@ptengine/inline-core/protocol';
+export const TARGET_VIEWPORT_WIDTH = { pc: 1440, mobile: 390 };
+const SANDBOX = [
+    'allow-scripts',
+    'allow-same-origin',
+    'allow-forms',
+    'allow-popups',
+    'allow-popups-to-escape-sandbox'
+].join(' ');
+export function computeZoom(panelWidth, targetViewportWidth) {
+    if (!panelWidth || !targetViewportWidth)
+        return 1;
+    const raw = panelWidth / targetViewportWidth;
+    const truncated = Math.trunc(raw * 10000) / 10000;
+    return Math.min(1, truncated);
+}
+export function CanvasFrame({ url, sessionId, device, panelWidth, targetViewportWidth, onFrameLoad, domReady = false, iframeRef }) {
+    const ref = useRef(null);
+    const [loaded, setLoaded] = useState(false);
+    const zoom = computeZoom(panelWidth, targetViewportWidth);
+    const revealed = loaded || domReady;
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.setAttribute('style', [
+            `width: ${targetViewportWidth}px`,
+            'max-width: none',
+            'height: 100%',
+            'margin: 0',
+            'border: none',
+            `zoom: ${zoom}`,
+            `visibility: ${revealed ? 'visible' : 'hidden'}`
+        ].join('; '));
+    }, [zoom, revealed, targetViewportWidth]);
+    return (_jsx("div", { style: { width: '100%', height: '100%', display: 'flex', justifyContent: 'center' }, children: _jsx("div", { "data-testid": "canvas-frame-shell", style: {
+                display: 'flex',
+                height: '100%',
+                border: '1px solid #DFE1E6',
+                borderRadius: 6,
+                background: '#fff',
+                overflow: 'hidden'
+            }, children: _jsx("iframe", { ref: node => {
+                    ref.current = node;
+                    if (iframeRef)
+                        iframeRef.current = node;
+                }, title: "Canvas", name: canvasFrameName(sessionId, device, zoom), src: url, sandbox: SANDBOX, onLoad: () => {
+                    setLoaded(true);
+                    onFrameLoad();
+                } }) }) }));
+}