@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

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 {};

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

@@ -0,0 +1,30 @@
+import type { XhsNotePreviewData } from "../../types";
+/** REDNote 壳层默认用户头像（导航栏兜底） */
+export declare const DEFAULT_AVATAR = "https://picasso-static.xiaohongshu.com/fe-platform/6544a4b19792523b3a9c97aa0fec738f821381cf.png";
+/**
+ * REDNote 详情半屏 Sheet 的默认 resting 高度比例。
+ * 外部 `createMiniAppSimulator({ rednoteDetail: { heightRatio } })` 传入可覆盖；
+ * 取值范围 `[0.5, 0.95]`，超出会被 clamp。
+ */
+export declare const DEFAULT_REDNOTE_HALF_SHEET_HEIGHT_RATIO = 0.75;
+/** 小工具入口卡片默认文案 */
+export declare const DEFAULT_APP_CARD_NAME = "\u5C0F\u5DE5\u5177\u6A21\u62DF\u5668";
+export declare const DEFAULT_APP_CARD_DESC = "\u70B9\u51FB\u300C\u7528\u4E00\u7528\u300D\u6253\u5F00\u5C0F\u5DE5\u5177\u9884\u89C8";
+/** 轮播图片页数，也是分页徽标里的数字总数 */
+export declare const NOTE_GALLERY_IMAGE_COUNT = 2;
+/** 轮播总页数：图片页 + 末尾的小工具尾卡，尾卡同样占一个圆点 */
+export declare const NOTE_GALLERY_TOTAL: number;
+/** 占位页插画（设计稿 placeholder/笔记） */
+export declare const NOTE_GALLERY_PLACEHOLDER_ICON = "https://fe-platform.xhscdn.com/platform/104101l0324qamsiqgo06277180ac7t8006ptl0ev7ed16.png";
+/** 占位页提示文案 */
+export declare const NOTE_GALLERY_PLACEHOLDER_TEXT = "\u6B64\u5904\u4E3A\u53D1\u5E03\u9875\u4E0A\u4F20\u7684\u56FE\u7247";
+/** 个人页小工具卡片右上角「笔记类型」角标（设计稿原图：深灰半透明圆底 + 白色图形） */
+export declare const PROFILE_CARD_TYPE_ICON_URL = "https://fe-platform.xhscdn.com/platform/104101l0325aul06cl006277180ac7t8006ptl09n4ess6.png";
+/**
+ * 各占位页底色（设计稿）。第一张比后续更深，否则相邻两张纯色占位切换时看不出差别。
+ * 页数超出数组长度时复用最后一档。
+ */
+export declare const NOTE_GALLERY_PLACEHOLDER_BG: string[];
+export declare const DEFAULT_NOTE_PREVIEW: XhsNotePreviewData;
+export declare function mergeNotePreview(partial?: XhsNotePreviewData): XhsNotePreviewData;
+export declare function formatRatio(ratio: number): number;

package/lib/types/native-ui/rednote-preview/half-sheet-drag.d.ts

@@ -0,0 +1,61 @@
+/**
+ * REDNote 半屏 Sheet 拖拽吸附（iOS bottom sheet 风格）。
+ *
+ * 实现要点（解耦 Web Component，便于单测/复用）：
+ *   - sheet 底部锚定（bottom:0），通过**改变自身高度**向上增高露出
+ *     → iframe 填满 sheet，视口高度 = 可见高度，随高度变化而回流
+ *       （H5 的 `position:fixed; bottom:0` 元素始终贴在可见底部，对齐真机半屏 webview resize）
+ *   - 手指位移 1px === 高度变化 1px（顶边跟手），按下与拖动位置严格一致
+ *   - 松手按阈值吸附到 half / full
+ *
+ *   坐标约定（visible = sheet 当前高度）：
+ *     visible = bounds          → 全屏，sheet 铺满
+ *     visible = halfVisiblePx   → 半屏，露出屏幕高度的 halfRatio
+ *     visible = 0               → 关闭，高度归零
+ *     visibleRatio = visible / bounds
+ */
+export type HalfSheetSnapState = "closed" | "half" | "full";
+export interface HalfSheetDragConfig {
+    /** 半屏 resting 时的可见比例，[0.5, 0.95]，默认由宿主提供 */
+    halfHeightRatio: number;
+    /** visible ≥ 此值 → 进入全屏。默认 = half + (1 - half) * 0.55 */
+    expandThresholdRatio?: number;
+    /** visible ≤ 此值 → 回到半屏。默认 = half + (1 - half) * 0.35 */
+    collapseThresholdRatio?: number;
+    /** 半屏向下拖拽，可见比例 ≤ 此值（即 sheet 进入屏幕底部 20% 区域）→ 关闭。默认 0.2 */
+    closeThresholdRatio?: number;
+    /** 全屏态下，sheet 顶部多少比例区域可触发下拖。默认 0.08 */
+    topDragZoneRatio?: number;
+    /** snap 动画时长（ms），默认 280 */
+    snapTransitionMs?: number;
+    /** 初始吸附态，默认 `half` */
+    initialState?: HalfSheetSnapState;
+    /** 锁定拖拽：为 true 时禁止一切指针拖拽（程序化 snapTo 仍可用） */
+    locked?: boolean;
+}
+export interface HalfSheetDragAttachOptions extends HalfSheetDragConfig {
+    sheet: HTMLElement;
+    handle: HTMLElement;
+    /** bounds 高度（一般是 sheet 的父容器 clientHeight） */
+    getBoundsHeight: () => number;
+    /**
+     * 整机屏幕高度（用于半屏 resting 高度按「屏幕高度」计算，而非 bounds）。
+     * bounds 通常已扣除顶部状态栏，若半屏比例要对齐「屏幕高度的 N%」需用此值。
+     * 不提供时回退用 bounds。
+     */
+    getViewportHeight?: () => number;
+    /** 全屏态附加可拖拽区域（status + nav 顶栏，用于下拖返回半屏） */
+    fullScreenDragZone?: HTMLElement;
+    onStateChange?: (state: HalfSheetSnapState) => void;
+}
+export interface HalfSheetDragController {
+    getState(): HalfSheetSnapState;
+    /** 外部更新半屏 resting 比例（如 attribute 变更） */
+    setHalfHeightRatio(ratio: number): void;
+    /** 程序化吸附 */
+    snapTo(state: HalfSheetSnapState, animate?: boolean): void;
+    /** 窗口尺寸变化后重算 offset（保持当前 state） */
+    refresh(): void;
+    destroy(): void;
+}
+export declare function attachHalfSheetDrag(options: HalfSheetDragAttachOptions): HalfSheetDragController;

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

@@ -0,0 +1,2 @@
+export * from "./register";
+export * from "./defaults";

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

@@ -0,0 +1,7 @@
+/** 注册小红书笔记预览相关 Web Components（幂等） */
+export declare function registerRednotePreviewElements(): void;
+export { XHS_NOTE_DETAIL_SHELL_TAG, XhsNoteDetailShell, } from "./xhs-note-detail-shell";
+export { XHS_NOTE_HALF_SHEET_TAG, XhsNoteHalfSheet, } from "./xhs-note-half-sheet";
+export { XHS_PROFILE_SHELL_TAG, XhsProfileShell, } from "./xhs-profile-shell";
+export { DEFAULT_NOTE_PREVIEW, DEFAULT_REDNOTE_HALF_SHEET_HEIGHT_RATIO, mergeNotePreview, } from "./defaults";
+export { attachHalfSheetDrag, type HalfSheetDragAttachOptions, type HalfSheetDragConfig, type HalfSheetDragController, type HalfSheetSnapState, } from "./half-sheet-drag";

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

@@ -0,0 +1,4 @@
+/** 共享 design token（基于创作者发布页 ImagePreview / CoverPreview） */
+/** 手机顶部状态栏高度（390 逻辑宽 iOS 模拟器） */
+export declare const STATUS_BAR_HEIGHT = 44;
+export declare const REDNOTE_CSS_VARS = "\n  :host {\n    --xhs-red: #ff2442;\n    --xhs-title: rgba(0, 0, 0, 0.8);\n    --xhs-paragraph: rgba(0, 0, 0, 0.62);\n    --xhs-fill: #f5f5f5;\n    --xhs-bg: #ffffff;\n    --xhs-sheet-radius: 16px;\n    --xhs-status-bar-height: 44px;\n    font-family: \"PingFang SC\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n    display: block;\n    width: 100%;\n    height: 100%;\n    box-sizing: border-box;\n    user-select: none;\n    -webkit-user-select: none;\n    -webkit-touch-callout: none;\n  }\n  *, *::before, *::after {\n    box-sizing: border-box;\n    user-select: none;\n    -webkit-user-select: none;\n    -webkit-touch-callout: none;\n  }\n  img, a, svg {\n    -webkit-user-drag: none;\n    user-drag: none;\n  }\n";

package/lib/types/native-ui/rednote-preview/xhs-note-detail-shell.d.ts

@@ -0,0 +1,70 @@
+import type { MiniAppContentMode, NormalizedRednoteDetailSheetOptions, XhsNotePreviewData } from "../../types";
+declare const TAG = "xhs-note-detail-shell";
+export declare class XhsNoteDetailShell extends HTMLElement {
+    private _data;
+    private _sheetOptions;
+    private _halfSheet;
+    /** 启动模式：half（下滑收起）/ fullscreen（右侧滑入、初始全屏、锁定拖拽） */
+    private _launchMode;
+    /** 状态栏时钟定时器，组件卸载时清理 */
+    private _statusTimeTimer;
+    /** 轮播当前停留位；默认停在最后一档（小工具聚焦） */
+    private _galleryIndex;
+    /** 壳层内容收起回调（下滑 / 全屏返回 → snap "closed"） */
+    onContentClose?: () => void;
+    /** 壳层内容重新唤起回调（从 closed 再次打开） */
+    onContentOpen?: () => void;
+    /** 点击入口时先判断是否允许唤起；拒绝时保持笔记页，不展示空内容容器。 */
+    onContentOpenRequest?: () => boolean;
+    /** 导航栏头像点击 → 跳转个人页 */
+    onAvatarClick?: () => void;
+    set notePreview(value: XhsNotePreviewData | null);
+    get notePreview(): XhsNotePreviewData | null;
+    set sheetOptions(value: NormalizedRednoteDetailSheetOptions);
+    set launchMode(value: MiniAppContentMode);
+    get launchMode(): MiniAppContentMode;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** 半屏内的内容载体挂载点（载体可为 <iframe> 或 <webview>，与具体渲染器无关） */
+    getContentMountTarget(): HTMLElement;
+    setHasAppUrl(hasApp: boolean): void;
+    /** 收起小工具页，等待半屏/全屏退场结束后回到笔记详情页。 */
+    closeContent(): Promise<void>;
+    /**
+     * 外部唤起小工具内容（先过准入检查）；`sheetMode` 指定半屏 / 全屏吸附态。
+     * 供 `redirectTo("minitool", { sheetMode })` 与个人页卡片点击使用。
+     */
+    openContent(sheetMode?: "half" | "full"): void;
+    /**
+     * 模拟触摸时隐藏系统光标（改由 gesture 的「手指圆点」表示指针）。
+     * shadow DOM 内部各元素自带 cursor 规则会覆盖外部继承的 `none`，
+     * 故需向 shadowRoot 注入 `cursor: none` 强制规则，并向半屏透传。
+     */
+    setSimulatedCursorHidden(hidden: boolean): void;
+    private render;
+    private requestContentOpen;
+    /**
+     * 轮播页 DOM：前 NOTE_GALLERY_IMAGE_COUNT 页是发布图（缺图时按页取色占位），
+     * 末页是小工具尾卡。尾卡与图片同在 track 内，因此切换共用同一段位移过渡。
+     */
+    private buildGalleryPages;
+    /** 绑定左右翻页箭头，以及点击「小工具」tag 直接跳到尾卡 */
+    private bindGalleryArrows;
+    private goToGalleryPage;
+    /** 同步轮播位移、分页徽标焦点、圆点与箭头可用态 */
+    private renderGallery;
+    /** 外链头像加载失败时回退到内置默认图 */
+    private bindAvatarFallback;
+    /** 刷新状态栏时间为当前本地时间 */
+    private updateStatusTime;
+    /** 启动状态栏时钟：立即显示并在每分钟整点刷新 */
+    private startStatusTimeClock;
+    /** 停止状态栏时钟，避免组件卸载后仍更新 DOM */
+    private stopStatusTimeClock;
+    /** 仅增量更新顶栏用户信息、封面与小工具卡片（标题/正文为骨架占位，无需更新） */
+    private renderChrome;
+    /** 增量更新笔记内小工具入口卡片（名称 / 描述 / 图标） */
+    private renderAppCard;
+}
+export declare function defineXhsNoteDetailShell(): void;
+export { TAG as XHS_NOTE_DETAIL_SHELL_TAG };

package/lib/types/native-ui/rednote-preview/xhs-note-half-sheet.d.ts

@@ -0,0 +1,100 @@
+import { type ChromeTone } from "./chrome-tone";
+import { type HalfSheetSnapState } from "./half-sheet-drag";
+declare const TAG = "xhs-note-half-sheet";
+export declare class XhsNoteHalfSheet extends HTMLElement {
+    static get observedAttributes(): string[];
+    private _bodyEl;
+    private _placeholderEl;
+    private _sheetEl;
+    private _handleEl;
+    private _fullChromeEl;
+    private _fullScreenDragZoneEl;
+    private _backBtn;
+    private _drag;
+    private _resizeObserver;
+    /** 监听 body 内 iframe 的挂载/替换，挂载后绑定 load/scroll 触发底色探测 */
+    private _iframeObserver;
+    /** 当前被探测的内容载体（iframe），用于解绑事件 */
+    private _watchedIframe;
+    private _detachIframeListeners;
+    /** 底色探测节流句柄（rAF），避免 scroll 高频触发 */
+    private _toneRafId;
+    /** 当前 chrome tone（默认浅色前景，适配深底） */
+    private _chromeTone;
+    /** 吸附态变化回调（供详情壳同步背景遮罩等外层 chrome） */
+    onSnapStateChange?: (state: HalfSheetSnapState) => void;
+    /** chrome 底色明暗变化回调（供详情壳同步状态栏时间/信号明暗） */
+    onChromeToneChange?: (tone: ChromeTone) => void;
+    /** 内部状态，勿用 attribute（改 attribute 会触发 render 并清掉已挂载的 iframe） */
+    private _hasApp;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private attachResizeObserver;
+    /**
+     * 监听 body 内载体变化：渲染器会向 .body 挂载 / 替换 iframe，
+     * 每次有 iframe 出现都重新绑定 load/scroll 并探测底色。
+     */
+    private attachIframeObserver;
+    /** 找到当前 body 内的 iframe；若与已监听的不同则重新绑定 */
+    private syncWatchedIframe;
+    private unwatchIframe;
+    /** rAF 节流的底色探测 */
+    private scheduleToneDetection;
+    private detectAndApplyTone;
+    /** 应用 chrome tone：驱动顶栏 icon 圆底/前景色与拖杆明暗，并向详情壳透传 */
+    private applyChromeTone;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** 是否全屏模式（launch-mode="fullscreen"）：初始即 full、锁定拖拽、右侧滑入/滑出 */
+    private isFullscreenMode;
+    /** 内容载体挂载容器（半屏 body 区域；载体可为 iframe 或 webview） */
+    getSheetBody(): HTMLDivElement;
+    /** 当前 sheet 吸附态（closed / half / full） */
+    getSnapState(): HalfSheetSnapState;
+    /** 唤起壳层内容：全屏模式从右侧滑入 full，半屏模式向上升起到 half（由详情页「使用」按钮触发） */
+    open(animate?: boolean): void;
+    /**
+     * 以指定吸附态唤起内容：全屏模式恒为 full（右侧滑入）；
+     * 半屏模式可指定 half / full（供宿主 `redirectTo("minitool", { sheetMode })` 使用）。
+     */
+    openAtSnap(snap: "half" | "full", animate?: boolean): void;
+    /** 关闭壳层内容，回到详情页背景（全屏模式向右滑出，半屏模式向下收起） */
+    close(animate?: boolean): void;
+    /**
+     * 收起并等待退场动画结束。用于资源超限等必须先回到笔记页、再展示宿主提示的流程。
+     * 以超时兜底处理 display/transition 被外部样式关闭的情况，保证不会阻塞主流程。
+     */
+    closeAndWait(animate?: boolean): Promise<void>;
+    /** 程序化回到半屏 */
+    collapseToHalf(animate?: boolean): void;
+    /** 模拟触摸时隐藏系统光标（与详情壳层一致，由「手指圆点」表示指针） */
+    setSimulatedCursorHidden(hidden: boolean): void;
+    setHasApp(hasApp: boolean): void;
+    setPlaceholderText(text: string): void;
+    private syncHalfHeightRatio;
+    /** 外部容器尺寸变化后调用，重新对齐 translate 偏移 */
+    refreshDragLayout(): void;
+    private applyPlaceholderText;
+    private readHeightRatio;
+    /**
+     * placeholder 与 body 都常驻 DOM 但层叠：
+     *   - body 始终 display:block，里面 iframe 永远在线（gesture overlay 也挂在这里，
+     *     若隐藏 body 会导致 hover-indicator 圆点消失）
+     *   - placeholder absolute 覆盖在 body 之上；未挂载 app 时显示，挂载后隐藏
+     */
+    private updatePlaceholderVisibility;
+    private mountDragController;
+    /** 全屏入场：sheet 从右侧屏外滑入到 0 */
+    private slideInFromRight;
+    /** 全屏退场：sheet 向右滑出后再收起高度（露出详情页背景） */
+    private slideOutToRight;
+    /**
+     * 半屏 / 全屏 chrome 切换（class 由 drag 控制器统一维护，这里仅做语义钩子位）。
+     * 半屏只有 handle；全屏显示返回按钮（status 由 detail-shell 提供）。
+     */
+    private applySnapChrome;
+    private bindFullChromeActions;
+    /** 仅首次构建 DOM；后续增量更新，避免 innerHTML 清掉 iframe */
+    private render;
+}
+export declare function defineXhsNoteHalfSheet(): void;
+export { TAG as XHS_NOTE_HALF_SHEET_TAG };

package/lib/types/native-ui/rednote-preview/xhs-profile-shell.d.ts

@@ -0,0 +1,31 @@
+import type { XhsProfilePreviewData, XhsWidgetCoverData } from "../../types";
+declare const TAG = "xhs-profile-shell";
+/**
+ * 个人页壳层（Web Component）：深色资料区（头像 / 统计 / 简介 / 组件占位）
+ * + 白色内容区（笔记/作品 tab、小工具 subtab、两列卡片瀑布流）。
+ * 「作品 → 小工具」首个卡片由 widgetCover（title / cover）驱动，用户信息来自 profilePreview.user。
+ */
+export declare class XhsProfileShell extends HTMLElement {
+    private _data;
+    private _cover;
+    private _statusTimeTimer;
+    /** 返回按钮（导航栏左侧图标）点击 → 回笔记页 */
+    onBackClick?: () => void;
+    /** 首个小工具卡片角标点击 → 唤起小工具内容 */
+    onWidgetCardClick?: () => void;
+    set widgetCover(value: XhsWidgetCoverData | null);
+    get widgetCover(): XhsWidgetCoverData | null;
+    set profilePreview(value: XhsProfilePreviewData | null);
+    get profilePreview(): XhsProfilePreviewData | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private render;
+    /** 增量更新首个小工具卡片（widgetCover）与用户名；未注入数据时首个卡片保持占位态 */
+    private renderDynamic;
+    /** 刷新状态栏时间为当前本地时间 */
+    private updateStatusTime;
+    private startStatusTimeClock;
+    private stopStatusTimeClock;
+}
+export declare function defineXhsProfileShell(): void;
+export { TAG as XHS_PROFILE_SHELL_TAG };

package/lib/types/native-ui/toast/frame-toast-host.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 手机框内 toast 控制器：挂载在 renderer 的 contentRoot 上（覆盖手机框视口，随缩放层一起缩放），
+ * 用 `position: absolute` 相对手机屏幕居中——区别于 `showHostToast` 的 `position: fixed`（相对整页视口）。
+ *
+ * 用于「假 jsapi」在手机壳内给出提示（如 openRedPage → 请前往真机调试）。
+ */
+export interface FrameToastOptions {
+    duration?: number;
+}
+/** 手机框内 toast 控制器，挂载在 contentRoot 上。 */
+export declare class FrameToastHost {
+    private readonly mountEl;
+    private container;
+    constructor(mountEl: HTMLElement);
+    private ensureContainer;
+    show(text: string, options?: FrameToastOptions): void;
+    destroy(): void;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 简单的宿主侧 toast 工具。
+ *
+ * - 默认挂在 `document.body`；传入 `root`（如 shadow root / shadow host）时挂到该根内，
+ *   保证 Shadow DOM 隔离下样式仍生效、不逸出宿主页面
+ * - 使用 `position: fixed`，不受手机壳遮罩与 iframe 沙盒影响
+ * - 多条消息纵向堆叠，自动淡入淡出
+ * - 每个挂载根共用一个容器，避免重复创建
+ */
+/** 挂载根：document.body（默认）/ shadow root / 普通元素 */
+type ToastRoot = ShadowRoot | HTMLElement;
+export interface HostToastOptions {
+    duration?: number;
+    /** 挂载根；默认 `document.body`，Shadow DOM 隔离时传 shadow root / host */
+    root?: ToastRoot;
+}
+export type HostToastFn = (text: string, options?: HostToastOptions) => void;
+export declare function showHostToast(text: string, options?: HostToastOptions): void;
+export {};

package/lib/types/presets.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 静态预设资源：设备 viewport 与手机壳贴图（原 utils/{device-presets,phone-frames}.ts 合并）。
+ */
+import type { MiniAppPhoneFrame, MiniAppViewport } from "./types";
+export declare const DEFAULT_VIEWPORT: MiniAppViewport;
+export declare const DEVICE_PRESETS: Record<string, MiniAppViewport>;
+export declare function resolveViewport(device?: string, viewport?: MiniAppViewport): MiniAppViewport;
+export declare const DEFAULT_PHONE_FRAME_ID = "iphone-14-pro-max";
+export declare const PHONE_FRAME_PRESETS: Record<string, MiniAppPhoneFrame>;
+export declare function resolvePhoneFrame(frame?: string | MiniAppPhoneFrame | false): MiniAppPhoneFrame | undefined;
+export declare function listPhoneFrames(): MiniAppPhoneFrame[];

package/lib/types/remote/client.d.ts

@@ -0,0 +1,89 @@
+import type { BusinessLine } from "../business-line";
+import type { MiniAppEventMap, MiniAppHostApiController, MiniAppHostApiEntry, MiniAppInspectorSelectionMode, MiniAppLoadFilesResult, MiniAppLoadZipResult, MiniAppPhoneFrame, MiniAppRedirectOptions, MiniAppSceneTreeSnapshot, MiniAppScreenShotResult, MiniAppSimulatorOptions, MiniAppSimulatorRoute, MiniAppViewport, VisualSelection, XhsNoteAppCardData, XhsNotePreviewData, XhsNotePreviewUser, XhsWidgetCoverData } from "../types";
+import { type RemoteLoadTiming } from "./load-timing";
+import { type RemoteMethodArgumentMap, type RemoteSimulatorGatewayOptions, type RemoteSimulatorMethod, type RemoteSimulatorReadyMessage, type RemoteSimulatorSerializableOptions } from "./protocol";
+export interface RemoteMiniAppSimulatorOptions {
+    mount: string | HTMLElement;
+    /** 模拟器服务入口；SDK 会先请求 `/runtime-manifest` 选择协议对应的 Runtime。 */
+    serviceUrl: string;
+    /** 主服务不可用时按顺序尝试的备用服务入口。 */
+    fallbackServiceUrls?: string[];
+    /** 小工具 ID；与业务线同属远端 Runtime 的基础上下文。 */
+    appId: string;
+    /** 接入平台标识；远端 Runtime 据此选择平台默认行为并写入 APM 公共字段。 */
+    businessLine: BusinessLine;
+    /** 是否启用远端 Runtime APM，默认启用。 */
+    tracker?: boolean;
+    /** 注入到 launchOptions.miniToolEnv.gateways 的宿主网关配置。 */
+    gateway?: RemoteSimulatorGatewayOptions;
+    /** 宿主自定义 bridge 行为；优先于 Runtime 按 businessLine 提供的默认行为。 */
+    hostApi?: Record<string, MiniAppHostApiEntry>;
+    /**
+     * 传给远端 Runtime 的模拟器选项（可序列化部分）。
+     * `onRouterChange` / `onScreenShot` 回调留在宿主侧绑定，事件经协议转发触发。
+     */
+    options?: RemoteSimulatorSerializableOptions & Pick<MiniAppSimulatorOptions, "onRouterChange" | "onScreenShot">;
+    timeout?: number;
+    className?: string;
+    iframeAllow?: string;
+}
+export type RemoteSimulatorEventHandler = (payload: unknown) => void;
+export interface RemoteMiniAppSimulator {
+    readonly iframe: HTMLIFrameElement;
+    readonly ready: Promise<RemoteSimulatorReadyMessage>;
+    load(): Promise<void>;
+    loadZip(source: Blob | ArrayBuffer | Uint8Array, options?: {
+        entry?: string;
+    }): Promise<MiniAppLoadZipResult>;
+    loadFiles(files: RemoteMethodArgumentMap["loadFiles"][0]["files"], options?: RemoteMethodArgumentMap["loadFiles"][0]["options"]): Promise<MiniAppLoadFilesResult>;
+    loadApp(url: string, options?: RemoteMethodArgumentMap["loadApp"][1]): Promise<void>;
+    unload(): void;
+    reload(): Promise<void>;
+    capture(options?: {
+        fullPage?: boolean;
+    }): Promise<Blob>;
+    setViewport(viewport: MiniAppViewport): void;
+    switchContentMode(mode: "half" | "fullscreen"): Promise<void>;
+    switchPhoneFrame(frame: string | MiniAppPhoneFrame | false): Promise<void>;
+    permissionSheet: {
+        show(kinds?: string[]): Promise<unknown>;
+        hide(): void;
+    };
+    notePreview: {
+        update(data: Partial<XhsNotePreviewData>): void;
+        updateUser(user: Partial<XhsNotePreviewUser>): void;
+        updateAppCard(appCard: Partial<XhsNoteAppCardData>): void;
+    };
+    /** 更新小工具封面：笔记尾卡 + 个人页卡片两处生效 */
+    widgetCover: {
+        update(data: Partial<XhsWidgetCoverData>): void;
+    };
+    redirectTo(route: MiniAppSimulatorRoute, options?: MiniAppRedirectOptions): Promise<void>;
+    getCurrentRoute(): Promise<MiniAppSimulatorRoute>;
+    /** 主动截图（完整画面）；结果同时经 screenShot 事件（source: "manual"）回调 */
+    screenShot(): Promise<MiniAppScreenShotResult>;
+    /**
+     * 控制部署完成后是否自动截图并更新小工具封面。默认开启。
+     * 已有手动或历史封面时，传入 `false` 可在后续部署中保留当前封面。
+     */
+    setAutoScreenShot(flag: boolean): Promise<void>;
+    inspector: {
+        enable(): void;
+        disable(): void;
+        toggle(): void;
+        isEnabled(): boolean;
+        clear(): void;
+        setSelectionMode(mode: MiniAppInspectorSelectionMode): void;
+        getSelectionMode(): MiniAppInspectorSelectionMode;
+        getSceneTree(): Promise<MiniAppSceneTreeSnapshot>;
+        selectByRef(ref: string): Promise<VisualSelection | null>;
+    };
+    hostApi: MiniAppHostApiController;
+    invoke<M extends RemoteSimulatorMethod>(method: M, ...args: RemoteMethodArgumentMap[M]): Promise<unknown>;
+    on<E extends keyof MiniAppEventMap>(event: E, handler: (payload: MiniAppEventMap[E]) => void): () => void;
+    on(event: string, handler: RemoteSimulatorEventHandler): () => void;
+    destroy(reason?: string): void;
+}
+export declare function createRemoteMiniAppSimulator(input: RemoteMiniAppSimulatorOptions): RemoteMiniAppSimulator;
+/** @internal Exported for deterministic retry tests; not part of the package public entry. */
+export declare function resolveRuntimeUrl(serviceUrls: URL[], loadTiming: RemoteLoadTiming): Promise<URL>;

package/lib/types/remote/jsapi-config.d.ts

@@ -0,0 +1,9 @@
+import type { MiniAppHostApiEntry, MiniAppUnsupportedJsApiBehavior } from "../types";
+type RemoteJsApiNotice = MiniAppUnsupportedJsApiBehavior;
+export type RemoteJsApiConfig = Record<string, RemoteJsApiNotice>;
+/** Server 透传通用 JSON；具体 JSAPI 提示语义只在 Runtime 解析。 */
+export declare function parseRemoteJsApiConfig(input: unknown): RemoteJsApiConfig | undefined;
+export declare function getUnsupportedJsApiBehavior(config?: RemoteJsApiConfig): MiniAppUnsupportedJsApiBehavior | undefined;
+/** `unsupported` 是统一兜底，其余 key 是可覆盖任意 API 的精确配置。 */
+export declare function createConfiguredJsApiHostApi(config?: RemoteJsApiConfig, businessLine?: string): Record<string, MiniAppHostApiEntry>;
+export {};

package/lib/types/remote/load-timing.d.ts

@@ -0,0 +1,46 @@
+import type { BusinessLine } from "../business-line";
+export interface RemoteLoadTiming {
+    report(stage: string, fields?: RemoteLoadTimingFields): void;
+    flush(): void;
+}
+/**
+ * 加载点位只使用这一组通用字段，避免每增加一个阶段就登记一套字段。
+ * 阶段差异统一放在低基数的 stage 中。
+ */
+export interface RemoteLoadTimingFields {
+    result?: string;
+    duration?: number;
+    type?: string;
+    count?: number;
+    bytes?: number;
+    network_duration?: number;
+    dns_duration?: number;
+    connect_duration?: number;
+    ttfb_duration?: number;
+    runtime_version?: string;
+    request_id?: string;
+    code?: number;
+    error_name?: string;
+    message?: string;
+}
+export interface RemoteLoadTimingOptions {
+    enabled: boolean;
+    businessLine: BusinessLine;
+    appId: string;
+    sessionId: string;
+    runtimeVersion?: string;
+    resolveUserId?: () => Promise<string>;
+}
+/**
+ * 远程模拟器启动链路复用统一加载点位，避免扩展 MessageChannel 消息并触发协议升级。
+ * client/runtime/core 通过协议中已有的 sessionId 关联，stage 用于按阶段聚合 P50/P95/P99。
+ */
+export declare function createRemoteLoadTiming(options: RemoteLoadTimingOptions): RemoteLoadTiming;
+export declare function timingNow(): number;
+export declare function elapsedMs(startedAt: number): number;
+/**
+ * Resource Timing 可用时补齐通用网络分段字段。
+ * 没有 TAO 或浏览器拒绝读取时直接放弃，不影响主链路。
+ */
+export declare function reportResourceTiming(timing: RemoteLoadTiming, stage: string, url: string, fields?: RemoteLoadTimingFields): void;
+export declare function navigationTimingFields(): RemoteLoadTimingFields;