@vobs/runtime 1.7.8 → 1.8.1

package/src/component-empty-return.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+/*
+ * 组件返回 `null` / `undefined` / `false` **不得让 App 崩溃**。
+ *
+ * 这是生产事故的根因（Labelune 2026-09-30 发版黑屏）：
+ * `createComponent` 把渲染结果直接当作 `nodeOwners` 这个 **WeakMap 的 key**，
+ * 而 `null` / `undefined` 不是合法 key → 抛 `Invalid value used as weak map key`。
+ * 最贵的地方是**诊断信息**：App 挂载即崩、没有任何 JS 崩溃日志、splash 兜底也失效。
+ *
+ * 「组件顶层条件 return null」（`cond ? <X/> : null`、`cond && <X/>`）是合法 JSX 写法。
+ * 修法：归一化成**空注释节点** —— 视觉为空（与返回 null 一致），但满足 `VobsNode` 契约，
+ * 于是挂载 / HMR 刷新 / 节点替换 / 水合都不需要各自特判"空"分支。
+ */
+import { describe, expect, it } from 'vitest'
+import { scheduler, state } from '@vobs/reactivity'
+import { createComponent, createDOMRenderer, createText, createVobs, setRenderer } from '@vobs/vobs'
+import type { VobsNode } from '@vobs/vobs'
+import { insertDynamic } from './index'
+
+setRenderer(createDOMRenderer())
+const settle = (): void => { scheduler.flush() }
+
+function mount(render: () => VobsNode) {
+  const host = document.createElement('main')
+  document.body.appendChild(host)
+  const app = createVobs({ render })
+  app.mount(host)
+  return { host, app, cleanup: () => { app.destroy(); host.remove() } }
+}
+
+describe('组件返回空值不再崩溃', () => {
+  it('顶层 return null → 不抛、渲染为空', () => {
+    const Cond = (props: { on: boolean }): VobsNode =>
+      (props.on ? createText('yes') : null) as unknown as VobsNode
+    let view: ReturnType<typeof mount> | undefined
+    expect(() => { view = mount(() => createComponent(Cond, { on: false })) }).not.toThrow()
+    expect(view!.host.textContent).toBe('')
+    view!.cleanup()
+  })
+
+  it('返回 undefined → 不抛、渲染为空', () => {
+    const Blank = (): VobsNode => undefined as unknown as VobsNode
+    let view: ReturnType<typeof mount> | undefined
+    expect(() => { view = mount(() => createComponent(Blank, {})) }).not.toThrow()
+    expect(view!.host.textContent).toBe('')
+    view!.cleanup()
+  })
+
+  it('返回 false（`cond && <X/>` 形态）→ 不抛、渲染为空', () => {
+    const Maybe = (props: { on: boolean }): VobsNode =>
+      (props.on && createText('yes')) as unknown as VobsNode
+    let view: ReturnType<typeof mount> | undefined
+    expect(() => { view = mount(() => createComponent(Maybe, { on: false })) }).not.toThrow()
+    expect(view!.host.textContent).toBe('')
+    view!.cleanup()
+  })
+
+  it('cond 为真时正常渲染（没有把功能一起打死）', () => {
+    const Cond = (props: { on: boolean }): VobsNode =>
+      (props.on ? createText('yes') : null) as unknown as VobsNode
+    const view = mount(() => createComponent(Cond, { on: true }))
+    expect(view.host.textContent).toBe('yes')
+    view.cleanup()
+  })
+
+  it('返回 null 的组件**嵌在树中间**时，兄弟节点照常渲染', () => {
+    const Blank = (): VobsNode => null as unknown as VobsNode
+    const view = mount(() => {
+      const wrap = document.createElement('div')
+      wrap.append(document.createTextNode('before'))
+      wrap.appendChild(createComponent(Blank, {}) as unknown as Node)
+      wrap.append(document.createTextNode('after'))
+      return wrap as unknown as VobsNode
+    })
+    expect(view.host.textContent).toBe('beforeafter')
+    view.cleanup()
+  })
+
+  it('条件工厂在 null ↔ 节点之间切换（响应式）', () => {
+    const on = state(false)
+    /*
+     * 注意这里用的是 `createBlock`（条件工厂）而不是 `createComponent(..., { on: on.value })`。
+     * 后者是**违反 run-once 契约**的写法：组件体与渲染只执行一次，
+     * 在外层 render 里读信号不会订阅、也不会重跑（正是文档里 B 条那条纪律）。
+     * 结构性变化必须由条件工厂或绑定 effect 承担 —— 响应式来自 `insertDynamic`
+     * 驱动的工厂，`createBlock` 只是"每次都重新建"的工厂本身。
+     */
+    const view = mount(() => {
+      const wrap = document.createElement('div')
+      insertDynamic(wrap as unknown as Node, null, () => (on.value ? createText('shown') : null))
+      return wrap as unknown as VobsNode
+    })
+
+    expect(view.host.textContent).toBe('')
+    on.value = true
+    settle()
+    expect(view.host.textContent, '切到节点后没有渲染出来').toBe('shown')
+    on.value = false
+    settle()
+    expect(view.host.textContent, '切回 null 后没有清空').toBe('')
+    view.cleanup()
+  })
+
+  it('返回 null 的组件销毁时不抛错（Owner 正常释放）', () => {
+    const Blank = (): VobsNode => null as unknown as VobsNode
+    const view = mount(() => createComponent(Blank, {}))
+    expect(() => view.app.destroy()).not.toThrow()
+    view.host.remove()
+  })
+
+  it('连续多个返回 null 的组件并存', () => {
+    const Blank = (): VobsNode => null as unknown as VobsNode
+    const view = mount(() => {
+      const wrap = document.createElement('div')
+      wrap.appendChild(createComponent(Blank, {}) as unknown as Node)
+      wrap.appendChild(createComponent(Blank, {}) as unknown as Node)
+      wrap.appendChild(createComponent(Blank, {}) as unknown as Node)
+      return wrap as unknown as VobsNode
+    })
+    expect(view.host.textContent).toBe('')
+    expect(() => view.cleanup()).not.toThrow()
+  })
+})

package/src/debug.ts

@@ -26,7 +26,7 @@ export interface RuntimeHydrationMismatch {
   readonly message: string
 }
 
-export type RuntimeDomMutationOperation = 'text' | 'property' | 'attribute' | 'insert' | 'remove'
+export type RuntimeDomMutationOperation = 'text' | 'property' | 'attribute' | 'insert' | 'remove' | 'clear'
 
 export interface RuntimeDomMutation {
   readonly operation: RuntimeDomMutationOperation
@@ -49,6 +49,17 @@ export interface RuntimeDebugHooks {
   domMutation?(mutation: RuntimeDomMutation): void
   error?(event: RuntimeErrorEvent): void
   hydrationMismatch?(event: RuntimeHydrationMismatch): void
+  /**
+   * 水合时**临时认领**了一个内容不为空的文本节点（服务端渲染了真实文本，客户端此刻要的是空文本：
+   * 只能先认领、等绑定 effect 覆写）。这一步过去完全无声 —— 服务端 "Ada" 遇上客户端忘传 state
+   * （会渲染 "loading"）时就静默变成了后者。给出可观测出口，便于工具发现这类"值被悄悄换掉"。
+   */
+  hydrationProvisionalText?(event: RuntimeProvisionalText): void
+}
+
+export interface RuntimeProvisionalText {
+  readonly expected: string
+  readonly actual: string
 }
 
 let activeRuntimeDebugHooks: RuntimeDebugHooks | null = null

package/src/dom-events.ts

@@ -0,0 +1,32 @@
+/**
+ * `on*` 属性名 → 真实 DOM 事件名。
+ *
+ * 与 `dom-props.ts` 的属性名表同理：这必须是**单一来源**。
+ * 此前编译期与运行期各写一份、且不一致：
+ *  - 编译期（`@vobs/compiler` 的 `dom-events.ts`）有别名表，知道 `onDoubleClick` → `dblclick`；
+ *  - 运行期的 `{...props}` 展开路径只做 `name.slice(2).toLowerCase()`
+ *    → `onDoubleClick` 变成 `"doubleclick"`，**DOM 里根本叫 dblclick**，
+ *    于是回调永不触发，而且不报错。
+ * 实测（.artifacts/reports/runtime.supplement.md 缺点 2）：派发 `dblclick` 命中 0 次，
+ * 隐藏的 `doubleclick` 监听命中 1 次。同一个包在 `dom-props.ts:1-8` 自称"两边逐字重复、
+ * 已收拢成单一来源"，但那只覆盖属性名，没覆盖事件名。
+ */
+
+/** JSX 驼峰名与 DOM 事件名不一致的少数情况（小写后的驼峰名 → 真实事件名）。 */
+export const EVENT_NAME_ALIASES: Readonly<Record<string, string>> = {
+  // React 风格的 onDoubleClick 对应的 DOM 事件是 dblclick
+  doubleclick: 'dblclick',
+  // 少数人按 addEventListener 的写法写成 onDblClick
+  dblclick: 'dblclick'
+}
+
+/**
+ * 把 `on*` 属性名解析成真实事件名。
+ *
+ * @returns 名字不以 `on` 开头或只有 `on` 本身时返回 undefined。
+ */
+export function resolveEventName(attributeName: string): string | undefined {
+  if (!attributeName.startsWith('on') || attributeName.length <= 2) return undefined
+  const lowered = attributeName.slice(2).toLowerCase()
+  return EVENT_NAME_ALIASES[lowered] ?? lowered
+}

package/src/dom-props-consistency.test.ts

@@ -0,0 +1,149 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { compile } from '@vobs/compiler'
+import { createDOMRenderer, setRenderer, state } from '@vobs/vobs'
+import { isPropertyName } from './dom-props'
+import { bindSpreadProps, createElement, setProperty, setStaticProps, spreadProps } from './index'
+
+setRenderer(createDOMRenderer())
+
+const flush = async () => { await Promise.resolve(); await Promise.resolve() }
+
+/*
+ * 两条都是"编译期与运行期各写一份、且不一致"的老问题（.artifacts/reports/runtime.supplement.md 缺点 2/3）。
+ * `dom-props.ts:1-8` 自称两边已收拢成单一来源，但那只覆盖**属性名**，没覆盖**事件名**，
+ * 而属性名表里 `autofocus` 又用 DOM 小写、与同表的 readOnly/tabIndex 约定相反。
+ */
+describe('on* 事件名：运行期必须与编译期用同一张别名表', () => {
+  it('onDoubleClick 展开后挂的是 dblclick，不是不存在的 doubleclick', async () => {
+    const calls: string[] = []
+    const props = { onDoubleClick: () => calls.push('dbl') }
+    const el = createElement('div')
+    spreadProps(el, props)
+
+    el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }))
+    // 修复前：真实事件名是 "doubleclick"，dblclick 命中 0 次（回调永不触发且静默）
+    expect(calls).toEqual(['dbl'])
+  })
+
+  it('onDoubleClick 的"隐藏监听"不存在（不会再挂到 doubleclick 上）', () => {
+    const calls: string[] = []
+    const el = createElement('div')
+    spreadProps(el, { onDoubleClick: () => calls.push('dbl') })
+    el.dispatchEvent(new Event('doubleclick', { bubbles: true }))
+    expect(calls).toEqual([])
+  })
+
+  it('自定义事件 onMyEvent 保留大小写语义（不把 myEvent 降成 myevent 之外的东西）', () => {
+    const calls: string[] = []
+    const el = createElement('div')
+    spreadProps(el, { onMyEvent: () => calls.push('custom') })
+    el.dispatchEvent(new Event('myevent', { bubbles: true }))
+    expect(calls).toEqual(['custom'])
+  })
+
+  it('身份稳定的展开里替换 onDoubleClick 时，旧监听被摘掉', async () => {
+    const calls: string[] = []
+    const first = state<() => void>(() => calls.push('first'))
+    const props = { get onDoubleClick() { return first.value } }
+    const el = createElement('div')
+    bindSpreadProps(el, () => props)
+    await flush()
+
+    el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }))
+    expect(calls).toEqual(['first'])
+
+    first.value = () => calls.push('second')
+    await flush()
+    el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }))
+    expect(calls).toEqual(['first', 'second'])
+  })
+
+  it('编译产物直接跑：onDoubleClick 真的能用', () => {
+    // 注意 compile() 直接返回**代码字符串**（不是 { code }）
+    const output = compile(
+      'export const A = (props) => <div onDoubleClick={props.hit} />',
+      { filename: 'a.tsx' }
+    )
+    expect(output).toContain('"dblclick"')
+    expect(output).not.toContain('"doubleclick"')
+  })
+})
+
+describe('autoFocus={false} 不得让元素自动聚焦', () => {
+  /*
+   * 判据是**属性存在与否**，不是 `el.autofocus`：
+   * 实测 jsdom 与真实 DOM 的 IDL 都不反射 autofocus（`el.autofocus = true` 是 no-op，
+   * 既不建属性也不改值），所以 property 通道在这里是静默失败 —— 修法必须走 attribute 通道。
+   * 而 autofocus 的语义是"**属性存在**就聚焦"，与属性的值无关，
+   * 所以 `String(false)` 写出的 `autofocus="false"` 会让 `autoFocus={false}` **真的自动聚焦**。
+   */
+  it('autoFocus={false} 不得留下 autofocus 属性', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    setStaticProps(node, { autoFocus: false })
+    // 修复前：走 attribute 通道 → String(false) → autofocus="false" → 仍然自动聚焦
+    expect(node.hasAttribute('autofocus')).toBe(false)
+  })
+
+  it('autoFocus 为真时属性存在（属性存在即聚焦）', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    setStaticProps(node, { autoFocus: true })
+    expect(node.hasAttribute('autofocus')).toBe(true)
+  })
+
+  it('autoFocus 走 property 通道，且映射到全小写的 IDL 名', () => {
+    /*
+     * 这里曾经断言 `domAttributeName('autoFocus') === 'autofocus'`（走 attribute 别名）。
+     * 那个做法是**错的**：`autofocus` 是布尔属性，attribute 通道会把 false 序列化成
+     * `autofocus="false"`，而"属性存在即聚焦" → `autoFocus={false}` 反而真的聚焦。
+     * 正解是走 property 通道（属性随 IDL 反射被正确移除）。
+     */
+    expect(isPropertyName('autoFocus')).toBe(true)
+    // 但 IDL 名是全小写 `autofocus` —— 直接用驼峰 Reflect.set 只会挂 expando（静默无效）
+    const el = document.createElement('input') as HTMLInputElement
+    setProperty(el, 'autoFocus', true)
+    expect(el.hasAttribute('autofocus')).toBe(true)
+    expect(el.autofocus).toBe(true)
+    setProperty(el, 'autoFocus', false)
+    expect(el.hasAttribute('autofocus')).toBe(false)
+    expect(el.autofocus).toBe(false)
+  })
+
+  it('展开里值为 false 时不设置属性（初始与增量都算）', async () => {
+    const flag = state(false)
+    const props = { get autoFocus() { return flag.value } }
+    const el = createElement('input')
+    bindSpreadProps(el, () => props)
+    await flush()
+    // 这是缺陷的本体：修复前 `String(false)` 会写出 autofocus="false" → 仍然自动聚焦
+    expect(el.hasAttribute('autofocus')).toBe(false)
+
+    // 真值时属性存在（属性存在即聚焦）
+    flag.value = true
+    await flush()
+    expect(el.hasAttribute('autofocus')).toBe(true)
+  })
+
+  it('展开里删掉 autoFocus 键时属性被移除', async () => {
+    const present = state(true)
+    const props = new Proxy({} as Record<string, unknown>, {
+      ownKeys: () => (present.value ? ['autoFocus'] : []),
+      getOwnPropertyDescriptor: () => ({ enumerable: true, configurable: true, value: true }),
+      get: (_t, key) => (key === 'autoFocus' ? true : undefined)
+    })
+    const el = createElement('input')
+    bindSpreadProps(el, () => props)
+    await flush()
+    expect(el.hasAttribute('autofocus')).toBe(true)
+
+    present.value = false
+    await flush()
+    expect(el.hasAttribute('autofocus')).toBe(false)
+  })
+
+  it('小写 autofocus 同样走属性通道（老写法不能是另一套语义）', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    setStaticProps(node, { autofocus: false })
+    expect(node.hasAttribute('autofocus')).toBe(false)
+  })
+})

package/src/dom-props.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { domAttributeName, isPropertyName } from './dom-props'
+
+describe('isPropertyName —— 哪些名字必须走 property 通道', () => {
+  it('attribute 形式无效或名字对不上的，走 property', () => {
+    // innerHTML / textContent 根本不是 HTML 属性，setAttribute 完全无效
+    expect(isPropertyName('innerHTML')).toBe(true)
+    expect(isPropertyName('innerText')).toBe(true)
+    expect(isPropertyName('textContent')).toBe(true)
+    // defaultValue 的 attribute 形式叫 value，名字对不上
+    expect(isPropertyName('defaultValue')).toBe(true)
+    expect(isPropertyName('defaultChecked')).toBe(true)
+    // 这两个没有对应 attribute
+    expect(isPropertyName('indeterminate')).toBe(true)
+    expect(isPropertyName('currentTime')).toBe(true)
+  })
+
+  it('表单状态与常见 property', () => {
+    for (const name of ['value', 'checked', 'selected', 'disabled', 'multiple', 'readOnly', 'required', 'tabIndex', 'colSpan']) {
+      expect(isPropertyName(name)).toBe(true)
+    }
+  })
+
+  it('attribute 与 data-*/aria-* 不受影响', () => {
+    for (const name of ['className', 'title', 'id', 'data-id', 'aria-label', 'strokeWidth', 'someProp']) {
+      expect(isPropertyName(name)).toBe(false)
+    }
+  })
+})
+
+describe('domAttributeName —— JSX 属性名 → DOM attribute 名', () => {
+  it('HTML 别名', () => {
+    expect(domAttributeName('className')).toBe('class')
+    expect(domAttributeName('htmlFor')).toBe('for')
+    expect(domAttributeName('autoComplete')).toBe('autocomplete')
+    expect(domAttributeName('spellCheck')).toBe('spellcheck')
+  })
+
+  it('SVG 表现属性转短横线（写驼峰会静默无效）', () => {
+    expect(domAttributeName('strokeWidth')).toBe('stroke-width')
+    expect(domAttributeName('strokeLinecap')).toBe('stroke-linecap')
+    expect(domAttributeName('fillOpacity')).toBe('fill-opacity')
+    expect(domAttributeName('textAnchor')).toBe('text-anchor')
+    expect(domAttributeName('stopColor')).toBe('stop-color')
+    expect(domAttributeName('pointerEvents')).toBe('pointer-events')
+    expect(domAttributeName('markerStart')).toBe('marker-start')
+  })
+
+  /*
+   * 回归：SVG 的属性命名是混合的 —— 表现属性是短横线，结构属性却真是驼峰。
+   * 曾经按「驼峰一律转短横线」实现过，会把下面这些改坏（viewBox → view-box 等），
+   * 而改坏之后是完全静默的：浏览器不认识的属性，图形照旧不渲染，没有任何报错。
+   */
+  it('SVG 结构属性必须保持驼峰', () => {
+    for (const name of [
+      'viewBox', 'preserveAspectRatio', 'pathLength', 'startOffset', 'textLength', 'lengthAdjust',
+      'markerWidth', 'markerHeight', 'markerUnits', 'clipPathUnits', 'gradientUnits',
+      'patternUnits', 'maskUnits', 'spreadMethod', 'zoomAndPan', 'baseFrequency', 'numOctaves',
+      'attributeName', 'calcMode', 'keyTimes', 'repeatCount', 'refX', 'refY'
+    ]) {
+      expect(domAttributeName(name), name).toBe(name)
+    }
+  })
+
+  it('不认识的名字原样透传', () => {
+    expect(domAttributeName('data-id')).toBe('data-id')
+    expect(domAttributeName('aria-label')).toBe('aria-label')
+    expect(domAttributeName('someProp')).toBe('someProp')
+  })
+})

package/src/dom-props.ts

@@ -0,0 +1,107 @@
+/**
+ * JSX 属性名 → DOM 设置方式的**单一来源**。
+ *
+ * compiler 在编译期用它决定生成 setProperty/bindProperty 还是 setAttribute/bindAttribute，
+ * runtime 在展开 `{...props}` 时用同一套判断。此前两边各写了一份**逐字重复**的实现
+ * （compile.ts 与 ops.ts），注释还写着「保持一致」—— 分叉即静默改道，所以收到这里。
+ *
+ * 这张表只描述「名字」，不占用户包体：compiler 侧是构建期用，runtime 侧是几十个字符串。
+ */
+
+/**
+ * 走 property 通道的名字（`el[name] = value`）。
+ *
+ * 判断标准是「当成 attribute 设不管用、或者语义不同」：
+ * - `innerHTML` / `textContent` 不是 HTML 属性，setAttribute 完全无效（静默无操作）
+ * - `defaultValue` / `defaultChecked` 的 attribute 形式是 value/checked，名字对不上
+ * - `indeterminate` / `currentTime` / `volume` 等根本没有对应 attribute
+ * 其余常见名字（value/checked/disabled/…）两条通道都能工作，列在这里是为了语义正确
+ * （如 `disabled={false}` 必须清除 property）。
+ */
+const PROPERTY_NAMES: ReadonlySet<string> = new Set([
+  // 表单状态
+  'value', 'checked', 'selected', 'disabled', 'multiple', 'readOnly', 'required',
+  'defaultValue', 'defaultChecked', 'indeterminate',
+  /*
+   * `autoFocus` 用**驼峰**（与同表 readOnly/tabIndex/defaultChecked 一致），且必须走
+   * **property 通道**：`autofocus` 是**布尔属性**（只看存在与否、与值无关），
+   * 所以 `autoFocus={false}` 必须"移除属性"而不是写 `autofocus="false"`
+   * （attribute 通道只能把 false 序列化成字符串，属性照样存在 = 仍然聚焦）。
+   *
+   * ⚠️ 但 `setProperty` 必须把它映射成 **IDL 名 `autofocus`（全小写）** ——
+   * `Reflect.set(el, 'autoFocus', …)` 只会挂一个不反射的 expando，**静默无效**。
+   * 映射表见 ops.ts 的 `PROPERTY_IDL_NAMES`。实测（jsdom，与真实 DOM 同语义）：
+   *   IDL `autofocus` → 写 true 得 has=true/idl=true；写 false 得 has=false/idl=false ✓
+   *   JSX `autoFocus` → 属性与 IDL 都不变（只是 expando）                        ✗
+   */
+  'autoFocus', 'hidden', 'tabIndex', 'colSpan', 'rowSpan', 'open',
+  // 只能走 property 的（attribute 路径会静默无效）
+  'innerHTML', 'innerText', 'textContent',
+  // 媒体
+  'muted', 'volume', 'currentTime', 'playbackRate'
+])
+
+/** camelCase JSX 属性名 → HTML attribute 名的别名。 */
+const ATTRIBUTE_ALIASES: Readonly<Record<string, string>> = {
+  className: 'class',
+  htmlFor: 'for',
+  autoComplete: 'autocomplete',
+  spellCheck: 'spellcheck',
+}
+
+/**
+ * SVG 里「JSX 写驼峰、真实 DOM 属性是短横线」的那一批。
+ *
+ * **不能按通用规则把驼峰转短横线** —— SVG 的属性命名是混合的：
+ * - 表现属性（就是那些能当 CSS 用的）是短横线：`stroke-width`、`fill-opacity`、`text-anchor`
+ * - 结构属性却真是驼峰：`viewBox`、`preserveAspectRatio`、`markerWidth`、`pathLength`
+ * 所以只对下面这批做转换；其余同名照旧（`viewBox` 写驼峰本来就是对的）。
+ *
+ * 写错大小写的后果是完全静默：setAttribute 出一个浏览器不认识的属性，图形照旧没有描边，
+ * 没有任何报错。
+ */
+const SVG_KEBAB_ATTRIBUTES: ReadonlySet<string> = new Set([
+  // stroke
+  'strokeWidth', 'strokeLinecap', 'strokeLinejoin', 'strokeDasharray', 'strokeDashoffset',
+  'strokeMiterlimit', 'strokeOpacity',
+  // fill
+  'fillOpacity', 'fillRule',
+  // clip（注意 clipPathUnits 是结构属性，不在这里）
+  'clipPath', 'clipRule',
+  // 文本对齐
+  'textAnchor', 'dominantBaseline', 'alignmentBaseline', 'baselineShift',
+  // 字体
+  'fontFamily', 'fontSize', 'fontSizeAdjust', 'fontStretch', 'fontStyle', 'fontVariant', 'fontWeight',
+  'letterSpacing', 'wordSpacing',
+  // marker 的表现属性（markerWidth / markerHeight / markerUnits 是结构属性，不在这里）
+  'markerStart', 'markerMid', 'markerEnd',
+  // 颜色
+  'colorInterpolation', 'colorInterpolationFilters', 'colorProfile', 'colorRendering',
+  'floodColor', 'floodOpacity', 'lightingColor', 'stopColor', 'stopOpacity',
+  'glyphOrientationHorizontal', 'glyphOrientationVertical',
+  // 渲染与合成
+  'imageRendering', 'paintOrder', 'pointerEvents', 'shapeRendering',
+  'textDecoration', 'textRendering', 'transformOrigin', 'vectorEffect', 'writingMode'
+])
+
+/** 名字是否应走 property 通道（`el[name] = value`）。 */
+export function isPropertyName(name: string): boolean {
+  return PROPERTY_NAMES.has(name)
+}
+
+/** SVG 驼峰属性名是否应转成短横线形式（`strokeWidth` → `stroke-width`）。 */
+export function isSvgKebabAttribute(name: string): boolean {
+  return SVG_KEBAB_ATTRIBUTES.has(name)
+}
+
+/**
+ * camelCase JSX 属性名 → 真正写进 DOM 的 attribute 名。
+ *
+ * 注意 property 通道**不**经过这里：`colSpan` / `rowSpan` 的 JS 属性名本就是驼峰。
+ */
+export function domAttributeName(name: string): string {
+  const alias = ATTRIBUTE_ALIASES[name]
+  if (alias !== undefined) return alias
+  if (SVG_KEBAB_ATTRIBUTES.has(name)) return name.replace(/[A-Z]/gu, letter => `-${letter.toLowerCase()}`)
+  return name
+}