@skillbuilder/miniapp-simulator 0.0.0-beta-20261023084421

package/lib/types/injection/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Injection —— 注入模块清单（介质无关）
+ *
+ * 每个 InjectionModule 只关心"我要注入什么"，由 Renderer 决定"注入到哪里"：
+ * - IframeRenderer：调 `buildHeadSnippet`，拼到 srcdoc `<head>`
+ * - WebviewRenderer：调 `buildPreloadSource`，物化成 preload script
+ *
+ * 一个模块可以同时实现两个函数（如 jsapi UMD），也可以只实现一个
+ * （如 RenderDoneBootstrap 仅在 iframe 才需要）。
+ *
+ * 设计意图见：design/mini-app/mini-app-simulator-refactor-design.md §8
+ */
+import type { NormalizedMiniAppSimulatorOptions } from "../types";
+export interface InjectionContext {
+    /** 当前渲染介质 */
+    rendererType: "iframe" | "webview";
+    /** 归一化后的 simulator options（供模块按需读取 jsapi/security 等配置） */
+    options: NormalizedMiniAppSimulatorOptions;
+    /** 当前 load 的 appUrl（用于 base href 等场景） */
+    appUrl: string;
+    /** 当前渲染实例可写 usr 根路径；SW 模式为同源 `_xhsfile_` URL。 */
+    userDataPath?: string;
+    /** 宿主为当前 Runtime 指定的网关；缺省时由各 SDK 使用内置默认值。 */
+    gateways?: Record<string, string>;
+    /** 业务线；用于启动参数和 AI 网关路由。 */
+    businessLine?: string;
+    /** iframe srcdoc 路径：fetch 到的原始 HTML（供 jsapi 等模块做 auto-detect） */
+    rawHtml?: string;
+    /** CSP nonce：装配器打在合并 `<script>` 上，模块用于 CSP meta 的 script-src。 */
+    scriptNonce?: string;
+    /** true（SW 模式）时 CSP 走响应头，head 内不注入 CSP meta。 */
+    cspAsHeader?: boolean;
+}
+export interface InjectionModule {
+    /** 唯一名，用于去重与调试 */
+    id: string;
+    /** head 非脚本 HTML（meta / style / link）。 */
+    buildHeadSnippet?(ctx: InjectionContext): string | Promise<string>;
+    /** head 合并 `<script>` 内的裸 JS（装配器逐段包 try/catch）。 */
+    buildHeadScriptSource?(ctx: InjectionContext): string | Promise<string>;
+    /** webview preload script 的一段 IIFE 函数体。 */
+    buildPreloadSource?(ctx: InjectionContext): string | Promise<string>;
+}

package/lib/types/inspector/host-inspector.d.ts

@@ -0,0 +1,108 @@
+/**
+ * HostInspector —— 父窗口侧的可视化元素选取器。
+ *
+ * 职责：
+ * 1. enable 时在 iframe 之上盖一层独立 overlay（高于手势 overlay），接管悬停 / 点击
+ * 2. DOM 同源直读；Canvas 则通过 guest bridge 委托模板注册的场景 Provider 命中
+ * 3. 画悬停 / 选中高亮框，并把统一的 VisualSelection 回调给宿主
+ * 4. disable 时彻底移除 overlay，恢复正常预览 / 手势交互
+ *
+ * 设计要点（关键：**不影响现有功能**）：
+ * - overlay 只在选取模式开启时存在；关闭即移除，手势 / jsapi / 渲染链路零感知。
+ * - DOM 仍与手势模块的 `readCursorAt` 共用同一套坐标换算；场景能力按 Provider 渐进增强。
+ */
+import type { MiniAppInspectorSelectionMode, MiniAppSceneTreeSnapshot, MiniAppVisualSelectionChangeEvent, VisualSelection } from "../types";
+export interface HostInspectorOptions {
+    /** 内容载体 iframe：读取 contentDocument + 坐标换算的基准 */
+    element: HTMLIFrameElement;
+    /** overlay 挂载点（iframe 父容器，与 iframe 盒对齐）；惰性求值以适配 reload 重建 */
+    getMountTarget: () => HTMLElement | null;
+    /** 点击选中回调 */
+    onSelect: (selection: VisualSelection) => void;
+    /** 选中集合变化回调 */
+    onSelectionChange?: (event: MiniAppVisualSelectionChangeEvent) => void;
+    /** 悬停变化回调（移出小应用区域时传 null） */
+    onHover: (selection: VisualSelection | null) => void;
+    debug?: boolean;
+}
+export declare class HostInspector {
+    private readonly opts;
+    private enabled;
+    private destroyed;
+    private overlay;
+    private hoverBox;
+    private readonly selectedBoxes;
+    private readonly selections;
+    private selectionMode;
+    /** 当前悬停元素，避免重复 emit / 重画 */
+    private hoveredEl;
+    /** 悬停 / 选中框是否已可见（决定移动时是「滑动」还是「首次出现」） */
+    private hoverShown;
+    private requestSeq;
+    private latestHoverRequest;
+    private guestHoverFrame;
+    private pendingGuestHover;
+    private readonly pendingRequests;
+    private sceneRefreshTimer;
+    private sceneRefreshPending;
+    /** 同源不可访问时只告警一次 */
+    private warnedNoAccess;
+    constructor(opts: HostInspectorOptions);
+    get isEnabled(): boolean;
+    enable(): void;
+    disable(): void;
+    /** 清除选中高亮（保持选取模式开启） */
+    clear(): void;
+    setSelectionMode(mode: MiniAppInspectorSelectionMode): void;
+    destroy(): void;
+    private readonly onFrameLoad;
+    private notifyGuestPause;
+    private buildOverlay;
+    private teardownOverlay;
+    private createBox;
+    private readonly onMove;
+    private readonly onLeave;
+    private readonly onMouseDown;
+    private select;
+    /** contentDocument 不可读时，经常驻 guest bridge 请求同一份结构化定位结果。 */
+    private queueGuestHover;
+    private cancelGuestHover;
+    private requestGuestSelection;
+    /** 获取 Guest 中所有已注册 Provider 的只读场景树。 */
+    getSceneTree(): Promise<MiniAppSceneTreeSnapshot>;
+    /** 从 Hierarchy / Outliner 反向选择，并复用同一个 Selection Store 与高亮层。 */
+    selectByRef(ref: string): Promise<VisualSelection | null>;
+    private startSceneSelectionRefresh;
+    private stopSceneSelectionRefresh;
+    /**
+     * Scene 对象通常每帧运动；通过稳定 ref 重新 describe，只更新宿主选框与缓存，
+     * 不重复触发用户级 select 事件。对象销毁后自动移除对应选择。
+     */
+    private refreshSceneSelections;
+    private requestGuestRpc;
+    private readonly onGuestMessage;
+    private completeGuestSelection;
+    private selectionKey;
+    private selectionRect;
+    /**
+     * 宿主视口坐标 → iframe 内容元素。
+     * 与手势模块 `readCursorAt` 同一套换算：用 offsetWidth/rect.width 修正设备缩放。
+     * 同源不可访问（跨源 / webview）时返回 null 并降级告警一次。
+     */
+    private resolveElement;
+    /** html/body 表示点到了应用内容之外的根背景，用作清空当前选择。 */
+    private isDocumentSurface;
+    /**
+     * 摆放高亮框。overlay 与 iframe 内容共享同一未缩放坐标空间（设备缩放在共同祖先上），
+     * 故元素的 getBoundingClientRect（iframe 内容 CSS px）可直接作为 overlay 内定位。
+     *
+     * @param wasShown 框是否已可见：已可见则保留过渡，框「滑」到新元素（粘黏感）；
+     *                 首次出现则临时关掉几何过渡，避免从 (0,0) 滑入。
+     */
+    private placeBox;
+    private placeRect;
+    /** 选中时弹一下，给"咔哒选中"的手感（transform 动画独立于 left/top 过渡） */
+    private popBox;
+    private hideBox;
+    private createSelectedBox;
+}

package/lib/types/inspector/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Inspector 模块 —— 可视化元素选取（悬停高亮 + 点击选中）。
+ *
+ * host-inspector 在父窗口侧盖独立 overlay 接管指针，同源直读 iframe DOM；
+ * selector 负责把命中元素转成可抛给宿主 / AI 的结构化描述。
+ */
+export { HostInspector, type HostInspectorOptions } from "./host-inspector";
+export { buildElementSelection, computeSelector } from "./selector";

package/lib/types/inspector/selector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 元素 → 结构化描述（ElementSelection）。
+ *
+ * 纯 DOM 计算，运行在宿主侧（同源 iframe 的 contentDocument 可直接访问）。
+ * 不依赖任何宿主全局，可对任意业务 DOM 安全求值。
+ */
+import type { ElementSelection } from "../types";
+/**
+ * 计算从文档根到该元素的稳定 CSS selector。
+ * - 命中唯一 id 即作为锚点截断（短且稳定）
+ * - 否则用 tag + :nth-of-type(同标签兄弟索引) 逐级回溯
+ */
+export declare function computeSelector(node: Element): string;
+/**
+ * 把元素转成可抛给宿主 / AI 的结构化描述。
+ * @param iframe 内容载体，用于把元素包围盒换算到宿主视口坐标（viewportRect）。
+ */
+export declare function buildElementSelection(el: Element, iframe: HTMLIFrameElement): ElementSelection;

package/lib/types/native-ui/devtools/CapabilitiesView.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `<miniapp-devtools-capabilities>` —— 能力管控视图。
+ *
+ * DevTools 风格组件：数据经 setter 注入 → 调度重渲染；用户操作不直接改状态，而是
+ * 冒泡 `capabilitychange`（CustomEvent，detail.allow 为新白名单），由父面板决定如何应用
+ * （触发模拟器整页 reload）。样式经 adoptedStyleSheets 适配，模板用 `html\`\`` 声明。
+ */
+import type { DevtoolsSnapshot } from "./types";
+export declare const CAPABILITIES_TAG = "miniapp-devtools-capabilities";
+/** 派发的能力变更事件名（detail: { allow: string[] }） */
+export declare const CAPABILITY_CHANGE_EVENT = "capabilitychange";
+export declare class CapabilitiesView extends HTMLElement {
+    #private;
+    constructor();
+    set snapshot(value: DevtoolsSnapshot | null);
+    set applying(value: boolean);
+}
+export declare function defineCapabilitiesView(): void;

package/lib/types/native-ui/devtools/DevtoolsPanel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<miniapp-devtools>` —— 调试面板根组件（DevTools 风格的「面板外壳 + tab 切换 + 视图装配」）。
+ *
+ * 职责：
+ * - fixed 停靠窗口右侧（不进入模拟器 mount、不遮挡舞台），`[open]` 属性驱动滑入/滑出过渡；
+ * - 装配两个子视图（CapabilitiesView / LogsView），把模拟器事件流转发给日志视图；
+ * - 监听能力视图冒泡的 `capabilitychange`，调用 onApplyCapabilities（整页 reload）并自刷新；
+ * - 对外（经工厂）暴露 open/close/toggle/refresh/dispose 控制器接口。
+ */
+import type { DevtoolsPanelOptions } from "./types";
+export declare const PANEL_TAG = "miniapp-devtools";
+export declare class DevtoolsPanelElement extends HTMLElement {
+    #private;
+    constructor();
+    /** 注入模拟器侧回调（创建后立即调用） */
+    bind(options: DevtoolsPanelOptions): void;
+    get isOpen(): boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    refresh(): void;
+    dispose(): void;
+}
+export declare function defineDevtoolsPanel(): void;

package/lib/types/native-ui/devtools/LogsView.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<miniapp-devtools-logs>` —— 运行日志视图。
+ *
+ * 自带事件缓冲（环形上限）、文本过滤、暂停自动滚动。父面板把模拟器事件经 `push()` 灌入；
+ * 视图负责归一、增量渲染（新行 `insertAdjacentHTML` 追加，避免全量重排）。
+ */
+import type { MiniAppEventName } from "../../types";
+export declare const LOGS_TAG = "miniapp-devtools-logs";
+export declare class LogsView extends HTMLElement {
+    #private;
+    constructor();
+    connectedCallback(): void;
+    /** 灌入一条模拟器事件 */
+    push(event: MiniAppEventName | string, payload: unknown): void;
+    clear(): void;
+}
+export declare function defineLogsView(): void;

package/lib/types/native-ui/devtools/dom.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DevTools 风格的极简 DOM / 模板基建（零依赖，替代 lit-html）。
+ *
+ * 对齐 Chrome DevTools frontend 的工程习惯：
+ * - 组件用 `adoptedStyleSheets` 适配「构造式样式表」（co-located CSS 文本），而非内联 <style>；
+ * - 视图用标签模板 `html\`\`` 声明式描述结构，插值默认转义（防 XSS），已可信片段用 `raw()`；
+ * - 渲染走调度（rAF 合并），由 {@link RenderScheduler} 提供。
+ */
+/** 标记「已可信、无需转义」的 HTML 片段（如子模板拼接结果）。 */
+declare class RawHtml {
+    readonly value: string;
+    constructor(value: string);
+}
+export declare function raw(value: string): RawHtml;
+export declare function escapeHtml(value: unknown): string;
+/**
+ * lit 风格标签模板：返回 HTML 字符串。插值默认转义；数组自动 join；
+ * `raw(...)` / 由 `html` 产出的片段视为可信不再转义。
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): RawHtml;
+/** 把 `html\`\`` 结果转为最终字符串（用于 innerHTML 落地）。 */
+export declare function toHtmlString(node: RawHtml): string;
+/**
+ * 把若干 CSS 文本以「构造式样式表」适配进 shadow root（DevTools 习惯）。
+ * 同一份 CSS 文本只构造一次并跨组件复用。不支持的环境降级为内联 <style>。
+ */
+export declare function adoptStyles(shadow: ShadowRoot, cssTexts: string[]): void;
+/** 幂等注册自定义元素。 */
+export declare function defineComponent(tag: string, ctor: CustomElementConstructor): void;
+/**
+ * rAF 合并的渲染调度器：多次 schedule 只触发一次 render。
+ */
+export declare class RenderScheduler {
+    #private;
+    private readonly render;
+    constructor(render: () => void);
+    schedule(): void;
+    flushCancel(): void;
+}
+export {};

package/lib/types/native-ui/devtools/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Debug DevTools 面板出口（Chrome DevTools frontend 风格）。
+ *
+ * 仅在 `createMiniAppSimulator({ debug: true })` 时由模拟器内部实例化，
+ * 通过 `Shift + Cmd/Ctrl + U` 快捷键唤起。架构：
+ *   - 组件化自定义元素（`<miniapp-devtools>` 装配 capabilities / logs 两个子视图）
+ *   - adoptedStyleSheets 构造式样式表 + 设计 token，子视图经 setter 注入、CustomEvent 上报
+ * 能力：
+ *   - 能力管控（封印能力枚举 + 动态启停并重载）
+ *   - 运行日志 / 关键事件实时流
+ */
+import type { DevtoolsPanel, DevtoolsPanelOptions } from "./types";
+/**
+ * 创建并挂载调试面板，返回控制器。面板默认挂到 `document.body`，以 fixed 停靠窗口右侧。
+ */
+export declare function createDevtoolsPanel(options: DevtoolsPanelOptions): DevtoolsPanel;
+export { registerDevtoolsShortcut } from "./shortcut";
+export { DEVTOOLS_PANEL_WIDTH } from "./tokens";
+export type { DevtoolsPanel, DevtoolsPanelOptions, DevtoolsSnapshot, DevtoolsLogEntry, } from "./types";

package/lib/types/native-ui/devtools/log-entry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 事件 → 日志条目归一。模拟器各类事件 payload 形态不同，这里收敛成统一的
+ * `{ timestamp, event, message, level }`，供 LogsView 渲染。
+ */
+import type { MiniAppEventName } from "../../types";
+import type { DevtoolsLogEntry } from "./types";
+export declare function toLogEntry(event: MiniAppEventName | string, payload: unknown): DevtoolsLogEntry;
+export declare function formatLogTime(ts: number): string;

package/lib/types/native-ui/devtools/shortcut.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DevTools 唤起快捷键：
+ * - macOS：`Shift + Command + U`
+ * - 其他平台：`Shift + Ctrl + U`
+ *
+ * 监听挂在 capture 阶段的 document 上。注意：当焦点位于小应用 iframe 内部时，
+ * 父文档收不到该 keydown，此时需先点击手机外区域再触发（已在文档说明）。
+ */
+/**
+ * 注册唤起快捷键，返回卸载函数。
+ */
+export declare function registerDevtoolsShortcut(onTrigger: () => void, target?: Document): () => void;

package/lib/types/native-ui/devtools/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 设计 token（CSS 变量，暗色玻璃拟态主题）。
+ *
+ * 对齐 Chrome DevTools 的 `--sys-color-*` 思路：所有组件共享同一份 token 样式表
+ * （经 `adoptStyles` 适配进各自 shadow root），具体组件样式只引用变量，便于统一换肤。
+ */
+/** 面板停靠宽度（px）；与 token --dt-width 同步，供 JS 侧引用。 */
+export declare const DEVTOOLS_PANEL_WIDTH = 420;
+export declare const TOKENS_CSS = "\n:host {\n  --dt-width: 420px;\n\n  --dt-fg: #e8eaf0;\n  --dt-fg-2: rgba(232, 234, 240, 0.72);\n  --dt-fg-3: rgba(232, 234, 240, 0.45);\n  --dt-fg-4: rgba(232, 234, 240, 0.38);\n\n  --dt-bg: linear-gradient(180deg, rgba(20, 22, 30, 0.92) 0%, rgba(14, 15, 22, 0.94) 100%);\n  --dt-surface: rgba(255, 255, 255, 0.05);\n  --dt-surface-2: rgba(255, 255, 255, 0.08);\n  --dt-surface-hover: rgba(255, 255, 255, 0.12);\n  --dt-border: rgba(255, 255, 255, 0.08);\n  --dt-border-soft: rgba(255, 255, 255, 0.04);\n\n  --dt-accent: #ff2442;\n  --dt-accent-2: #ff6b81;\n  --dt-ok: #4ade80;\n  --dt-err: #ff7a72;\n  --dt-warn: #ffd166;\n  --dt-host: #7ab0ff;\n\n  --dt-radius: 8px;\n  --dt-radius-pill: 999px;\n  --dt-font: 13px/1.5 -apple-system, BlinkMacSystemFont, \"Segoe UI\", \"PingFang SC\", sans-serif;\n  --dt-mono: 11.5px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;\n}\n";
+/**
+ * 通用控件样式（滚动区 / 工具条 / 输入框 / 按钮 / 空态），各视图共享适配，
+ * 避免每个组件重复声明。仅引用 token 变量。
+ */
+export declare const BASE_CSS = "\n*, *::before, *::after { box-sizing: border-box; }\n.dt-content {\n  display: flex;\n  flex-direction: column;\n  min-height: 0;\n  height: 100%;\n}\n.dt-scroll {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow-y: auto;\n  overflow-x: hidden;\n  padding: 4px 0 14px;\n}\n.dt-scroll::-webkit-scrollbar { width: 8px; }\n.dt-scroll::-webkit-scrollbar-thumb {\n  background: rgba(255, 255, 255, 0.14);\n  border-radius: 8px;\n}\n.dt-toolbar {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 10px 14px;\n  flex: none;\n}\n.dt-input {\n  flex: 1 1 auto;\n  min-width: 0;\n  height: 30px;\n  padding: 0 10px;\n  border-radius: var(--dt-radius);\n  border: 1px solid rgba(255, 255, 255, 0.1);\n  background: var(--dt-surface);\n  color: var(--dt-fg);\n  font-size: 12px;\n  outline: none;\n}\n.dt-input::placeholder { color: var(--dt-fg-4); }\n.dt-input:focus { border-color: rgba(255, 36, 66, 0.5); }\n.dt-btn {\n  height: 30px;\n  padding: 0 12px;\n  border-radius: var(--dt-radius);\n  border: 1px solid rgba(255, 255, 255, 0.1);\n  background: var(--dt-surface);\n  color: var(--dt-fg-2);\n  font-size: 12px;\n  cursor: pointer;\n  white-space: nowrap;\n  transition: background 0.15s, border-color 0.15s;\n}\n.dt-btn:hover { background: var(--dt-surface-hover); }\n.dt-btn[aria-pressed=\"true\"] {\n  border-color: rgba(255, 36, 66, 0.55);\n  color: var(--dt-accent-2);\n}\n.dt-empty {\n  padding: 40px 24px;\n  text-align: center;\n  font-size: 12px;\n  color: var(--dt-fg-4);\n}\n";

package/lib/types/native-ui/devtools/types.d.ts

@@ -0,0 +1,51 @@
+import type { MiniAppCapability } from "../../seal-config";
+import type { MiniAppEventName } from "../../types";
+/** 调试面板从模拟器读取的当前快照（每次 open / refresh 调用） */
+export interface DevtoolsSnapshot {
+    /** 当前生效的 seal allow 白名单（已展开默认值；即便使用 DEFAULT_ALLOW 也是具体数组） */
+    allow: ReadonlyArray<MiniAppCapability>;
+    /** 是否为消费方显式传入的 sealAllow（false = 当前用 seal 内置 DEFAULT_ALLOW） */
+    custom: boolean;
+    renderer: string;
+    contentMode: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    appUrl: string;
+}
+/** 单条日志条目 */
+export interface DevtoolsLogEntry {
+    timestamp: number;
+    event: MiniAppEventName | string;
+    message: string;
+    level: "info" | "ok" | "warn" | "error" | "blocked";
+}
+export interface DevtoolsPanelOptions {
+    /**
+     * 面板挂载根，默认 `document.body`。面板以 fixed 停靠窗口右侧，不进入模拟器
+     * mount 容器，因此不遮挡 / 不压缩手机舞台。
+     */
+    mountRoot?: HTMLElement;
+    /** 读取当前模拟器快照（用于能力 Tab 与信息条渲染） */
+    getSnapshot: () => DevtoolsSnapshot;
+    /**
+     * 应用新的能力白名单（会触发模拟器整页 reload）。
+     * resolve 后面板用最新 snapshot 重渲染能力列表。
+     */
+    onApplyCapabilities: (sealAllow: MiniAppCapability[]) => Promise<void> | void;
+    /** 订阅模拟器事件流，返回退订函数 */
+    subscribe: (handler: (event: MiniAppEventName | string, payload: unknown) => void) => () => void;
+    /** 面板显隐变化回调（如收窄/还原 bounds 之外的联动） */
+    onOpenChange?: (open: boolean) => void;
+}
+/** 调试面板控制器 */
+export interface DevtoolsPanel {
+    open(): void;
+    close(): void;
+    toggle(): void;
+    readonly isOpen: boolean;
+    /** 重新从 snapshot 渲染能力列表（reload 后由模拟器调用） */
+    refresh(): void;
+    destroy(): void;
+}

package/lib/types/native-ui/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Native UI 模块出口。
+ *
+ * 包含"小应用 jsapi 调用时由模拟器渲染的、模拟真机原生界面的 UI 组件"：
+ *   - `toast`           - 顶部短提示（对应真机 `showToast`）
+ *   - `permission-sheet` - 权限授权 bottom sheet（对应真机系统弹窗）
+ *   - `rednote-preview` - 小红书笔记 Feed / 详情壳层
+ *
+ * 这些组件由 simulator 在内部按需挂载，通过 BridgeProtocol 接收 jsapi 路由后渲染。
+ * 与 `hostApi`（宿主能力委托）的区别：native-ui 是"模拟器内置实现"，hostApi 是"宿主真实能力"。
+ */
+export { showHostToast, type HostToastFn, type HostToastOptions } from "./toast";
+export { FrameToastHost, type FrameToastOptions } from "./toast/frame-toast-host";
+export { PermissionSheetHost, type PermissionSheetHostOptions, type PermissionSheetShowOptions, } from "./permission-sheet/permission-sheet-host";
+export type { MiniAppPermissionKind, MiniAppPermissionSheetResult, } from "./permission-sheet/types";
+export { registerRednotePreviewElements, mergeNotePreview, XHS_NOTE_DETAIL_SHELL_TAG, type XhsNoteDetailShell, } from "./rednote-preview";
+export { NotePublishHost, type NotePublishHostOptions, toNotePublishViewData, type NoteMedia, type NotePublishResult, type NotePublishViewData, } from "./note-publish";

package/lib/types/native-ui/note-publish/defaults.d.ts

@@ -0,0 +1,40 @@
+export declare const NOTE_PUBLISH_TEXT: {
+    readonly titlePlaceholder: "添加标题";
+    readonly contentPlaceholder: "添加正文或发语音";
+    readonly location: "标记地点";
+    readonly visibility: "公开可见";
+    readonly addComponent: "添加组件";
+    readonly advanced: "高级选项";
+    readonly topic: "话题";
+    readonly mention: "用户";
+    readonly vote: "投票";
+    readonly chooseCover: "选封面";
+    readonly livePhoto: "实况";
+    readonly saveDraft: "存草稿";
+    readonly publish: "发布笔记";
+};
+export declare const NOTE_PUBLISH_ICON: {
+    readonly navBar: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkiknu0m277180ac7t8006ptl0akiev06.png";
+    readonly statusLevels: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkih7a06277180ac7t8006ptl0b0qgdka.png";
+    readonly homeIndicator: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkipga06277180ac7t8006ptl0dehcmn4.png";
+    readonly voice: "https://fe-platform.xhscdn.com/platform/104101l0323g0lki10206277180ac7t8006ptl0br01bmu.png";
+    readonly location: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkiknk0m277180ac7t8006ptl0e7n5ldm.png";
+    readonly visibility: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkiknk06277180ac7t8006ptl0e1f6908.png";
+    readonly addComponent: "https://fe-platform.xhscdn.com/platform/104101l0323g0lki07k06277180ac7t8006ptl0ck0o7v8.png";
+    readonly setting: "https://fe-platform.xhscdn.com/platform/104101l0323g0lki07u06277180ac7t8006ptl09f764ic.png";
+    readonly chevron: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkij7a06277180ac7t8006ptl0aholfs6.png";
+    readonly topic: "https://fe-platform.xhscdn.com/platform/104101l0323g0lkiqna06277180ac7t8006ptl0ckpb7vo.png";
+    readonly mention: "https://fe-platform.xhscdn.com/platform/104101l0323g0lki1nu76277180ac7t8006ptl0e2eecng.png";
+    readonly vote: "https://fe-platform.xhscdn.com/platform/104101l0323g0lki07k0m277180ac7t8006ptl0bpvoc3i.png";
+    readonly videoBadge: "https://fe-platform.xhscdn.com/platform/104101l0323g0ofcn0206277180ac7t8006ptl0ctk6mds.png";
+};
+export declare const NOTE_PUBLISH_COLOR: {
+    readonly red: "#FF2442";
+    readonly title: "rgba(0, 0, 0, 0.8)";
+    readonly placeholder: "rgba(0, 0, 0, 0.27)";
+    readonly chipBg: "#F5F5F5";
+    readonly border: "rgba(0, 0, 0, 0.08)";
+    readonly coverBadgeBg: "rgba(48, 48, 52, 0.5)";
+    readonly chooseCoverBg: "rgba(0, 0, 0, 0.65)";
+    readonly chooseCoverBorder: "rgba(255, 255, 255, 0.3)";
+};

package/lib/types/native-ui/note-publish/index.d.ts

@@ -0,0 +1,2 @@
+export { NotePublishHost, type NotePublishHostOptions } from "./note-publish-host";
+export { toNotePublishViewData, type NoteMedia, type NotePublishResult, type NotePublishViewData, } from "./view-data";

package/lib/types/native-ui/note-publish/miniapp-note-publish.d.ts

@@ -0,0 +1,15 @@
+import type { NotePublishResult, NotePublishViewData } from "./view-data";
+export declare class MiniappNotePublish extends HTMLElement {
+    private _panelEl;
+    private _resolve;
+    connectedCallback(): void;
+    present(data: NotePublishViewData): Promise<NotePublishResult>;
+    hide(): void;
+    private finish;
+    private settle;
+    private syncOpen;
+    private renderContent;
+    private render;
+}
+export declare function registerMiniappNotePublish(): void;
+export declare function createMiniappNotePublishElement(): MiniappNotePublish;

package/lib/types/native-ui/note-publish/note-publish-host.d.ts

@@ -0,0 +1,15 @@
+import type { NotePublishResult, NotePublishViewData } from "./view-data";
+export interface NotePublishHostOptions {
+    onOpenChange?: (open: boolean) => void;
+}
+export declare class NotePublishHost {
+    private readonly mountEl;
+    private readonly options;
+    private readonly page;
+    private mounted;
+    constructor(mountEl: HTMLElement, options?: NotePublishHostOptions);
+    mount(): void;
+    show(data: NotePublishViewData): Promise<NotePublishResult>;
+    hide(): void;
+    destroy(): void;
+}

package/lib/types/native-ui/note-publish/view-data.d.ts

@@ -0,0 +1,21 @@
+export type NoteMedia = {
+    type: "image";
+    url: string;
+} | {
+    type: "video";
+    url: string;
+    cover?: string;
+} | {
+    type: "live_photo";
+    url: string;
+    cover: string;
+};
+export interface NotePublishViewData {
+    title: string;
+    content: string;
+    media: NoteMedia[];
+    tags: string[];
+    pageType?: string;
+}
+export type NotePublishResult = "publish" | "cancel";
+export declare function toNotePublishViewData(message: Record<string, unknown>): NotePublishViewData;

package/lib/types/native-ui/permission-sheet/defaults.d.ts

@@ -0,0 +1,12 @@
+import type { MiniAppPermissionItem, MiniAppPermissionKind } from "./types";
+/** 设计稿固定文案 */
+export declare const PERMISSION_PRESETS: Record<MiniAppPermissionKind, MiniAppPermissionItem>;
+/**
+ * V1 permission-gate 入口写死：未来由业务勾选覆盖。
+ * gate 脚本将根据该列表决定包装 getUserMedia / 拦截 file 等。
+ */
+export declare const V1_PERMISSION_GATE_ENABLED: MiniAppPermissionKind[];
+export declare const PERMISSION_SHEET_TITLE = "\u5C0F\u5DE5\u5177\u7533\u8BF7\u4F7F\u7528\u4EE5\u4E0B\u6743\u9650";
+export declare const PERMISSION_SHEET_CANCEL_LABEL = "\u53D6\u6D88";
+export declare const PERMISSION_SHEET_GRANT_LABEL = "\u540C\u610F\u6388\u6743";
+export declare function buildPermissionItems(kinds: MiniAppPermissionKind[]): MiniAppPermissionItem[];

package/lib/types/native-ui/permission-sheet/index.d.ts

@@ -0,0 +1,4 @@
+export type { MiniAppPermissionKind, MiniAppPermissionItem, MiniAppPermissionSheetResult, } from "./types";
+export { buildPermissionItems, PERMISSION_PRESETS, PERMISSION_SHEET_TITLE, V1_PERMISSION_GATE_ENABLED, } from "./defaults";
+export { createMiniappPermissionSheetElement, registerMiniappPermissionSheet, MiniappPermissionSheet, } from "./miniapp-permission-sheet";
+export { PermissionSheetHost, type PermissionSheetShowOptions } from "./permission-sheet-host";

package/lib/types/native-ui/permission-sheet/miniapp-permission-sheet.d.ts

@@ -0,0 +1,19 @@
+import type { MiniAppPermissionItem, MiniAppPermissionSheetResult } from "./types";
+export declare class MiniappPermissionSheet extends HTMLElement {
+    private _backdropEl;
+    private _panelEl;
+    private _listEl;
+    private _resolve;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** 展示授权 Sheet，返回用户选择 */
+    present(items: MiniAppPermissionItem[]): Promise<MiniAppPermissionSheetResult>;
+    hide(): void;
+    private finish;
+    private syncOpenAttr;
+    private renderList;
+    private render;
+}
+export declare function registerMiniappPermissionSheet(): void;
+export declare function createMiniappPermissionSheetElement(): MiniappPermissionSheet;

package/lib/types/native-ui/permission-sheet/permission-sheet-host.d.ts

@@ -0,0 +1,23 @@
+import type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from "./types";
+export interface PermissionSheetShowOptions {
+    /** 要展示的权限项；省略则使用 V1_PERMISSION_GATE_ENABLED 全量 */
+    kinds?: MiniAppPermissionKind[];
+}
+export interface PermissionSheetHostOptions {
+    /** Sheet 显隐变化（用于暂时关闭 gesture overlay 等上层拦截） */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * 宿主侧权限 Sheet 控制器：挂载在 iframe 的 contentRoot 上，覆盖手机框视口。
+ */
+export declare class PermissionSheetHost {
+    private readonly mountEl;
+    private readonly options;
+    private readonly sheet;
+    private mounted;
+    constructor(mountEl: HTMLElement, options?: PermissionSheetHostOptions);
+    mount(): void;
+    show(options?: PermissionSheetShowOptions): Promise<MiniAppPermissionSheetResult>;
+    hide(): void;
+    destroy(): void;
+}

package/lib/types/native-ui/permission-sheet/types.d.ts

@@ -0,0 +1,8 @@
+/** 第一版支持的权限种类（与 MiniTool 规范 §3 允许项对齐） */
+export type MiniAppPermissionKind = "album" | "camera" | "microphone";
+export interface MiniAppPermissionItem {
+    kind: MiniAppPermissionKind;
+    title: string;
+    description: string;
+}
+export type MiniAppPermissionSheetResult = "grant" | "cancel";

package/lib/types/native-ui/rednote-preview/chrome-tone.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 顶部 chrome（状态栏时间/信号 + 半屏全屏态返回/分享/更多）底色自适应探测。
+ *
+ * 背景：小工具半屏拖全后做沉浸式导航，顶部 svg / 状态栏浮于小程序内容之上。
+ * 若小程序底色偏深，默认的白色图标尚可见；若底色偏亮，白色图标几乎不可见。
+ * 故对 iframe（同源 srcdoc）内容顶部区域采样底色，按通用亮度公式判定明暗，
+ * 自动切换 chrome 前景明暗，保证任意底色下都有足够对比度。
+ *
+ * tone 语义（描述「前景应使用的明暗」，与背景相反）：
+ *   - "light" → 浅色前景（白图标 / 白拖杆），适配深色背景
+ *   - "dark"  → 深色前景（黑图标 / 深拖杆），适配浅色背景
+ */
+export type ChromeTone = "light" | "dark";
+/** 默认 tone：深色前景对应浅底，但模拟器默认底色未知，按设计稿默认浅色前景（深底） */
+export declare const DEFAULT_CHROME_TONE: ChromeTone;
+/** 通用亮度阈值：Y > 128 视为亮底（用深色前景），Y ≤ 128 视为暗底（用浅色前景） */
+export declare const LUMINANCE_THRESHOLD = 128;
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** 通用亮度公式 Y = 0.299R + 0.587G + 0.114B（0–255） */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** 亮度转 tone：亮底用深前景，暗底用浅前景 */
+export declare function luminanceToTone(luminance: number): ChromeTone;
+/**
+ * 解析 getComputedStyle 返回的背景色（仅 rgb()/rgba()，浏览器计算值恒为此形式）。
+ * 返回含 alpha；无法解析或全透明返回 null。
+ */
+export declare function parseCssColor(value: string | null | undefined): (Rgb & {
+    a: number;
+}) | null;
+/**
+ * 自元素向上回溯祖先链，取第一个不透明（alpha ≥ 0.5）的背景色。
+ * 全链透明时回退到浏览器默认白底。
+ */
+export declare function resolveBackgroundColor(el: Element | null, view: Window & typeof globalThis): Rgb;
+/**
+ * 探测同源 iframe 顶部内容底色对应的 chrome tone。
+ * 跨域或文档未就绪时返回 null（调用方据此保留当前 tone）。
+ */
+export declare function detectChromeToneFromIframe(iframe: HTMLIFrameElement): ChromeTone | null;
+export {};