@lingfan-engine/create 0.0.0-stage → 0.1.5

package/template/overlays/miniprogram/src/components/StageView.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+/**
+ * 舞台视图：舞台盒（基准尺寸 + 宿主下发的平移缩放）与其中的两层节点树。
+ *
+ * 画布不在这里——帧时钟画布留在页面上，页面的选择器查询才拿得到它（跨组件查询
+ * 在小程序里不可靠）。这里只负责把宿主算好的描述树铺成节点。
+ */
+import NodeTree from "./NodeTree.vue";
+import type { MiniNode } from "../mp/index.ts";
+
+defineOptions({ name: "StageView" });
+
+defineProps<{
+  /** 舞台层的节点树（基准坐标系） */
+  stage: MiniNode[];
+  /** 元素层的节点树（同上，叠在舞台层之上） */
+  elements: MiniNode[];
+  /** 舞台盒的行内样式：尺寸、平移与缩放，由宿主按视口算好 */
+  stageBox: string;
+}>();
+</script>
+
+<template>
+  <view class="stage-box" :style="stageBox">
+    <NodeTree :nodes="stage" />
+    <view class="element-layer">
+      <NodeTree :nodes="elements" />
+    </view>
+  </view>
+</template>
+
+<style>
+/* 舞台盒：基准尺寸 + 宿主下发的平移与缩放；原点取左上角，与布局口径一致 */
+.stage-box {
+  position: absolute;
+  left: 0;
+  top: 0;
+  transform-origin: 0 0;
+}
+
+/* 元素层不吃点击：叙事元素暂不接管交互（元素交互走覆盖层的命令出口，属后续接线） */
+.element-layer {
+  position: absolute;
+  left: 0;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  pointer-events: none;
+}
+</style>

package/template/overlays/miniprogram/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="@dcloudio/types" />

package/template/overlays/miniprogram/src/main.ts

@@ -0,0 +1,12 @@
+/**
+ * UniApp 约定入口：返回应用实例（小程序与 H5 共用同一份代码）。
+ *
+ * 页面装配在 `pages/index/index.vue`，宿主接线在 `mp/`——入口只负责建应用。
+ */
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+
+export function createApp(): { app: ReturnType<typeof createSSRApp> } {
+  const app = createSSRApp(App);
+  return { app };
+}

package/template/overlays/miniprogram/src/manifest.json

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT__",
+  "appid": "",
+  "description": "灵泛叙事引擎的小程序形态：UniApp（Vue 3）页面层接住框架无关的端口装配",
+  "versionName": "0.1.0",
+  "versionCode": "0",
+  "mp-weixin": {
+    "appid": "",
+    "libVersion": "3.15.1",
+    "setting": {
+      "urlCheck": false,
+      "es6": true,
+      "minified": false
+    },
+    "usingComponents": true,
+    "lazyCodeLoading": "requiredComponents"
+  },
+  "h5": {
+    "title": "__PROJECT__"
+  }
+}

package/template/overlays/miniprogram/src/mp/frame.ts

@@ -0,0 +1,51 @@
+/**
+ * 帧源装配：叙事覆盖层每帧只要一个「下一帧」回调，帧从哪来由宿主决定。
+ *
+ * 有画布节点就用它的 requestAnimationFrame（与真机刷新同步、后台自动停），
+ * 没有就退回定时器（约 60 帧/秒）。两条路都满足同一个 `FrameSource` 形状，
+ * 上层装配器与帧循环不需要知道用的是哪条。
+ */
+import {
+  createMiniprogramFrameSource,
+  type MiniprogramFrameSource,
+} from "@lingfan-engine/adapters";
+import { uniApi, type MiniprogramCanvasNode } from "./platform.ts";
+
+/** 定时器帧源的间隔（毫秒）：约 60 帧/秒，与常见屏幕刷新率一致 */
+const TIMER_FRAME_MS = 16;
+
+/** 造帧源：给画布就走画布，否则走定时器 */
+export function createHostFrameSource(
+  canvas: MiniprogramCanvasNode | null,
+): MiniprogramFrameSource {
+  return canvas !== null
+    ? createMiniprogramFrameSource(canvas)
+    : createTimerFrameSource();
+}
+
+/**
+ * 定时器帧源：句柄从 1 起编（0 留给「无句柄」的既有约定），取消时清掉在排的定时器。
+ */
+function createTimerFrameSource(): MiniprogramFrameSource {
+  const api = uniApi();
+  const pending = new Map<number, number>();
+  let nextHandle = 1;
+  return {
+    request(callback: (now: number) => void): number {
+      const handle = nextHandle;
+      nextHandle += 1;
+      const timer = api.setTimeout(() => {
+        pending.delete(handle);
+        callback(Date.now());
+      }, TIMER_FRAME_MS);
+      pending.set(handle, timer);
+      return handle;
+    },
+    cancel(handle: number): void {
+      const timer = pending.get(handle);
+      if (timer === undefined) return;
+      api.clearTimeout(timer);
+      pending.delete(handle);
+    },
+  };
+}

package/template/overlays/miniprogram/src/mp/guards.ts

@@ -0,0 +1,28 @@
+/**
+ * 演示工程的守卫实现：故事 JSON 里只写守卫名（`{"op":"guard","fn":"gold-non-negative"}`），
+ * 实现必须由宿主提供——引擎是「组合根注册制」，没登记的守卫名在运行期会 fail-closed。
+ *
+ * 内容是包外的、守卫是包内的，这是有意为之：守卫属于代码而不是内容，服务端换一份故事
+ * 也换不掉它。演示工程用到的两个守卫语义与 `apps/playground/Stories.src/lib/guards.ts`
+ * 的 cell 声明一致（那边由 `stories:build` 生成注册表，这边没有生成器，手写同一份语义）。
+ *
+ * 名字闭合靠 `tests/miniprogram/app-host.test.ts` 的互锁：`project/Stories/**` 里出现的
+ * 每个 `"fn"` 都必须在 `guards` 里登记，缺一个就是运行期的「未注册的守卫」。
+ */
+import type { GuardFn } from "@lingfan-engine/core";
+
+export const guards: Readonly<Record<string, GuardFn>> = {
+  /** 金币非负：`player.gold` 被改成负数即拦下，故事停在当前命令。 */
+  "gold-non-negative": (ctx) => {
+    const gold = ctx.get("player.gold");
+    if (typeof gold !== "number" || gold < 0) {
+      ctx.fail(`player.gold 非法：${String(gold)}`);
+    }
+  },
+  /** 巡礼守卫：站点自带的闸门演示——先 set 状态再 guard，守卫读的是 SSOT 事实。 */
+  "tour-open": (ctx) => {
+    if (ctx.get("tour.open") !== true) {
+      ctx.fail("巡礼尚未开始（tour.open 未置位）");
+    }
+  },
+};

package/template/overlays/miniprogram/src/mp/host.ts

@@ -0,0 +1,252 @@
+/**
+ * 小程序宿主装配：从远端工程到可跑的叙事覆盖层，一次接线到位。
+ *
+ * 接线顺序与嵌入演示一致——装载工程 → 建引擎（注入平台端口与文案）→ 建媒体渲染器 →
+ * 建表面 → 建覆盖层 → 起帧循环。差别只有三处：工程来自工程接口而不是包内文件；
+ * 表面把视图变成页面数据而不是 DOM 节点；舞台按视口与基准算出缩放再交给页面
+ * （小程序没有 vw/vh 之类整体缩放手段）；媒体的位置回写借覆盖层的帧循环
+ * （与打字机同一条时间线），视频播完由页面回传。
+ *
+ * 本文件是组合根：允许它同时知道引擎、展示层与平台，别处不允许这样横跨。
+ */
+import {
+  defaultEngineTexts,
+  findMissingGuards,
+  PlayerPreferences,
+  resolveSavesConfig,
+  slotIds,
+  StoryEngine,
+  type SavesConfig,
+  type Story,
+} from "@lingfan-engine/core";
+import { loadProject } from "@lingfan-engine/adapters";
+import {
+  computeStageLayout,
+  DEFAULT_STAGE_FIT,
+  DEFAULT_STAGE_HEIGHT,
+  DEFAULT_STAGE_WIDTH,
+  withSlotLabels,
+  type StageConfig,
+  type StageLayout,
+} from "@lingfan-engine/shell";
+import {
+  createAudioRenderer,
+  createElementResourceResolver,
+  createNarrativeOverlay,
+  createVideoRenderer,
+  type AudioRenderer,
+  type NarrativeOverlay,
+  type VideoRenderer,
+} from "@lingfan-engine/ui";
+import { createHostFrameSource } from "./frame.ts";
+import {
+  createRequestFetch,
+  readWindowSize,
+  type MiniprogramCanvasNode,
+} from "./platform.ts";
+import {
+  createMiniprogramHostPorts,
+  type MiniprogramHostPorts,
+} from "./ports.ts";
+import {
+  createRemoteProjectFilesPort,
+  resolveProjectBaseUrl,
+} from "./project-source.ts";
+import { guards } from "./guards.ts";
+import {
+  createMiniprogramOverlaySurface,
+  type MiniprogramSurfacePatch,
+} from "./surface.ts";
+import {
+  createMiniprogramVideoSurface,
+  type MiniprogramVideoData,
+  type MiniprogramVideoSurface,
+} from "./video-surface.ts";
+import { stageStyle } from "./view.ts";
+
+/** 覆盖层字速（字符/秒） */
+const TEXT_SPEED = 30;
+
+/** 舞台基准与装入方式：1280×720 等比装入视口（换基准改这里即可） */
+const STAGE_CONFIG: StageConfig = {
+  width: DEFAULT_STAGE_WIDTH,
+  height: DEFAULT_STAGE_HEIGHT,
+  fit: DEFAULT_STAGE_FIT,
+};
+
+/** 页面数据补丁：覆盖层各层 + 视频状态 + 舞台尺寸串 + 错误横幅 */
+export type MiniprogramHostPatch = MiniprogramSurfacePatch & {
+  stageBox?: string;
+  video?: MiniprogramVideoData;
+  error?: string;
+};
+
+/** 宿主装配参数 */
+export interface MiniprogramHostDeps {
+  /** 页面数据发布口 */
+  publish(patch: MiniprogramHostPatch): void;
+  /** 画布节点（有则用它做帧源；无则退回定时器帧源） */
+  canvas?: MiniprogramCanvasNode | null;
+  /** 工程基址（故事与资源都从它取）；缺省读运行期配置 */
+  projectBaseUrl?: string;
+}
+
+/** 宿主句柄：页面用它做重算、媒体回传、销毁与调试观测 */
+export interface MiniprogramHostHandle {
+  engine: StoryEngine;
+  overlay: NarrativeOverlay;
+  ports: MiniprogramHostPorts;
+  /** 当前舞台布局（视口 + 基准算出的缩放与偏移） */
+  layout(): StageLayout;
+  /** 视口尺寸变化后重算布局并下发 */
+  resize(): void;
+  /** 视频自然播完（页面 `bindended` 转发）：引擎据此解除 video 等待 */
+  videoEnded(): void;
+  /** 媒体与引擎状态对齐（读档/回溯完成后显式调用） */
+  syncMedia(): void;
+  /** 存档壳配置（槽数由工程清单 `shell.saves` 覆盖，缺省内建值） */
+  saves: SavesConfig;
+  /** 槽位 id 序列（面板呈现顺序） */
+  slotIds: string[];
+  /** 写入存档：回执来自引擎（失败文案由引擎通知，宿主不另编） */
+  saveGame(slot: string): boolean;
+  /** 读取存档：成功则媒体与投影各对齐一次 */
+  loadGame(slot: string): boolean;
+  /** 卸载：停帧循环、停媒体、退订状态、清空各层 */
+  dispose(): void;
+}
+
+/** 启动小程序宿主：从工程接口装载故事并起叙事循环 */
+export async function startMiniprogramHost(
+  deps: MiniprogramHostDeps,
+): Promise<MiniprogramHostHandle> {
+  const projectBaseUrl = deps.projectBaseUrl ?? resolveProjectBaseUrl();
+  const filesPort = createRemoteProjectFilesPort({
+    baseUrl: projectBaseUrl,
+    fetch: createRequestFetch(),
+  });
+  const story: Story = await loadProject(filesPort);
+
+  // 存档槽数与缩略图参数来自同一份工程清单（`shell.saves` 逐键覆盖）：清单与故事是同一次
+  // 装载（端口内 memo），这里再取一次不产生第二个请求。
+  const saves: SavesConfig = resolveSavesConfig(await filesPort.manifest());
+
+  // 内容是包外的（故事走工程接口，改故事不必发版），守卫却在包里：装载完成先对名字，
+  // 缺谁一次报全——错误停在起播之前，而不是播到那条命令才弹「未注册的守卫」。
+  const missingGuards = findMissingGuards(story, guards);
+  if (missingGuards.length > 0) {
+    throw new Error(
+      `故事引用了未注册的守卫：${missingGuards.join("、")}（宿主需在 src/mp/guards.ts 补齐实现）`,
+    );
+  }
+
+  const videoSurface: MiniprogramVideoSurface = createMiniprogramVideoSurface({
+    publish: (video) => deps.publish({ video }),
+  });
+  const ports = createMiniprogramHostPorts({ videoSurface, projectBaseUrl });
+  const engine = new StoryEngine(story, {
+    savePort: ports.save,
+    texts: withSlotLabels(defaultEngineTexts),
+    // 守卫实现由宿主随代码带上：故事 JSON 只写名字（装载期已校验名字齐全）
+    guards,
+  });
+
+  // 玩家偏好在渲染器之前水合：首帧起用的就是上次的音量，不必等下一次用户操作
+  const preferences = new PlayerPreferences(ports.preferences);
+  await preferences.hydrate();
+
+  /** 诊断出口：媒体装配失败与覆盖层运行时错误都落到同一条出口（fail-closed：不播，但不静默） */
+  const reportError = (message: string): void => {
+    deps.publish({ error: message });
+  };
+
+  // 音频渲染器与视频渲染器都按引擎状态做差量；构造即订阅，先于覆盖层建好不影响语义。
+  const audio: AudioRenderer = createAudioRenderer(
+    engine,
+    ports.audio,
+    ports.resources,
+    { onError: reportError, preferences },
+  );
+  const video: VideoRenderer = createVideoRenderer(
+    engine,
+    ports.video,
+    ports.resources,
+    {
+      onError: reportError,
+      // 组合根职责：cutscene 播完 → 引擎解除 video 等待
+      onVideoFinished: () => engine.videoFinished(),
+    },
+  );
+
+  const surface = createMiniprogramOverlaySurface({
+    frame: createHostFrameSource(deps.canvas ?? null),
+    publish: deps.publish,
+  });
+
+  // 元素资源解析是异步的而元素渲染是同步的：用现成的同步查表皮接上，
+  // 解析完成后要求覆盖层补一次重渲（回调延后读 overlay，故用闭包而非参数）。
+  const elementResources = createElementResourceResolver({
+    resolve: (path) => ports.resources.resolve(path),
+    onResolved: () => overlay.sync(),
+  });
+  const overlay: NarrativeOverlay = createNarrativeOverlay({
+    surface,
+    engine,
+    textSpeed: TEXT_SPEED,
+    resolveResource: elementResources.resolveForElement,
+    onError: reportError,
+    // 覆盖层的帧循环一直在跑：音频播放位置借它逐帧回写（与打字机同一条时间线）
+    onFrame: () => audio.pollPosition(),
+    // NVL 累积层读同一条渲染投影（桌面面板也是读它自己渲染）：表面把它翻成页面数据
+    onView: (view) => surface.setNvl(view),
+  });
+
+  let layout = computeStageLayout(readWindowSize(), STAGE_CONFIG);
+
+  /** 读一次视口、重算布局并下发（初始化与尺寸变化共用） */
+  function resize(): void {
+    layout = computeStageLayout(readWindowSize(), STAGE_CONFIG);
+    deps.publish({ stageBox: stageStyle(layout) });
+  }
+
+  resize();
+  engine.start();
+
+  /** 媒体与投影对齐：读档/回溯后音频、视频与 NVL 要跟引擎状态重新对齐 */
+  function syncMedia(): void {
+    audio.sync();
+    video.sync();
+    // 覆盖层 sync 只重渲各层、不触发投影通知：NVL 也在这里补一次对齐
+    surface.setNvl(overlay.view());
+  }
+
+  // 读档真正落地晚于命令返回：对齐挂在完成信号上，别在 `loadGame` 里当场同步。
+  // 覆盖层 sync 是必须的——引擎重放只驱动「变化量」，读档后的整幅画面要靠一次全量重渲补齐。
+  const stopLoadEvents = engine.onEvent((event) => {
+    if (event.payload.kind !== "load.done") return;
+    overlay.sync();
+    syncMedia();
+  });
+
+  return {
+    engine,
+    overlay,
+    ports,
+    saves,
+    slotIds: slotIds(saves.slots),
+    layout: () => layout,
+    resize,
+    videoEnded: () => videoSurface.notifyEnded(),
+    syncMedia,
+    saveGame: (slot) => engine.save(slot),
+    loadGame: (slot) => engine.load(slot),
+    dispose: () => {
+      stopLoadEvents();
+      overlay.dispose();
+      audio.dispose();
+      video.dispose();
+      engine.dispose();
+      preferences.dispose();
+    },
+  };
+}

package/template/overlays/miniprogram/src/mp/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 小程序宿主的对外出口：页面与其它入口只从这里取件，别处不允许深引内部模块。
+ */
+export * from "./platform.ts";
+export * from "./view.ts";
+export * from "./surface.ts";
+export * from "./video-surface.ts";
+export * from "./slots.ts";
+export * from "./host.ts";

package/template/overlays/miniprogram/src/mp/platform.ts

@@ -0,0 +1,210 @@
+/**
+ * 平台取用点：宿主工程里的 `uni` 全局只在本文件出现，其余模块一律经此取件。
+ *
+ * UniApp 的 `uni` 是各端 API 的统一面（微信端即 `wx` 的镜像），因此同一份页面代码既能跑
+ * 小程序，也能在浏览器里跑 H5 预览。把全局收在一处的原因有两条：其余模块要能在 Node 下被
+ * 类型检查与单测导入，把 `uni` 撒在各处会让它们只能在真机里跑；平台能力的形状集中在这里，
+ * 将来换端只需替换本文件。
+ */
+
+import type {
+  HttpFetch,
+  MiniprogramAudioContextLike,
+} from "@lingfan-engine/adapters";
+
+/** 小程序同步存储面（值与键都是字符串；取不存在的键返回空串） */
+export interface UniStorageApi {
+  setStorageSync(key: string, value: string): void;
+  getStorageSync(key: string): unknown;
+  removeStorageSync(key: string): void;
+  getStorageInfoSync(): { keys: string[] };
+}
+
+/** 画布节点面：只声明宿主用到的那一层（帧源与像素尺寸） */
+export interface MiniprogramCanvasNode {
+  width: number;
+  height: number;
+  requestAnimationFrame(callback: (now: number) => void): number;
+  cancelAnimationFrame(handle: number): void;
+}
+
+/** 系统信息面：只声明窗口尺寸与像素比 */
+export interface UniSystemInfo {
+  windowWidth: number;
+  windowHeight: number;
+  pixelRatio: number;
+  platform?: string;
+}
+
+/** 选择器查询面：只声明取画布节点用到的那两步 */
+export interface UniSelectorQuery {
+  select(selector: string): UniSelectorQuery;
+  node(
+    callback: (result: { node?: MiniprogramCanvasNode }) => void,
+  ): UniSelectorQuery;
+  exec(): void;
+}
+
+/** 尺寸变化回执：小程序按窗口给了新的逻辑尺寸 */
+export interface UniResizeResult {
+  size: { windowWidth: number; windowHeight: number };
+}
+
+/** 网络请求回执：只声明工程接口用到的那几个字段（`data` 可能已被平台解析） */
+export interface UniRequestResult {
+  statusCode: number;
+  data: unknown;
+}
+
+/** 网络请求的失败回执：`errMsg` 是平台给的可读原因 */
+export interface UniRequestFailure {
+  errMsg?: string;
+}
+
+/** 网络请求参数：只声明本工程用到的那一层 */
+export interface UniRequestOptions {
+  url: string;
+  method?: "GET";
+  /** 返回体的处理方式：`"text"` = 不当 JSON 解析（故事要原文） */
+  dataType?: string;
+  responseType?: string;
+  success(result: UniRequestResult): void;
+  fail(error: UniRequestFailure): void;
+}
+
+/**
+ * 视频组件的控制柄（`uni.createVideoContext(id)` 返回值里用到的四个动作）。
+ * 小程序的 `video` 是声明式组件：起播靠组件属性，播放中控制靠这个柄。
+ */
+export interface UniVideoContext {
+  play(): void;
+  pause(): void;
+  seek(seconds: number): void;
+  stop(): void;
+}
+
+/** 本工程用到的 `uni` 全局的一层 */
+export interface UniApi {
+  getSystemInfoSync(): UniSystemInfo;
+  setStorageSync(key: string, value: string): void;
+  getStorageSync(key: string): unknown;
+  removeStorageSync(key: string): void;
+  getStorageInfoSync(): { keys: string[] };
+  createSelectorQuery(): UniSelectorQuery;
+  createInnerAudioContext(): MiniprogramAudioContextLike;
+  createVideoContext(id: string): UniVideoContext;
+  request(options: UniRequestOptions): void;
+  onWindowResize(callback: (result: UniResizeResult) => void): void;
+  offWindowResize(callback: (result: UniResizeResult) => void): void;
+  nextTick(callback: () => void): void;
+  setTimeout(callback: () => void, ms: number): number;
+  clearTimeout(handle: number): void;
+}
+
+/** 画布节点查询的等待上限：超时按「取不到」处理，退回定时器帧源 */
+const CANVAS_QUERY_TIMEOUT_MS = 300;
+
+/** 取 `uni` 全局（本工程唯一的取用点） */
+export function uniApi(): UniApi {
+  return uni as unknown as UniApi;
+}
+
+/** 读窗口尺寸：小程序给的是逻辑像素，不需要再折算像素比 */
+export function readWindowSize(): { width: number; height: number } {
+  const info = uniApi().getSystemInfoSync();
+  return { width: info.windowWidth, height: info.windowHeight };
+}
+
+/**
+ * 造一个音频实例（`bgm` / `ambient` / `voice` / `se` 四条通道各持一个）。
+ *
+ * 实例的 `src` 是包内路径或临时地址；`se` 通道播完即销毁，常驻通道由适配器回收。
+ */
+export function createAudioContext(): MiniprogramAudioContextLike {
+  return uniApi().createInnerAudioContext();
+}
+
+/**
+ * 取页面上某个 `video` 组件的控制柄；组件还没渲染时调用方要自己兜住异常。
+ * @param id 页面里 `video` 组件的 id
+ */
+export function createVideoContext(id: string): UniVideoContext {
+  return uniApi().createVideoContext(id);
+}
+
+/**
+ * 造一个取件面（HTTP）：把 `uni.request` 包成适配器认的最小 `fetch` 形状。
+ *
+ * 工程接口要的是**原文**（故事的解析归引擎），所以返回体不交给平台解析；失败走 reject，
+ * 由装载方 fail-closed（不降级成空工程）。取件面在调用时才碰 `uni`，模块导入不依赖运行时。
+ */
+export function createRequestFetch(): HttpFetch {
+  return (url) =>
+    new Promise((resolve, reject) => {
+      uniApi().request({
+        url,
+        method: "GET",
+        // 非 json 的处理方式：原样拿到文本，不在平台侧解析
+        dataType: "text",
+        responseType: "text",
+        success: (result) => {
+          resolve({
+            ok: result.statusCode >= 200 && result.statusCode < 300,
+            status: result.statusCode,
+            text: async () =>
+              typeof result.data === "string"
+                ? result.data
+                : JSON.stringify(result.data),
+          });
+        },
+        fail: (error) => {
+          reject(new Error(`${url} 请求失败：${error.errMsg ?? "未知原因"}`));
+        },
+      });
+    });
+}
+
+/**
+ * 按选择器取画布节点；取不到、或该端不支持节点查询时返回 null，由调用方决定退回哪条帧源。
+ *
+ * 两种取不到都要兜住：H5 的节点查询不回调，小程序上画布可能还没渲染完。
+ */
+export function queryCanvasNode(
+  selector: string,
+): Promise<MiniprogramCanvasNode | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (node: MiniprogramCanvasNode | null): void => {
+      if (settled) return;
+      settled = true;
+      resolve(node);
+    };
+    try {
+      uniApi()
+        .createSelectorQuery()
+        .select(selector)
+        .node((result) => {
+          finish(result.node ?? null);
+        })
+        .exec();
+    } catch {
+      finish(null);
+      return;
+    }
+    setTimeout(() => {
+      finish(null);
+    }, CANVAS_QUERY_TIMEOUT_MS);
+  });
+}
+
+/** 盯住窗口尺寸变化；返回退订函数（卸载时调用，避免页面销毁后仍被回调） */
+export function watchWindowResize(handler: () => void): () => void {
+  const api = uniApi();
+  const callback = (): void => {
+    handler();
+  };
+  api.onWindowResize(callback);
+  return () => {
+    api.offWindowResize(callback);
+  };
+}