weifuwu 0.94.1 → 0.95.0

package/dist/level2/serve.ts

@@ -0,0 +1,349 @@
+import http, { type IncomingMessage, type ServerResponse } from 'node:http'
+import crypto from 'node:crypto'
+import { parseQuery } from '../level0/router/context.ts'
+import { HttpError, type Context } from '../level0/types.ts'
+import { Router } from './router.ts'
+import type { WsHandlePort } from './ws.ts'
+
+export interface ServeOptions {
+  port?: number
+  hostname?: string
+  signal?: AbortSignal
+  /** Max request body size in bytes. Default: 10MB. Set to 0 for unlimited. */
+  maxBodySize?: number
+  /** Socket timeout in ms (inactivity). Default: 120_000（2 分钟，适配 LLM 生成等长任务）. */
+  timeout?: number
+  /** Keep-Alive idle timeout in ms. Default: 5_000. */
+  keepAliveTimeout?: number
+  /** Headers timeout in ms (must be > keepAliveTimeout). Default: 6_000. */
+  headersTimeout?: number
+  shutdown?: boolean
+  /**
+   * WS 适配器工厂（惰性——仅当路由注册了 WS 端点时调用）。
+   * core 不含协议实现：`weifuwu` 入口的 serve() 自动注入 ws 实现；
+   * 直接使用 core serve() 且有 WS 路由时必须显式提供（否则报错）。
+   */
+  wsAdapter?: () => WsHandlePort
+}
+
+export interface Server {
+  stop: (timeoutMs?: number) => Promise<void>
+  /** Alias for `stop()`. Prefer this for consistency with other modules. */
+  close: (timeoutMs?: number) => Promise<void>
+  readonly port: number
+  readonly hostname: string
+  ready: Promise<void>
+}
+
+/** Default max body size: 10MB. Set maxBodySize: 0 for unlimited. */
+export const DEFAULT_MAX_BODY = 10 * 1024 * 1024
+
+/** S6：无 body 请求共用零长 Buffer（避免每请求分配） */
+const EMPTY_BODY = Buffer.alloc(0)
+
+export async function readBody(req: IncomingMessage, maxSize?: number): Promise<Buffer> {
+  const limit = maxSize ?? DEFAULT_MAX_BODY
+
+  if (limit > 0) {
+    const cl = parseInt(req.headers['content-length'] ?? '0', 10)
+    if (cl > limit) throw new HttpError('Request body too large', 413)
+  }
+
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of req) {
+    total += (chunk as Buffer).byteLength
+    if (limit > 0 && total > limit) throw new HttpError('Request body too large', 413)
+    chunks.push(chunk as Buffer)
+  }
+  return Buffer.concat(chunks)
+}
+
+export function createRequest(
+  req: IncomingMessage,
+  body: Buffer,
+): [Request, Record<string, string>] {
+  const url = new URL(req.url ?? '/', 'http://localhost')
+  const query = parseQuery(url)
+
+  const headers: Record<string, string> = {}
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value !== undefined) {
+      headers[key] = Array.isArray(value) ? value.join(', ') : value
+    }
+  }
+
+  const request = new Request(url.href, {
+    method: req.method?.toUpperCase() ?? 'GET',
+    headers,
+    body:
+      req.method !== 'GET' && req.method !== 'HEAD' && body.length > 0 ? (body as BodyInit) : null,
+  })
+
+  return [request, query]
+}
+
+export async function sendResponse(
+  res: ServerResponse,
+  response: Response,
+  opts?: { traceId?: string | null },
+): Promise<void> {
+  const headers: Record<string, string | string[]> = {}
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === 'set-cookie') {
+      const existing = headers[key]
+      headers[key] = existing
+        ? Array.isArray(existing)
+          ? [...existing, value]
+          : [existing, value]
+        : value
+    } else {
+      headers[key] = value
+    }
+  })
+
+  // Inject trace header
+  if (opts?.traceId && !headers['x-trace-id']) {
+    headers['x-trace-id'] = opts.traceId
+  }
+
+  res.writeHead(response.status, response.statusText, headers)
+
+  if (response.body) {
+    // 流式泵（S1——SERVER-PERF-PLAN 波次 1）：
+    //   a) 背压：write() 返回 false → 等 drain（快流 + 慢客户端不再无界缓冲）
+    //   b) 断开传播：socket close → reader.cancel() → ReadableStream.cancel()
+    //      → SSE/AI 上游 onAbort 生效（源停止生产——token 不再写入死连接）
+    //   c) res 'error' 兑底：destroy 后 write 触发的 ERR_STREAM_DESTROYED
+    //      无监听会崩进程——吞掉（泵经 close 事件退出）
+    const reader = response.body.getReader()
+    const closed = new Promise<'closed'>((resolve) => {
+      res.once('close', () => resolve('closed'))
+    })
+    res.on('error', () => {})
+    const cancelStream = () =>
+      reader.cancel(new Error('client disconnected')).catch(() => {})
+    try {
+      while (true) {
+        const winner = await Promise.race([
+          reader.read().then((r) => ({ kind: 'chunk' as const, r })),
+          closed,
+        ])
+        if (winner === 'closed' || res.destroyed) {
+          await cancelStream()
+          return
+        }
+        const { done, value } = winner.r
+        if (done) break
+        if (!res.write(value)) {
+          const drained = new Promise<'drain'>((resolve) =>
+            res.once('drain', () => resolve('drain')),
+          )
+          if ((await Promise.race([drained, closed])) === 'closed') {
+            await cancelStream()
+            return
+          }
+        }
+      }
+      res.end()
+    } catch (err) {
+      // 源错误 → 干净地销毁 socket（客户端看到连接截断——服务器不崩）
+      if (!res.destroyed) {
+        res.destroy(err instanceof Error ? err : undefined)
+      }
+    } finally {
+      reader.releaseLock()
+    }
+    return
+  }
+
+  res.end()
+}
+export function serve<T extends object>(router: Router<T>, options?: ServeOptions): Server {
+  const handler = router.handler()
+  const port = options?.port ?? 0
+  const hostname = options?.hostname ?? '0.0.0.0'
+
+  // 在途请求追踪（S2 优雅停机）：从请求进入到响应完成——
+  // stop() 排空目标（server.close() 后无新增，快照即全量）
+  const inFlight = new Set<Promise<void>>()
+
+  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const traceId =
+      (req.headers['x-trace-id'] as string) ||
+      (req.headers['traceparent'] as string)?.split('-')[1] ||
+      crypto.randomUUID()
+
+    try {
+      // S6：无 body 请求（无 Content-Length 且无 Transfer-Encoding）跳过读取管线——
+      // GET/HEAD 零 body 场景省一次异步迭代器创建 + for-await 开销
+      const hasBody =
+        Number(req.headers['content-length'] ?? '0') > 0 ||
+        req.headers['transfer-encoding'] !== undefined
+      const body = hasBody ? await readBody(req, options?.maxBodySize) : EMPTY_BODY
+      const [request, query] = createRequest(req, body)
+      const response = await handler(request, { params: {}, query } as T)
+      await sendResponse(res, response, { traceId })
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err))
+      // HttpError → 对应状态码（README 承诺：serve 自动返回对应状态码）
+      if (e instanceof HttpError) {
+        res.writeHead(e.status, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: e.message }))
+        return
+      }
+      // Log unexpected errors so developers can debug
+      const url = req.url ?? '/'
+      const method = req.method ?? 'GET'
+      console.error(`[serve] ${method} ${url}:`, e.stack || e.message)
+      // 错误形态统一（S9）：500 = JSON { error }——与 router 层/ serverError() 一致
+      res.writeHead(500, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Internal Server Error' }))
+    }
+  }
+
+  const server = http.createServer((req, res) => {
+    const p = handleRequest(req, res)
+    const settled = p.then(
+      () => {},
+      () => {}, // handleRequest 内部已兜底——此处防御未处理拒绝
+    )
+    inFlight.add(settled)
+    void settled.then(() => { inFlight.delete(settled) })
+  })
+
+  // Connection timeouts — prevent slowloris and idle connection leaks
+  server.timeout = options?.timeout ?? 120_000
+  server.keepAliveTimeout = options?.keepAliveTimeout ?? 5_000
+  server.headersTimeout = options?.headersTimeout ?? 6_000
+
+  // WS 升级：仅注册了 WS 路由才挂（无 WS 应用零开销）；协议适配器由装备面注入
+  let wsPort: WsHandlePort | null = null
+  if (router.hasWsRoutes()) {
+    if (!options?.wsAdapter) {
+      throw new Error(
+        'serve(): 路由注册了 WS 端点但未提供 wsAdapter——core 不含 ws 实现；'
+          + '从 weifuwu 导入 serve（自动注入），或传 options.wsAdapter',
+      )
+    }
+    wsPort = options.wsAdapter()
+    server.on('upgrade', router.websocketHandler(wsPort))
+  }
+
+  let resolveReady!: () => void
+  const ready = new Promise<void>((r) => {
+    resolveReady = r
+  })
+
+  let shutdownHandler: (() => void) | null = null
+
+  if (options?.shutdown !== false) {
+    let shuttingDown = false
+    const shutdown = async () => {
+      if (shuttingDown) return
+      shuttingDown = true
+      console.log('weifuwu shutting down...')
+      // 与 stop() 同一实现（排空在途 → 优雅关闭）——收敛双路径漂移
+      await stop().catch(() => {})
+      process.exit(0)
+    }
+    shutdownHandler = shutdown
+    process.on('SIGTERM', shutdown)
+    process.on('SIGINT', shutdown)
+  }
+
+  let _cachedPort = 0
+  let _cachedHostname = ''
+
+  if (options?.signal) {
+    if (options.signal.aborted) {
+      _cachedPort = 0
+      _cachedHostname = ''
+      server.close()
+      resolveReady()
+      return {
+        stop: () => Promise.resolve(),
+        close: () => Promise.resolve(),
+        ready,
+        get port() {
+          return 0
+        },
+        get hostname() {
+          return hostname
+        },
+      }
+    }
+    options.signal.addEventListener(
+      'abort',
+      () => {
+        server.close()
+      },
+      { once: true },
+    )
+  }
+
+  server.on('error', (err) => {
+    // Event emitter errors cannot be caught by try-catch.
+    // Log, clean up, and resolve ready so the caller can detect failure
+    // by checking server.port === 0 after ready.
+    console.error('weifuwu server error:', err.message || err)
+    server.close()
+    _cachedPort = 0
+    resolveReady()
+  })
+
+  server.listen(port, hostname, () => {
+    const addr = server.address()
+    if (addr && typeof addr !== 'string') {
+      _cachedPort = addr.port
+      _cachedHostname = addr.address
+    }
+    resolveReady()
+
+    // Startup message — automatic in all environments
+    const displayHost = _cachedHostname === '0.0.0.0' ? 'localhost' : _cachedHostname || 'localhost'
+    console.log(`weifuwu listening on http://${displayHost}:${_cachedPort}`)
+  })
+
+  async function stop(timeoutMs = 2_000): Promise<void> {
+    if (shutdownHandler) {
+      process.off('SIGTERM', shutdownHandler)
+      process.off('SIGINT', shutdownHandler)
+      shutdownHandler = null
+    }
+    // 1. 停止接收新连接 + 释放空闲 keep-alive（排空只针对在途请求）
+    server.close()
+    server.closeIdleConnections()
+    // 2. 排空在途（timeoutMs 到点强杀兑底——timeoutMs=0 跳过等待）
+    if (inFlight.size > 0 && timeoutMs > 0) {
+      await Promise.race([
+        Promise.allSettled([...inFlight]).then(() => {}),
+        new Promise<void>((r) => setTimeout(r, timeoutMs)),
+      ])
+    }
+    // 3. 优雅关闭：WS 1001 握手（适配器，优先——必在 closeAllConnections 前）
+    //    + 有状态模块（postgres/redis 池等）
+    if (wsPort?.shutdown) {
+      try {
+        await wsPort.shutdown()
+      } catch { /* ignore shutdown errors */ }
+    }
+    await router.close().catch(() => {})
+    // 4. 强杀残余（未完成握手/卡死的流——最终兑底）
+    server.closeAllConnections()
+  }
+
+  return {
+    close: stop,
+    stop,
+    ready,
+    get port() {
+      if (!server.listening) return 0
+      return _cachedPort
+    },
+    get hostname() {
+      if (!server.listening) return hostname
+      return _cachedHostname || hostname
+    },
+  }
+}

package/dist/level2/ws.d.ts

@@ -0,0 +1,44 @@
+/**
+ * WebSocket upgrade + connection lifecycle.
+ *
+ * Handles the HTTP-to-WS upgrade and per-connection state.
+ * Used internally by Router — not exported to end users.
+ *
+ * W2 端口化：core 不依赖 `ws`——协议侧由 `WsHandlePort` 注入
+ * （默认实现 src/level5/server/ws/native/——W5 自研 RFC6455；`ws` 仅差分参考）。
+ */
+import type { Duplex } from 'node:stream';
+import type { IncomingMessage } from 'node:http';
+import type { Context, Hub, WebSocket } from '../level0/types.ts';
+/** Hub 类型自 L0 types.ts 重出（历史导入路径兼容）。 */
+export type { Hub } from '../level0/types.ts';
+/** WebSocket lifecycle handler. */
+export type WebSocketHandler = {
+    open?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    message?: (ws: WebSocket, ctx: Context, data: string | Buffer) => void | Promise<void>;
+    close?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>;
+};
+/**
+ * WS 升级端口（core 契约）——协议侧实现属装备：
+ * - 默认：自研 RFC6455（src/level5/server/ws/native/——`weifuwu` 入口 serve() 自动注入）
+ * - `ws` 包实现 / 测试替身：同一结构即可替换（差分对账参考）
+ *
+ * 缺适配器且注册了 WS 路由 → serve() 显式报错（不静默 404）。
+ */
+export interface WsHandlePort {
+    /** HTTP upgrade → 协议握手；完成时回调连接（结构兼容 ws 的 handleUpgrade） */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: WebSocket) => void): void;
+    /** 优雅停机：通知活跃连接关闭（1001）并等待握手（可选——无连接管理时省略） */
+    shutdown?(): void | Promise<void>;
+}
+type WsMatch = {
+    handler: WebSocketHandler;
+    params: Record<string, string>;
+};
+export type WsUpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+/**
+ * Minimal context shape for WS handler execution.
+ * ctx.hub = 路由级 Hub（默认内存，可用 app.wsHub() 替换为 Redis 后端）。
+ */
+export declare function createWsUpgradeHandler(port: WsHandlePort, matchWs: (segments: string[]) => WsMatch | null, hub: Hub): WsUpgradeHandler;

package/dist/level2/ws.ts

@@ -0,0 +1,148 @@
+/**
+ * WebSocket upgrade + connection lifecycle.
+ *
+ * Handles the HTTP-to-WS upgrade and per-connection state.
+ * Used internally by Router — not exported to end users.
+ *
+ * W2 端口化：core 不依赖 `ws`——协议侧由 `WsHandlePort` 注入
+ * （默认实现 src/level5/server/ws/native/——W5 自研 RFC6455；`ws` 仅差分参考）。
+ */
+
+import type { Duplex } from 'node:stream'
+import type { IncomingMessage } from 'node:http'
+import type { Context, Hub, WebSocket } from '../level0/types.ts'
+
+/** Hub 类型自 L0 types.ts 重出（历史导入路径兼容）。 */
+export type { Hub } from '../level0/types.ts'
+
+/** WebSocket lifecycle handler. */
+export type WebSocketHandler = {
+  open?: (ws: WebSocket, ctx: Context) => void | Promise<void>
+  message?: (ws: WebSocket, ctx: Context, data: string | Buffer) => void | Promise<void>
+  close?: (ws: WebSocket, ctx: Context) => void | Promise<void>
+  error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>
+}
+
+/**
+ * WS 升级端口（core 契约）——协议侧实现属装备：
+ * - 默认：自研 RFC6455（src/level5/server/ws/native/——`weifuwu` 入口 serve() 自动注入）
+ * - `ws` 包实现 / 测试替身：同一结构即可替换（差分对账参考）
+ *
+ * 缺适配器且注册了 WS 路由 → serve() 显式报错（不静默 404）。
+ */
+export interface WsHandlePort {
+  /** HTTP upgrade → 协议握手；完成时回调连接（结构兼容 ws 的 handleUpgrade） */
+  handleUpgrade(
+    req: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+    callback: (ws: WebSocket) => void,
+  ): void
+  /** 优雅停机：通知活跃连接关闭（1001）并等待握手（可选——无连接管理时省略） */
+  shutdown?(): void | Promise<void>
+}
+
+type WsMatch = { handler: WebSocketHandler; params: Record<string, string> }
+
+export type WsUpgradeHandler = (
+  req: IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+) => void
+
+/**
+ * hook 错误兑底（S3——SERVER-PERF-PLAN 波次 1）：
+ * 任意 hook（open/message/close）同步抛错或异步拒绝都**不逃逸进程**
+ * （无兑底 = unhandledRejection/uncaughtException = 生产整机宕机——实证）：
+ *   - 有 error hook → 转交（应用获得感知点）
+ *   - 无 error hook → console.error（审计可见——静默吞错是违例）
+ */
+function safeHook<A extends unknown[]>(
+  hookName: string,
+  fn: ((...args: A) => unknown) | undefined,
+  onError: ((err: Error) => void) | null,
+): (...args: A) => void {
+  if (!fn) return () => {}
+  const report = (err: unknown) => {
+    const e = err instanceof Error ? err : new Error(String(err))
+    if (onError) {
+      onError(e)
+    } else {
+      console.error(`[ws] ${hookName} handler error:`, e.stack || e.message)
+    }
+  }
+  return (...args: A) => {
+    try {
+      const result = fn(...args)
+      if (
+        result &&
+        typeof (result as Promise<unknown>).catch === 'function'
+      ) {
+        ;(result as Promise<unknown>).catch(report)
+      }
+    } catch (err) {
+      report(err)
+    }
+  }
+}
+
+/**
+ * Minimal context shape for WS handler execution.
+ * ctx.hub = 路由级 Hub（默认内存，可用 app.wsHub() 替换为 Redis 后端）。
+ */
+export function createWsUpgradeHandler(
+  port: WsHandlePort,
+  matchWs: (segments: string[]) => WsMatch | null,
+  hub: Hub,
+): WsUpgradeHandler {
+  return (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const segments = req.url?.split('/').filter(Boolean) ?? []
+    const match = matchWs(segments)
+
+    if (!match) {
+      socket.destroy()
+      return
+    }
+
+    port.handleUpgrade(req, socket, head, (ws: WebSocket) => {
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const ctx = { params: match.params, query: Object.fromEntries(url.searchParams), hub } as Context
+      const h = match.handler
+
+      // error hook 本体也要兑底（防递归/防二次逃逸）
+      const errorHook = h.error
+        ? (err: Error) => {
+            try {
+              const result = h.error!(ws, ctx, err)
+              if (result && typeof (result as Promise<unknown>).catch === 'function') {
+                ;(result as Promise<unknown>).catch((e: unknown) =>
+                  console.error('[ws] error handler failed:', e),
+                )
+              }
+            } catch (e) {
+              console.error('[ws] error handler failed:', e)
+            }
+          }
+        : null
+
+      const openHook = safeHook('open', h.open, errorHook)
+      const messageHook = safeHook('message', h.message, errorHook)
+      const closeHook = safeHook('close', h.close, errorHook)
+
+      openHook(ws, ctx)
+      // 适配器归一（W5）：text → string（native 已归一；ws 库 text 也发 Buffer——isBinary=false）；
+      // 无 isBinary 的替身实现保持原 payload（向后兼容）。
+      ws.on('message', (data, isBinary) => {
+        const payload =
+          isBinary === false && typeof data !== 'string' ? String(data) : (data as string | Buffer)
+        messageHook(ws, ctx, payload)
+      })
+      ws.on('close', () => closeHook(ws, ctx))
+      ws.on('error', (error) => {
+        const e = error as Error
+        if (errorHook) errorHook(e)
+        else console.error('[ws] connection error:', e.message)
+      })
+    })
+  }
+}

package/dist/level3/vdom/browser/Browser.ts

@@ -0,0 +1,78 @@
+/**
+ * vdom browser — 浏览器环境接口（依赖注入——uiServe 显式接收）
+ *
+ * 设计（2026-12）：uiServe(router, { root, browser })——**无全局依赖**——
+ * 注入 window/document 两字段为基座 + **组件消费面方法**（设计规则 §5.5——
+ * 组件禁止直接访问 DOM 全局——一律经 ctx.browser 唯一入口——46 处迁移
+ * 基线）。接口按组件库消费面扩展（P2 组件迁移——activeElement/byId/
+ * copyText/scrollTop/storage 等）。
+ *
+ * 三态实现：客户端 createClientBrowser（惰性 typeof 防御）· SSR shim
+ * （null/0/false/no-op——组件 SSR 安全）· 测试 testBrowser()/jsdom。
+ */
+
+/** 浏览器环境（基座 window/document + 组件消费面方法） */
+export interface Browser {
+  /** 浏览器窗口（location/事件/媒体查询/定时器——完整环境面） */
+  window: Window
+  /** 文档（元素创建/查询——渲染 DOM 面） */
+  document: Document
+
+  // ── 组件消费面（设计规则 §5.5 能力映射表——唯一入口） ──
+  /** 复制文本 */
+  copyText(text: string): void
+  /** 下载文件（dataURL/blob） */
+  downloadFile(filename: string, content: string, mime?: string): boolean
+  /** 当前聚焦元素 */
+  activeElement(): HTMLElement | null
+  /** 按 id 查询 */
+  byId(id: string): HTMLElement | null
+  /** 查询元素（CSS 选择器） */
+  query(sel: string): HTMLElement | null
+  queryAll(sel: string): NodeListOf<Element> | null
+  /** 创建元素/片段/注释/文本 */
+  createElement<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K] | null
+  createElementNS(ns: string, tag: string): Element | null
+  createDocumentFragment(): DocumentFragment | null
+  createComment(text: string): Comment | null
+  createTextNode(text: string): Text | null
+  /** 事件监听（全局——组件层统一入口） */
+  addEventListener(type: string, fn: (e: any) => void, options?: any): void
+  removeEventListener(type: string, fn: (e: any) => void, options?: any): void
+/** 页面刷新（location.reload——应用层重试/回滚后刷新） */
+  reload(): void
+  /** 滚动 */
+  scrollTo(y: number): void
+  /** 当前滚动量（scrollingElement 优先——headless 漂移防护） */
+  scrollTop(): number
+  /** 媒体查询（matchMedia——headless 无 → null） */
+  matchMedia(query: string): MediaQueryList | null
+  /** 可视视口（visualViewport——键盘弹起/缩放） */
+  visualViewport(): VisualViewport | null
+  /** 滚动根元素 */
+  scrollingElement(): Element | null
+  bodyElement(): HTMLElement | null
+  bodyAppend(el: Node): void
+  bodyRemove(el: Node): void
+  clearBody(): void
+  /** 事件构造（jsdom 兼容——跨 realm 安全） */
+  event(type: string, init?: any): Event
+  /** 主题根元素 */
+  rootElement(): HTMLElement | null
+  /** 选区 */
+  getSelection(): Selection | null
+  selectionText(): string
+  /** 存储（SSR/隐私模式安全） */
+  storageGet(key: string): string | null
+  storageSet(key: string, value: string): void
+  /** 定时器（SSR no-op） */
+  timeout(fn: () => void, ms: number): number
+  /** 当前路径 */
+  pathname(): string
+  /** 设置 hash（锚点滚动——Anchor 用） */
+  setHash(hash: string): void
+  /** 视口高度 */
+  viewportHeight(): number
+  /** 表单恢复回调（ui-dom 兼容——Slider/Form 字段恢复） */
+  onFormRestore?(fn: () => void): void
+}