@vobs/runtime 1.7.8 → 1.8.0

package/dist/svg.js

@@ -0,0 +1,76 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// packages/runtime/src/svg.ts
+var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+var SVG_TAGS = /* @__PURE__ */ 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"
+]);
+function isSvgTag(tag) {
+  return SVG_TAGS.has(tag);
+}
+__name(isSvgTag, "isSvgTag");
+export {
+  SVG_NAMESPACE,
+  SVG_TAGS,
+  isSvgTag
+};
+//# sourceMappingURL=svg.js.map

package/dist/svg.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/svg.ts"],"sourcesContent":["/**\n * SVG 标签与命名空间 —— 编译期判定提升、运行期决定怎么建节点的**同一份依据**。\n *\n * 两处都需要知道「这个名字是不是 SVG 标签」：\n * - 运行期：`document.createElement('rect')` 得到的是 HTMLUnknownElement，\n *   整棵 SVG 子树都不渲染（且没有报错），所以必须走 createElementNS\n * - 编译期：静态子树被提升成 HTML 模板串再 cloneNode，而模板串是**用 HTML 解析器**\n *   解析的 —— `<g>`、`<rect>` 同样变成 HTMLUnknownElement。这条路径漏了整整一个大版本\n *   （1.7.4 只修了 createElement 那条入口，svg.test.ts 也只测那条）。\n */\nexport const SVG_NAMESPACE = 'http://www.w3.org/2000/svg'\n\n/**\n * SVG 标签全集（= TypeScript SVGElementTagNameMap 的键，运行时分发依据）。\n * 与 React 的运行时清单同思路：只含纯 SVG 标签，刻意排除与 HTML 同名的\n * a/script/style/title（它们在 JSX 类型里归 HTMLElement，按 HTML 创建）。\n */\nexport const SVG_TAGS: ReadonlySet<string> = new Set([\n  'animate', 'animateMotion', 'animateTransform', 'circle', 'clipPath', 'defs', 'desc',\n  'ellipse', 'feBlend', 'feColorMatrix', 'feComponentTransfer', 'feComposite',\n  'feConvolveMatrix', 'feDiffuseLighting', 'feDisplacementMap', 'feDistantLight',\n  'feDropShadow', 'feFlood', 'feFuncA', 'feFuncB', 'feFuncG', 'feFuncR',\n  'feGaussianBlur', 'feImage', 'feMerge', 'feMergeNode', 'feMorphology', 'feOffset',\n  'fePointLight', 'feSpecularLighting', 'feSpotLight', 'feTile', 'feTurbulence',\n  'filter', 'foreignObject', 'g', 'image', 'line', 'linearGradient', 'marker', 'mask',\n  'metadata', 'mpath', 'path', 'pattern', 'polygon', 'polyline', 'radialGradient',\n  'rect', 'set', 'stop', 'svg', 'switch', 'symbol', 'text', 'textPath', 'tspan',\n  'use', 'view'\n])\n\n/** 是否是 SVG 专属标签（按名字判定，不看父级）。 */\nexport function isSvgTag(tag: string): boolean {\n  return SVG_TAGS.has(tag)\n}\n"],"mappings":";;;;AAUO,IAAM,gBAAgB;AAOtB,IAAM,WAAgC,oBAAI,IAAI;AAAA,EACnD;AAAA,EAAW;AAAA,EAAiB;AAAA,EAAoB;AAAA,EAAU;AAAA,EAAY;AAAA,EAAQ;AAAA,EAC9E;AAAA,EAAW;AAAA,EAAW;AAAA,EAAiB;AAAA,EAAuB;AAAA,EAC9D;AAAA,EAAoB;AAAA,EAAqB;AAAA,EAAqB;AAAA,EAC9D;AAAA,EAAgB;AAAA,EAAW;AAAA,EAAW;AAAA,EAAW;AAAA,EAAW;AAAA,EAC5D;AAAA,EAAkB;AAAA,EAAW;AAAA,EAAW;AAAA,EAAe;AAAA,EAAgB;AAAA,EACvE;AAAA,EAAgB;AAAA,EAAsB;AAAA,EAAe;AAAA,EAAU;AAAA,EAC/D;AAAA,EAAU;AAAA,EAAiB;AAAA,EAAK;AAAA,EAAS;AAAA,EAAQ;AAAA,EAAkB;AAAA,EAAU;AAAA,EAC7E;AAAA,EAAY;AAAA,EAAS;AAAA,EAAQ;AAAA,EAAW;AAAA,EAAW;AAAA,EAAY;AAAA,EAC/D;AAAA,EAAQ;AAAA,EAAO;AAAA,EAAQ;AAAA,EAAO;AAAA,EAAU;AAAA,EAAU;AAAA,EAAQ;AAAA,EAAY;AAAA,EACtE;AAAA,EAAO;AACT,CAAC;AAGM,SAAS,SAAS,KAAsB;AAC7C,SAAO,SAAS,IAAI,GAAG;AACzB;AAFgB;","names":[]}

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/vobsjs/vobs.git"
   },
-  "version": "1.7.8",
+  "version": "1.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,6 +32,24 @@
       "require": "./dist/error.cjs",
       "default": "./dist/error.js"
     },
+    "./dom-props": {
+      "types": "./dist/dom-props.d.ts",
+      "import": "./dist/dom-props.js",
+      "require": "./dist/dom-props.cjs",
+      "default": "./dist/dom-props.js"
+    },
+    "./dom-events": {
+      "types": "./dist/dom-events.d.ts",
+      "import": "./dist/dom-events.js",
+      "require": "./dist/dom-events.cjs",
+      "default": "./dist/dom-events.js"
+    },
+    "./svg": {
+      "types": "./dist/svg.d.ts",
+      "import": "./dist/svg.js",
+      "require": "./dist/svg.cjs",
+      "default": "./dist/svg.js"
+    },
     "./source": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
@@ -39,6 +57,6 @@
     "./source/*": "./src/*"
   },
   "dependencies": {
-    "@vobs/reactivity": "1.7.8"
+    "@vobs/reactivity": "1.8.0"
   }
 }

package/src/bind.ts

@@ -2,7 +2,7 @@
 
 import { effect } from '@vobs/reactivity'
 import type { Signal } from '@vobs/reactivity'
-import { registerSelectValueBinding, setAttribute, setProperty, setTextContent } from './ops'
+import { applyClassList, registerSelectValueBinding, setAttribute, setProperty, setTextContent } from './ops'
 
 export type ValueSource<T> = Signal<T> | (() => T)
 
@@ -27,6 +27,30 @@ export function bindAttribute(
 ): void {
   effect(() => {
     const value = readSource(source)
+    /*
+     * 只挡 null/undefined：`String(undefined)` 会把字面量 "undefined" 写进 placeholder 等属性。
+     *
+     * ⚠️ **`false` 必须透传**，不能在这里当成"不设置" —— HTML 的属性分两类：
+     * - **枚举属性**（spellcheck / contenteditable / draggable / autocomplete…）**值有语义**：
+     *   `spellcheck="false"` 与缺省（= true）意图**相反**，所以 `spellCheck={false}`
+     *   必须真的写出 `spellcheck="false"`。这一条有测试钉住（jsx-integration ⑤）。
+     * - **布尔属性**（disabled / checked / autofocus…）只看"存在与否"、与值无关 ——
+     *   那类必须走 **property 通道**（`bindProperty` + 布尔清除值 false）才能正确移除。
+     *
+     * 曾经试过在这里把 `false` 一律当"移除"来修 `autoFocus={false}`，结果把 spellCheck
+     * 的语义弄反了（`false` 变成"移除属性" = 回到缺省 true = 打开拼写检查，与意图相反）。
+     * 正确做法是让**布尔属性走 property 通道**，见 `dom-props.ts` 的 PROPERTY_NAMES。
+     */
+    if (value === null || value === undefined) return
+    /*
+     * `classList` 走专用通道：它与 `class` 写的是同一个 HTML 属性，
+     * 需要"记住上次贡献、本次替换"的合并语义（见 ops.ts 的 applyClassList）。
+     * 直接 `setAttribute(node,'classList', …)` 只会写出一个浏览器不认识的 `classlist` 属性。
+     */
+    if (key === 'classList') {
+      applyClassList(node, value)
+      return
+    }
     setAttribute(node, key, key === 'style' && value && typeof value === 'object' && !Array.isArray(value)
       ? Object.entries(value as Record<string, unknown>)
         .filter(([, entry]) => entry !== null && entry !== undefined && entry !== false)
@@ -47,6 +71,10 @@ export function bindProperty(
     registerSelectValueBinding(node, () => readSource(source))
   }
   effect(() => {
-    setProperty(node, key, readSource(source))
+    const value = readSource(source)
+    // property 键的 false 有语义（如 disabled={false} 必须清除）必须透传；
+    // 但 null/undefined 跳过——DOM 会把 undefined 强转成字符串 "undefined"（如 input.value）
+    if (value === null || value === undefined) return
+    setProperty(node, key, value)
   })
 }

package/src/boundaries.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { describe, expect, it, vi } from 'vitest'
-import { createDOMRenderer, createText, createVobs, Profiler, AsyncBoundary, state } from '@vobs/vobs'
+import { createDOMRenderer, createElement, createText, createVobs, insertErrorBoundary, Profiler, AsyncBoundary, setRuntimeDebugHooks, state } from '@vobs/vobs'
 
 describe('AsyncBoundary and Profiler', () => {
   it('renders loading then resolved content', async () => {
@@ -58,3 +58,56 @@ describe('AsyncBoundary and Profiler', () => {
     vi.restoreAllMocks()
   })
 })
+
+/*
+ * 边界捕获错误之后，原来只调 invokeRuntimeDebug('error', …) ——
+ * 没装 DevTools（也就没有 error 钩子）时控制台一个字都不输出：
+ * 错误被替换成 fallback，现场再无痕迹。
+ */
+describe('边界错误不再静默', () => {
+  const mountFailing = () => {
+    const host = document.createElement('div')
+    const app = createVobs({
+      renderer: createDOMRenderer(),
+      render: () => {
+        const root = createElement('div')
+        insertErrorBoundary(root, null, {
+          children: () => { throw new Error('boom') },
+          fallback: () => createText('failed')
+        })
+        return root
+      }
+    })
+    app.mount(host)
+    app.update()
+    return { host, app }
+  }
+
+  it('没有 error 钩子时写进控制台', () => {
+    setRuntimeDebugHooks(null)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { host, app } = mountFailing()
+
+    expect(host.textContent).toBe('failed')
+    expect(spy).toHaveBeenCalled()
+    expect(String(spy.mock.calls[0][0])).toContain('boom')
+
+    app.destroy()
+    spy.mockRestore()
+  })
+
+  it('装了 error 钩子时交给钩子，不重复输出', () => {
+    const events: unknown[] = []
+    const restore = setRuntimeDebugHooks({ error: event => events.push(event) })
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { host, app } = mountFailing()
+
+    expect(host.textContent).toBe('failed')
+    expect(events.length).toBeGreaterThan(0)
+    expect(spy).not.toHaveBeenCalled()
+
+    app.destroy()
+    setRuntimeDebugHooks(restore)
+    spy.mockRestore()
+  })
+})

package/src/boundary.ts

@@ -1,11 +1,27 @@
 import { createOwner, state } from '@vobs/reactivity'
-import { invokeRuntimeDebug } from './debug'
+import { getRuntimeDebugHooks, invokeRuntimeDebug, type RuntimeErrorEvent } from './debug'
 import { insertDynamic, type NodeFactory } from './dynamic'
-import { normalizeVobsError } from './error'
+import { formatVobsError, normalizeVobsError } from './error'
 
 export type BoundaryRetry = () => void | Promise<unknown>
 export type BoundaryFallback = (error: Error, retry: BoundaryRetry) => ReturnType<NodeFactory>
 
+/**
+ * 边界捕获到的错误必须有人看得见。
+ *
+ * 原来只调 `invokeRuntimeDebug('error', …)` —— 没装 DevTools（也就没有 error 钩子）时
+ * 控制台**一个字都不输出**：错误被替换成 fallback，现场再无痕迹。这是排查成本最高的一种
+ * 静默。装了钩子就交给它（避免重复输出），没装就打到控制台。
+ *
+ * @param loud 只有「真的吞下了错误」才需要吵；retrying / recovered 属于信息，不进控制台。
+ */
+function reportBoundaryError(event: RuntimeErrorEvent, loud: boolean): void {
+  invokeRuntimeDebug('error', event)
+  if (loud && getRuntimeDebugHooks()?.error === undefined) {
+    console.error(formatVobsError(event.error, { includeStack: true }))
+  }
+}
+
 export interface BoundaryOptions {
   children: NodeFactory
   fallback: BoundaryFallback
@@ -38,25 +54,25 @@ export function insertBoundary(
         fix: '检查组件渲染逻辑，或在边界 fallback 中提供恢复操作。'
       })
       lastError = normalized
-      invokeRuntimeDebug('error', {
+      reportBoundaryError({
         error: normalized,
         owner: boundary,
         phase: 'boundary',
         handled: true,
         recovery: 'fallback'
-      })
+      }, true)
       error.value = normalized
     })
 
     const retry = (): void | Promise<unknown> => {
       if (error.value) {
-        invokeRuntimeDebug('error', {
+        reportBoundaryError({
           error: error.value,
           owner: boundary,
           phase: 'boundary',
           handled: true,
           recovery: 'retrying'
-        })
+        }, false)
       }
       error.value = null
       return options.onRetry?.()
@@ -73,13 +89,13 @@ export function insertBoundary(
       const currentError = error.value
       if (!currentError) {
         if (fallbackActive && lastError) {
-          invokeRuntimeDebug('error', {
+          reportBoundaryError({
             error: lastError,
             owner: boundary,
             phase: 'boundary',
             handled: true,
             recovery: 'recovered'
-          })
+          }, false)
           lastError = null
         }
         fallbackActive = false

package/src/clear-remove.test.ts

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { onDispose, state } from '@vobs/reactivity'
+import { createDOMRenderer, setRenderer } from '@vobs/vobs'
+import {
+  bindText,
+  clear,
+  createComponent,
+  createElement,
+  createText,
+  insertBefore,
+  removeChild,
+  type VobsNode
+} from './index'
+
+setRenderer(createDOMRenderer())
+
+function Item(props: { readonly label: () => string }): VobsNode {
+  const el = createElement('div')
+  const text = createText('')
+  insertBefore(el, text, null)
+  bindText(text, () => props.label())
+  return el
+}
+
+/** 组件清理时抛错的组件（用于验证顺序：DOM 先摘、Owner 后释放）。 */
+function Boom(): VobsNode {
+  const el = createElement('div')
+  onDispose(() => { throw new Error('cleanup boom') })
+  return el
+}
+
+/*
+ * `removeChild` 原来是「先释放 Owner 再摘 DOM」：cleanup 抛错就永远走不到摘除，
+ * DOM 里留着旧节点、它的 effect 却已经没了 —— 屏幕上两棵树且没有任何提示。
+ */
+describe('removeChild 的顺序', () => {
+  it('cleanup 抛错也仍然把节点从 DOM 摘掉', () => {
+    const parent = document.createElement('div')
+    const child = createComponent(Boom, {})
+    insertBefore(parent as unknown as Node, child, null)
+    expect((parent as unknown as Node).contains(child as unknown as Node)).toBe(true)
+
+    expect(() => removeChild(parent as unknown as Node, child)).toThrow('cleanup boom')
+    // 关键：DOM 已经一致了
+    expect((parent as unknown as Node).contains(child as unknown as Node)).toBe(false)
+  })
+})
+
+/*
+ * `clear` 原来只调渲染器（`textContent = ''`）——被清掉子树的 Owner 一个都不释放：
+ * 组件里的 effect 继续订阅信号（幽灵更新）、监听不解绑、onDispose 不跑。
+ */
+describe('clear 释放 Owner', () => {
+  it('组件输出节点上的 Owner 被释放，清空后不再幽灵更新', async () => {
+    const label = state('a')
+    const host = document.createElement('div')
+    for (let i = 0; i < 3; i++) {
+      insertBefore(host, createComponent(Item, { label: () => label.value }), null)
+    }
+    const flush = async () => { await Promise.resolve(); await Promise.resolve() }
+
+    await flush()
+    expect(host.textContent).toBe('aaa')
+
+    clear(host)
+    expect(host.textContent).toBe('')
+
+    // 幽灵更新：如果 Owner 没释放，这里会重新写回文本
+    label.value = 'b'
+    await flush()
+    expect(host.textContent).toBe('')
+  })
+
+  it('清理抛错也不影响容器被清空，错误照旧抛出', () => {
+    const host = document.createElement('div')
+    // 用组件（输出节点会登记 Owner）—— 手工 createOwner 不登记节点，walk 找不到它，
+    // 这正是 clear 的覆盖边界：组件边界内的清理是完整的，组件外自己建的 effect 归它的 Owner 管。
+    insertBefore(host as unknown as Node, createComponent(Boom, {}), null)
+    insertBefore(host as unknown as Node, createComponent(Item, { label: () => 'x' }), null)
+
+    expect(() => clear(host as unknown as Node)).toThrow('cleanup boom')
+    expect((host as unknown as Node).childNodes.length).toBe(0)
+  })
+})

package/src/client-only.test.ts

@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+/*
+ * `<ClientOnly>` —— 只在客户端渲染的子树（外部踩坑文档 D 条的后一半）。
+ *
+ * 这个组件唯一需要想清楚的地方是**两阶段**：朴素实现（服务端渲染空、客户端渲染 children）
+ * 会造成**水合不匹配**。所以首轮两侧都渲染 fallback，挂载后才换入 children。
+ *
+ * 本文件的核心判据就是**水合能对上**（`strictHydration` 不报差异），
+ * 以及换入之后内容真的出现了。
+ */
+import { describe, expect, it } from 'vitest'
+import { scheduler } from '@vobs/reactivity'
+import { createComponent, createDOMRenderer, createElement, createText, createVobs, setRenderer } from '@vobs/vobs'
+import type { VobsNode } from '@vobs/vobs'
+import { renderToString, hydrate } from '@vobs/ssr'
+import { ClientOnly, insertBefore } from './index'
+
+setRenderer(createDOMRenderer())
+const flush = (): void => { scheduler.flush() }
+const microtasks = async (): Promise<void> => {
+  await Promise.resolve(); await Promise.resolve(); await Promise.resolve()
+}
+
+function mountClientOnly(extra: Record<string, unknown> = {}) {
+  const host = document.createElement('main')
+  document.body.appendChild(host)
+  const app = createVobs({
+    render: () => {
+      const wrap = createElement('div')
+      const child = createComponent(ClientOnly, {
+        children: () => {
+          const widget = createElement('span')
+          widget.textContent = 'CLIENT'
+          return widget
+        },
+        ...extra
+      } as never)
+      // ClientOnly 返回的是 fragment，必须由 insertBefore 挂载（它会处理 fragment）
+      insertBefore(wrap, child, null)
+      return wrap as unknown as VobsNode
+    }
+  })
+  app.mount(host)
+  return { host, app, cleanup: () => { app.destroy(); host.remove() } }
+}
+
+describe('ClientOnly', () => {
+  it('挂载后换入 children', async () => {
+    const view = mountClientOnly()
+    flush()
+    // 首轮：还没有
+    expect(view.host.textContent).toBe('')
+    await microtasks()
+    flush()
+    expect(view.host.textContent, '挂载后没有换入 children').toBe('CLIENT')
+    view.cleanup()
+  })
+
+  it('服务端渲染不产出 children（SSG 阶段不会碰浏览器 API）', () => {
+    const tree = () => {
+      const wrap = createElement('div')
+      const child = createComponent(ClientOnly, {
+        children: () => {
+          const el = createElement('span')
+          el.textContent = 'CLIENT'
+          return el
+        }
+      } as never)
+      insertBefore(wrap, child, null)
+      return wrap as unknown as VobsNode
+    }
+    const html = renderToString(tree)
+    expect(html, 'SSR 产物里出现了只在客户端才该有的内容').not.toContain('CLIENT')
+  })
+
+  it('**水合对得上**（strictHydration 不报差异）—— 这是两阶段设计的理由', async () => {
+    const tree = () => {
+      const wrap = createElement('div')
+      const child = createComponent(ClientOnly, {
+        children: () => {
+          const el = createElement('span')
+          el.textContent = 'CLIENT'
+          return el
+        },
+        fallback: () => createText('placeholder')
+      } as never)
+      insertBefore(wrap, child, null)
+      return wrap as unknown as VobsNode
+    }
+    document.body.innerHTML = renderToString(tree)
+    // 服务端产物里是 fallback
+    expect(document.body.textContent).toBe('placeholder')
+
+    let error: unknown
+    let app: { destroy(): void } | undefined
+    try {
+      app = hydrate(tree, document.body, { strictHydration: true })
+    } catch (reason) {
+      error = reason
+    }
+    expect(
+      error,
+      `水合报出了差异：${JSON.stringify((error as { vobsHydration?: unknown })?.vobsHydration)}`
+    ).toBeUndefined()
+
+    // 水合首轮仍是 fallback（与产物一致），之后才换成 children
+    expect(document.body.textContent).toBe('placeholder')
+    await microtasks()
+    flush()
+    expect(document.body.textContent, '水合后没有换入 children').toBe('CLIENT')
+
+    app?.destroy()
+    document.body.innerHTML = ''
+  })
+
+  it('fallback 在首轮渲染（服务端与客户端一致）', () => {
+    const view = mountClientOnly({ fallback: () => createText('loading') })
+    flush()
+    expect(view.host.textContent).toBe('loading')
+    view.cleanup()
+  })
+
+  it('组件在微任务之前被卸载 → 不翻转、不抛错', async () => {
+    const view = mountClientOnly()
+    view.cleanup()
+    await microtasks()
+    flush()
+    expect(view.host.textContent).toBe('')
+    expect(view.host.isConnected).toBe(false)
+  })
+
+  it('卸载后没有残留（fragment 节点被清掉）', async () => {
+    const view = mountClientOnly()
+    await microtasks()
+    flush()
+    expect(view.host.textContent).toBe('CLIENT')
+    view.cleanup()
+    expect(view.host.innerHTML).toBe('')
+  })
+})

package/src/client-only.ts

@@ -0,0 +1,65 @@
+import { getCurrentOwner, state } from '@vobs/reactivity'
+import { insertDynamic } from './dynamic'
+import { createFragment, type VobsNode } from './fragment'
+
+export interface ClientOnlyProps {
+  /** 只在客户端渲染的内容。 */
+  readonly children?: VobsNode | (() => VobsNode | null | undefined)
+  /** 服务端（以及水合首轮）渲染的占位。 */
+  readonly fallback?: VobsNode | (() => VobsNode | null | undefined)
+}
+
+/**
+ * `<ClientOnly>` —— 只在客户端渲染的子树。
+ *
+ * 补的是外部踩坑文档 D 条的后一半：`onMount`（`39c155b`）管**副作用**
+ * （定时器 / matchMedia / localStorage），`ClientOnly` 管**渲染** ——
+ * 某些子树在服务端根本渲染不出来（依赖 `window`、第三方 widget、需要真实布局测量）。
+ *
+ * ## 为什么必须是**两阶段**（这是这个组件唯一需要想清楚的地方）
+ *
+ * 朴素实现是"服务端渲染空、客户端渲染 children" —— **那会造成水合不匹配**：
+ * 服务端产物里没有那棵子树，客户端却期望认领它（本仓库严格水合会报 `missing-node`，
+ * 非严格模式也会静默重建，表现为内容闪烁）。
+ *
+ * 所以这里：
+ * 1. **首轮**：服务端与客户端**都**渲染 `fallback`（默认什么都不渲染）—— 对得上
+ * 2. **挂载之后**（微任务）：翻成"已就绪"，`insertDynamic` 换入 `children`
+ *
+ * ## 父节点从哪来
+ *
+ * 用 `createFragment` —— 它的工厂签名是 `(parent, anchor) => void`，
+ * **框架在挂载时把父节点与锚点交进来**，于是可以直接用 `insertDynamic` 换内容，
+ * 不需要包裹元素（包裹层会改 flex/grid 布局）。
+ *
+ * ## 边界（如实说明）
+ *
+ * 客户端判定用的是 `typeof document === 'undefined'`，与 `onMount`（`39c155b`）
+ * 以及 `@vobs/ssr` 的 `prerender.ts` **同一套判据**。其已知局限也一样：
+ * **在 jsdom 这类带 DOM 的环境里做预渲染时会被判成客户端**（框架目前没有"正在预渲染"标志）。
+ * 那种环境下 `ClientOnly` 的首轮会渲染 `fallback`、微任务里再换成 `children`，
+ * 水合仍然是对得上的（两侧首轮一致），只是"跳过客户端渲染"这件事没生效。
+ */
+export function ClientOnly(props: ClientOnlyProps = {}): VobsNode {
+  return createFragment((parent, anchor) => {
+    const ready = state(false)
+    /*
+     * 只有存在 `document` 才排这个微任务 —— Node 端预渲染时不应留下会稍后执行的副作用
+     * （那会让"服务端渲染"在 renderToString 返回之后还动到已完成的输出）。
+     */
+    if (typeof document !== 'undefined') {
+      const owner = getCurrentOwner()
+      queueMicrotask(() => {
+        // 组件在这之前被卸载 → 不再翻转（与 onMount 同一防御）
+        if (owner?.disposed) return
+        ready.value = true
+      })
+    }
+    insertDynamic(parent, anchor, () => {
+      const slot = ready.value ? props.children : props.fallback
+      // 用 unknown 承接：声明类型不含 false，但 `cond && <X/>` 会给出 false
+      const value: unknown = typeof slot === 'function' ? slot() : slot
+      return value === undefined || value === null || value === false ? null : (value as VobsNode)
+    })
+  })
+}