@vobs/runtime 1.7.8 → 1.8.1

package/src/ops.ts

@@ -1,7 +1,11 @@
 // 编译产物调用的基础操作
 
-import { createOwner, getCurrentOwner, setOwnerDebugName, untrack, type Owner } from '@vobs/reactivity'
+import { createOwner, effect, getCurrentOwner, setOwnerDebugName, untrack, type Owner } from '@vobs/reactivity'
 import { isVobsFragment, type VobsNode } from './fragment'
+import { domAttributeName, isPropertyName } from './dom-props'
+import { resolveEventName } from './dom-events'
+import { isSvgTag } from './svg'
+import { formatVobsError } from './error'
 import { describeDebugNode, getRuntimeDebugHooks, invokeRuntimeDebug, readDebugValue } from './debug'
 import {
   associateHmrInstance,
@@ -23,14 +27,42 @@ interface EventBinding {
 }
 const eventBindings = new WeakMap<object, Map<string, EventBinding>>()
 
+/*
+ * 事件清理槽。目的：让**每个 (Owner, node, event) 只在 `Owner.cleanups` 里占一个槽**，
+ * 重绑 handler 时只换槽里的间接引用，数组不增长（理由见 addEventListener）。
+ *
+ * 用 WeakMap<Owner, Map<key, handle>> 而不是往 Owner 上挂属性：
+ * Owner 是 class 实例，挂新属性会把它推进字典模式（reactivity/src/owner.ts:30-50 记过这笔账）。
+ * key 由 per-node 数字 id 与事件名拼成，避免每次重绑比较长字符串前缀。
+ */
+const eventCleanupSlots = new WeakMap<Owner, Map<string, EventBinding>>()
+const eventCleanupNodeIds = new WeakMap<object, number>()
+let nextEventCleanupNodeId = 0
+
+function eventCleanupKey(node: object, event: string): string {
+  let id = eventCleanupNodeIds.get(node)
+  if (id === undefined) {
+    id = ++nextEventCleanupNodeId
+    eventCleanupNodeIds.set(node, id)
+  }
+  return `${id}:${event}`
+}
+
 export function setRenderer<
   NodeType,
   TextNode extends NodeType,
   ElementNode extends NodeType,
   CommentNode extends NodeType
->(renderer: VobsRenderer<NodeType, TextNode, ElementNode, CommentNode>): void {
+>(
+  renderer: VobsRenderer<NodeType, TextNode, ElementNode, CommentNode> | undefined
+): VobsRenderer<NodeType, TextNode, ElementNode, CommentNode> | undefined {
+  // 返回**上一份**渲染器（没有则是 undefined），调用方据此成对"安装 / 还原"。
+  // 全局单例原来只装不还：一次 renderToString 之后就永久停在 SSR 渲染器上（见 vobs/src/app.ts）。
+  const previous = currentRenderer as unknown as
+    VobsRenderer<NodeType, TextNode, ElementNode, CommentNode> | undefined
   // 编译产物仍使用 DOM 节点声明；实际宿主类型由应用提供的渲染器决定。
-  currentRenderer = renderer as unknown as RuntimeRenderer
+  currentRenderer = (renderer as unknown as RuntimeRenderer) ?? null
+  return previous
 }
 
 export function getRenderer(): RuntimeRenderer {
@@ -44,38 +76,35 @@ export function createText(content: string): Text {
   return getRenderer().createText(content)
 }
 
-/** SVG 命名空间（与 HTML 解析器 foreign-content 规则一致） */
-export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg'
-
-/**
- * SVG 标签全集（= TypeScript SVGElementTagNameMap 的键，运行时分发依据）。
- * 与 React 的运行时清单同思路：只含纯 SVG 标签，刻意排除与 HTML 同名的
- * a/script/style/title（它们在 JSX 类型里归 HTMLElement，按 HTML 创建）。
- */
-const SVG_TAGS = new Set([
-  'animate', 'animateMotion', 'animateTransform', 'circle', 'clipPath', 'defs', 'desc',
-  'ellipse', 'feBlend', 'feColorMatrix', 'feComponentTransfer', 'feComposite',
-  'feConvolveMatrix', 'feDiffuseLighting', 'feDisplacementMap', 'feDistantLight',
-  'feDropShadow', 'feFlood', 'feFuncA', 'feFuncB', 'feFuncG', 'feFuncR',
-  'feGaussianBlur', 'feImage', 'feMerge', 'feMergeNode', 'feMorphology', 'feOffset',
-  'fePointLight', 'feSpecularLighting', 'feSpotLight', 'feTile', 'feTurbulence',
-  'filter', 'foreignObject', 'g', 'image', 'line', 'linearGradient', 'marker', 'mask',
-  'metadata', 'mpath', 'path', 'pattern', 'polygon', 'polyline', 'radialGradient',
-  'rect', 'set', 'stop', 'svg', 'switch', 'symbol', 'text', 'textPath', 'tspan',
-  'use', 'view'
-])
+/** SVG 命名空间与标签清单见 ./svg —— 编译期判定提升用的是同一份依据。 */
+export { SVG_NAMESPACE } from './svg'
 
 export function createElement(tag: string): Element {
   // SVG 标签走命名空间创建：document.createElement('rect') 产物是 HTMLUnknownElement，
   // 整棵 SVG 子树都不会渲染（无报错）。渲染器未实现 createSvgElement 时按 createElement
   // 兜底（旧自定义渲染器保持原行为）。
-  if (SVG_TAGS.has(tag)) {
+  if (isSvgTag(tag)) {
     const renderer = getRenderer()
     if (renderer.createSvgElement) return renderer.createSvgElement(tag)
   }
   return getRenderer().createElement(tag)
 }
 
+/**
+ * 在 SVG 命名空间里建元素，**不看标签名**。
+ *
+ * 给编译器用在 `<svg>` 祖先下那些与 HTML 同名的标签（a / title / style / script）——
+ * 它们不在 SVG_TAGS 里，`createElement` 会按 HTML 建。只按名字判定命名空间是行不通的：
+ * `<svg><a href="…">` 会变成 HTML 锚点，而且不报错。
+ *
+ * 渲染器没实现 createSvgElement 时按 createElement 兜底（自定义渲染器保持原行为）。
+ */
+export function createSvgElement(tag: string): Element {
+  const renderer = getRenderer()
+  if (renderer.createSvgElement) return renderer.createSvgElement(tag)
+  return renderer.createElement(tag)
+}
+
 export function createComment(content: string): Comment {
   return getRenderer().createComment(content)
 }
@@ -121,7 +150,17 @@ function syncSelectValue(parent: Node): void {
   while (current !== null) {
     if ((current as Element).nodeName === 'SELECT') {
       const read = selectValueReaders.get(current)
-      if (read !== undefined) setProperty(current as Element, 'value', read())
+      /*
+       * 读取必须 `untrack` —— 这里是在**插入 option 的过程中同步**重放当前值，
+       * 而插入往往发生在某个 effect 运行时（`insertList` / `insertDynamic` 都由 effect 驱动）。
+       * 若那次读取被算进外层 effect 的依赖，该 effect 以后会被这个信号唤醒：
+       * 一个**隐藏订阅** —— 依赖关系图上多一条没人打算建立的边，
+       * 表现为"插入选项时恰好重跑了某个不相关的 effect"，很难追。
+       *
+       * 这条绑定的订阅由 `bindProperty` 自己的 effect 负责（bind.ts），
+       * 这里的重放只是把值**再写一次**，不需要也不应该建立依赖。
+       */
+      if (read !== undefined) setProperty(current as Element, 'value', untrack(read))
       return
     }
     current = current.parentNode
@@ -132,9 +171,16 @@ export function removeChild(
   parent: Node,
   child: VobsNode
 ): void {
-  disposeNodeOwner(child)
+  /*
+   * **先摘 DOM，再释放 Owner。**
+   *
+   * 原来是反过来的：`disposeNodeOwner(child)` 抛错（用户 cleanup 里抛）就永远走不到
+   * 摘除那一步 —— DOM 里留着旧节点、它的 effect 却已经没了，屏幕上出现两棵树且没有提示。
+   * 顺序反过来之后，即使清理抛错，DOM 也已一致；错误照旧抛给调用方。
+   */
   if (isVobsFragment(child)) {
     child.unmount(parent)
+    disposeNodeOwner(child)
     return
   }
   getRenderer().removeChild(parent, child)
@@ -145,6 +191,7 @@ export function removeChild(
       parent: describeDebugNode(parent)
     })
   }
+  disposeNodeOwner(child)
 }
 
 export function setTextContent(
@@ -173,7 +220,7 @@ export function setProperty(
   const previousValue = getRuntimeDebugHooks()
     ? readDebugValue(() => Reflect.get(node, key))
     : undefined
-  getRenderer().setProperty(node, key, value)
+  getRenderer().setProperty(node, PROPERTY_IDL_NAMES[key] ?? key, value)
   if (key === 'value' && (node as { tagName?: unknown }).tagName === 'SELECT') {
     scheduleSelectValueSync(node, value)
   }
@@ -203,12 +250,20 @@ function scheduleSelectValueSync(node: Element, value: unknown): void {
   pendingSelectValues.set(node, value)
   if (selectSyncScheduled.has(node)) return
   selectSyncScheduled.add(node)
+  /*
+   * 在这一刻就把渲染器抓下来，**不要**在微任务里再 getRenderer()：
+   * 1) 应用销毁会把全局渲染器还原（没装过就是"没有"），那时微任务里的 getRenderer() 会抛
+   *    "渲染器未初始化" —— 抛在微任务里没人接，直接变成进程级 unhandled error（实测
+   *    `packages/ui/src/bind.test.ts` 就因为这条让 vitest 报 1 个 unhandled error，退出码非 0）；
+   * 2) 语义上也更对：节点是哪个渲染器造的，就用哪个渲染器写回（期间全局可能已经换人）。
+   */
+  const renderer = getRenderer()
   queueMicrotask(() => {
     selectSyncScheduled.delete(node)
     if (!pendingSelectValues.has(node)) return
     const pending = pendingSelectValues.get(node)
     pendingSelectValues.delete(node)
-    getRenderer().setProperty(node, 'value', pending)
+    renderer.setProperty(node, 'value', pending)
   })
 }
 
@@ -233,19 +288,186 @@ export function setAttribute(
 }
 
 export function spreadProps(node: Element, props: Record<string, unknown>): void {
-  for (const [key, value] of Object.entries(props)) {
-    if (key === 'key' || value === null || value === undefined) continue
+  applySpreadProps(node, null, props)
+}
+
+/** 删除一个 attribute。渲染器没实现时退回空串（属性仍在，但内容清空）—— 老自定义渲染器的降级行为。 */
+export function removeAttribute(node: Element, key: string): void {
+  const renderer = getRenderer()
+  if (renderer.removeAttribute) {
+    renderer.removeAttribute(node, key)
+    return
+  }
+  renderer.setAttribute(node, key, '')
+}
+
+/** 布尔型 property 的「清除」值是 false，其余是空串（与 React 的移除语义一致）。 */
+const BOOLEAN_PROPERTIES = new Set([
+  'checked', 'selected', 'disabled', 'multiple', 'readOnly', 'required',
+  'hidden', 'open', 'indeterminate', 'defaultChecked', 'muted', 'autoFocus'
+])
+
+/**
+ * JSX 属性名 → **IDL 属性名**（`el[name] = value` 里的那个 name）。
+ *
+ * 多数名字两边相同，但少数不同；写错名字的后果是**静默的**：
+ * `Reflect.set(el, 'autoFocus', …)` 只是给元素挂了一个不反射的 expando，
+ * 既不产生 `autofocus` 属性、也不改变 IDL 属性 —— 于是 `autoFocus={false}` 毫无作用。
+ * 实测（jsdom，与真实 DOM 同语义）：
+ *   IDL 名 `autofocus`（全小写）→ has=true/idl=true，写 false 则 has=false/idl=false  ← 反射正确
+ *   JSX 名 `autoFocus`（驼峰）  → 只挂 expando，属性与 IDL 都不变
+ * 这也解释了为什么 `disabled` / `checked` / `readOnly` / `tabIndex` 一直是对的：
+ * 它们的 IDL 名恰好与 JSX 名相同。
+ */
+const PROPERTY_IDL_NAMES: Readonly<Record<string, string>> = {
+  autoFocus: 'autofocus'
+}
+
+/**
+ * 把一份 props 应用（或**增量**应用到）节点上。
+ *
+ * `previous` 为 null 表示首次应用（`spreadProps` 的老路径）；否则只处理真正变化的键，
+ * 并**移除**新对象里已经消失的键 —— 这正是原来缺的那一半：`{...props}` 只在创建时应用一次，
+ * 之后对象里删掉的键会永远留在 DOM 上，而且改了的值也不会生效。
+ */
+function applySpreadProps(
+  node: Element,
+  previous: Record<string, unknown> | null,
+  next: Record<string, unknown>
+): void {
+  for (const [key, value] of Object.entries(next)) {
+    if (key === 'key') continue
+    if (previous !== null && Object.is(previous[key], value)) continue
+
+    if (key.startsWith('on')) {
+      // 事件：先摘旧监听（值变了、或新值不再是函数），再挂新的。
+      // 事件名必须过别名表：`onDoubleClick` 的真实事件名是 `dblclick`，
+      // 直接小写会得到不存在的 `"doubleclick"`（回调永不触发且静默）。
+      const eventName = resolveEventName(key) ?? key.slice(2).toLowerCase()
+      const previousHandler = previous?.[key]
+      if (typeof previousHandler === 'function') {
+        removeEventListener(node, eventName, previousHandler as EventListener)
+      }
+      if (typeof value === 'function') {
+        addEventListener(node, eventName, value as EventListener)
+      }
+      continue
+    }
     if (key === 'ref') {
       setRef(node, value)
       continue
     }
-    if (key.startsWith('on') && typeof value === 'function') addEventListener(node, key.slice(2).toLowerCase(), value as EventListener)
+    // null/undefined 表示"不提供值"，**保持现状**（props.test.ts 把这条钉成了契约）。
+    // 注意它有一个已知后果：键仍在 `next` 里时移除循环够不着（`key in next`），
+    // 所以"值从中变成 null"不会清掉已有属性 —— 要清就得把键从对象里删掉。
+    if (value === null || value === undefined) continue
     // property 键的 false 有语义（如 disabled={false} 必须清除），不能跳过；
-    // attribute 键的 false 表示“不设置”，与 HTML 语义一致。
-    else if (isPropertyKey(key)) setProperty(node, key, value)
+    // attribute 键的 false 表示"不设置"，与 HTML 语义一致。
+    else if (isClassListKey(key)) applyClassList(node, value)
+    else if (isPropertyName(key)) setProperty(node, key, value)
     else if (value === false) continue
     else setAttribute(node, domAttributeName(key), key === 'style' && isStyleObject(value) ? formatStyle(value) : String(value))
   }
+
+  if (previous === null) return
+  for (const key of Object.keys(previous)) {
+    if (key in next || key === 'key') continue
+    if (key.startsWith('on')) {
+      const eventName = resolveEventName(key) ?? key.slice(2).toLowerCase()
+      const previousHandler = previous[key]
+      if (typeof previousHandler === 'function') {
+        removeEventListener(node, eventName, previousHandler as EventListener)
+      }
+      continue
+    }
+    if (key === 'ref') continue
+    if (isPropertyName(key)) setProperty(node, key, BOOLEAN_PROPERTIES.has(key) ? false : '')
+    else removeAttribute(node, domAttributeName(key))
+  }
+}
+
+/**
+ * 把 `{...props}` 绑定成**响应式**的：对象变了就增量应用，消失的键会被移除。
+ *
+ * 编译器对带展开的 JSX 属性发射这个而不是 `spreadProps` —— 后者只在创建时应用一次，
+ * 于是「改了 props 不生效」「删掉的键留在 DOM 上」两个问题都**不报错**。
+ *
+ * ⚠️ `previous` 必须是**值的快照**，不能是 `next` 的引用。
+ * 这里存引用时，下一轮 `applySpreadProps` 里的 `Object.is(previous[key], value)`
+ * 读的是同一份值 → 恒等 → **整个 diff 短路**，移除循环也因 `key in next` 全跳过。
+ * 而编译器为 `<div {...props}>` 发射的正是**身份稳定 + getter**的形状
+ * （`bindSpreadProps(_el0, () => props)`，值经 getter 反应式求值），
+ * 于是真实产物下"改了 props 什么都不更新"。
+ *
+ * 快照用浅拷贝即可，且**必须在应用之前取**：拷贝会把 getter 求值一次、转成数据属性，
+ * 而 `applySpreadProps` 又会把 `next` 的每个键读一遍 —— 两者都在 effect 的追踪窗口内，
+ * 所以信号依赖不会因为多这一遍而丢失。
+ */
+/**
+ * `classList` 每次贡献的类名（按元素记账，便于下次替换而不是叠加）。
+ *
+ * 为什么需要记账：`classList` 与 `class` 写的是**同一个** HTML 属性。
+ * 若不记住上次由 `classList` 贡献了哪些，切换时要么越加越多、要么把作者的 `class` 抹掉。
+ */
+const classListContributions = new WeakMap<object, string[]>()
+
+/** `classList` 值 → 类名数组。支持对象 / 数组 / 字符串三种写法。 */
+export function parseClassList(value: unknown): string[] {
+  const names: string[] = []
+  const push = (candidate: unknown): void => {
+    if (typeof candidate === 'string') {
+      for (const name of candidate.split(/\s+/u)) if (name !== '') names.push(name)
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      if (entry !== null && typeof entry === 'object') {
+        for (const [name, on] of Object.entries(entry)) if (on) push(name)
+      } else push(entry)
+    }
+  } else if (value !== null && typeof value === 'object') {
+    for (const [name, on] of Object.entries(value)) if (on) push(name)
+  } else push(value)
+  return names
+}
+
+/**
+ * 应用 `classList`：与元素上已有的 `class` **合并**，并可反复切换。
+ *
+ * 存在的理由（外部踩坑文档 C 条）：条件分支里的输入控件会丢焦点 ——
+ * `insertDynamic` 按引用比较（`next === current`），写条件表达式就会重建子树。
+ * 文档给出的对策是「固定渲染 + 响应式 class 显隐」，但此前只能手写字符串模板：
+ *
+ * ```tsx
+ * <div class={open.value ? 'panel is-open' : 'panel'}>   // 易漏、易写错
+ * <div class="panel" classList={{ 'is-open': open.value }}>  // 现在：
+ * ```
+ *
+ * `classList` 只负责它自己贡献的部分，作者写在 `class` 里的类名不受影响。
+ */
+export function applyClassList(node: Element, value: unknown): void {
+  const next = parseClassList(value)
+  const previous = classListContributions.get(node) ?? []
+  classListContributions.set(node, next)
+  const base = (node.getAttribute('class') ?? '')
+    .split(/\s+/u)
+    .filter(name => name !== '' && !previous.includes(name))
+  const merged = [...new Set([...base, ...next])]
+  setAttribute(node, 'class', merged.join(' '))
+}
+
+function isClassListKey(key: string): boolean {
+  return key === 'classList'
+}
+
+export function bindSpreadProps(node: Element, source: () => Record<string, unknown>): void {
+  let previous: Record<string, unknown> | null = null
+  effect(() => {
+    const next = source() ?? {}
+    const snapshot = { ...next }
+    applySpreadProps(node, previous, next)
+    previous = snapshot
+  })
 }
 
 /** Apply compile-time host properties in one renderer pass. */
@@ -253,29 +475,13 @@ export function setStaticProps(node: Element, props: Record<string, unknown>): v
   for (const [key, value] of Object.entries(props)) {
     if (key === 'key' || key === 'ref' || key.startsWith('on')) continue
     if (value === null || value === undefined) continue
-    if (isPropertyKey(key)) setProperty(node, key, value)
+    if (isClassListKey(key)) applyClassList(node, value)
+    else if (isPropertyName(key)) setProperty(node, key, value)
     else if (value === false) continue
     else setAttribute(node, domAttributeName(key), key === 'style' && isStyleObject(value) ? formatStyle(value) : String(value))
   }
 }
 
-function isPropertyKey(key: string): boolean {
-  return key === 'value' || key === 'checked' || key === 'selected' || key === 'disabled'
-    || key === 'multiple' || key === 'readOnly' || key === 'required'
-    || key === 'autofocus' || key === 'hidden' || key === 'tabIndex'
-    || key === 'colSpan' || key === 'rowSpan'
-}
-
-/** camelCase JSX 属性名 → HTML attribute 名（与 compiler 的 domAttributeName 保持一致） */
-function domAttributeName(key: string): string {
-  switch (key) {
-    case 'className': return 'class'
-    case 'htmlFor': return 'for'
-    case 'autoComplete': return 'autocomplete'
-    case 'spellCheck': return 'spellcheck'
-    default: return key
-  }
-}
 
 function isStyleObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
@@ -300,7 +506,10 @@ export function addEventListener(
   }
   const previous = bindings.get(event)
   if (previous && previous.original === handler && previous.owner === owner) return
-  if (previous) renderer.removeEventListener(node, event, previous.handler)
+  if (previous) {
+    // 旧监听先摘掉；Owner 清理槽由下面的 slots 原地续用，不在清理表里增删
+    renderer.removeEventListener(node, event, previous.handler)
+  }
   const listener = owner ? (reason: Event) => {
     // Owner 已销毁说明节点所属子树已被卸载/替换，事件来自游离 DOM，直接忽略。
     // 否则 owner.run 会抛"已销毁的 Owner"，在事件流里制造无意义的错误噪音。
@@ -316,16 +525,65 @@ export function addEventListener(
         handled,
         recovery: handled ? 'handled' : 'propagated'
       })
+      /*
+       * 被 owner 的 onError 处理掉之后，错误就只剩 debug 钩子这一个出口 ——
+       * 没装 DevTools 时控制台一个字都没有：事件处理器抛错、界面没反应、无从查起。
+       * 没被处理的情况下面会 rethrow（浏览器自己会报），所以只在「被吞下」时补控制台。
+       */
+      if (handled && getRuntimeDebugHooks()?.error === undefined) {
+        console.error(formatVobsError(error, { includeStack: true }))
+      }
       if (!handled) throw error
     }
   } : handler
+  /*
+   * 这个 (node,event) 在 Owner 清理表里只占**一个**槽，替换 handler 时**原地**换掉它做的事。
+   *
+   * 此前是在**每次** addEventListener 里无条件 `owner.onDispose(...)`，而 `Owner.cleanups`
+   * 是只 push 的数组（reactivity/src/owner.ts:57,84）→ 换一次 handler 就多一条永不执行的
+   * 清理项，旧的 handler 闭包也被一并扣住。实测（.artifacts/reports/runtime.supplement.md
+   * 缺点 4 与既有报告缺点 1，两轮独立复现）：500 次替换 → `cleanups.length === 500`；
+   * 一轮 `{...props}` 换 onClick → 202。组件的 effect 每次重跑都会重绑事件，
+   * 所以这是热路径上的**无界增长**（长寿命页面里等价于内存泄漏）。
+   *
+   * `binding` 是 `const`，所以槽里必须包一层可变的 `current` —— 换绑时改的是 `current`，
+   * 数组长度不变、旧闭包被释放。
+   */
   const binding: EventBinding = { handler: listener, owner, original: handler }
   bindings.set(event, binding)
   renderer.addEventListener(node, event, listener)
-  owner?.onDispose(() => {
-    if (bindings?.get(event) !== binding) return
-    bindings.delete(event)
-    renderer.removeEventListener(node, event, listener)
+  if (!owner) return
+  /*
+   * **每个 (node,event) 在 Owner 清理表里只占一个槽。**
+   *
+   * 此前是在**每次** addEventListener 里无条件 `owner.onDispose(...)`，而 `Owner.cleanups`
+   * 是只 push 的数组（reactivity/src/owner.ts:57,84）→ 换一次 handler 就多一条永不执行的
+   * 清理项，旧的 handler 闭包也被一并扣住。实测（.artifacts/reports/runtime.supplement.md
+   * 缺点 4 与既有报告缺点 1，两轮独立复现）：500 次替换 → `cleanups.length === 500`；
+   * 一轮 `{...props}` 换 onClick → 202。组件 effect 每次重跑都会重绑事件，
+   * 所以这是热路径上的**无界增长**（长寿命页面里等价于内存泄漏）。
+   *
+   * 做法：清理槽里存的是**间接引用**（owner → (node,event) → 当前 handle），
+   * 重绑时只换间接引用指向的东西，槽本身不增不减；最后一个引用被清掉时槽自然失效。
+   * 键用 per-owner 的 `eventCleanupKeys` 映射成数字，避免长字符串前缀比较。
+   */
+  const key = eventCleanupKey(node, event)
+  let slots = eventCleanupSlots.get(owner)
+  if (!slots) {
+    slots = new Map()
+    eventCleanupSlots.set(owner, slots)
+  }
+  // 槽存的永远是"当前该清哪一条绑定"，所以重绑/摘除后再绑都只是覆盖它
+  const hasSlot = slots.has(key)
+  slots.set(key, binding)
+  if (hasSlot) return
+  owner.onDispose(() => {
+    const current = eventCleanupSlots.get(owner)?.get(key)
+    if (!current) return
+    eventCleanupSlots.get(owner)?.delete(key)
+    const map = eventBindings.get(node)
+    if (map?.get(event) === current) map.delete(event)
+    renderer.removeEventListener(node, event, current.handler)
   })
 }
 
@@ -335,13 +593,64 @@ export function removeEventListener(
   handler: EventListener
 ): void {
   const renderer = getRenderer()
-  const binding = eventBindings.get(node)?.get(event)
+  const map = eventBindings.get(node)
+  const binding = map?.get(event)
+  /*
+   * **必须比 handler 身份**（DOM 的 `removeEventListener` 语义就是如此）。
+   *
+   * 原来这里忽略传入的 `handler`：只要 `(node,event)` 上有绑定就一律摘掉，
+   * 并把绑定记录删掉。于是"用另一个 handler 调 remove"会把**别人的**绑定误摘 ——
+   * 调用方以为只是取消自己那次（本来应当是 no-op），实际把当前生效的监听弄没了。
+   *
+   * 现在的行为：
+   * - 有绑定且身份一致 → 摘掉（正常路径）
+   * - 有绑定但身份不同 → **no-op**（不去动别人的绑定）
+   * - 绑定记录里没有（例如由别处直接经 renderer 绑的）→ 按传入的 handler 兜底摘一次，
+   *   保持与渲染器 API 直连时的可用性
+   */
+  if (binding) {
+    if (binding.handler !== handler) return
+    map?.delete(event)
+  }
   renderer.removeEventListener(node, event, binding?.handler ?? handler)
-  eventBindings.get(node)?.delete(event)
 }
 
+/**
+ * 清空容器。
+ *
+ * 原来只调渲染器的 clear（DOM 实现就是 `textContent = ''`）—— **被清掉子树的 Owner
+ * 一个都不释放**：组件里的 effect 继续订阅信号（幽灵更新）、监听不解绑、onDispose 不跑。
+ * 现在先把子树里能找到的 Owner 释放掉，再清 DOM。
+ *
+ * 覆盖范围如实说明：`nodeOwners` 只登记**组件输出节点**（`createComponent` 时
+ * `associateNodeOwner`）。所以在组件边界上清理是完整的（组件 Owner 的销毁会级联它的
+ * effect 与子 Owner）；而在组件外直接 `bindText` 之类建立的 effect 挂在调用方当时的
+ * Owner 上、不在节点表里，这里**清不到** —— 那部分归它的 Owner 管，通常由
+ * `app.destroy()` 负责。要彻底解决需要节点表能反向枚举，代价更大，先不做。
+ *
+ * 清理抛错不影响 DOM 被清空（先释放、后清 DOM 的顺序也保证了这一点）。
+ */
 export function clear(container: Node): void {
+  let firstError: unknown
+  const walk = (node: Node): void => {
+    try {
+      disposeNodeOwner(node as unknown as VobsNode)
+    } catch (error) {
+      firstError ??= error
+    }
+    for (const child of Array.from(node.childNodes)) walk(child)
+  }
+  for (const child of Array.from(container.childNodes)) walk(child)
+
   getRenderer().clear(container)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'clear',
+      target: describeDebugNode(container as unknown as VobsNode),
+      parent: describeDebugNode(container as unknown as VobsNode)
+    })
+  }
+  if (firstError) throw firstError
 }
 
 type VobsComponent = (...args: any[]) => VobsNode
@@ -385,20 +694,46 @@ export function createComponent<Component extends VobsComponent>(
   // 重渲染前释放上一轮作用域，旧实例的 effect 不再订阅信号、portal 节点不再
   // 残留在 body 中每轮热更新叠加；组件 Owner 与 HMR 注册保活。
   const renderScope = owner.mark()
-  let node: VobsNode
+  /*
+   * 局部类型放宽到运行时真实值域：组件返回 `null` / `undefined` / `false`
+   * 都是合法 JSX 写法（`cond ? <X/> : null`、`cond && <X/>`），
+   * 只是 `VobsComponent` 的声明把它写窄了。下面统一归一化成空注释节点。
+   */
+  /*
+   * 用**独立变量**承接渲染结果再归一化。
+   * 直接写 `let node: VobsNode | null | undefined | false` 再比较 `node === false` 时，
+   * TS 的控制流分析会依据 `component(props)` 的声明类型把 `node` 收窄回 `VobsNode`，
+   * 于是 `false` 分支被判成"类型不可达"而报错 —— 但运行时它确实会出现。
+   */
+  let rendered: unknown
   try {
     // 组件渲染必须 untrack：组件是 run-once 的，其渲染发生在某次 effect 求值
     // （insertDynamic/insertBoundary 的渲染工厂、路由挂载）内时，若不切断追踪，
     // 组件体内读取的信号会被收集为祖先 effect 的依赖——一次无关编辑就会触发
     // 整棵子树销毁重建（输入框被换掉、焦点丢失、事件监听随旧树一起被清理）。
     // 结构性响应只属于条件工厂与绑定 effect，组件本体渲染一次即止。
-    node = owner.run(() => untrack(() => component(props)))
+    rendered = owner.run(() => untrack(() => component(props)))
   } catch (error) {
     owner.dispose()
     attachSourceLocation(error, source)
     attachComponentContext(error, componentName, owner.id)
     throw error
   }
+  /*
+   * 组件返回 `null` / `undefined` / `false` 时用**注释节点**代替。
+   *
+   * 这是生产事故（Labelune 2026-09-30 发版黑屏）的根因：`createComponent` 把渲染结果
+   * 直接当作 `nodeOwners` 这个 **WeakMap 的 key**，而 `null` / `undefined` 不是合法 key ——
+   * `nodeOwners.set(null, owner)` 抛 `Invalid value used as weak map key`。
+   * 后果特别贵：App 挂载即崩、**没有任何 JS 崩溃日志**、splash 兜底也失效，
+   * 只能靠人肉纪律「组件永远返回真实节点」避免。
+   *
+   * 「组件顶层条件 return null」是合法的 JSX 写法，框架不该崩。
+   * 注释节点是**渲染为空的既有原语**（fragment 与 dynamic 的标记都用它），
+   * 视觉结果与返回 null 完全一致，但满足 `VobsNode` 契约 —— 于是挂载、HMR 刷新、
+   * 节点替换、水合这些下游路径都不需要各自特判一个"空"分支。
+   */
+  const node: VobsNode = isRenderableNode(rendered) ? rendered : createComment('vobs:empty')
   associateNodeOwner(node, owner)
   if (instance) {
     instance.node = node
@@ -486,7 +821,31 @@ export function createBlock(factory: () => VobsNode | null | undefined | false):
   return node
 }
 
+/**
+ * 组件渲染结果是否是**可用的节点值**。
+ *
+ * `VobsNode` 的真实值域是一个对象（`Node` / fragment / 自定义渲染器的宿主对象），
+ * 而合法 JSX 写法可能返回 `null` / `undefined` / `false`（`cond ? <X/> : null`、`cond && <X/>`）。
+ * 用一个守卫而不是直接比较，是因为 `component()` 的声明类型是 `VobsNode`，
+ * TS 的控制流会把 `=== false` 之类的比较判成"类型不可达"。
+ */
+function isRenderableNode(value: unknown): value is VobsNode {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+}
+
 export function associateNodeOwner(node: VobsNode, owner: Owner): void {
+  /*
+   * 防御：`node` 在类型上必然是 `VobsNode`，但运行时可能收到 `null`/`undefined`
+   * （组件返回空、第三方渲染器返回非节点）。直接当 WeakMap key 会抛
+   * `Invalid value used as weak map key` —— 那是**框架内部错误**，信息量为零，
+   * 且会让 App 挂载静默崩溃。这条断言把它变成一条能指认原因的报错。
+   */
+  if (node === null || node === undefined || (typeof node !== 'object' && typeof node !== 'function')) {
+    throw new Error(
+      `Vobs: associateNodeOwner 收到非节点值（${String(node)}）。`
+      + '组件必须返回 VobsNode；返回 null/undefined 由 createComponent 转成空注释节点。'
+    )
+  }
   nodeOwners.set(node, owner)
 }