weifuwu 0.94.0 → 0.95.0

package/dist/level0/router/trie.d.ts

@@ -0,0 +1,69 @@
+/**
+ * weifuwu shared — Trie 路径匹配核心（前后端共用——零 HTTP 依赖）
+ *
+ * 来源：后端 Router（src/level2/router.ts）的 Trie 匹配逻辑抽离——
+ * 真实事故语义保留：
+ * - **静态段优先** → :param → * 通配（O(path_segments) 匹配——确定性——
+ *   注册序优先静态）
+ * - **param 冲突检查**：同一位置 :id 与 :name 并存抛错（不静默）
+ * - **通配独立槽**：精确 value 与通配 value 互不覆盖（showcase SSR 事故——
+ *   '/' + '/*' 并存时通配曾抢先精确 handler）
+ * - **根路径 '/'**：splitPath 过滤空段返回 []——value 绑 root 节点
+ *
+ * 泛型 value：后端 = method 表（{ handlers, middlewares }）；前端 = 页面
+ * handler。匹配返回 { value, params }——params 注入由调用方决定
+ * （后端 ctx/前端 req）。
+ */
+/** 泛型 Trie 节点 */
+export interface TrieNode<T> {
+    children: Map<string, TrieNode<T>>;
+    /** 参数段名（:id → 'id'——该子节点是参数槽） */
+    param?: string;
+    /** 通配段（*——匹配剩余任意段） */
+    wildcard?: boolean;
+    /** 精确路径 value（路径完全匹配） */
+    value?: T;
+    /** 通配路径 value（独立槽——不被精确覆盖；反之亦然） */
+    wildcardValue?: T;
+}
+export declare function createTrie<T>(): TrieNode<T>;
+/** 路径分段（'/a/b' → ['a','b']——空段过滤——根路径 '/' → []） */
+export declare function splitPath(path: string): string[];
+/**
+ * 查找路径终点节点（不含通配语义——用于冲突检查/多方法合并）——
+ * 遇 '*' 段返回当前节点（通配槽）；未注册路径返回 null。
+ *
+ * **精确匹配纪律（真实事故——agent-platform 沙盒路由）**：静态段只匹配
+ * 静态子节点——参数段（:xxx）只匹配参数槽。此前静态段用 `children.get(':')`
+ * 兜底——`:id/debug` 会命中 `:id/:action` 参数槽（children key ':'）——
+ * 冲突检查返回 POST action 节点——value.handlers.set('GET', debugHandler)
+ * **污染共享 value**（GET 写进 POST action 的 handlers）——后续
+ * `:id/<静态段>`（processes/stats）注册时再次命中 action 槽——误报
+ * `route conflict already registered`。
+ */
+export declare function trieFind<T>(root: TrieNode<T>, path: string): TrieNode<T> | null;
+/**
+ * 注册（path → value）——分段插入：
+ * '/'（空段）→ value 绑 root；'*' 结尾 → wildcardValue（独立槽）；
+ * 其余逐段 getOrCreateChild——终点绑 value。返回终点节点（冲突检查）。
+ */
+/**
+ * 注册（path → value）——分段插入：
+ * '/'（空段）→ value 绑 root；'*' 结尾 → wildcardValue（独立槽——
+ * **path 自描述**——SHARED-TRIE D1 收紧：原 isWildcardValue 参数与
+ * 内部 path.includes('*') 判定重复（恒真验证：生产调用面 isWildcard =
+ * path.includes('*')——第三态零消费——参数删除））；
+ * 其余逐段 getOrCreateChild——终点绑 value。返回终点节点（冲突检查）。
+ */
+export declare function trieRegister<T>(root: TrieNode<T>, path: string, value: T): TrieNode<T>;
+/**
+ * 匹配（segments → { value, params, wildcard } | null）：
+ * 精确优先（DFS——静态 → :param 回溯——见 exactDfs）——精确未命中 → 通配
+ * 兜底（从 root 沿路径检查任意前缀深度的通配注册——params['*'] = 剩余段）；
+ * 精确命中且节点有通配槽（'/' + '/*' 并存）→ params['*'] = ''（精确优先标记）。
+ */
+export declare function trieMatch<T>(root: TrieNode<T>, segments: string[]): {
+    value: T;
+    params: Record<string, string>;
+    wildcard: boolean;
+} | null;

package/dist/level0/router/trie.ts

@@ -0,0 +1,202 @@
+/**
+ * weifuwu shared — Trie 路径匹配核心（前后端共用——零 HTTP 依赖）
+ *
+ * 来源：后端 Router（src/level2/router.ts）的 Trie 匹配逻辑抽离——
+ * 真实事故语义保留：
+ * - **静态段优先** → :param → * 通配（O(path_segments) 匹配——确定性——
+ *   注册序优先静态）
+ * - **param 冲突检查**：同一位置 :id 与 :name 并存抛错（不静默）
+ * - **通配独立槽**：精确 value 与通配 value 互不覆盖（showcase SSR 事故——
+ *   '/' + '/*' 并存时通配曾抢先精确 handler）
+ * - **根路径 '/'**：splitPath 过滤空段返回 []——value 绑 root 节点
+ *
+ * 泛型 value：后端 = method 表（{ handlers, middlewares }）；前端 = 页面
+ * handler。匹配返回 { value, params }——params 注入由调用方决定
+ * （后端 ctx/前端 req）。
+ */
+
+/** 泛型 Trie 节点 */
+export interface TrieNode<T> {
+  children: Map<string, TrieNode<T>>
+  /** 参数段名（:id → 'id'——该子节点是参数槽） */
+  param?: string
+  /** 通配段（*——匹配剩余任意段） */
+  wildcard?: boolean
+  /** 精确路径 value（路径完全匹配） */
+  value?: T
+  /** 通配路径 value（独立槽——不被精确覆盖；反之亦然） */
+  wildcardValue?: T
+}
+
+export function createTrie<T>(): TrieNode<T> {
+  return { children: new Map() }
+}
+
+/** 路径分段（'/a/b' → ['a','b']——空段过滤——根路径 '/' → []） */
+export function splitPath(path: string): string[] {
+  return path.split('/').filter(Boolean)
+}
+
+function createParamChild<T>(
+  node: TrieNode<T>, segment: string, createNode: () => TrieNode<T>,
+): TrieNode<T> {
+  const paramName = segment.slice(1)
+  if (!node.children.has(':')) {
+    const child = createNode()
+    child.param = paramName
+    node.children.set(':', child)
+  }
+  const child = node.children.get(':')!
+  if (child.param !== paramName) {
+    throw new Error(
+      `[router] param conflict: ":${child.param}" already registered, cannot register ":${paramName}"`,
+    )
+  }
+  return child
+}
+
+function getOrCreateChild<T>(
+  node: TrieNode<T>, segment: string, createNode: () => TrieNode<T>,
+): TrieNode<T> {
+  if (segment === '*') {
+    node.wildcard = true
+    return node
+  }
+  if (segment.startsWith(':')) return createParamChild(node, segment, createNode)
+  if (!node.children.has(segment)) node.children.set(segment, createNode())
+  return node.children.get(segment)!
+}
+
+/**
+ * 查找路径终点节点（不含通配语义——用于冲突检查/多方法合并）——
+ * 遇 '*' 段返回当前节点（通配槽）；未注册路径返回 null。
+ *
+ * **精确匹配纪律（真实事故——agent-platform 沙盒路由）**：静态段只匹配
+ * 静态子节点——参数段（:xxx）只匹配参数槽。此前静态段用 `children.get(':')`
+ * 兜底——`:id/debug` 会命中 `:id/:action` 参数槽（children key ':'）——
+ * 冲突检查返回 POST action 节点——value.handlers.set('GET', debugHandler)
+ * **污染共享 value**（GET 写进 POST action 的 handlers）——后续
+ * `:id/<静态段>`（processes/stats）注册时再次命中 action 槽——误报
+ * `route conflict already registered`。
+ */
+export function trieFind<T>(root: TrieNode<T>, path: string): TrieNode<T> | null {
+  const segments = splitPath(path)
+  let node: TrieNode<T> | null = root
+  for (const segment of segments) {
+    if (!node) return null
+    if (segment === '*') return node
+    node = segment.startsWith(':')
+      ? (node.children.get(':') ?? null)
+      : (node.children.get(segment) ?? null)
+  }
+  return node
+}
+
+/**
+ * 注册（path → value）——分段插入：
+ * '/'（空段）→ value 绑 root；'*' 结尾 → wildcardValue（独立槽）；
+ * 其余逐段 getOrCreateChild——终点绑 value。返回终点节点（冲突检查）。
+ */
+/**
+ * 注册（path → value）——分段插入：
+ * '/'（空段）→ value 绑 root；'*' 结尾 → wildcardValue（独立槽——
+ * **path 自描述**——SHARED-TRIE D1 收紧：原 isWildcardValue 参数与
+ * 内部 path.includes('*') 判定重复（恒真验证：生产调用面 isWildcard =
+ * path.includes('*')——第三态零消费——参数删除））；
+ * 其余逐段 getOrCreateChild——终点绑 value。返回终点节点（冲突检查）。
+ */
+export function trieRegister<T>(
+  root: TrieNode<T>, path: string, value: T,
+): TrieNode<T> {
+  const segments = splitPath(path)
+  let node = root
+  for (const segment of segments) {
+    if (segment === '*') {
+      node.wildcard = true
+      node.wildcardValue = value
+      return node
+    }
+    node = getOrCreateChild(node, segment, () => createTrie<T>())
+  }
+  node.value = value
+  return node
+}
+
+/**
+ * **精确匹配 DFS（ROUTER-CORE A3 fuzz 实证修复——2027-10）**：静态优先 +
+ * param 回溯——**first hit = 逐段贪心最具体路线**。
+ *
+ * **回溯必要性（fuzz seed=11 req=c/c 实证）**：`/c/c/*`（通配）与
+ * `/:p0/c`（精确）并存时——逐段贪心走静态 'c' 路线到通配 fallback——
+ * param 路线（精确 `/:p0/c`）被静态首段**遮蔽后不回溯**——违反
+ * 「精确 > 通配」语义。DFS：静态分支失败后回溯 param 分支——精确命中
+ * 优先于任何通配。
+ */
+function exactDfs<T>(
+  node: TrieNode<T>, segments: string[], i: number, params: Record<string, string>,
+  want: 'value' | 'wildcard' = 'value',
+): { value: T; params: Record<string, string>; node: TrieNode<T> } | null {
+  if (i === segments.length) {
+    const v = want === 'value' ? node.value : node.wildcardValue
+    return v !== undefined ? { value: v, params: { ...params }, node } : null
+  }
+  const seg = segments[i]
+  // 静态优先（逐段贪心——具体者胜）
+  const st = node.children.get(seg)
+  if (st) {
+    const r = exactDfs(st, segments, i + 1, params, want)
+    if (r) return r
+  }
+  // param 回溯（静态路线失败后——精确语义完整性）
+  const p = node.children.get(':')
+  if (p?.param) {
+    const params2 = { ...params, [p.param]: decodeURIComponent(seg) }
+    const r = exactDfs(p, segments, i + 1, params2, want)
+    if (r) return r
+  }
+  return null
+}
+
+/**
+ * 匹配（segments → { value, params, wildcard } | null）：
+ * 精确优先（DFS——静态 → :param 回溯——见 exactDfs）——精确未命中 → 通配
+ * 兜底（从 root 沿路径检查任意前缀深度的通配注册——params['*'] = 剩余段）；
+ * 精确命中且节点有通配槽（'/' + '/*' 并存）→ params['*'] = ''（精确优先标记）。
+ */
+export function trieMatch<T>(
+  root: TrieNode<T>, segments: string[],
+): { value: T; params: Record<string, string>; wildcard: boolean } | null {
+  // 精确匹配（DFS——静态优先 + param 回溯——A3 fuzz 实证修复）
+  // **空段（根路径 '/'）天然处理**：exactDfs(root, [], 0) 终端即 root——
+  // （A2 统一——原手写空段分支与 DFS 逻辑重复——语义漂移面）
+  const exact = exactDfs(root, segments, 0, {})
+  if (exact) {
+    // 精确命中节点若有通配槽（'/' + '/*' 并存）→ '*': ''（精确优先标记）
+    const hasWf = exact.node.wildcardValue !== undefined
+    return { value: exact.value, params: hasWf ? { ...exact.params, '*': '' } : exact.params, wildcard: false }
+  }
+  // 精确未命中 → 通配兜底（SPA catch-all 场景）
+  return wildcardFallback(root, segments, segments.length)
+}
+
+/**
+ * 通配兜底（精确失败后——**逐前缀深度浅优先 + exactDfs 回溯**——A3 fuzz
+ * seed=42 实证修复）：
+ * **旧实现**（matchChild 逐段）与精确匹配同病——静态子节点遮蔽 param 槽
+ * 且不回溯——`/a/:p1/c` 的静态 'a' 遮蔽 `/:p0/a/*` 的 param 前缀路线——
+ * fallback 走错分支后失败返回 null（通配注册静默丢失）。
+ * **新实现**：对每个前缀深度 d（0..len——**浅优先**：`/*` 与 `/a/*` 并存
+ * 时 root 通配胜——探针②实证）——exactDfs（带回溯）匹配前 d 段——
+ * 到达节点有 wildcardValue 即命中。
+ */
+function wildcardFallback<T>(
+  root: TrieNode<T>, segments: string[], depth: number,
+): { value: T; params: Record<string, string>; wildcard: boolean } | null {
+  for (let d = 0; d <= depth; d++) {
+    const r = exactDfs(root, segments.slice(0, d), 0, {}, 'wildcard')
+    if (r) {
+      return { value: r.value, params: { ...r.params, '*': segments.slice(d).join('/') }, wildcard: true }
+    }
+  }
+  return null
+}

package/dist/level0/router/types.ts

@@ -0,0 +1,34 @@
+/**
+ * shared router 类型（SHARED-TRIE-EXCELLENCE B0——2027-10）
+ *
+ * **双端同构的机制形状**（server/types.ts 与 client PageHandler 字面同构——
+ * handler 签名 `(req: Request, ctx) => Response`、middleware洋葱
+ * `(req, ctx, next) => Response`——单一实现源）。server/types.ts 可
+ * re-export（D 波次收紧时统一）——当前结构类型兼容并存。
+ */
+
+/** 路由 handler——双端签名同构（req 标准 Request 零扩展；Response 原生） */
+export type SharedHandler<TCtx = unknown> = (
+  req: Request,
+  ctx: TCtx,
+) => Response | Promise<Response>
+
+/** 中间件——洋葱模型（next 调用透传——可短路可改写响应） */
+export type SharedMiddleware<TCtx = unknown> = (
+  req: Request,
+  ctx: TCtx,
+  next: SharedHandler<TCtx>,
+) => Response | Promise<Response>
+
+/** middleware 元信息（ctx 扩展声明——depends 必须先注册/injects 登记字段） */
+export interface MiddlewareMeta {
+  /** Fields this middleware injects into ctx. */
+  injects: string[]
+  /** Fields this middleware depends on (must be injected earlier). */
+  depends: string[]
+}
+
+/** 带 meta 的 middleware（__meta 可选——ctx-fields 注册表检查依据） */
+export type MetaMiddleware<TCtx = unknown> = SharedMiddleware<TCtx> & {
+  __meta?: MiddlewareMeta
+}

package/dist/level0/types.d.ts

@@ -0,0 +1,112 @@
+/** Re-export for downstream usage. */
+/** Lightweight WebSocket interface for WS handler types (avoids external dep resolution). */
+export interface WebSocket {
+    send(data: string | Buffer): void;
+    close(code?: number, reason?: string): void;
+    ping(data?: unknown): void;
+    readyState: number;
+    readonly OPEN: number;
+    readonly CLOSED: number;
+    readonly CONNECTING: number;
+    readonly CLOSING: number;
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    off(event: string, handler: (...args: unknown[]) => void): this;
+    addEventListener(event: string, handler: (...args: unknown[]) => void): void;
+    removeEventListener(event: string, handler: (...args: unknown[]) => void): void;
+}
+/**
+ * WebSocket 房间 Hub——发布/订阅组（默认内存实现 core/hub.ts；
+ * 多实例部署可注入自定义实现——`app.wsHub(hub)`）。L0 协议面：不依赖任何实现。
+ */
+export interface Hub {
+    join(key: string, ws: WebSocket): void;
+    leave(ws: WebSocket): void;
+    send(key: string, message: string): void;
+    close(): Promise<void>;
+}
+/** User injected by user() or custom auth middleware. */
+export interface User {
+    id: string;
+    role?: string;
+    tenant?: string;
+    [key: string]: unknown;
+}
+export interface Context {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    mountPath?: string;
+    /** Currently authenticated user (set by user() or userSystem()). */
+    user?: User | null;
+    loaderData?: Record<string, unknown>;
+    /** Public environment variables. */
+    env?: Record<string, string>;
+    /** WebSocket 房间 Hub（仅 WS 连接 ctx 注入；HTTP 请求 ctx 为 undefined） */
+    hub?: Hub;
+    [key: string]: unknown;
+}
+export type Handler<T extends object = Context> = (req: Request, ctx: T) => Response | Promise<Response>;
+/**
+ * Metadata for middleware dependency checking.
+ * Middleware factories attach this for runtime validation.
+ */
+export interface MiddlewareMeta {
+    /** Fields this middleware injects into ctx. */
+    injects: string[];
+    /** Fields this middleware depends on (must be injected earlier). */
+    depends: string[];
+}
+export type Middleware<In extends Context = Context, Out extends In = In> = {
+    (req: Request, ctx: In, next: Handler<Out>): Response | Promise<Response>;
+    __meta?: MiddlewareMeta;
+};
+export type ErrorHandler<T extends object = Context> = (error: Error, req: Request, ctx: T) => Response | Promise<Response>;
+/**
+ * Interface for resources that require explicit cleanup (connections, pools, timers).
+ * All stateful modules implement this.
+ */
+export interface Closeable {
+    /** Release all resources. Call once when shutting down. */
+    close(): Promise<void>;
+}
+/**
+ * HTTP error with an explicit status code.
+ * Throw from a handler or middleware to return a non-200 response.
+ *
+ * ```ts
+ * if (!resource) throw new HttpError('Not found', 404)
+ * serve() catches it and returns the status code.
+ * ```
+ */
+export declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * 类型安全的中间件工厂 — 减少中间件样板代码。
+ *
+ * 自动生成 `__meta`，自动类型推导注入字段。
+ * 开发者仍需用 `declare module` 扩展 Context 接口以获得编译时类型检查。
+ *
+ * ```ts
+ * declare module 'weifuwu' {
+ *   interface Context { myField: string }
+ * }
+ *
+ * const myMw = createMiddleware({
+ *   injects: ['myField'],
+ *   depends: ['orm'],
+ *   setup: async (ctx) => {
+ *     const result = await ctx.orm.query.from('things').where({ kind: { eq: 'x' } }).run()
+ *     return { myField: result }
+ *   },
+ * })
+ * ```
+ */
+export declare function createMiddleware<C extends Record<string, unknown>>(config: {
+    /** 此中间件注入的字段名列表（用于 __meta） */
+    injects: (keyof C)[];
+    /** 此中间件依赖的字段名列表（必须已被前面的中间件注入） */
+    depends?: string[];
+    /** 初始化逻辑，返回要注入到 ctx 的值 */
+    setup: (ctx: Context) => C | Promise<C>;
+}): Middleware<Context, Context & C>;

package/dist/level0/types.ts

@@ -0,0 +1,153 @@
+
+/** Re-export for downstream usage. */
+/** Lightweight WebSocket interface for WS handler types (avoids external dep resolution). */
+export interface WebSocket {
+  send(data: string | Buffer): void
+  close(code?: number, reason?: string): void
+  ping(data?: unknown): void
+  readyState: number
+  readonly OPEN: number
+  readonly CLOSED: number
+  readonly CONNECTING: number
+  readonly CLOSING: number
+  on(event: string, handler: (...args: unknown[]) => void): this
+  off(event: string, handler: (...args: unknown[]) => void): this
+  addEventListener(event: string, handler: (...args: unknown[]) => void): void
+  removeEventListener(event: string, handler: (...args: unknown[]) => void): void
+}
+
+/**
+ * WebSocket 房间 Hub——发布/订阅组（默认内存实现 core/hub.ts；
+ * 多实例部署可注入自定义实现——`app.wsHub(hub)`）。L0 协议面：不依赖任何实现。
+ */
+export interface Hub {
+  join(key: string, ws: WebSocket): void
+  leave(ws: WebSocket): void
+  send(key: string, message: string): void
+  close(): Promise<void>
+}
+
+/** User injected by user() or custom auth middleware. */
+export interface User {
+  id: string
+  role?: string
+  tenant?: string
+  [key: string]: unknown
+}
+
+// Context — extensible via module augmentation.
+
+export interface Context {
+  params: Record<string, string>
+  query: Record<string, string>
+  mountPath?: string
+  /** Currently authenticated user (set by user() or userSystem()). */
+  user?: User | null
+  loaderData?: Record<string, unknown>
+  /** Public environment variables. */
+  env?: Record<string, string>
+  /** WebSocket 房间 Hub（仅 WS 连接 ctx 注入；HTTP 请求 ctx 为 undefined） */
+  hub?: Hub
+  [key: string]: unknown // allow arbitrary middleware-injected data
+}
+
+// Generic handler — T extends Context so middleware-injected properties are visible.
+// Default T = Context means no generics needed for simple cases.
+export type Handler<T extends object = Context> = (
+  req: Request,
+  ctx: T,
+) => Response | Promise<Response>
+
+/**
+ * Metadata for middleware dependency checking.
+ * Middleware factories attach this for runtime validation.
+ */
+export interface MiddlewareMeta {
+  /** Fields this middleware injects into ctx. */
+  injects: string[]
+  /** Fields this middleware depends on (must be injected earlier). */
+  depends: string[]
+}
+
+// Generic middleware — In receives accumulated context from previous middlewares,
+// Out adds new properties. next receives the enriched Out type.
+// Default In = Out = Context means backward-compatible.
+export type Middleware<In extends Context = Context, Out extends In = In> = {
+  (req: Request, ctx: In, next: Handler<Out>): Response | Promise<Response>
+  __meta?: MiddlewareMeta
+}
+
+export type ErrorHandler<T extends object = Context> = (
+  error: Error,
+  req: Request,
+  ctx: T,
+) => Response | Promise<Response>
+
+/**
+ * Interface for resources that require explicit cleanup (connections, pools, timers).
+ * All stateful modules implement this.
+ */
+
+export interface Closeable {
+  /** Release all resources. Call once when shutting down. */
+  close(): Promise<void>
+}
+
+/**
+ * HTTP error with an explicit status code.
+ * Throw from a handler or middleware to return a non-200 response.
+ *
+ * ```ts
+ * if (!resource) throw new HttpError('Not found', 404)
+ * serve() catches it and returns the status code.
+ * ```
+ */
+export class HttpError extends Error {
+  status: number
+  constructor(message: string, status: number) {
+    super(message)
+    this.name = 'HttpError'
+    this.status = status
+  }
+}
+
+/**
+ * 类型安全的中间件工厂 — 减少中间件样板代码。
+ *
+ * 自动生成 `__meta`，自动类型推导注入字段。
+ * 开发者仍需用 `declare module` 扩展 Context 接口以获得编译时类型检查。
+ *
+ * ```ts
+ * declare module 'weifuwu' {
+ *   interface Context { myField: string }
+ * }
+ *
+ * const myMw = createMiddleware({
+ *   injects: ['myField'],
+ *   depends: ['orm'],
+ *   setup: async (ctx) => {
+ *     const result = await ctx.orm.query.from('things').where({ kind: { eq: 'x' } }).run()
+ *     return { myField: result }
+ *   },
+ * })
+ * ```
+ */
+export function createMiddleware<C extends Record<string, unknown>>(config: {
+  /** 此中间件注入的字段名列表（用于 __meta） */
+  injects: (keyof C)[]
+  /** 此中间件依赖的字段名列表（必须已被前面的中间件注入） */
+  depends?: string[]
+  /** 初始化逻辑，返回要注入到 ctx 的值 */
+  setup: (ctx: Context) => C | Promise<C>
+}): Middleware<Context, Context & C> {
+  const mw: Middleware = async (req, ctx, next) => {
+    const injected = await config.setup(ctx)
+    Object.assign(ctx, injected)
+    return next(req, ctx)
+  }
+  mw.__meta = {
+    injects: config.injects as unknown as string[],
+    depends: config.depends ?? [],
+  }
+  return mw as Middleware<Context, Context & C>
+}

package/dist/level0/vdom/command/create.ts

@@ -0,0 +1,28 @@
+/**
+ * vdom command — create（节点创建命令）
+ *
+ * create 携带 attrs = 可序列化面（class/id/style/data-*——服务端 create 即吐
+ * 完整开标签——不依赖后续 setProp）；运行时面（事件/ref）走 setProp。
+ */
+
+/** 创建元素（attrs 序列化面——服务端吐 HTML 开标签） */
+export type CreateCommand = {
+  op: 'create'
+  id: string
+  tag: string
+  attrs: Record<string, unknown>
+}
+
+/** 创建文本节点 */
+export type CreateTextCommand = {
+  op: 'createText'
+  id: string
+  value: string
+}
+
+/** 创建占位锚（空洞槽——childNodes 同构——detail 诊断信息） */
+export type CreateAnchorCommand = {
+  op: 'createAnchor'
+  id: string
+  detail?: string
+}

package/dist/level0/vdom/command/index.ts

@@ -0,0 +1,39 @@
+/**
+ * vdom command — index（命令汇总——统一导出 + 判定）
+ *
+ * 命令集 = 修改 DOM 的全部动作（流元素——纯数据——自足不依赖 vn 引用——
+ * 可序列化/可流——NDJSON 传输）。
+ */
+
+import type { CreateCommand, CreateTextCommand, CreateAnchorCommand } from './create.ts'
+import type { InsertCommand, MoveCommand, RemoveCommand } from './insert.ts'
+import type { SetPropCommand, SetTextCommand } from './props.ts'
+import type { RefCommand, UnrefCommand, MountCommand, UnmountCommand, CloseCommand, DoneCommand } from './lifecycle.ts'
+
+export type {
+  CreateCommand, CreateTextCommand, CreateAnchorCommand,
+  InsertCommand, MoveCommand, RemoveCommand,
+  SetPropCommand, SetTextCommand,
+  RefCommand, UnrefCommand, MountCommand, UnmountCommand,
+  CloseCommand, DoneCommand,
+}
+
+/** 渲染指令（流元素——修改 DOM 的最小操作集） */
+export type Command =
+  | CreateCommand
+  | CreateTextCommand
+  | CreateAnchorCommand
+  | InsertCommand
+  | MoveCommand
+  | RemoveCommand
+  | SetPropCommand
+  | SetTextCommand
+  | RefCommand
+  | UnrefCommand
+  | MountCommand
+  | UnmountCommand
+  | CloseCommand
+  | DoneCommand
+
+/** 命令名（调试/审计——op 类型收窄） */
+export type CommandOp = Command['op']

package/dist/level0/vdom/command/insert.ts

@@ -0,0 +1,35 @@
+/**
+ * vdom command — insert/remove（挂载与移除命令）
+ *
+ * insert 的 ref = 已插入的**前一个兄弟**（流式渲染——后一个尚未插入）——
+ * apply 侧插到 prev 之后（insertBefore(el, prev.nextSibling)）；ref null =
+ * 追加尾部。
+ */
+
+/** 挂载节点（parent/ref 均为节点 id） */
+export type InsertCommand = {
+  op: 'insert'
+  id: string
+  parent: string
+  ref: string | null
+}
+
+/** 移动节点（keyed 重排——**DOM 不重建**——子树 id 重映射——
+ *  id = 旧 id；ref = 前一个兄弟（insertAfter 语义——null = 尾部）；
+ *  first = 移到父最前（首位标记）；newId = 新位置 id（子树前缀迁移）） */
+export type MoveCommand = {
+  op: 'move'
+  id: string
+  parent: string
+  ref: string | null
+  newId: string
+  first?: boolean
+  /** 顺移 remap-only（相对顺序一致——DOM 位置自然到位——只做 id 前缀迁移） */
+  noMove?: boolean
+}
+
+/** 移除节点（含子树——事件监听随元素 GC） */
+export type RemoveCommand = {
+  op: 'remove'
+  id: string
+}