@ptengine/inline-editor 0.0.0-stage → 0.1.1

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('');
+}

package/dist/kernel/moveState.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 「移动元素」的两步拾取状态机。
+ *
+ * 两步：① 记下**源**元素（点工具条那一刻的选中元素）；② 用户在画布里点**目标**元素；
+ * ③ 选相对位置，产出 `elementMove`。
+ *
+ * ⚠️ **选目标期间绝不能动源选中态。** 画布里的点选平时会刷新选中元素，移动模式下那次
+ * 点选的语义完全不同 —— 不拦的话「源」会在第二步被自己覆盖掉，用户最后把元素移到了
+ * 它自己旁边（或者更糟：agent 报「不能移进自己」，而用户根本不知道源什么时候变的）。
+ *
+ * 抽成纯函数是因为这套时序在组件里测不动：它跨「点工具条 → 收 elementPicked 事件 →
+ * 点位置按钮」三次异步交互。
+ */
+export type MovePosition = 'top' | 'bottom' | 'before' | 'after';
+export interface MoveState {
+    /** 要移动的元素。 */
+    source: string;
+    /** 目标元素；`null` = 还在等用户点选。 */
+    target: string | null;
+    /** 上一次拾取被拒的原因，供界面提示。 */
+    rejected?: 'same-element';
+}
+export declare function startMove(source: string): MoveState;
+/**
+ * 收到一次画布拾取。返回新状态 —— 调用方据此决定「这次点选算选目标，还是算普通选中」。
+ *
+ * 目标 == 源时**拒绝并留在等待态**：把元素移到它自己里面是没有意义的，
+ * 而 agent 侧对这种情况的行为未确证（可能静默无效，也可能抛错）。在这里拦掉最省事。
+ */
+export declare function pickTarget(state: MoveState, selector: string): MoveState;
+/** 移动模式下这次拾取该被「吃掉」吗（吃掉 = 不刷新选中态）。 */
+export declare function shouldCapturePick(state: MoveState | null): boolean;
+export declare function isReady(state: MoveState | null): state is MoveState & {
+    target: string;
+};

package/dist/kernel/moveState.js

@@ -0,0 +1,14 @@
+export function startMove(source) {
+    return { source, target: null };
+}
+export function pickTarget(state, selector) {
+    if (selector === state.source)
+        return { ...state, target: null, rejected: 'same-element' };
+    return { source: state.source, target: selector };
+}
+export function shouldCapturePick(state) {
+    return state !== null && state.target === null;
+}
+export function isReady(state) {
+    return state !== null && state.target !== null;
+}

package/dist/kernel/selection/SelectionOverlay.d.ts

@@ -0,0 +1,10 @@
+import type { CanvasGeometryPayload } from '@ptengine/inline-core/protocol';
+import { type FrameToProductContext } from './geometry.js';
+export interface SelectionOverlayProps {
+    geometry: CanvasGeometryPayload | null;
+    /** iframe 在产品页里的位置与画布缩放 —— 换算所需。 */
+    context: FrameToProductContext;
+    /** 选中元素的类型标签文案（如 `<img>`）。空则不显示标签。 */
+    selectedLabel?: string;
+}
+export declare function SelectionOverlay({ geometry, context, selectedLabel }: SelectionOverlayProps): import("react").JSX.Element | null;

package/dist/kernel/selection/SelectionOverlay.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SELECTION_CLASS } from '../../canvas-ui/index.js';
+import { frameRectToProductRect } from './geometry.js';
+function rectStyle(rect) {
+    return {
+        position: 'fixed',
+        left: `${rect.x}px`,
+        top: `${rect.y}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        boxSizing: 'border-box',
+        zIndex: 2147483000
+    };
+}
+export function SelectionOverlay({ geometry, context, selectedLabel }) {
+    if (!geometry)
+        return null;
+    const selected = geometry.selectedViewportRect
+        ? frameRectToProductRect(geometry.selectedViewportRect, context)
+        : null;
+    const hover = geometry.hoverViewportRect
+        ? frameRectToProductRect(geometry.hoverViewportRect, context)
+        : null;
+    return (_jsxs("div", { style: { pointerEvents: 'none' }, "data-testid": "canvas-overlay-root", children: [hover && (_jsx("div", { "data-testid": "canvas-hover-box", className: SELECTION_CLASS.hoverBox, style: rectStyle(hover) })), selected && (_jsx("div", { "data-testid": "canvas-selected-box", className: SELECTION_CLASS.selectBox, style: rectStyle(selected), children: selectedLabel ? (_jsxs("div", { "data-testid": "canvas-selected-label", className: SELECTION_CLASS.selectLabel, style: { top: selected.y > 22 ? '-20px' : '0px' }, children: [selectedLabel, _jsxs("span", { "data-testid": "canvas-selected-size", className: SELECTION_CLASS.selectSize, children: [Math.round(selected.width), " \u00D7 ", Math.round(selected.height)] })] })) : null }))] }));
+}

package/dist/kernel/selection/SelectionToolbar.d.ts

@@ -0,0 +1,30 @@
+import type { ElementCapabilities, ViewportRect } from '@ptengine/inline-core/protocol';
+import { type ToolbarHostCapabilities } from './toolbarButtons.js';
+export interface ToolbarPosition {
+    left: number;
+    top: number;
+}
+/**
+ * 三段式垂直定位 + 水平钳制。抽成纯函数以便单测（组件里内联的话只能靠快照测样式）。
+ *
+ * @param rect 选中元素在**产品页**坐标系的矩形（已换算过）
+ * @param area 画布可视区在产品页坐标系的矩形 —— 钳制边界
+ * @param width 工具条实际宽度
+ */
+export declare function computeToolbarPosition(rect: ViewportRect, area: ViewportRect, width: number): ToolbarPosition;
+export interface SelectionToolbarProps {
+    /** 选中元素在产品页坐标系的矩形；`null` = 无选中，不渲染。 */
+    selectedRect: ViewportRect | null;
+    /** 画布可视区（产品页坐标系），用于钳制。 */
+    area: ViewportRect;
+    /** `null` = 能力位还没拿到，先不渲染按钮（避免闪一批错误按钮）。 */
+    capabilities: ElementCapabilities | null;
+    /** DEC-15：滚动期间不渲染。 */
+    isScrolling: boolean;
+    onAction: (buttonId: string) => void;
+    /** 量到真实宽度之前用的估算宽度；渲染后一律按实测宽度定位。 */
+    width?: number;
+    /** 宿主注入的能力，决定依赖宿主的按钮出不出现（见 ToolbarHostCapabilities）。 */
+    host?: ToolbarHostCapabilities;
+}
+export declare function SelectionToolbar({ host, selectedRect, area, capabilities, isScrolling, onAction, width }: SelectionToolbarProps): import("react").JSX.Element | null;

package/dist/kernel/selection/SelectionToolbar.js

@@ -0,0 +1,82 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Camera, ClipboardPaste, Code, Copy, ImageIcon, MousePointerClick, Move, Paintbrush, Pencil, Plus, Settings2, Sparkles, Trash2, Video } from 'lucide-react';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@ptengine/design-components';
+import { SELECTION_CLASS } from '../../canvas-ui/index.js';
+import { visibleButtons } from './toolbarButtons.js';
+const TOOLBAR_HEIGHT = 34;
+const GAP = 6;
+const TOOLBAR_ICONS = {
+    image: ImageIcon,
+    video: Video,
+    plus: Plus,
+    setting: Settings2,
+    click: MousePointerClick,
+    move: Move,
+    copy: Copy,
+    paste: ClipboardPaste,
+    text: Pencil,
+    style: Paintbrush,
+    code: Code,
+    camera: Camera,
+    delete: Trash2,
+    sparkles: Sparkles
+};
+const ICON_SIZE = 15;
+const ICON_STROKE_WIDTH = 1.75;
+const TOOLTIP_DELAY = 200;
+export function computeToolbarPosition(rect, area, width) {
+    const spaceAbove = rect.y - area.y;
+    const spaceBelow = area.y + area.height - (rect.y + rect.height);
+    let top;
+    if (spaceAbove >= TOOLBAR_HEIGHT + GAP) {
+        top = rect.y - TOOLBAR_HEIGHT - GAP;
+    }
+    else if (spaceBelow >= TOOLBAR_HEIGHT + GAP) {
+        top = rect.y + rect.height + GAP;
+    }
+    else {
+        top = rect.y + GAP;
+    }
+    let left = rect.x + rect.width - width;
+    const minLeft = area.x;
+    const maxLeft = area.x + area.width - width;
+    if (left > maxLeft)
+        left = maxLeft;
+    if (left < minLeft)
+        left = minLeft;
+    return { left, top };
+}
+export function SelectionToolbar({ host = {}, selectedRect, area, capabilities, isScrolling, onAction, width = 240 }) {
+    const { t } = useTranslation();
+    const barRef = useRef(null);
+    const [measuredWidth, setMeasuredWidth] = useState(null);
+    useLayoutEffect(() => {
+        const measured = barRef.current?.offsetWidth ?? 0;
+        if (measured > 0 && measured !== measuredWidth)
+            setMeasuredWidth(measured);
+    });
+    if (!selectedRect || !capabilities || isScrolling)
+        return null;
+    const buttons = visibleButtons(capabilities, host);
+    if (buttons.length === 0)
+        return null;
+    const { left, top } = computeToolbarPosition(selectedRect, area, measuredWidth ?? width);
+    return (_jsx("div", { ref: barRef, "data-testid": "canvas-selection-toolbar", className: SELECTION_CLASS.toolbar, style: {
+            position: 'fixed',
+            left: `${left}px`,
+            top: `${top}px`,
+            transform: 'none',
+            zIndex: 2147483001
+        }, children: _jsx(TooltipProvider, { delayDuration: TOOLTIP_DELAY, children: buttons.map(button => {
+                const label = t(button.labelKey);
+                const Icon = TOOLBAR_ICONS[button.icon];
+                const isAi = button.id === 'ask-ai';
+                const className = `${SELECTION_CLASS.tool}${button.id === 'delete' ? ` ${SELECTION_CLASS.toolDanger}` : ''}${isAi ? ` ${SELECTION_CLASS.toolAi}` : ''}`;
+                if (isAi) {
+                    return (_jsxs("button", { type: "button", "data-testid": `canvas-toolbar-${button.id}`, className: className, onClick: () => onAction(button.id), children: ["\u2726 ", label] }, button.id));
+                }
+                return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "data-testid": `canvas-toolbar-${button.id}`, "aria-label": label, className: className, onClick: () => onAction(button.id), children: _jsx(Icon, { size: ICON_SIZE, strokeWidth: ICON_STROKE_WIDTH, "aria-hidden": true }) }) }), _jsx(TooltipContent, { className: "z-[2147483003]", children: label })] }, button.id));
+            }) }) }));
+}

package/dist/kernel/selection/SelectorPathBar.d.ts

@@ -0,0 +1,27 @@
+import type { AncestorNode } from '@ptengine/inline-core/protocol';
+/**
+ * 路径选择器（DEC-23）—— **常驻、放大、浮在画布 iframe 之上**的主控件。
+ *
+ * 三条要求逐条对应：
+ * | 要求 | 实现 |
+ * |---|---|
+ * | 常驻放大，不折叠 | 不做 hover 展开（现役默认 `max-width: 0`、hover 300ms 才展开、离开 1500ms 收起） |
+ * | 点节点反选元素 | `onSelect(node.selector)` → 产品页下发 `setSelection` |
+ * | 悬浮节点高亮对应元素 | `onHover(node.selector)` → 下发 `setHoverTarget`；**移出整条时 `onHoverEnd()`** |
+ *
+ * **为什么它是主控件而不是辅助显示**：跨域画布里点击命中的总是最深的可视元素
+ * （`elementFromPoint` 语义），想选中包裹它的容器**只能靠路径**。现役把它折叠起来是
+ * 因为它只是辅助显示；在我们这里它承担导航职责，必须常驻。
+ *
+ * **不截断**：现役只渲染 4 层祖先、`...` 是静态 `<i>` 无 click handler，超 4 层完全
+ * 够不着。链过长时**横向滚动**，不截断 —— 截断就回到「够不着」那个问题。
+ */
+export interface SelectorPathBarProps {
+    /** `[自己, 父, …, body]`，index 0 是自己。 */
+    chain: AncestorNode[];
+    onSelect: (selector: string) => void;
+    onHover: (selector: string) => void;
+    /** ⚠️ 鼠标移出整条时必须调 —— 否则画布里的高亮会**残留**。 */
+    onHoverEnd: () => void;
+}
+export declare function SelectorPathBar({ chain, onSelect, onHover, onHoverEnd }: SelectorPathBarProps): import("react").JSX.Element | null;

package/dist/kernel/selection/SelectorPathBar.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+import { tagLabelKey } from './tagLabels.js';
+export function SelectorPathBar({ chain, onSelect, onHover, onHoverEnd }) {
+    const { t } = useTranslation();
+    const scrollRef = useRef(null);
+    const deepest = chain[0]?.selector;
+    useEffect(() => {
+        const el = scrollRef.current;
+        if (el)
+            el.scrollLeft = el.scrollWidth;
+    }, [deepest]);
+    if (chain.length === 0)
+        return null;
+    const display = chain.slice().reverse();
+    return (_jsx("nav", { ref: scrollRef, "data-testid": "canvas-selector-path", "aria-label": t('inlineCanvas.selectorPath.label', '元素路径'), onMouseLeave: onHoverEnd, style: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: '2px',
+            overflowX: 'auto',
+            whiteSpace: 'nowrap',
+            padding: '6px 10px',
+            fontSize: '13px',
+            lineHeight: '20px',
+            background: 'rgba(9, 30, 66, 0.86)',
+            borderRadius: '4px'
+        }, children: display.map((node, index) => {
+            const key = tagLabelKey(node.tag);
+            const label = key ? `${t(key)} <${node.tag}>` : `<${node.tag}>`;
+            const isLast = index === display.length - 1;
+            return (_jsxs("span", { style: { display: 'inline-flex' }, children: [index > 0 && (_jsx("span", { "aria-hidden": true, style: { color: 'rgba(255,255,255,0.45)', padding: '0 4px' }, children: "\u203A" })), _jsxs("button", { type: "button", disabled: node.isBody, onClick: () => {
+                            if (node.isBody)
+                                return;
+                            onSelect(node.selector);
+                        }, onMouseEnter: () => {
+                            if (node.isBody)
+                                return;
+                            onHover(node.selector);
+                        }, style: {
+                            border: 'none',
+                            background: isLast ? '#00a92e' : 'transparent',
+                            color: node.isBody ? 'rgba(255,255,255,0.4)' : '#fff',
+                            cursor: node.isBody ? 'default' : 'pointer',
+                            padding: '2px 8px',
+                            borderRadius: '3px',
+                            fontSize: '13px',
+                            lineHeight: '20px',
+                            maxWidth: '220px',
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap'
+                        }, title: node.selector, children: [label, node.elementId ? `#${node.elementId}` : ''] })] }, `${node.selector}:${index}`));
+        }) }));
+}

package/dist/kernel/selection/buildDescendantShelf.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `getDomTree({rootSelector})` 的返回 → AI 上下文里的**可编辑后代货架**。
+ *
+ * 为什么用 DOM 树而不是解析 outerHTML：树里的 `selector` 是**内核生成的、可直接回传给
+ * 画布命令**的那一份（带 nth-of-type 消歧）。自己从 HTML 里拼 selector 就是在复制内核的
+ * 逻辑，而两份逻辑一旦漂移，selector 会指到另一个元素上且不报错。
+ */
+import type { DomTreeNode } from '@ptengine/inline-core/protocol';
+import '../linkHref.js';
+import { type AiDescendant } from './elementAiContext.js';
+/**
+ * 广度优先摊平子树，**跳过根**（根就是选中元素本身，它已经在上下文里了）。
+ *
+ * 广度优先而不是深度优先：预算有限时，浅层的元素（区块里的标题、按钮）比深层的
+ * 内联包裹更可能是用户想改的东西。
+ *
+ * **不按层数截**：树有多深走多深（取树那一步用的是扩展的硬上限 + `maxNodes` 总量闸，见
+ * `SHELF_TREE_MAX_DEPTH`）。此前区块货架按 `maxDepth: 4` 取树，而 PageFly 的标题在第 5 层
+ * （Section > div > Row > .pf-c > Column > h1）—— 出方案时 B2 的货架全是容器，模型只能锚到
+ * Column。预算改由「值不值得出行」控制：包装层（`isWrapper`）与 `<br>` 这类噪音不出行，
+ * 但照常遍历、照常记祖先链。
+ */
+export declare function buildDescendantShelf(root: DomTreeNode, limit?: number): AiDescendant[];
+/**
+ * 同一次遍历，**顺带把每一项的祖先链记下来**（由近及远，含根自己）。
+ *
+ * 为什么要这份表：整页作用域（`onPageContextReady` 那条路）里，作用域的「根」是 `body`，
+ * 而 `MOVE_ELEMENT` 的 target 必须是**被移动那个元素**的祖先 —— 不是 body 的祖先
+ * （body 没有）。拿 body 的祖先链去判，整页模式下所有移动都会被判成非法。
+ *
+ * ⚠️ **必须与货架同一次遍历产出**。另写一个函数再走一遍树的话，两边的截断口径
+ * （`limit`、BFS 顺序）一旦漂移，就会出现「货架里有这一项、祖先表里没有」——
+ * 表现是同一个 selector 有时能移、有时不能，且没有任何报错。
+ *
+ * 祖先链只覆盖**货架里的项**：作用域本来就只认货架，不在货架里的 selector 走不到这一步。
+ */
+export declare function buildDescendantShelfWithPaths(root: DomTreeNode, limit?: number): {
+    shelf: AiDescendant[];
+    ancestorsOf: Map<string, string[]>;
+};

package/dist/kernel/selection/buildDescendantShelf.js

@@ -0,0 +1,50 @@
+import '../linkHref.js';
+import { AI_DESCENDANT_LIMIT, AI_DESCENDANT_TEXT_CHARS } from './elementAiContext.js';
+const NOISE_TAGS = new Set(['br', 'wbr', 'hr', 'script', 'style', 'noscript', 'template', 'link', 'meta']);
+const INTERACTIVE_TAGS = new Set(['a', 'button', 'input', 'select', 'textarea', 'label', 'summary', 'details', 'form']);
+function hasChildrenOf(node) {
+    return node.childCount > 0 || node.children.length > 0;
+}
+function isWrapper(node) {
+    if (node.children.length !== 1 || node.childCount > 1)
+        return false;
+    if (node.image)
+        return false;
+    if (node.href)
+        return false;
+    if (INTERACTIVE_TAGS.has(node.tag.toLowerCase()))
+        return false;
+    const child = node.children[0];
+    return node.textSummary.trim() === child.textSummary.trim();
+}
+export function buildDescendantShelf(root, limit = AI_DESCENDANT_LIMIT) {
+    return buildDescendantShelfWithPaths(root, limit).shelf;
+}
+export function buildDescendantShelfWithPaths(root, limit = AI_DESCENDANT_LIMIT) {
+    const shelf = [];
+    const ancestorsOf = new Map();
+    const queue = root.children.map(node => ({ node, ancestors: [root.selector], depth: 0 }));
+    while (queue.length && shelf.length < limit) {
+        const { node, ancestors, depth } = queue.shift();
+        if (NOISE_TAGS.has(node.tag.toLowerCase()))
+            continue;
+        const childAncestors = [node.selector, ...ancestors];
+        if (isWrapper(node)) {
+            queue.push({ node: node.children[0], ancestors: childAncestors, depth });
+            continue;
+        }
+        const text = node.textSummary.trim().slice(0, AI_DESCENDANT_TEXT_CHARS);
+        shelf.push({
+            selector: node.selector,
+            tag: node.tag,
+            text,
+            hasChildren: hasChildrenOf(node),
+            ...(node.image ? { image: node.image } : {}),
+            ...(node.href ? { href: node.href } : {}),
+            ...(depth > 0 ? { depth } : {})
+        });
+        ancestorsOf.set(node.selector, ancestors);
+        queue.push(...node.children.map(child => ({ node: child, ancestors: childAncestors, depth: depth + 1 })));
+    }
+    return { shelf, ancestorsOf };
+}

package/dist/kernel/selection/buildRootShelf.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 整页（以 body 为根）的 AI 货架：**区块优先**。
+ *
+ * 朴素 BFS（`buildDescendantShelfWithPaths`）在真实站点上的病：header 25 个菜单项、几个
+ * 隐藏抽屉各带几十个子节点、footer 30 条链接——60 个槽位在到达 `main > div > div > section`
+ * 之前就被吃光，AI 手上的货架里根本没有要改的那个区块，只能回「请你点选」。
+ *
+ * 这里改成按**几何**挑区块：新 agent 的树带 `rect`（文档坐标）/ `hidden` / `heading`
+ * （`getDomTree` 的 `includeRect` / `visibleOnly`），于是能先找出「够高、够宽」的可见区块，
+ * 每块给 1 行容器 + 最多几行可改点，header/nav/footer 各封顶，隐藏节点一律不给。
+ *
+ * **兼容**：树上一个 `rect` 都没有 = 老 agent，整个函数退化成老算法，逐项一致。
+ *
+ * ⚠️ `ancestorsOf` 与货架**由同一个 `emit` 产出**：货架里每一项都在表里、表里也只有货架
+ * 里的项。MOVE 闸靠这张表判 target 是不是被移元素的祖先，两边一旦漂移就是「同一个
+ * selector 有时能移有时不能，且不报错」（见 buildDescendantShelf 头部说明）。
+ */
+import type { DomTreeNode } from '@ptengine/inline-core/protocol';
+import { type AiDescendant } from './elementAiContext.js';
+export declare function buildRootShelf(root: DomTreeNode, opts: {
+    limit: number;
+    viewportWidth?: number;
+}): {
+    shelf: AiDescendant[];
+    ancestorsOf: Map<string, string[]>;
+};

package/dist/kernel/selection/buildRootShelf.js

@@ -0,0 +1,149 @@
+import { buildDescendantShelfWithPaths } from './buildDescendantShelf.js';
+import { AI_DESCENDANT_TEXT_CHARS } from './elementAiContext.js';
+const LANDMARK_MIN_HEIGHT = 120;
+const LANDMARK_MIN_WIDTH_RATIO = 0.5;
+const DEFAULT_VIEWPORT_WIDTH = 375;
+const LEAVES_PER_LANDMARK = 6;
+const CHROME_ROWS_CAP = 5;
+const PREFERRED_LANDMARK_TAGS = new Set(['main', 'section', 'article']);
+const CHROME_TAGS = new Set(['header', 'nav', 'footer']);
+const TEXT_LEAF_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'a', 'button', 'span']);
+export function buildRootShelf(root, opts) {
+    const { limit } = opts;
+    const viewportWidth = typeof opts.viewportWidth === 'number' && opts.viewportWidth > 0
+        ? opts.viewportWidth
+        : DEFAULT_VIEWPORT_WIDTH;
+    const minWidth = viewportWidth * LANDMARK_MIN_WIDTH_RATIO;
+    const entries = [];
+    const entryOf = new Map();
+    let sawRect = root.rect !== undefined;
+    const isLandmarkNode = (n) => n.rect !== undefined && n.rect.height >= LANDMARK_MIN_HEIGHT && n.rect.width >= minWidth;
+    const visit = (n, ancestors, chromeKey, nearestLandmark) => {
+        for (const child of n.children) {
+            if (child.hidden)
+                continue;
+            if (child.rect)
+                sawRect = true;
+            const ownChrome = CHROME_TAGS.has(child.tag) ? child.selector : chromeKey;
+            const entry = {
+                node: child,
+                ancestors,
+                order: entries.length,
+                chromeKey: ownChrome,
+                nearestLandmark,
+                isLandmark: isLandmarkNode(child)
+            };
+            entries.push(entry);
+            entryOf.set(child, entry);
+            visit(child, [child.selector, ...ancestors], ownChrome, entry.isLandmark ? entry : nearestLandmark);
+        }
+    };
+    visit(root, [root.selector], null, null);
+    if (!sawRect)
+        return buildDescendantShelfWithPaths(root, limit);
+    const beaten = new Set();
+    const absorbed = new Set();
+    for (const e of entries) {
+        if (!e.isLandmark || !e.nearestLandmark)
+            continue;
+        const outer = e.nearestLandmark;
+        const wins = !!e.node.heading ||
+            (PREFERRED_LANDMARK_TAGS.has(e.node.tag) && !PREFERRED_LANDMARK_TAGS.has(outer.node.tag));
+        if (wins)
+            beaten.add(outer);
+        else
+            absorbed.add(e);
+    }
+    const surviving = new Set();
+    for (const e of entries) {
+        if (!e.isLandmark || beaten.has(e))
+            continue;
+        if (absorbed.has(e)) {
+            let a = e.nearestLandmark;
+            let hasSurvivingAncestor = false;
+            while (a) {
+                if (surviving.has(a)) {
+                    hasSurvivingAncestor = true;
+                    break;
+                }
+                a = a.nearestLandmark;
+            }
+            if (hasSurvivingAncestor)
+                continue;
+        }
+        surviving.add(e);
+    }
+    const landmarks = [...surviving].sort((a, b) => {
+        const dt = a.node.rect.top - b.node.rect.top;
+        return dt !== 0 ? dt : a.order - b.order;
+    });
+    const shelf = [];
+    const ancestorsOf = new Map();
+    const emittedSelectors = new Set();
+    const chromeRows = new Map();
+    const emit = (e) => {
+        if (shelf.length >= limit)
+            return false;
+        if (emittedSelectors.has(e.node.selector))
+            return false;
+        if (e.chromeKey !== null && (chromeRows.get(e.chromeKey) ?? 0) >= CHROME_ROWS_CAP)
+            return false;
+        const n = e.node;
+        const hasChildren = n.childCount > 0 || n.children.length > 0;
+        const row = {
+            selector: n.selector,
+            tag: n.tag,
+            text: n.textSummary.trim().slice(0, AI_DESCENDANT_TEXT_CHARS),
+            hasChildren
+        };
+        if (hasChildren && n.heading)
+            row.heading = n.heading;
+        if (n.rect)
+            row.top = n.rect.top;
+        if (n.image)
+            row.image = n.image;
+        shelf.push(row);
+        ancestorsOf.set(n.selector, e.ancestors);
+        emittedSelectors.add(n.selector);
+        if (e.chromeKey !== null)
+            chromeRows.set(e.chromeKey, (chromeRows.get(e.chromeKey) ?? 0) + 1);
+        return true;
+    };
+    const isTextLeaf = (n) => n.tag === 'img' || (TEXT_LEAF_TAGS.has(n.tag) && n.textSummary.trim().length > 0);
+    for (const lm of landmarks) {
+        if (shelf.length >= limit)
+            break;
+        emit(lm);
+        let taken = 0;
+        const collect = (n) => {
+            for (const child of n.children) {
+                if (taken >= LEAVES_PER_LANDMARK || shelf.length >= limit)
+                    return;
+                if (child.hidden)
+                    continue;
+                const ce = entryOf.get(child);
+                if (!ce)
+                    continue;
+                if (surviving.has(ce) && ce !== lm)
+                    continue;
+                if (isTextLeaf(child) && emit(ce))
+                    taken += 1;
+                collect(child);
+            }
+        };
+        collect(lm.node);
+    }
+    if (shelf.length < limit) {
+        const queue = [...root.children];
+        while (queue.length && shelf.length < limit) {
+            const n = queue.shift();
+            if (n.hidden)
+                continue;
+            const e = entryOf.get(n);
+            if (e)
+                emit(e);
+            queue.push(...n.children);
+        }
+    }
+    return { shelf, ancestorsOf };
+}