@vobs/runtime 1.7.8 → 1.8.1

package/src/dynamic.ts

@@ -19,8 +19,9 @@ interface ListEntry<T> {
   owner: Owner
   viewOwner: Owner
   item: Signal<T>
-  /** 最近一次赋值的原始 item：供比较与刷新使用，避免在列表 effect 内读取 item 信号造成自依赖。 */
-  value: T
+  /** 最近一次赋值的原始 item：供比较与刷新使用，避免在列表 effect 内读取 item 信号造成自依赖。
+   *  （刻意不叫 value —— `vobs check` 的 VOBS_C210 会把 `X.value` 的读写当成信号自订阅）。 */
+  current: T
   index: number
 }
 
@@ -161,6 +162,45 @@ export function insertList<T>(
       if (!allKeyed) keys = null
     }
 
+    /*
+     * 快路径：key 序列与上一轮**逐位相同** —— 行一个不多、一个不少、顺序也没变。
+     *
+     * 此时 DOM 已经是正确顺序（每次更新末尾的重排保证了「DOM 顺序 === entries 顺序」），
+     * 于是建表（Map）、查重（Set）、差集（retained Set）、重排（seq 数组 + LIS）**全都不需要**，
+     * 只同步每行的 item 与 index。这些记账是逐行的，200 行一次的固定成本实测约 34µs，
+     * 而这一轮真正需要做的 DOM 写只有 0.2µs（见 scripts/bench）。
+     *
+     * 扫描本身是 O(n) 的两次比较（key 与是否需重建），比省掉的记账便宜一个数量级。
+     * 任何一行需要重建（原始类型项的值变了 —— 那种行的视图是静态捕获的）就退回常规路径。
+     */
+    if (keys !== null && entries.length === items.length) {
+      let fast = true
+      for (let index = 0; index < keys.length; index++) {
+        if (!Object.is(entries[index].key, keys[index])) {
+          fast = false
+          break
+        }
+        const item = items[index]
+        if (isPrimitiveItem(item) && !Object.is(entries[index].current, item)) {
+          fast = false
+          break
+        }
+      }
+      if (fast) {
+        for (let index = 0; index < items.length; index++) {
+          const entry = entries[index]
+          entry.index = index
+          const item = items[index]
+          if (!Object.is(entry.current, item)) {
+            // item 信号写入在值相同时会被 Object.is 短路，所以这里只对真正变了的行动手
+            entry.item.value = item
+            entry.current = item
+          }
+        }
+        return
+      }
+    }
+
     const nextEntries = keys
       ? reconcileKeyed(items, keys, entries, renderItem)
       : reconcileIndexed(items, entries, renderItem)
@@ -283,7 +323,10 @@ function reconcileKeyed<T>(
   entries: Array<ListEntry<T>>,
   renderItem: (item: T, index: number) => VobsNode
 ): Array<ListEntry<T>> {
-  const previous = new Map(entries.map(entry => [entry.key, entry]))
+  // 逐项建表，不用 entries.map(...)：后者会先造一个等长的「键值对数组」中间产物，
+  // 200 行就是 200 个元组对象的分配 —— 每次更新都白付一次。
+  const previous = new Map<unknown, ListEntry<T>>()
+  for (const entry of entries) previous.set(entry.key, entry)
   const seen = new Set<unknown>()
   const nextEntries: Array<ListEntry<T>> = []
 
@@ -297,13 +340,13 @@ function reconcileKeyed<T>(
     const entry = previous.get(key)
     if (entry) {
       previous.delete(key)
-      if (isPrimitiveItem(item) && !Object.is(entry.value, item)) {
+      if (isPrimitiveItem(item) && !Object.is(entry.current, item)) {
         // 原始类型项在编译产物中被静态捕获，无法通过 item 信号刷新视图：值变化时必须重建行。
         nextEntries.push(createListEntry(item, index, key, renderItem))
         continue
       }
       entry.item.value = item
-      entry.value = item
+      entry.current = item
       nextEntries.push(entry)
       continue
     }
@@ -322,14 +365,14 @@ function reconcileIndexed<T>(
   for (let index = 0; index < items.length; index++) {
     const item = items[index]
     const entry = entries[index]
-    if (entry && isPrimitiveItem(item) && !Object.is(entry.value, item)) {
+    if (entry && isPrimitiveItem(item) && !Object.is(entry.current, item)) {
       // 原始类型项被编译产物静态捕获，值变化时必须重建行；旧行由主循环统一 dispose。
       nextEntries.push(createListEntry(item, index, index, renderItem))
       continue
     }
     if (entry) {
       entry.item.value = item
-      entry.value = item
+      entry.current = item
       nextEntries.push(entry)
       continue
     }
@@ -359,7 +402,7 @@ function createListEntry<T>(
     node = viewOwner.run(() => renderItem(toReactiveItem(itemSignal, item), index))
   })
   associateNodeOwner(node, viewOwner)
-  return { key, node, owner, viewOwner, item: itemSignal, value: item, index }
+  return { key, node, owner, viewOwner, item: itemSignal, current: item, index }
 }
 
 function refreshListEntry<T>(
@@ -374,7 +417,7 @@ function refreshListEntry<T>(
   entry.owner.run(() => {
     entry.viewOwner = createOwner()
     entry.node = entry.viewOwner.run(() => renderItem(
-      toReactiveItem(entry.item, entry.value),
+      toReactiveItem(entry.item, entry.current),
       index
     ))
   })
@@ -388,9 +431,8 @@ function toReactiveItem<T>(item: Signal<T>, initialValue: T): T {
     return initialValue
   }
 
-  // 代理目标使用创建时的原始对象：避免在列表 effect 内读取 item 信号造成自依赖；
-  // 属性读取始终转发到 item.value，在行内绑定 effect 中被正常追踪。
-  return new Proxy(initialValue as object, {
+  // 属性读取转发到 item.value（顶替后的新条目），由 get 陷阱完成追踪；目标见 reactiveProxyTarget。
+  return new Proxy(reactiveProxyTarget(initialValue), {
     get(_target, property, receiver) {
       return Reflect.get(item.value as object, property, receiver)
     },
@@ -400,12 +442,47 @@ function toReactiveItem<T>(item: Signal<T>, initialValue: T): T {
     ownKeys() {
       return Reflect.ownKeys(item.value as object)
     },
-    getOwnPropertyDescriptor(_target, property) {
-      return Object.getOwnPropertyDescriptor(item.value as object, property)
+    getOwnPropertyDescriptor(target, property) {
+      const descriptor = Object.getOwnPropertyDescriptor(item.value as object, property)
+      if (!descriptor) return undefined
+      // 目标上已有的自有属性不能改报"可配置性"（数组的 length 就不可配置），否则违反不变量
+      const own = Object.getOwnPropertyDescriptor(target, property)
+      return { ...descriptor, configurable: own ? own.configurable : true }
     }
   }) as T
 }
 
+/**
+ * 选择代理目标。
+ *
+ * 目标**不能**带"不可配置"的自有属性：代理把属性读取转发到 `item.value`（同 key 顶替后的
+ * 新条目），而 Proxy 不变量要求 get / getOwnPropertyDescriptor / ownKeys 与目标一致。实测
+ * `Object.freeze` 过的条目（@vobs/notification 每条通知都冻结）直接抛：
+ *
+ *   TypeError: 'get' on proxy: property 'content' is a read-only and non-configurable data
+ *   property on the proxy target but the proxy did not return its actual value
+ *
+ * 于是"冻结条目的行原地刷新"这条路径根本不可能成立（首轮渲染恰好同值，把问题掩盖了）。
+ *
+ * 安全的条目（可扩展 + 自有属性全部可配置：普通字面量、DOM 包装器等）照旧用条目自身当目标 ——
+ * jsdom 会把 sameObjectCaches 之类的 Symbol 缓存写在包装器上，写与读必须落在同一个对象上，
+ * 换目标会让 `element.classList` 直接抛 TypeError。冻结/密封/defineProperty 过的条目改用
+ * 同原型的空对象（数组用空数组，保住 Array.isArray）。
+ */
+function reactiveProxyTarget(value: object): object {
+  if (Object.isExtensible(value)) {
+    let allConfigurable = true
+    for (const key of Reflect.ownKeys(value)) {
+      if (Object.getOwnPropertyDescriptor(value, key)?.configurable === false) {
+        allConfigurable = false
+        break
+      }
+    }
+    if (allConfigurable) return value
+  }
+  return Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value) as object | null)
+}
+
 function disposeEntry(parent: Node, entry: ListEntry<unknown>): void {
   removeChild(parent, entry.node)
   entry.owner.dispose()

package/src/error.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { VobsError, formatVobsError, normalizeVobsError } from './error'
+import { VobsError, formatVobsError, isVobsError, normalizeVobsError } from './error'
 
 describe('Vobs error protocol', () => {
   it('normalizes unknown throws with a stable code', () => {
@@ -25,4 +25,79 @@ describe('Vobs error protocol', () => {
     expect(output).toContain('Fix: Guard the value before reading it.')
     expect(formatVobsError(error, { environment: 'production' })).toBe('[Vobs VOBS_R001] Component render failed')
   })
+
+  /*
+   * 诊断系统自己丢诊断 —— 三处都是这样。
+   * `isVobsError` 要求 code + message + layer 三者齐全，于是调用方递一个
+   * `{ code, message }` 会被判为「不是 VobsError」，掉进 String(value) 兜底，
+   * 输出 `[object Object]`，消息彻底消失。
+   */
+  describe('不丢消息', () => {
+    it('code + message 的结构化对象保留消息', () => {
+      const error = normalizeVobsError({ code: 'VOBS_H001', message: 'boom' })
+      expect(error.message).toBe('boom')
+      expect(error.message).not.toContain('[object')
+      expect(error.code).toBe('VOBS_H001')
+      expect(error.layer).toBe('runtime')
+      expect(formatVobsError(error).split('\n')[0]).toBe('[Vobs Error] boom')
+    })
+
+    it('只有 message 的对象也保留消息', () => {
+      expect(normalizeVobsError({ message: 'just a message' }).message).toBe('just a message')
+    })
+
+    it('既不是 Error 也没有 message 的值仍然给出可读内容', () => {
+      expect(normalizeVobsError({ some: 'object' }).message).toContain('object')
+      expect(normalizeVobsError(null).message).toBe('null')
+    })
+
+    it('isVobsError 不要求 layer 齐全', () => {
+      expect(isVobsError({ code: 'X', message: 'y' })).toBe(true)
+      expect(isVobsError({ code: 'X' })).toBe(false)
+      expect(isVobsError('not an error')).toBe(false)
+    })
+  })
+
+  /*
+   * tsup `splitting: false` 让 error.ts 同时进 dist/index.js 与 dist/error.js，
+   * 两份类互不 instanceof。跨入口传进来的实例必须被识别并复制成本地实例，
+   * 否则下游的 instanceof 与格式化都会走偏。
+   */
+  describe('跨打包副本的类身份', () => {
+    it('结构识别把外来实例复制成本地实例', () => {
+      // 模拟「另一个副本」：名字与字段都像 VobsError，但不 instanceof 本地类
+      const foreign = Object.assign(new Error('来自另一个副本'), {
+        name: 'VobsError',
+        code: 'VOBS_F001',
+        severity: 'error',
+        layer: 'runtime'
+      })
+      expect(foreign).not.toBeInstanceOf(VobsError)
+
+      const adopted = normalizeVobsError(foreign)
+      expect(adopted).toBeInstanceOf(VobsError)
+      expect(adopted.code).toBe('VOBS_F001')
+      expect(adopted.message).toBe('来自另一个副本')
+      expect(adopted.cause).toBe(foreign)
+    })
+
+    it('本地实例原样返回，普通 Error 保持同一性', () => {
+      const local = new VobsError({ code: 'VOBS_L', message: 'local' })
+      expect(normalizeVobsError(local)).toBe(local)
+
+      const plain = new TypeError('plain')
+      const normalized = normalizeVobsError(plain, { code: 'VOBS_P' })
+      expect(normalized).toBe(plain)
+      expect((plain as { code?: string }).code).toBe('VOBS_P')
+    })
+
+    it('冻结的 Error 上挂不上元数据时复制成本地实例，而不是丢掉 code', () => {
+      const frozen = Object.freeze(new Error('frozen boom'))
+      const normalized = normalizeVobsError(frozen, { code: 'VOBS_FROZEN' })
+
+      expect(normalized.code).toBe('VOBS_FROZEN')
+      expect(normalized.message).toBe('frozen boom')
+      expect(normalized.cause).toBe(frozen)
+    })
+  })
 })

package/src/error.ts

@@ -69,17 +69,77 @@ export function createVobsError(options: VobsErrorOptions): VobsError {
   return new VobsError(options)
 }
 
+/**
+ * 结构化识别（不依赖 `instanceof`）。
+ *
+ * **不能要求 `layer` 也齐全** —— 原来要求 code + message + layer 三者都是字符串，
+ * 于是调用方递一个 `{ code, message }` 就会被判为「不是 VobsError」，掉进最后的
+ * `String(value)` 兜底，输出 `[object Object]`：诊断系统自己把诊断丢了。
+ * layer 缺失在下面构造时会补上默认值，没有理由在识别阶段就否掉。
+ */
 export function isVobsError(value: unknown): value is VobsError {
   return value instanceof VobsError
     || Boolean(value && typeof value === 'object'
       && typeof (value as { code?: unknown }).code === 'string'
-      && typeof (value as { message?: unknown }).message === 'string'
-      && typeof (value as { layer?: unknown }).layer === 'string')
+      && typeof (value as { message?: unknown }).message === 'string')
+}
+
+/**
+ * 别的打包副本造的 VobsError。
+ *
+ * tsup `splitting: false` 让 error.ts 同时进 `dist/index.js` 与 `dist/error.js`，
+ * 两份类互不 `instanceof`。字段齐全，只是身份不同 —— 识别出来复制成本地实例。
+ */
+function isForeignVobsError(value: unknown): value is Error & VobsErrorOptions {
+  return value instanceof Error
+    && value.name === 'VobsError'
+    && typeof (value as { code?: unknown }).code === 'string'
+}
+
+/** 兜底取消息：至少要能读出对象上的 message，别再输出 `[object Object]`。 */
+function describeUnknown(value: unknown): string {
+  if (value === null || value === undefined) return String(value)
+  if (typeof value === 'string') return value
+  if (typeof value === 'object') {
+    const message = (value as { message?: unknown }).message
+    if (typeof message === 'string' && message !== '') return message
+    try {
+      return JSON.stringify(value) ?? String(value)
+    } catch {
+      return String(value)
+    }
+  }
+  return String(value)
+}
+
+/** 把任意来源的「类 VobsError」字段复制成本地实例。 */
+function adoptVobsError(
+  value: VobsErrorOptions & { cause?: unknown },
+  defaults: VobsErrorDefaults
+): VobsError {
+  return new VobsError({
+    code: value.code,
+    message: value.message,
+    severity: value.severity ?? defaults.severity,
+    layer: value.layer ?? defaults.layer,
+    cause: value.cause ?? (value instanceof Error ? value : undefined),
+    fix: value.fix ?? defaults.fix,
+    location: value.location,
+    trace: value.trace,
+    example: value.example,
+    docs: value.docs,
+    codeFrame: value.codeFrame
+  })
 }
 
 /** Convert thrown strings and third-party errors without losing their message. */
 export function normalizeVobsError(value: unknown, defaults: VobsErrorDefaults = {}): VobsError {
+  // 本地实例：原样返回，保持同一性与已有 stack
   if (value instanceof VobsError) return value
+
+  // 别的副本造的：复制成本地实例，下游 instanceof 才成立
+  if (isForeignVobsError(value)) return adoptVobsError(value, defaults)
+
   if (value instanceof Error) {
     // Preserve the original Error identity so boundaries and DevTools can
     // correlate event/effect phases without creating duplicate diagnostics.
@@ -89,7 +149,24 @@ export function normalizeVobsError(value: unknown, defaults: VobsErrorDefaults =
       readonly vobsSource?: unknown
     }
     const code = defaults.code ?? (typeof metadata.vobsCode === 'string' ? metadata.vobsCode : undefined)
-    if (code) defineErrorMetadata(value, 'code', code)
+    if (code) {
+      defineErrorMetadata(value, 'code', code)
+      /*
+       * 冻结 / 不可扩展的第三方 Error 上挂不上元数据。原来这里静默吞掉，
+       * 于是 normalize 的结果 code 是 undefined（打印成 VOBS_UNKNOWN）。
+       * 挂不上就复制成本地实例，别把 code 丢了。
+       */
+      if ((value as { code?: unknown }).code !== code) {
+        return new VobsError({
+          code,
+          message: value.message,
+          severity: defaults.severity ?? 'error',
+          layer: defaults.layer ?? 'runtime',
+          cause: value,
+          fix: defaults.fix ?? (typeof metadata.vobsHint === 'string' ? metadata.vobsHint : undefined)
+        })
+      }
+    }
     defineErrorMetadata(value, 'severity', defaults.severity ?? 'error')
     defineErrorMetadata(value, 'layer', defaults.layer ?? 'runtime')
     const fix = defaults.fix ?? (typeof metadata.vobsHint === 'string' ? metadata.vobsHint : undefined)
@@ -103,26 +180,13 @@ export function normalizeVobsError(value: unknown, defaults: VobsErrorDefaults =
     }
     return value as VobsError
   }
-  if (isVobsError(value)) {
-    const candidate = value as VobsErrorOptions & { severity?: VobsErrorSeverity; layer?: VobsErrorLayer }
-    return new VobsError({
-      code: candidate.code,
-      message: candidate.message,
-      severity: candidate.severity ?? defaults.severity,
-      layer: candidate.layer ?? defaults.layer,
-      cause: candidate.cause,
-      fix: candidate.fix ?? defaults.fix,
-      location: candidate.location,
-      trace: candidate.trace,
-      example: candidate.example,
-      docs: candidate.docs,
-      codeFrame: candidate.codeFrame
-    })
-  }
-  const message = String(value)
+
+  // 结构化对象（可能缺 layer，甚至缺 severity）：补齐后构造成本地 VobsError
+  if (isVobsError(value)) return adoptVobsError(value as VobsErrorOptions, defaults)
+
   return new VobsError({
     code: defaults.code ?? 'VOBS_UNKNOWN',
-    message,
+    message: describeUnknown(value),
     severity: defaults.severity ?? 'error',
     layer: defaults.layer ?? 'runtime',
     cause: undefined,
@@ -135,7 +199,8 @@ function defineErrorMetadata(target: Error, key: string, value: unknown): void {
   try {
     Object.defineProperty(target, key, { configurable: true, enumerable: false, value, writable: true })
   } catch {
-    // Frozen third-party errors still retain their original message and stack.
+    // 冻结 / 不可扩展的第三方 Error：元数据挂不上。调用方会用「写完再读回」判断
+    // 是否成功，失败时改成复制成本地实例，而不是静默丢掉 code。
   }
 }
 

package/src/event-cleanup-growth.test.ts

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createOwner } from '@vobs/reactivity'
+import { createDOMRenderer, setRenderer } from '@vobs/vobs'
+import { addEventListener, bindSpreadProps, createElement, removeEventListener, setStaticProps } from './index'
+
+setRenderer(createDOMRenderer())
+
+const flush = async () => { await Promise.resolve(); await Promise.resolve() }
+
+/*
+ * `Owner.cleanups` 是**只 push 的数组**（reactivity/src/owner.ts:57,84）。
+ * 事件重绑此前在**每次** `addEventListener` 里无条件 `owner.onDispose(...)`，
+ * 于是换一次 handler 就多一条永不执行的清理项，旧 handler 闭包被一并扣住。
+ *
+ * 实测（.artifacts/reports/runtime.supplement.md 缺点 4 与既有报告缺点 1，两轮独立复现）：
+ * 500 次替换 → `cleanups.length === 500`；一轮 `{...props}` 换 onClick → 202。
+ * 组件 effect 每次重跑都会重绑事件，所以这是热路径上的**无界增长**
+ * （长寿命页面里等价于内存泄漏）。
+ *
+ * 判据用 `owner.mark()` 前后的 cleanups 计数差 —— `mark()` 是 Owner 公开接口，
+ * 不依赖 `cleanups` 是私有字段。
+ */
+describe('事件重绑不会让 Owner.cleanups 无界增长', () => {
+  it('同一 (node,event) 换 200 次 handler，清理槽只涨 1', () => {
+    const owner = createOwner()
+    const el = createElement('button')
+    owner.run(() => {
+      const before = owner.mark().cleanups
+      for (let index = 0; index < 200; index += 1) {
+        addEventListener(el, 'click', () => { void index })
+      }
+      const after = owner.mark().cleanups
+      // 修复前这里是 200
+      expect(after - before).toBe(1)
+    })
+  })
+
+  it('不同事件名各占一个槽（不是共用）', () => {
+    const owner = createOwner()
+    const el = createElement('button')
+    owner.run(() => {
+      const before = owner.mark().cleanups
+      addEventListener(el, 'click', () => {})
+      addEventListener(el, 'keydown', () => {})
+      addEventListener(el, 'focus', () => {})
+      expect(owner.mark().cleanups - before).toBe(3)
+    })
+  })
+
+  it('同一事件名在不同节点上各占一个槽', () => {
+    const owner = createOwner()
+    const a = createElement('button')
+    const b = createElement('button')
+    owner.run(() => {
+      const before = owner.mark().cleanups
+      addEventListener(a, 'click', () => {})
+      addEventListener(b, 'click', () => {})
+      // 同一事件名但节点不同：必须各占一槽（用 per-node 数字 id 拼 key 就是为了这个）
+      expect(owner.mark().cleanups - before).toBe(2)
+    })
+  })
+
+  it('{...props} 反复重绑 onClick 200 轮，清理槽不随重绑增长', async () => {
+    const owner = createOwner()
+    let handler = (): void => {}
+    await owner.run(async () => {
+      const el = createElement('button')
+      const before = owner.mark().cleanups
+      bindSpreadProps(el, () => ({ onClick: handler }))
+      // 建立一次之后的基线：含绑定自己的 effect 清理 + 事件槽各 1
+      const baseline = owner.mark().cleanups
+
+      for (let index = 0; index < 200; index += 1) {
+        handler = () => { void index }
+        await flush()
+      }
+
+      const after = owner.mark().cleanups
+      // 判据是"重绑 200 轮**没有增长**"（而不是某个绝对数）：
+      // 修复前每轮各 +1 → 这里会是 202 级别的差；现在必须为 0。
+      expect(after - baseline).toBe(0)
+      // 且建立阶段只多了一小段固定开销（effect 清理 + 事件槽），不是 200
+      expect(baseline - before).toBeLessThanOrEqual(3)
+    })
+  })
+
+  it('Owner 销毁时仍能摘掉**最新**那个监听（槽没被换绑弄失效）', () => {
+    const owner = createOwner()
+    const el = createElement('button')
+    const hits: string[] = []
+    owner.run(() => {
+      addEventListener(el, 'click', () => hits.push('old'))
+      addEventListener(el, 'click', () => hits.push('new'))
+    })
+    el.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    expect(hits).toEqual(['new'])
+
+    owner.dispose()
+    el.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    // 销毁后必须彻底解绑 —— 槽里存的要是最新 handle，不能指向已摘掉的旧 handle
+    expect(hits).toEqual(['new'])
+  })
+
+  it('removeEventListener 之后再重新挂，仍然只占一个槽', () => {
+    const owner = createOwner()
+    const el = createElement('button')
+    owner.run(() => {
+      const before = owner.mark().cleanups
+      const first = (): void => {}
+      addEventListener(el, 'click', first)
+      removeEventListener(el, 'click', first)
+      addEventListener(el, 'click', () => {})
+      // 摘掉再挂：槽被覆盖，不再新增
+      expect(owner.mark().cleanups - before).toBe(1)
+    })
+  })
+
+  it('setStaticProps 的事件不占清理槽（静态事件不走 addEventListener）', () => {
+    const owner = createOwner()
+    const el = createElement('button')
+    owner.run(() => {
+      const before = owner.mark().cleanups
+      setStaticProps(el, { onClick: () => {} })
+      expect(owner.mark().cleanups - before).toBe(0)
+    })
+  })
+})

package/src/events.test.ts

@@ -11,12 +11,25 @@ describe('event binding dedupe', () => {
     const node = createElement('button')
     let first = 0
     let second = 0
-    addEventListener(node, 'click', () => { first++ })
-    addEventListener(node, 'click', () => { second++ })
+    const firstHandler = (): void => { first++ }
+    const secondHandler = (): void => { second++ }
+    addEventListener(node, 'click', firstHandler)
+    addEventListener(node, 'click', secondHandler)
     node.dispatchEvent(new MouseEvent('click'))
     expect(first).toBe(0)
     expect(second).toBe(1)
-    removeEventListener(node, 'click', (() => undefined) as EventListener)
+    /*
+     * 这里必须传**当前绑定的那个** handler。
+     *
+     * 原来传的是一个无关的 `() => undefined`，并期望仍然摘除 —— 那等于把
+     * "忽略 handler 身份"这个行为编成了契约。而 DOM 的 `removeEventListener` 语义是
+     * 只有 `(type, listener, capture)` 全一致才摘；用另一个 listener 调用是 **no-op**。
+     *
+     * 真实调用方（`ops.ts:339`/`:368`）传的正是准确的 `previousHandler`，
+     * 所以按真实用法断言；"传错 handler 不得误摘"由
+     * `remove-listener-identity.test.ts` 专门锁住。
+     */
+    removeEventListener(node, 'click', secondHandler)
     node.dispatchEvent(new MouseEvent('click'))
     expect(second).toBe(1)
   })

package/src/hmr.ts

@@ -1,4 +1,5 @@
 import type { VobsNode } from './fragment'
+import { formatVobsError } from './error'
 
 export type HmrComponent<Props extends object = Record<string, unknown>> =
   (props: Props) => VobsNode
@@ -76,8 +77,13 @@ export function updateHmrModule(moduleId: string, nextModule: Record<string, unk
   for (const instance of instances) {
     try {
       instance.refresh()
-    } catch {
-      // HMR failures remain application errors on the next normal render.
+    } catch (error) {
+      /*
+       * 静默吞掉会让开发者以为热更新成功了，而屏幕上是旧的 —— 最容易被当成
+       * 「改了没生效」查半天。刷新失败本身不冒泡（下一次正常渲染会再抛），
+       * 但必须留下记录。
+       */
+      console.error(formatVobsError(error, { includeStack: true }))
     }
   }
 }

package/src/index.ts

@@ -15,7 +15,8 @@ export type {
   RuntimeDomMutation,
   RuntimeDomMutationOperation,
   RuntimeErrorEvent,
-  RuntimeHydrationMismatch
+  RuntimeHydrationMismatch,
+  RuntimeProvisionalText
 } from './debug'
 export { createFragment, isVobsFragment } from './fragment'
 export type { FragmentFactory, VobsFragment, VobsNode } from './fragment'
@@ -24,6 +25,7 @@ export {
   getRenderer,
   createText,
   createElement,
+  createSvgElement,
   createComment,
   insertBefore,
   removeChild,
@@ -31,6 +33,8 @@ export {
   setProperty,
   setAttribute,
   spreadProps,
+  bindSpreadProps,
+  removeAttribute,
   setStaticProps,
   addEventListener,
   removeEventListener,
@@ -81,3 +85,11 @@ export { insertAsyncBoundary, AsyncBoundary } from './async-boundary'
 export type { AsyncBoundaryFallback, AsyncBoundaryOptions, AsyncBoundaryProps, AsyncBoundaryView } from './async-boundary'
 export { insertProfiler, Profiler } from './profiler'
 export type { ProfilerOptions, ProfilerProps, ProfilerRenderInfo } from './profiler'
+
+export { Show } from './show'
+export type { ShowProps } from './show'
+
+export { applyClassList, parseClassList } from './ops'
+
+export { ClientOnly } from './client-only'
+export type { ClientOnlyProps } from './client-only'