@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.0

package/lib/types/types/renderer.d.ts

@@ -0,0 +1,145 @@
+import type { InjectionRegistry } from "../injection/registry";
+import type { NotePublishResult, NotePublishViewData } from "../native-ui/note-publish/view-data";
+import type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from "../native-ui/permission-sheet/types";
+import type { BridgeInvokeResult, BridgeProtocol } from "../transport/bridge-protocol";
+import type { Transport } from "../transport/types";
+import type { MiniAppEventHandler, MiniAppEventName } from "./events";
+import type { GestureDispatchInput, GestureDispatchResult, GestureHostPluginLike, MiniAppContentMode, MiniAppPhoneFrame, MiniAppSimulatorRoute, MiniAppViewport, NormalizedMiniAppJsApiOptions, NormalizedMiniAppSecurityOptions, NormalizedMiniAppSimulatorOptions, NormalizedRednoteDetailSheetOptions, XhsNotePreviewData, XhsProfilePreviewData, XhsWidgetCoverData } from "./options";
+/**
+ * 渲染器接口（原 types.ts 段落 3）。
+ */
+export interface RendererAdapter {
+    /**
+     * jsapi 协议解析器；mount 完成后由 renderer 创建，destroy 时回收。
+     * simulator / native-ui 路由模块通过这个引用注册内置 jsapi handler 或主动 emit 事件。
+     */
+    readonly bridge: BridgeProtocol | null;
+    /** mount 可同步（iframe）或异步（webview 需物化 preload）；调用方应统一 await */
+    mount(container: HTMLElement): void | Promise<void>;
+    load(url: string): Promise<void>;
+    reload(): Promise<void>;
+    /** 销毁当前 Guest 运行环境，但保留模拟器外壳与未部署占位态。 */
+    unload?(): void;
+    resize(viewport: MiniAppViewport): void;
+    /**
+     * 设置渲染缩放系数（仅 webview 渲染器实现：调用 guest `webContents.setZoomFactor`）。
+     * iframe 渲染器的缩放由 stageFit（CSS transform）负责，此处不实现。
+     */
+    setZoomFactor?(factor: number): void;
+    capture?(): Promise<Blob>;
+    /** 调用受控的游戏测试桥；不暴露任意 executeJavaScript。 */
+    invokeGamePlaytest?(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    destroy(): void;
+    /** 注册手势 plugin（iframe + touchEmulation 时生效） */
+    dispatchGesture?(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    useGesturePlugin?(plugin: GestureHostPluginLike): void;
+    /** 卸载手势 plugin */
+    removeGesturePlugin?(name: string): boolean;
+    /** 是否已注册某个手势 plugin */
+    hasGesturePlugin?(name: string): boolean;
+    /** 列出所有已注册的手势 plugin 名称 */
+    listGesturePlugins?(): string[];
+    /**
+     * 开关手势 overlay 的 pointer-events（不影响 TouchCursor 视觉，仅释放/截获鼠标）。
+     * DevTools 元素审查、Permission Sheet 等场景需设为 false，让点击穿透到 webview/iframe。
+     */
+    setGestureOverlayInteractionEnabled?(enabled: boolean): void;
+    /** 开启可视化元素选取（iframe + 同源可访问时生效） */
+    enableInspector?(): void;
+    /** 关闭可视化元素选取 */
+    disableInspector?(): void;
+    /** 清除当前选中高亮（保持选取模式开启） */
+    clearInspectorSelection?(): void;
+    /** 设置可视化选取为单选 / 多选 */
+    setInspectorSelectionMode?(mode: import("./inspector").MiniAppInspectorSelectionMode): void;
+    /** 获取 Guest Scene Provider 的只读层级树。 */
+    getInspectorSceneTree?(): Promise<import("./inspector").MiniAppSceneTreeSnapshot>;
+    /** 从 Hierarchy 反向选中场景节点。 */
+    selectInspectorByRef?(ref: string): Promise<import("./inspector").VisualSelection | null>;
+    /** 同步 REDNote 壳层数据（iframe 与 webview 渲染器均实现，经 RednoteShellMount 共享） */
+    syncRednotePreviewContext?(notePreview: XhsNotePreviewData, rednoteDetail: NormalizedRednoteDetailSheetOptions): void;
+    /** 同步个人页数据（rednote 壳渲染器实现） */
+    syncProfilePreviewContext?(profilePreview: XhsProfilePreviewData): void;
+    /** 同步小工具封面（笔记尾卡 + 个人页卡片两处生效，rednote 壳渲染器实现） */
+    syncWidgetCoverContext?(widgetCover: XhsWidgetCoverData): void;
+    /** 切换壳层活动页：note 笔记页 / profile 个人页（rednote 壳渲染器实现） */
+    setActivePage?(page: Extract<MiniAppSimulatorRoute, "note" | "profile">): void;
+    /** 唤起小工具内容（先过壳层准入检查）；sheetMode 指定半屏 / 全屏（rednote 壳渲染器实现） */
+    openContent?(sheetMode: "half" | "full"): void;
+    /** 收起小工具内容并等待退场（rednote 壳渲染器实现） */
+    closeContent?(): Promise<void>;
+    showPermissionSheet?(kinds?: MiniAppPermissionKind[]): Promise<MiniAppPermissionSheetResult>;
+    hidePermissionSheet?(): void;
+    showNotePublish?(data: NotePublishViewData): Promise<NotePublishResult>;
+    hideNotePublish?(): void;
+    /** 在手机框内（contentRoot）居中展示一条 toast，随手机屏幕缩放；用于「假 jsapi」提示。 */
+    showToast?(text: string, options?: {
+        duration?: number;
+    }): void;
+    /**
+     * 开关小应用 DevTools。
+     * 仅 webview 渲染器实现（独立 webContents 可 `openDevTools()`）；
+     * iframe 渲染器与宿主同进程，DevTools 由宿主整窗负责，此处不实现。
+     */
+    setDevtools?(open: boolean): void;
+    /** 当前小应用 DevTools 是否打开（仅 webview 渲染器实现） */
+    isDevtoolsOpen?(): boolean;
+    /**
+     * 返回小应用渲染容器的 webContents id（仅 webview 渲染器实现，dom-ready 后可用）。
+     * 宿主可据此在主进程把真 Chrome DevTools 嵌入自定义面板（setDevToolsWebContents）。
+     */
+    getWebContentsId?(): number | null;
+    on<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+}
+export interface RendererAdapterContext {
+    viewport: MiniAppViewport;
+    phoneFrame?: MiniAppPhoneFrame;
+    sandboxFlags: string;
+    timeout: number;
+    debug: boolean;
+    /** 是否启用鼠标→触摸事件模拟 */
+    touchEmulation?: boolean;
+    /** jsapi 注入与 mock 配置 */
+    jsapi: NormalizedMiniAppJsApiOptions;
+    contentMode: MiniAppContentMode;
+    notePreview: XhsNotePreviewData;
+    profilePreview?: XhsProfilePreviewData;
+    widgetCover?: XhsWidgetCoverData;
+    rednoteDetail: NormalizedRednoteDetailSheetOptions;
+    /**
+     * 壳层路由变化（笔记页头像点击 → profile / 个人页返回 → note / 卡片点击与 sheet 开合 → minitool / "back"）。
+     * "back" 表示小工具内容收起，由上层回落到当前活动页。
+     */
+    onShellRouteChange?: (to: MiniAppSimulatorRoute | "back") => void;
+    /** iframe 设备能力白名单与子文档封印；webview 渲染器仅占位不传参使用 */
+    security: NormalizedMiniAppSecurityOptions;
+    /**
+     * 宿主侧 overlay 挂载根（shadow root 或 host 元素）。
+     * native-ui（toast / permission-sheet / rednote-preview）需要它来挂自己的 DOM，
+     * 保证盖在 iframe/webview 之上且不逸出 shadow 隔离。
+     */
+    overlayRoot?: ShadowRoot | HTMLElement;
+    /** gesture 悬停圆点：跨 Shadow 边界的 light DOM 移入监听（shadow host） */
+    gestureHoverEnterTarget?: HTMLElement;
+    /**
+     * 注入清单：由 kernel 创建并填入 security / jsapi / render-done 等内置模块。
+     * renderer 在 load() 时调 `assembleHeadInjection(injection, ...)`（SW 直供 head）或
+     * `buildWebviewPreloadSource(injection, ...)`（webview preload）完成介质适配。
+     */
+    injection: InjectionRegistry;
+    /**
+     * 归一化后的完整 options。InjectionModule 的 build 函数需要它做条件判断
+     * （是否启用 jsapi/seal，何种 mode 等）。
+     */
+    normalizedOptions: NormalizedMiniAppSimulatorOptions;
+    /**
+     * 通信通道：由 Kernel 创建，注入给 Renderer。
+     * Renderer 在 mount 阶段 `attach(element)` 绑定到 DOM 元素。
+     * 仅当 jsapi 启用时存在。
+     */
+    transport?: Transport;
+    /** bridge 调用完成回调（Tracker 注入），供 BridgeProtocol onInvoke */
+    onBridgeInvoke?: (result: BridgeInvokeResult) => void;
+    /** SW 虚拟 URL 重新加载前恢复代理挂载（仅 iframe-service-worker 使用）。 */
+    restoreServiceWorkerMount?: (url: string) => Promise<void>;
+}

package/lib/types/utils/ancestor-scroll.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 宿主滚动位置快照。
+ *
+ * 模拟器被嵌进宿主页时，任何「把焦点交给 guest」的动作都可能让浏览器为了显示
+ * 获得焦点的元素而沿祖先链滚动，宿主页于是被小应用拽走。带 preventScroll 的
+ * `HTMLElement.focus()` 能规避，但 `Window.focus()` 没有这个选项。
+ *
+ * 这里在焦点转移前记下所有祖先滚动容器（含文档滚动）的位置，转移后立即还原：
+ * 焦点照常进入 guest，键盘输入与无障碍语义不受影响，宿主页的滚动位置保持不动。
+ */
+export declare function captureAncestorScroll(element: Element): () => void;

package/lib/types/utils/error-svg.d.ts

@@ -0,0 +1,12 @@
+/** @deprecated 请改用 `./miniapp-chrome-svg` */
+export { DEFAULT_MINIAPP_PLACEHOLDER_TEXT, MINIAPP_CHROME_BACK_SVG, MINIAPP_CHROME_BATTERY_SVG, MINIAPP_CHROME_MOBILE_SIGNAL_SVG, MINIAPP_CHROME_SHARE_SVG, MINIAPP_CHROME_WIFI_SVG, MINIAPP_UNDEPLOYED_ICON_SIZE, MINIAPP_UNDEPLOYED_ICON_SVG, MINIAPP_UNDEPLOYED_ICON_VIEWBOX, } from "./miniapp-chrome-svg";
+/** @deprecated 使用 MINIAPP_CHROME_BACK_SVG */
+export { MINIAPP_CHROME_BACK_SVG as back } from "./miniapp-chrome-svg";
+/** @deprecated 使用 MINIAPP_CHROME_SHARE_SVG */
+export { MINIAPP_CHROME_SHARE_SVG as share } from "./miniapp-chrome-svg";
+/** @deprecated 使用 MINIAPP_CHROME_WIFI_SVG */
+export { MINIAPP_CHROME_WIFI_SVG as wifi } from "./miniapp-chrome-svg";
+/** @deprecated 使用 MINIAPP_CHROME_MOBILE_SIGNAL_SVG */
+export { MINIAPP_CHROME_MOBILE_SIGNAL_SVG as mobileSignal } from "./miniapp-chrome-svg";
+/** @deprecated 使用 MINIAPP_CHROME_BATTERY_SVG */
+export { MINIAPP_CHROME_BATTERY_SVG as battery } from "./miniapp-chrome-svg";

package/lib/types/utils/frameless-shell.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 无手机壳模式下的标准设备边框。
+ *
+ * 数值与媒体查询对齐创作发布：
+ * - ImagePreview/Index.vue `.image-preview`
+ * - CoverPreview/Index.vue `.cover`
+ * - VideoPreview/Index.vue `.video-preview-wrapper`
+ * - AudioLayout.vue 预览栏宽度分档（208 / 260 / 312 / 344 / 409）
+ *
+ * 分档依据浏览器窗口宽度（与 Vue `@media` 一致）；无 window 时按逻辑 viewport 宽映射。
+ * 选定分档后，再按 `viewport.height / tier.shellHeight` 缩放到逻辑视口高度。
+ */
+import type { MiniAppViewport } from "../types";
+/** 对齐 publish-components StyleOverride：`--color-text-paragraph` */
+export declare const FRAMELESS_SHELL_BORDER_COLOR = "rgba(0, 0, 0, 0.65)";
+/** 对齐 ImagePreview / CoverPreview 默认内容区背景 */
+export declare const FRAMELESS_SHELL_BACKGROUND = "#fff";
+/**
+ * 创作发布预览框分档（与 Vue 源 `@media` + AudioLayout 预览栏宽度一致）。
+ * `minWindow`：该档起始窗口宽度；`panelWidth`：对应 `.publish-page-preview` 宽度。
+ */
+export declare const FRAMELESS_SHELL_TIERS: readonly [{
+    readonly id: "s";
+    readonly minWindow: 0;
+    readonly panelWidth: 208;
+    readonly shellHeight: 442;
+    readonly borderRadius: 26.463;
+    readonly borderWidth: 4;
+}, {
+    readonly id: "m";
+    readonly minWindow: 1440;
+    readonly panelWidth: 260;
+    readonly shellHeight: 552;
+    readonly borderRadius: 33;
+    readonly borderWidth: 5;
+}, {
+    readonly id: "l";
+    readonly minWindow: 1680;
+    readonly panelWidth: 312;
+    readonly shellHeight: 662;
+    readonly borderRadius: 40;
+    readonly borderWidth: 6;
+}, {
+    readonly id: "xl";
+    readonly minWindow: 1920;
+    readonly panelWidth: 344;
+    readonly shellHeight: 729;
+    readonly borderRadius: 44;
+    readonly borderWidth: 7;
+}, {
+    readonly id: "xxl";
+    readonly minWindow: 2285;
+    readonly panelWidth: 409;
+    readonly shellHeight: 868;
+    readonly borderRadius: 52;
+    readonly borderWidth: 8;
+}];
+export type FramelessShellTierId = (typeof FRAMELESS_SHELL_TIERS)[number]["id"];
+export interface FramelessShellTier {
+    id: FramelessShellTierId;
+    minWindow: number;
+    panelWidth: number;
+    shellHeight: number;
+    borderRadius: number;
+    borderWidth: number;
+}
+export interface FramelessShellMetrics {
+    tierId: FramelessShellTierId;
+    borderWidth: number;
+    borderRadius: number;
+    borderColor: string;
+    background: string;
+    /** 相对分档基准高度的缩放比 */
+    heightScale: number;
+}
+export interface FramelessShellResolveOptions {
+    /** 对齐 Vue `@media` 的窗口宽度；缺省取 `window.innerWidth` */
+    windowWidth?: number;
+}
+/** @deprecated 保留导出兼容；请使用 FRAMELESS_SHELL_TIERS */
+export declare const FRAMELESS_SHELL_BASE: {
+    readonly viewportWidth: 260;
+    readonly borderRadius: 33;
+    readonly borderWidth: 5;
+    readonly borderColor: "rgba(0, 0, 0, 0.65)";
+    readonly background: "#fff";
+};
+/** 按创作发布 `@media (min-width: …)` 窗口宽度选档 */
+export declare function resolveFramelessShellTierByWindow(windowWidth: number): FramelessShellTier;
+/** 无 window 时：按逻辑 viewport 宽在预览栏宽度分档间插值 */
+export declare function resolveFramelessShellTierByViewportWidth(viewportWidth: number): {
+    borderRadius: number;
+    borderWidth: number;
+    shellHeight: number;
+    tierId: FramelessShellTierId;
+};
+/** 解析无壳标准边框尺寸（创作发布 UI 走查对齐入口） */
+export declare function resolveFramelessShellMetrics(viewport: MiniAppViewport, options?: FramelessShellResolveOptions): FramelessShellMetrics;
+/** 无手机壳时容器外框尺寸（含 border，content-box） */
+export declare function getFramelessShellOuterSize(viewport: MiniAppViewport, options?: FramelessShellResolveOptions): {
+    width: number;
+    height: number;
+};
+/** 将创作发布标准边框应用到模拟器根容器（仅 `phoneFrame` 未设置时调用） */
+export declare function applyFramelessShellContainer(container: HTMLElement, viewport: MiniAppViewport, options?: FramelessShellResolveOptions): FramelessShellMetrics;
+/** 内容层内圆角（= 外圆角 − 边框厚度），保证 REDNote / iframe 内容贴边裁剪 */
+export declare function applyFramelessShellContentRoot(contentRoot: HTMLElement, shell: FramelessShellMetrics): void;
+/** 清除无壳标准边框（切回贴图手机壳时） */
+export declare function clearFramelessShellContainer(container: HTMLElement): void;
+export declare function clearFramelessShellContentRoot(contentRoot: HTMLElement): void;
+/**
+ * 监听 window resize 以同步 Vue `@media` 分档；返回卸载函数。
+ */
+export declare function attachFramelessShellWindowSync(container: HTMLElement, contentRoot: HTMLElement | null, getViewport: () => MiniAppViewport): () => void;

package/lib/types/utils/miniapp-chrome-svg.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 小应用模拟器 REDNote chrome 静态 SVG 资源：
+ * - 半屏占位插画
+ * - 全屏态 status / nav 图标（back / share / signal / wifi / battery）
+ * - 笔记详情底部互动栏图标（点赞 / 收藏 / 评论 / 写评论）
+ *
+ * 约定：所有常量均为可直接 innerHTML 注入的 SVG 字符串。
+ */
+/** 半屏占位默认提示文案 */
+export declare const DEFAULT_MINIAPP_PLACEHOLDER_TEXT = "\u90E8\u7F72\u6210\u529F\u540E\u53EF\u9884\u89C8";
+export declare const MINIAPP_UNDEPLOYED_ICON_SIZE: {
+    readonly width: 108;
+    readonly height: 73;
+};
+export declare const MINIAPP_UNDEPLOYED_ICON_VIEWBOX = "0 0 108 73";
+/** 手绘浏览器 + 眼睛插画，可直接 innerHTML 注入 */
+export declare const MINIAPP_UNDEPLOYED_ICON_SVG: string;
+/** 全屏态 nav：返回 */
+export declare const MINIAPP_CHROME_BACK_SVG = "<svg width=\"10\" height=\"20\" viewBox=\"0 0 10 20\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><path d=\"M2.38154 9.58986C2.30774 9.67252 2.30769 9.79882 2.38144 9.88154L9.50124 17.8683C9.85679 18.2672 9.82773 18.8842 9.43633 19.2465C9.04493 19.6088 8.43941 19.5792 8.08386 19.1804L0.248749 10.3912C-0.0831022 10.0189 -0.0828921 9.45059 0.249234 9.07859L8.06971 0.319091C8.42555 -0.0794786 9.03109 -0.108629 9.42222 0.253981C9.81335 0.616592 9.84196 1.23365 9.48612 1.63222L2.38154 9.58986Z\" fill=\"black\" fill-opacity=\"0.8\"/></svg>";
+/** 全屏态 nav：分享 */
+export declare const MINIAPP_CHROME_SHARE_SVG = "<svg width=\"22\" height=\"20\" viewBox=\"0 0 22 20\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><path d=\"M11.2986 5.67284C11.2986 5.97893 11.085 6.24354 10.7859 6.30818L10.0168 6.47435C7.99248 6.91173 5.77167 7.9941 4.13622 9.86952C2.72423 11.4887 1.6758 13.7798 1.62674 16.9708C3.27106 14.4059 5.66007 12.278 9.31215 11.4448L10.504 11.1729C10.9109 11.0801 11.2986 11.3893 11.2986 11.8066V16.1091C11.2986 16.3883 11.6275 16.5376 11.8376 16.3537L19.9263 9.27602C20.0743 9.14654 20.0743 8.91633 19.9263 8.78684L11.8376 1.70921C11.6275 1.52534 11.2986 1.67456 11.2986 1.9538V5.67284ZM20.9964 7.56391C21.8843 8.34081 21.8843 9.72205 20.9964 10.499L12.9077 17.5766C11.6468 18.6799 9.67359 17.7845 9.67359 16.1091V13.0291C9.09667 13.1607 8.55598 13.3292 8.04859 13.5306C5.44688 14.5636 3.72051 16.465 2.47251 18.7261C1.84869 19.8563 0.131189 19.728 0.0429597 18.44C-0.547868 9.8153 5.07299 5.88002 9.67359 4.88601V1.9538C9.67359 0.278437 11.6468 -0.616962 12.9077 0.486268L20.9964 7.56391Z\" fill=\"black\" fill-opacity=\"0.8\"/></svg>";
+/** 半屏拖全后顶部 chrome：返回（32×32 半透明圆底） */
+export declare const MINIAPP_HALF_SHEET_FULL_BACK_SVG = "<svg width=\"32\" height=\"32\" viewBox=\"0 0 32 32\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><rect width=\"32\" height=\"32\" rx=\"16\" fill=\"var(--mas-chrome-circle, rgba(0,0,0,0.27))\"/><path d=\"M14.082 15.8768C14.0252 15.9404 14.0251 16.0376 14.0819 16.1012L19.5586 22.2449C19.8321 22.5517 19.8098 23.0263 19.5087 23.305C19.2076 23.5837 18.7419 23.5609 18.4684 23.2541L12.4413 16.4932C12.1861 16.2069 12.1862 15.7697 12.4417 15.4835L18.4575 8.74545C18.7312 8.43886 19.197 8.41644 19.4979 8.69537C19.7987 8.9743 19.8207 9.44896 19.547 9.75555L14.082 15.8768Z\" fill=\"var(--mas-chrome-fg, #fff)\"/></svg>";
+/** 半屏拖全后顶部 chrome：分享（32×32 半透明圆底） */
+export declare const MINIAPP_HALF_SHEET_FULL_SHARE_SVG = "<svg width=\"32\" height=\"32\" viewBox=\"0 0 32 32\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><rect width=\"32\" height=\"32\" rx=\"16\" fill=\"var(--mas-chrome-circle, rgba(0,0,0,0.27))\"/><path d=\"M15.9534 13.3094C16.1845 13.2605 16.3499 13.0565 16.3499 12.8202V9.92041C16.3499 9.63317 16.689 9.48043 16.9041 9.67074L23.1371 15.1846C23.2871 15.3172 23.2871 15.5512 23.1371 15.6839L16.9041 21.1977C16.689 21.388 16.3499 21.2353 16.3499 20.948V17.4338C16.3499 17.1206 16.0652 16.8845 15.7574 16.9424L14.5725 17.1654C12.0387 17.6423 10.1764 19.018 8.75756 20.8225C8.83972 18.7314 9.57906 17.18 10.5879 16.0467C11.8143 14.6688 13.5183 13.8244 15.1603 13.4771L15.9534 13.3094ZM14.8499 20.948C14.8499 22.5279 16.7147 23.368 17.898 22.3212L24.131 16.8074C24.9558 16.0777 24.9558 14.7907 24.131 14.0611L17.898 8.54725C16.7147 7.5005 14.8499 8.34059 14.8499 9.92041V12.0096C11.0594 12.8112 6.80807 15.9291 7.28708 22.1643C7.3705 23.2502 8.78908 23.3974 9.39657 22.4935C10.4307 20.9549 11.6992 19.7501 13.3499 19.0781C13.8181 18.8876 14.3169 18.7399 14.8499 18.6395V20.948Z\" fill=\"var(--mas-chrome-fg, #fff)\"/></svg>";
+/** 半屏拖全后顶部 chrome：更多（32×32 半透明圆底） */
+export declare const MINIAPP_HALF_SHEET_FULL_MORE_SVG = "<svg width=\"32\" height=\"32\" viewBox=\"0 0 32 32\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><rect width=\"32\" height=\"32\" rx=\"16\" fill=\"var(--mas-chrome-circle, rgba(0,0,0,0.27))\"/><path d=\"M11 16C11 16.6903 10.4403 17.25 9.75 17.25C9.05972 17.25 8.5 16.6903 8.5 16C8.5 15.3097 9.05972 14.75 9.75 14.75C10.4403 14.75 11 15.3097 11 16Z\" fill=\"var(--mas-chrome-fg, #fff)\"/><path d=\"M17.25 16C17.25 16.6903 16.6903 17.25 16 17.25C15.3097 17.25 14.75 16.6903 14.75 16C14.75 15.3097 15.3097 14.75 16 14.75C16.6903 14.75 17.25 15.3097 17.25 16Z\" fill=\"var(--mas-chrome-fg, #fff)\"/><path d=\"M22.2502 17.25C22.9406 17.25 23.5 16.6906 23.5 16.0002C23.5 15.3098 22.9406 14.75 22.2502 14.75C21.5598 14.75 21 15.3098 21 16.0002C21 16.6906 21.5598 17.25 22.2502 17.25Z\" fill=\"var(--mas-chrome-fg, #fff)\"/></svg>";
+/** 全屏态 status：WiFi */
+export declare const MINIAPP_CHROME_WIFI_SVG = "<svg width=\"18\" height=\"13\" viewBox=\"0 0 18 13\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M8.5713 2.46628C11.0584 2.46639 13.4504 3.38847 15.2529 5.04195C15.3887 5.1696 15.6056 5.16799 15.7393 5.03834L17.0368 3.77487C17.1045 3.70911 17.1422 3.62004 17.1417 3.52735C17.1411 3.43467 17.1023 3.34603 17.0338 3.28104C12.3028 -1.09368 4.83907 -1.09368 0.108056 3.28104C0.039524 3.34598 0.000639766 3.4346 7.82398e-06 3.52728C-0.000624118 3.61996 0.0370483 3.70906 0.104689 3.77487L1.40255 5.03834C1.53615 5.16819 1.75327 5.1698 1.88893 5.04195C3.69167 3.38836 6.08395 2.46628 8.5713 2.46628ZM8.56795 6.68656C9.92527 6.68647 11.2341 7.19821 12.2403 8.12234C12.3763 8.2535 12.5907 8.25065 12.7234 8.11593L14.0106 6.79663C14.0784 6.72742 14.1161 6.63355 14.1151 6.536C14.1141 6.43844 14.0746 6.34536 14.0054 6.27757C10.9416 3.38672 6.19688 3.38672 3.13305 6.27757C3.06384 6.34536 3.02435 6.43849 3.02345 6.53607C3.02254 6.63366 3.06028 6.72752 3.12822 6.79663L4.41513 8.11593C4.54778 8.25065 4.76215 8.2535 4.89823 8.12234C5.90368 7.19882 7.21152 6.68713 8.56795 6.68656ZM11.0924 9.48011C11.0943 9.58546 11.0572 9.68703 10.9899 9.76084L8.81327 12.2156C8.74946 12.2877 8.66247 12.3283 8.5717 12.3283C8.48093 12.3283 8.39394 12.2877 8.33013 12.2156L6.1531 9.76084C6.08585 9.68697 6.04886 9.58537 6.05085 9.48002C6.05284 9.37467 6.09365 9.27491 6.16364 9.20429C7.55374 7.8904 9.58966 7.8904 10.9798 9.20429C11.0497 9.27497 11.0904 9.37476 11.0924 9.48011Z\" fill=\"currentColor\"/></svg>";
+/** 全屏态 status：蜂窝信号（四格柱状） */
+export declare const MINIAPP_CHROME_MOBILE_SIGNAL_SVG = "<svg width=\"20\" height=\"13\" viewBox=\"0 0 20 13\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M19.2 1.14623C19.2 0.513183 18.7224 0 18.1333 0H17.0667C16.4776 0 16 0.513183 16 1.14623V11.0802C16 11.7132 16.4776 12.2264 17.0667 12.2264H18.1333C18.7224 12.2264 19.2 11.7132 19.2 11.0802V1.14623ZM11.7659 2.44528H12.8326C13.4217 2.44528 13.8992 2.97078 13.8992 3.61902V11.0527C13.8992 11.7009 13.4217 12.2264 12.8326 12.2264H11.7659C11.1768 12.2264 10.6992 11.7009 10.6992 11.0527V3.61902C10.6992 2.97078 11.1768 2.44528 11.7659 2.44528ZM7.43411 5.09433H6.36745C5.77834 5.09433 5.30078 5.62652 5.30078 6.28301V11.0377C5.30078 11.6942 5.77834 12.2264 6.36745 12.2264H7.43411C8.02322 12.2264 8.50078 11.6942 8.50078 11.0377V6.28301C8.50078 5.62652 8.02322 5.09433 7.43411 5.09433ZM2.13333 7.53962H1.06667C0.477563 7.53962 0 8.06421 0 8.71132V11.0547C0 11.7018 0.477563 12.2264 1.06667 12.2264H2.13333C2.72244 12.2264 3.2 11.7018 3.2 11.0547V8.71132C3.2 8.06421 2.72244 7.53962 2.13333 7.53962Z\" fill=\"currentColor\"/></svg>";
+/** 全屏态 status：电池 */
+export declare const MINIAPP_CHROME_BATTERY_SVG = "<svg width=\"25\" height=\"12\" viewBox=\"0 0 25 12\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" aria-hidden=\"true\"><path opacity=\"0.35\" d=\"M2.66699 0.5H19.333C20.5296 0.5 21.5 1.47038 21.5 2.66699V8.66699C21.4998 9.86346 20.5295 10.833 19.333 10.833H2.66699C1.47048 10.833 0.500176 9.86346 0.5 8.66699V2.66699L0.510742 2.44531C0.621596 1.35265 1.54509 0.5 2.66699 0.5Z\" stroke=\"currentColor\"/><path opacity=\"0.4\" d=\"M23 3.6665V7.6665C23.8047 7.32773 24.328 6.53964 24.328 5.6665C24.328 4.79337 23.8047 4.00528 23 3.6665Z\" fill=\"currentColor\"/><path d=\"M2 3.33333C2 2.59695 2.59695 2 3.33333 2H18.6667C19.403 2 20 2.59695 20 3.33333V8C20 8.73638 19.403 9.33333 18.6667 9.33333H3.33333C2.59695 9.33333 2 8.73638 2 8V3.33333Z\" fill=\"currentColor\"/></svg>";
+/** 图片轮播：向前翻页箭头（白色 chevron，外层圆底由 CSS 提供） */
+export declare const MINIAPP_GALLERY_ARROW_PREV_SVG = "<svg width=\"7\" height=\"12\" viewBox=\"0 0 7 12\" fill=\"none\" aria-hidden=\"true\"><path d=\"M6.28 0.72a1 1 0 0 1 0 1.41L2.41 6l3.87 3.87a1 1 0 1 1-1.41 1.41L0.29 6.71a1 1 0 0 1 0-1.42L4.87 0.72a1 1 0 0 1 1.41 0Z\" fill=\"#fff\"/></svg>";
+/** 图片轮播：向后翻页箭头（白色 chevron，外层圆底由 CSS 提供） */
+export declare const MINIAPP_GALLERY_ARROW_NEXT_SVG = "<svg width=\"7\" height=\"12\" viewBox=\"0 0 7 12\" fill=\"none\" aria-hidden=\"true\"><path d=\"M0.72 0.72a1 1 0 0 1 1.41 0l4.58 4.57a1 1 0 0 1 0 1.42l-4.58 4.57a1 1 0 1 1-1.41-1.41L4.59 6 0.72 2.13a1 1 0 0 1 0-1.41Z\" fill=\"#fff\"/></svg>";
+/** 图片轮播小工具页浮层按钮前缀图标（断链 / bx-link-break） */
+export declare const MINIAPP_WIDGET_ENTRY_SVG = "<svg width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.8\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"m18.84 12.25 1.72-1.71a4.5 4.5 0 0 0-6.36-6.37l-1.72 1.72\"/><path d=\"m5.17 11.75-1.71 1.71a4.5 4.5 0 0 0 6.36 6.37l1.72-1.72\"/><path d=\"M8 2v3\"/><path d=\"M2 8h3\"/><path d=\"M16 22v-3\"/><path d=\"M22 16h-3\"/></svg>";
+/** 底部互动栏：点赞（心形，纯图标） */
+export declare const LIKE = "<svg width=\"26\" height=\"26\" viewBox=\"0 0 26 26\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M5.12701 6.16137L5.12684 6.16153C3.19177 8.07231 3.18948 11.1684 5.12171 13.0829C5.12195 13.0831 5.12219 13.0833 5.12243 13.0836L12.5956 20.4651L20.0639 13.0896C20.0642 13.0893 20.0645 13.089 20.0648 13.0887C22.003 11.1683 22.0001 8.07222 20.0655 6.16137C19.1221 5.22951 17.8626 4.72335 16.5498 4.72335C15.4589 4.72335 14.4068 5.07235 13.5423 5.72249L12.5963 6.43401L11.65 5.72281C10.7846 5.07238 9.73221 4.72335 8.64208 4.72335C7.32916 4.72335 6.07077 5.22917 5.12701 6.16137ZM21.1718 14.2083L13.6959 21.5913C13.0874 22.1923 12.1054 22.1923 11.4953 21.5913L4.01453 14.2022C1.45912 11.6714 1.46146 7.56825 4.02061 5.04124C5.26382 3.81327 6.92169 3.14893 8.64208 3.14893C10.0698 3.14893 11.4549 3.60663 12.596 4.46423C13.7364 3.60647 15.1215 3.14893 16.5498 3.14893C18.2699 3.14893 19.9289 3.81349 21.1719 5.04124C23.7315 7.56948 23.7322 11.6725 21.1718 14.2083Z\" fill=\"black\" fill-opacity=\"0.8\"/>\n</svg>";
+/** 底部互动栏：收藏（星形，纯图标） */
+export declare const COLLECT = "<svg width=\"26\" height=\"26\" viewBox=\"0 0 26 26\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M17.1378 22.407C17.7597 22.6785 18.4794 22.6002 19.0279 22.2013C19.5764 21.8025 19.8711 21.1433 19.8017 20.4701L19.3275 15.8682C19.3123 15.7204 19.3604 15.5731 19.4599 15.4629L22.6026 11.9787C23.0578 11.4742 23.2088 10.7662 22.9991 10.1206C22.7893 9.47513 22.2505 8.98986 21.585 8.84711L16.9624 7.85554C16.8187 7.82473 16.6946 7.73508 16.6201 7.60842L14.2422 3.5644C13.8997 2.98191 13.2731 2.62402 12.5958 2.62402C11.9185 2.62402 11.2919 2.98191 10.9494 3.5644L8.57151 7.60841C8.49703 7.73508 8.37286 7.82473 8.22918 7.85554L3.60656 8.84711C2.94108 8.98986 2.40227 9.47513 2.19251 10.1206C1.98275 10.7662 2.13381 11.4742 2.58894 11.9787L5.73172 15.4629C5.8312 15.5731 5.87929 15.7204 5.86407 15.8682L5.38986 20.4701C5.32049 21.1433 5.61514 21.8025 6.16364 22.2013C6.71214 22.6002 7.43189 22.6785 8.05379 22.407L12.3858 20.516C12.5197 20.4576 12.6719 20.4576 12.8057 20.516L17.1378 22.407ZM3.75802 10.9242C3.67946 10.8371 3.65435 10.7165 3.68987 10.6072C3.72553 10.4975 3.81835 10.4119 3.93677 10.3865L8.55939 9.39495C9.13409 9.27168 9.63078 8.91311 9.92871 8.40644L12.3066 4.36243C12.3654 4.26238 12.4748 4.19845 12.5958 4.19845C12.7168 4.19845 12.8262 4.26238 12.885 4.36242L15.2629 8.40644C15.5608 8.91312 16.0575 9.27168 16.6322 9.39495L21.2548 10.3865C21.3732 10.4119 21.4661 10.4975 21.5017 10.6072C21.5372 10.7165 21.5121 10.8371 21.4336 10.9242L18.2908 14.4083C17.8929 14.8495 17.7005 15.4386 17.7614 16.0296L18.2356 20.6315C18.2473 20.7451 18.1979 20.8583 18.1021 20.9279C18.0057 20.998 17.878 21.0122 17.7677 20.9641L13.4356 19.0731C12.9001 18.8393 12.2915 18.8393 11.756 19.0731L7.42393 20.9641C7.31359 21.0122 7.1859 20.998 7.08952 20.9279C6.99372 20.8583 6.94429 20.7451 6.956 20.6315L7.4302 16.0295C7.4911 15.4386 7.29874 14.8495 6.9008 14.4083L3.75802 10.9242Z\" fill=\"black\" fill-opacity=\"0.8\"/>\n</svg>\n";
+/** 底部互动栏：评论（气泡图标 + 内嵌「评论」文案，宽 62） */
+export declare const COMMENT = "<svg width=\"62\" height=\"30\" viewBox=\"0 0 62 30\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M5.96703 20.5975C6.29588 21.1269 6.38174 21.784 6.1787 22.3932L5.17491 25.4045C5.52307 25.3376 5.9134 25.2638 6.31068 25.191C6.88797 25.0851 7.49114 24.9791 8.00558 24.899C8.45957 24.8282 9.00755 24.75 9.375 24.75C9.90779 24.75 10.511 24.9129 10.9 25.018L11.0003 25.045C11.9316 25.2933 13.1806 25.625 15 25.625C20.8423 25.625 25.625 20.8652 25.625 15C25.625 9.13197 20.868 4.375 15 4.375C9.13197 4.375 4.375 9.13197 4.375 15C4.375 17.0576 4.95803 18.9733 5.96703 20.5975ZM4.20912 27.4998C3.36929 27.4835 2.78128 26.6562 3.04843 25.8547L4.39992 21.8002C4.42369 21.7289 4.414 21.6508 4.37434 21.587C3.18616 19.6743 2.5 17.4173 2.5 15C2.5 8.09644 8.09644 2.5 15 2.5C21.9036 2.5 27.5 8.09644 27.5 15C27.5 21.9036 21.875 27.5 15 27.5C12.9295 27.5 11.4892 27.1159 10.5171 26.8567C10.0221 26.7246 9.64851 26.625 9.375 26.625C8.59818 26.625 4.58859 27.4287 4.25621 27.4956C4.23991 27.4989 4.22575 27.5001 4.20912 27.4998ZM20.8124 15.3125C20.8124 14.4496 20.1128 13.75 19.2499 13.75C18.3869 13.75 17.6874 14.4496 17.6874 15.3125C17.6874 16.1754 18.3869 16.875 19.2499 16.875C20.1128 16.875 20.8124 16.1754 20.8124 15.3125ZM10.7501 16.875C9.88718 16.875 9.18762 16.1754 9.18762 15.3125C9.18762 14.4496 9.88718 13.75 10.7501 13.75C11.6131 13.75 12.3126 14.4496 12.3126 15.3125C12.3126 16.1754 11.6131 16.875 10.7501 16.875Z\" fill=\"black\" fill-opacity=\"0.8\"/>\n<path d=\"M39.404 9.08H47.076V10.326H43.87V15.31H47.496V16.57H43.87V21.442H42.582V16.57H39.012V15.31H42.582V10.326H39.404V9.08ZM45.62 10.872L46.782 11.18C46.502 12.524 46.138 13.7 45.69 14.708L44.57 14.316C44.962 13.406 45.312 12.258 45.62 10.872ZM40.692 10.928C41.084 11.95 41.42 13.126 41.728 14.456L40.594 14.736C40.328 13.532 39.978 12.384 39.558 11.292L40.692 10.928ZM36.422 8.632C37.332 9.318 38.102 10.004 38.732 10.704L37.822 11.628C37.262 10.97 36.492 10.27 35.498 9.542L36.422 8.632ZM34.532 12.692H37.766V18.586C38.144 18.236 38.55 17.844 38.984 17.424L39.348 18.824C38.508 19.65 37.598 20.392 36.646 21.036L36.142 19.832C36.366 19.636 36.492 19.398 36.492 19.118V13.966H34.532V12.692ZM56.4 8.506H57.59C58.374 10.2 59.718 11.684 61.636 12.972L60.908 14.092C59.144 12.916 57.842 11.46 57.002 9.752C55.98 11.67 54.706 13.154 53.166 14.19L52.438 13.07C54.146 11.894 55.476 10.382 56.4 8.506ZM59.032 21.204H55.966C54.902 21.204 54.384 20.63 54.384 19.496V13.518H55.7V15.814C56.988 15.324 58.234 14.652 59.424 13.784L60.18 14.848C58.612 15.842 57.114 16.598 55.7 17.13V19.23C55.7 19.706 55.924 19.958 56.372 19.958H58.794C59.158 19.958 59.41 19.846 59.578 19.65C59.802 19.426 59.942 18.768 59.998 17.648L61.244 18.054C61.118 19.58 60.88 20.49 60.516 20.784C60.194 21.064 59.704 21.204 59.032 21.204ZM50.352 8.632C51.262 9.318 52.032 10.004 52.662 10.704L51.752 11.628C51.192 10.97 50.422 10.27 49.428 9.542L50.352 8.632ZM48.546 12.692H51.71V18.656C52.144 18.278 52.606 17.844 53.11 17.368L53.446 18.698C52.55 19.566 51.584 20.336 50.562 21.036L50.058 19.846C50.296 19.65 50.422 19.398 50.422 19.118V13.966H48.546V12.692Z\" fill=\"black\" fill-opacity=\"0.8\"/>\n</svg>\n";
+/** 底部互动栏：写评论输入框前缀的铅笔图标 */
+export declare const EDIT = "<svg width=\"20\" height=\"20\" viewBox=\"0 0 20 20\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M5.33317 11.1461L13.2797 3.19953C14.1747 2.30458 15.6257 2.30458 16.5206 3.19953C17.4156 4.09449 17.4156 5.54549 16.5206 6.44044L8.58651 14.3746C8.33981 14.6213 8.01284 14.7714 7.66494 14.7976L5.82888 14.936C5.25521 14.9792 4.7551 14.5493 4.71185 13.9756C4.70695 13.9105 4.70817 13.8451 4.7155 13.7802L4.91527 12.0134C4.95237 11.6854 5.0997 11.3796 5.33317 11.1461ZM7.57097 13.5511C7.62067 13.5474 7.66738 13.5259 7.70263 13.4907L15.6368 5.55656C16.0436 5.14976 16.0436 4.49021 15.6368 4.08342C15.23 3.67662 14.5704 3.67662 14.1636 4.08342L6.21706 12.03C6.1837 12.0633 6.16266 12.107 6.15736 12.1539L5.98586 13.6706L7.57097 13.5511Z\" fill=\"black\" fill-opacity=\"0.45\"/>\n<path d=\"M3.95898 16.2499C3.61381 16.2499 3.33398 16.5297 3.33398 16.8749C3.33398 17.2201 3.61381 17.4999 3.95898 17.4999H16.0423C16.3875 17.4999 16.6673 17.2201 16.6673 16.8749C16.6673 16.5297 16.3875 16.2499 16.0423 16.2499H3.95898Z\" fill=\"black\" fill-opacity=\"0.45\"/>\n</svg>\n";

package/lib/types/utils/package-constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 小工具包结构相关常量 —— 统一管理入口文件名，避免魔法串散落各处。
+ *
+ * 注意：本文件须保持「零依赖、纯常量」，因为 SW 脚本（`sw/worker/`，独立打包、
+ * 运行在 Service Worker 上下文）也会引用它，引入任何 DOM/Node 依赖会污染 SW bundle。
+ */
+/** 小工具包入口 HTML 默认文件名。 */
+export declare const DEFAULT_ENTRY_FILE = "index.html";

package/lib/types/utils/screenshot.d.ts

@@ -0,0 +1,14 @@
+import { type MiniAppScreenShotResult } from "../types";
+/** 笔记尾卡封面裁剪比例（宽/高，PRD 封面上传规格 3:4）；仅 SDK 内部封面使用，对外 screenShot 恒为完整截图 */
+export declare const NOTE_COVER_CROP_RATIO: number;
+export declare function blobToDataUrl(blob: Blob): Promise<string>;
+/** 从已截取的 blob 构造 screenShot 结果（完整截图，不裁剪）。 */
+export declare function buildScreenShotResult(blob: Blob, source: "auto" | "manual"): Promise<MiniAppScreenShotResult>;
+/** 从已有 dataURL 构造 screenShot 结果（完整截图，不裁剪；避免二次截图）。 */
+export declare function buildScreenShotResultFromDataUrl(dataUrl: string, source: "auto" | "manual"): Promise<MiniAppScreenShotResult>;
+/** 按 cover 语义把图片裁剪到目标宽高比，返回 PNG dataURL 与裁剪后尺寸；解码失败返回 null。 */
+export declare function cropDataUrlToRatio(dataUrl: string, ratio: number): Promise<{
+    base64: string;
+    width: number;
+    height: number;
+} | null>;

package/lib/types/utils/simulator-pc-guard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 模拟器范围内禁用 PC 端特有交互（文本圈选、图片拖拽等），贴近真机体感。
+ * iframe 内由 gesture `selection-disabler` 另行处理；此处覆盖宿主壳层与 shadow 组件。
+ */
+/** 注入各 shadow 组件样式表中的 guard 规则 */
+export declare const SIMULATOR_PC_GUARD_RULES = "\n  :host {\n    user-select: none;\n    -webkit-user-select: none;\n    -moz-user-select: none;\n    -webkit-touch-callout: none;\n  }\n  *, *::before, *::after {\n    user-select: none;\n    -webkit-user-select: none;\n    -moz-user-select: none;\n    -webkit-touch-callout: none;\n  }\n  img, a, svg {\n    -webkit-user-drag: none;\n    user-drag: none;\n  }\n";
+/** 在 DOM 节点上拦截 selectstart / dragstart（CSS 之外的兜底） */
+export declare function attachSimulatorPcGuard(target: HTMLElement): () => void;
+/** 对元素应用禁止选中的内联样式（light DOM 容器） */
+export declare function applySimulatorPcGuardStyles(el: HTMLElement): void;

package/lib/types/utils/stage-fit.d.ts

@@ -0,0 +1,6 @@
+import type { NormalizedMiniAppStageFitOptions } from "../types";
+/**
+ * 在 bounds 内对 container 做自适应缩放（默认 100% 撑满；可选右上角拖拽调整 scaleMultiplier）。
+ * 卸载时恢复挂载前的内联样式。
+ */
+export declare function attachMiniAppStageFit(container: HTMLElement, config: NormalizedMiniAppStageFitOptions): () => void;

package/lib/types/utils/touch-emulate.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 独立式（standalone）触摸模拟工具。
+ *
+ * 本文件**不被** simulator 内部使用 —— simulator 走 `src/gesture/` 模块的
+ * 插件化方案（host + receiver 双边）。
+ *
+ * 这里保留 `setupMiniProgramEmulateTouch` 作为公共 utility：当 mini-app
+ * 业务希望在没有 simulator 宿主时（例如直接打包到 bundle 里跑在桌面浏览器），
+ * 同 document 内把鼠标事件就地转换为 touch 事件，零外部依赖。
+ *
+ * 改编自 https://hammerjs.github.io/touch-emulator/。
+ */
+/** 恢复 touch 模拟（默认开启） */
+export declare function startEmulateTouch(): void;
+/** 暂停 touch 模拟，恢复鼠标原生行为 */
+export declare function stopEmulateTouch(): void;
+/**
+ * 在 mini-app 的渲染上下文（同一个 document）中调用，将鼠标事件直接转换为 touch 事件。
+ * 无需宿主配合，适用于"把 simulator 能力打包进 mini-app bundle"或纯桌面预览场景。
+ *
+ * 若需要"宿主端控制 + iframe 内派发"的方案（推荐用于设计器/模拟器宿主），见 `src/gesture/`。
+ *
+ * @param isGame 是否为小游戏模式（touch 事件派发到 document 而非具体元素，
+ *               用于 Cocos 等劫持 canvas.dispatchEvent 的引擎）
+ */
+export declare function setupMiniProgramEmulateTouch(isGame?: boolean): void;

package/lib/types/utils/zip-entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 入口解析 —— 入口文件必须位于 zip / 文件表的「根层」。
+ *
+ * 规则（故意不做套目录自动剥离）：
+ *   - 默认入口 `index.html` 必须在根目录；放在子目录（如 `app/index.html`）不被接受。
+ *   - 也可通过 `options.entry` 显式指定，但同样必须是根层文件（不含 `/`）。
+ *   - 不满足 → 返回 null（交调用方抛错），不静默改写包结构。
+ */
+/**
+ * 给定包内全部文件路径（已归一化）与可选显式入口，返回根层入口路径。
+ * 入口不在根层或不存在时返回 null。
+ */
+export declare function resolveZipEntry(paths: readonly string[], requestedEntry?: string): string | null;

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

@@ -0,0 +1,63 @@
+import { type RemoteMiniAppSimulator, type RemoteMiniAppSimulatorOptions } from "../remote/client";
+import type { MiniAppViewport } from "../types";
+declare const SCENE_PRESETS: {
+    readonly fullscreen: {
+        readonly contentMode: "fullscreen";
+        readonly route: "minitool";
+    };
+    readonly half: {
+        readonly contentMode: "half";
+        readonly route: "minitool";
+    };
+    readonly note: {
+        readonly contentMode: "fullscreen";
+        readonly route: "note";
+    };
+    readonly profile: {
+        readonly contentMode: "fullscreen";
+        readonly route: "profile";
+    };
+};
+export type MiniAppWorkbenchScene = keyof typeof SCENE_PRESETS;
+export interface MiniAppWorkbenchOptions {
+    /** 工作台挂载节点；工作台自身使用 Shadow DOM 隔离样式。 */
+    mount: string | HTMLElement;
+    /** 小工具逻辑视口，默认 393 × 852。 */
+    viewport?: MiniAppViewport;
+    /** 顶栏展示的小工具或项目名称。 */
+    projectName?: string;
+    /** 自定义“重新运行”；本地工作台用于重新读取目录，省略时重载当前产物。 */
+    onReload?: () => Promise<void>;
+    /**
+     * 远端模拟器连接配置。Runtime、Service Worker 与策略均由 serviceUrl 对应的服务动态下发；
+     * mount / viewport / shell 由工作台接管，统一使用 rednote 原生壳层。
+     */
+    remote: Omit<RemoteMiniAppSimulatorOptions, "mount" | "options"> & {
+        options?: Omit<NonNullable<RemoteMiniAppSimulatorOptions["options"]>, "viewport" | "shell">;
+    };
+}
+type WorkbenchLoadZipSource = Parameters<RemoteMiniAppSimulator["loadZip"]>[0];
+type WorkbenchLoadZipOptions = Parameters<RemoteMiniAppSimulator["loadZip"]>[1];
+type WorkbenchLoadFiles = Parameters<RemoteMiniAppSimulator["loadFiles"]>[0];
+type WorkbenchLoadFilesOptions = Parameters<RemoteMiniAppSimulator["loadFiles"]>[1];
+type WorkbenchLoadAppOptions = Parameters<RemoteMiniAppSimulator["loadApp"]>[1];
+export interface MiniAppWorkbench {
+    readonly element: HTMLElement;
+    readonly simulator: RemoteMiniAppSimulator;
+    readonly ready: RemoteMiniAppSimulator["ready"];
+    /** 重新读取产物；连续请求串行执行，加载期间的新请求合并为下一次重载。 */
+    reload(): Promise<void>;
+    setScene(scene: MiniAppWorkbenchScene): Promise<void>;
+    loadZip(source: WorkbenchLoadZipSource, options?: WorkbenchLoadZipOptions): Promise<void>;
+    loadFiles(files: WorkbenchLoadFiles, options?: WorkbenchLoadFilesOptions): Promise<void>;
+    loadApp(appUrl: string, options?: WorkbenchLoadAppOptions): Promise<void>;
+    setViewport(viewport: MiniAppViewport): void;
+    destroy(reason?: string): void;
+}
+/**
+ * 创建面向本地开发与外部 AI 工具的调试工作台。
+ *
+ * 工作台只编排远端 simulator 能力，不改变 Runtime、Service Worker 和诊断协议。
+ */
+export declare function createMiniAppWorkbench(options: MiniAppWorkbenchOptions): MiniAppWorkbench;
+export {};

package/lib/types/workbench/preview-transition.d.ts

@@ -0,0 +1,8 @@
+type TransitionKind = "viewport" | "reload";
+/** 仅遮罩工作台预览区；同类请求取最新值，不同类型共同决定何时揭开遮罩。 */
+export declare function createPreviewTransition(overlay: HTMLElement, canvas: HTMLElement): {
+    isActive: (kind: TransitionKind) => boolean;
+    run(kind: TransitionKind, task: () => Promise<unknown>): Promise<void>;
+    destroy(): void;
+};
+export {};

package/lib/types/workbench/server/artifact.d.ts

@@ -0,0 +1,8 @@
+/** 每次请求重新扫描目录；不包含隐藏文件和符号链接。 */
+export declare function readArtifactManifest(rootDir: string): Promise<{
+    entry: string;
+    files: string[];
+}>;
+export declare function resolveArtifactRoot(directory: string): Promise<string>;
+/** 静态文件响应仍交给框架；这里仅防止符号链接或路径穿越逃出调试目录。 */
+export declare function resolveArtifactFile(rootDir: string, filePath: string): Promise<string>;

package/lib/types/workbench/server/index.d.ts

@@ -0,0 +1,19 @@
+import { BusinessLine } from "../../business-line";
+export { BusinessLine } from "../../business-line";
+export interface StartWorkbenchServerOptions {
+    /** 包含可运行 HTML 及静态资源的调试根目录。 */
+    rootDir: string;
+    /** 接入方可提供真实运行上下文；省略时连接正式 Simulator 服务。 */
+    remote?: {
+        serviceUrl?: string;
+        appId?: string;
+        businessLine?: BusinessLine;
+    };
+}
+export interface WorkbenchServer {
+    readonly url: string;
+    /** 停止接收请求并关闭本地服务；重复调用返回同一个 Promise。 */
+    close(): Promise<void>;
+}
+/** 启动本地工作台服务。浏览器入口负责创建工作台和 Remote Simulator。 */
+export declare function startWorkbenchServer(options: StartWorkbenchServerOptions): Promise<WorkbenchServer>;

package/lib/types/workbench/server/watch.d.ts

@@ -0,0 +1,6 @@
+import { PassThrough } from "node:stream";
+/** 目录监听与 SSE 连接共用一次服务生命周期，不跟随符号链接。 */
+export declare function watchArtifact(rootDir: string): Promise<{
+    subscribe(): PassThrough;
+    close(): Promise<void>;
+}>;

package/lib/types/workbench/view.d.ts

@@ -0,0 +1,36 @@
+export interface WorkbenchViewElements {
+    closeDiagnosticsButton: HTMLButtonElement;
+    deviceButtons: HTMLButtonElement[];
+    deviceIndicator: HTMLElement;
+    deviceShell: HTMLElement;
+    deviceSlot: HTMLElement;
+    diagnosticsButtons: HTMLButtonElement[];
+    diagnosticsPanel: HTMLElement;
+    eventCount: HTMLElement;
+    events: HTMLElement;
+    fitButton: HTMLButtonElement;
+    lastEvent: HTMLElement;
+    preview: HTMLElement;
+    previewCanvas: HTMLElement;
+    previewControls: HTMLElement;
+    reloadButton: HTMLButtonElement;
+    sceneButtons: HTMLButtonElement[];
+    screenshotButton: HTMLButtonElement;
+    stage: HTMLElement;
+    status: HTMLElement;
+    statusText: HTMLElement;
+    transitionOverlay: HTMLElement;
+    viewportLabel: HTMLElement;
+}
+export interface WorkbenchView {
+    host: HTMLElement;
+    root: ShadowRoot;
+    elements: WorkbenchViewElements;
+}
+/**
+ * 构建工作台静态视图。
+ *
+ * HTML 与 CSS 作为独立资源由 Vite 编译进 workbench 入口，既保持 SDK 单文件分发，
+ * 也避免在运行逻辑里维护大段模板字符串。
+ */
+export declare function createWorkbenchView(projectName: string): WorkbenchView;

package/lib/types/worker/adapters/csp-policy.d.ts

@@ -0,0 +1,7 @@
+declare const DIRECTIVES: readonly ["default-src", "script-src", "connect-src", "worker-src", "child-src"];
+export type WorkerCspPolicy = Partial<Record<(typeof DIRECTIVES)[number], string>>;
+/** Apollo 与本地配置共用；非法配置整体回退，不产生部分放开的策略。 */
+export declare function parseWorkerCspPolicy(input: unknown): WorkerCspPolicy | undefined;
+/** 缺失字段沿用内置值；每个 directive 的配置值完整替换该项。 */
+export declare function resolveWorkerContentSecurityPolicy(input: unknown): string;
+export {};

package/lib/types/worker/adapters/host-lifecycle.d.ts

@@ -0,0 +1,5 @@
+/** 仅由 Runtime 已建立的私有 MessagePort 更新外层宿主可见性。 */
+export declare function updateWorkerHostVisibility(visible: boolean): void;
+export declare function observeWorkerHostVisibility(element: HTMLElement, notify: (visible: boolean) => void): () => void;
+/** 宿主文档与容器 CSS 可见性接线；会话握手避免消息早于页面封印安装而丢失。 */
+export declare function attachWorkerHostLifecycle(iframe: HTMLIFrameElement, getUrl: () => string): () => void;

package/lib/types/worker/adapters/mount-recovery.d.ts

@@ -0,0 +1,2 @@
+/** 资源 SW 内存丢失时恢复宿主包快照；恢复后仍需校验请求所属会话。 */
+export declare function recoverWorkerMount(request: Request, clientId: string): Promise<void>;