@vobs/runtime 1.0.0

package/src/dynamic.test.ts

@@ -0,0 +1,228 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createDOMRenderer, setRenderer, createText, insertDynamicValue, insertList, createComponent } from '@vobs/vobs'
+import { effect, state } from '@vobs/reactivity'
+import { bindText } from './bind'
+import { createFragment, type VobsNode } from './fragment'
+
+describe('dynamic JSX child normalization', () => {
+  it('ignores empty conditional values and expands arrays without a wrapper', () => {
+    setRenderer(createDOMRenderer())
+    const parent = document.createElement('div')
+    insertDynamicValue(parent, null, () => [createText('a'), false, null, createText('b')])
+    expect(parent.textContent).toBe('ab')
+    expect(parent.querySelector('vobs-value')).toBeNull()
+  })
+
+  it('formats primitive children and nested arrays without stringifying booleans', () => {
+    setRenderer(createDOMRenderer())
+    const parent = document.createElement('div')
+    insertDynamicValue(parent, null, () => ['hello', false, [' ', 2]])
+    expect(parent.textContent).toBe('hello 2')
+  })
+
+  it('renders null, undefined and booleans as empty text', () => {
+    setRenderer(createDOMRenderer())
+    const node = document.createTextNode('')
+    const parent = document.createElement('div')
+    parent.append(node)
+    bindText(node, () => false)
+    expect(parent.textContent).toBe('')
+  })
+})
+
+describe('array dynamic child disposal', () => {
+  it('disposes inner component owners when the array is swapped', async () => {
+    setRenderer(createDOMRenderer())
+    const log: string[] = []
+    let mountCount = 0
+    function Inner(): Node {
+      // 按实例打标：数组替换后新组件的 effect 也会合法运行，不能共享计数
+      const instance = ++mountCount
+      effect(() => {
+        log.push(`run:${instance}`)
+        return () => log.push(`cleanup:${instance}`)
+      })
+      return document.createElement('span')
+    }
+    const parent = document.createElement('div')
+    const items = state([1])
+    insertDynamicValue(parent, null, () => items.value.map(() => createComponent(Inner, {})))
+    expect(log).toEqual(['run:1'])
+
+    items.value = [2]
+    await new Promise(resolve => setTimeout(resolve, 0))
+    // 旧组件的 effect 必须被清理，而不是继续订阅信号写已脱离的 DOM
+    expect(log).toContain('cleanup:1')
+    expect(log).toContain('run:2')
+    expect(log).not.toContain('cleanup:2')
+  })
+
+  it('disposed inner effects stop reacting to their signals', async () => {
+    setRenderer(createDOMRenderer())
+    const counter = state(0)
+    interface Instance {
+      runs: number
+      disposed: boolean
+    }
+    const mounted: Instance[] = []
+    function Inner(): Node {
+      const instance: Instance = { runs: 0, disposed: false }
+      mounted.push(instance)
+      effect(() => {
+        counter.value
+        instance.runs++
+        return () => { instance.disposed = true }
+      })
+      return document.createElement('span')
+    }
+    const parent = document.createElement('div')
+    const items = state([1])
+    insertDynamicValue(parent, null, () => items.value.map(() => createComponent(Inner, {})))
+    const first = mounted[0]
+    expect(first.runs).toBe(1)
+
+    items.value = [2]
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(first.disposed).toBe(true)
+
+    counter.value = 1
+    await new Promise(resolve => setTimeout(resolve, 0))
+    // 幽灵 effect 不允许再被触发
+    expect(first.runs).toBe(1)
+  })
+
+  it('disposes multi-root components nested in swapped arrays', async () => {
+    setRenderer(createDOMRenderer())
+    const log: string[] = []
+    function MultiRoot(): VobsNode {
+      effect(() => {
+        log.push('run')
+        return () => log.push('cleanup')
+      })
+      const first = document.createElement('span')
+      const second = document.createElement('span')
+      return createFragment((parent, anchor) => {
+        parent.insertBefore(first, anchor)
+        parent.insertBefore(second, anchor)
+      })
+    }
+    const parent = document.createElement('div')
+    const items = state([1])
+    insertDynamicValue(parent, null, () => items.value.map(() => createComponent(MultiRoot, {})))
+    items.value = [2]
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).toContain('cleanup')
+  })
+})
+
+describe('primitive list item updates', () => {
+  // 模拟编译产物：{item} 编译为 insertDynamicValue(() => item)，
+  // 原始值被静态捕获，不订阅 item 信号。
+  function compiledRow(item: string): Node {
+    const span = document.createElement('span')
+    const text = document.createTextNode('')
+    span.append(text)
+    insertDynamicValue(span, null, () => item)
+    return span
+  }
+
+  function loggedRow(item: string, log: string[]): Node {
+    const span = document.createElement('span')
+    const text = document.createTextNode('')
+    span.append(text)
+    effect(() => {
+      log.push(`run:${item}`)
+      return () => log.push(`cleanup:${item}`)
+    })
+    insertDynamicValue(span, null, () => item)
+    return span
+  }
+
+  it('updates indexed rows when primitive items change', async () => {
+    setRenderer(createDOMRenderer())
+    const parent = document.createElement('div')
+    const items = state(['a', 'b'])
+    insertList(parent, null, () => items.value, item => compiledRow(item))
+    expect(parent.textContent).toBe('ab')
+
+    items.value = ['a', 'c']
+    await new Promise(resolve => setTimeout(resolve, 0))
+    // 原始类型项无法通过 item 信号刷新视图，必须重建该行
+    expect(parent.textContent).toBe('ac')
+  })
+
+  it('updates keyed rows when the value changes under a stable key', async () => {
+    setRenderer(createDOMRenderer())
+    const parent = document.createElement('div')
+    const items = state(['a', 'b'])
+    insertList(parent, null, () => items.value, item => compiledRow(item), (_item, index) => index)
+    expect(parent.textContent).toBe('ab')
+
+    items.value = ['x', 'y']
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(parent.textContent).toBe('xy')
+  })
+
+  it('keeps rows when primitive values are unchanged', async () => {
+    setRenderer(createDOMRenderer())
+    const log: string[] = []
+    const parent = document.createElement('div')
+    const items = state(['a', 'b'])
+    insertList(parent, null, () => items.value, item => loggedRow(item, log))
+    const runsAfterMount = log.filter(entry => entry.startsWith('run:')).length
+
+    items.value = ['a', 'b']
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(parent.textContent).toBe('ab')
+    expect(log.filter(entry => entry.startsWith('cleanup:'))).toHaveLength(0)
+    expect(log.filter(entry => entry.startsWith('run:'))).toHaveLength(runsAfterMount)
+  })
+
+  it('disposes replaced primitive rows and keeps untouched rows', async () => {
+    setRenderer(createDOMRenderer())
+    const log: string[] = []
+    const parent = document.createElement('div')
+    const items = state(['a', 'b'])
+    insertList(parent, null, () => items.value, item => loggedRow(item, log))
+
+    items.value = ['c', 'b']
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(parent.textContent).toBe('cb')
+    expect(log).toContain('cleanup:a')
+    expect(log).toContain('run:c')
+    expect(log).not.toContain('cleanup:b')
+  })
+
+  it('still updates object rows in place through reactive proxies', async () => {
+    setRenderer(createDOMRenderer())
+    const parent = document.createElement('div')
+    const users = state([
+      { id: 1, name: 'a' },
+      { id: 2, name: 'b' }
+    ])
+    insertList(
+      parent,
+      null,
+      () => users.value,
+      user => {
+        const span = document.createElement('span')
+        const text = document.createTextNode('')
+        span.append(text)
+        // 模拟编译产物：{user.name} 经代理转发 item.value，在行内 effect 中被追踪
+        insertDynamicValue(span, null, () => user.name)
+        return span
+      },
+      user => user.id
+    )
+    expect(parent.textContent).toBe('ab')
+
+    users.value = [
+      { id: 1, name: 'a2' },
+      { id: 2, name: 'b2' }
+    ]
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(parent.textContent).toBe('a2b2')
+  })
+})
+

package/src/dynamic.ts

@@ -0,0 +1,266 @@
+import { createOwner, effect, state, type Owner, type Signal } from '@vobs/reactivity'
+import {
+  associateNodeOwner,
+  createBlock,
+  createComment,
+  createText,
+  insertBefore,
+  removeChild
+} from './ops'
+import { createFragment, isVobsFragment, type VobsNode } from './fragment'
+
+export type NodeFactory = () => VobsNode | null | undefined | false
+export type DynamicChild = VobsNode | string | number | boolean | null | undefined | readonly DynamicChild[]
+
+interface ListEntry<T> {
+  key: unknown
+  node: VobsNode
+  owner: Owner
+  viewOwner: Owner
+  item: Signal<T>
+  /** 最近一次赋值的原始 item：供比较与刷新使用，避免在列表 effect 内读取 item 信号造成自依赖。 */
+  value: T
+  index: number
+}
+
+export function insertDynamic(parent: Node, anchor: Node | null, factory: NodeFactory): void {
+  const marker = createComment('vobs:dynamic')
+  insertBefore(parent, marker, anchor)
+  let current: VobsNode | null = null
+
+  effect(() => {
+    const next = createBlock(factory)
+    if (next === current) return
+
+    if (current) removeChild(parent, current)
+    current = next
+    if (current) insertBefore(parent, current, marker)
+  })
+}
+
+/**
+ * Inserts any Vobs child value. This is the escape hatch for JSX expressions
+ * that return a node, an array of nodes, text, or an empty conditional value.
+ */
+export function insertDynamicValue(
+  parent: Node,
+  anchor: Node | null,
+  factory: () => DynamicChild
+): void {
+  const marker = createComment('vobs:value')
+  insertBefore(parent, marker, anchor)
+  let current: VobsNode | null = null
+  let scope: Owner | null = null
+
+  effect(() => {
+    // 每轮求值使用独立 scope Owner：factory 求值与挂载期间创建的组件 Owner 全部挂在它下面。
+    // 数组/节点被替换时整体 dispose 旧 scope，避免被丢弃子树的 effect 继续订阅信号（幽灵更新与内存泄漏）。
+    const nextScope = createOwner()
+    const next = nextScope.run(() => normalizeDynamicChild(factory()))
+    if (next === current) {
+      nextScope.dispose()
+      return
+    }
+    if (current) removeChild(parent, current)
+    scope?.dispose()
+    scope = nextScope
+    current = next
+    if (current) insertBefore(parent, current, marker)
+  })
+}
+
+/** Convert a JSX child value to a host node without creating a wrapper element. */
+export function normalizeDynamicChild(value: DynamicChild): VobsNode | null {
+  if (value === null || value === undefined || typeof value === 'boolean') return null
+  if (typeof value === 'string' || typeof value === 'number') return createText(String(value))
+  if (isVobsFragment(value) || isHostNode(value)) return value as VobsNode
+  if (Array.isArray(value)) {
+    const children = value
+    if (children.length === 0) return null
+    return createFragment((parent, anchor) => {
+      for (const child of children) {
+        const node = normalizeDynamicChild(child)
+        if (node) insertBefore(parent, node, anchor)
+      }
+    })
+  }
+  return null
+}
+
+function isHostNode(value: unknown): value is Node {
+  return Boolean(value && typeof value === 'object'
+    && ('nodeType' in value || ((value as { type?: unknown }).type === 'element'
+      || (value as { type?: unknown }).type === 'text'
+      || (value as { type?: unknown }).type === 'comment')))
+}
+
+export function insertList<T>(
+  parent: Node,
+  anchor: Node | null,
+  source: () => readonly T[],
+  renderItem: (item: T, index: number) => VobsNode,
+  keyOf?: (item: T, index: number) => unknown
+): void {
+  const marker = createComment('vobs:list')
+  insertBefore(parent, marker, anchor)
+  let entries: Array<ListEntry<T>> = []
+  const tracksIndex = renderItem.length >= 2
+
+  effect(() => {
+    const items = source()
+    const keyed = keyOf && items.every((item, index) => keyOf(item, index) != null)
+    const nextEntries = keyed
+      ? reconcileKeyed(items, entries, renderItem, keyOf)
+      : reconcileIndexed(items, entries, renderItem)
+
+    for (let index = 0; index < nextEntries.length; index++) {
+      const entry = nextEntries[index]
+      if (tracksIndex && entry && entry.index !== index) refreshListEntry(parent, entry, index, renderItem)
+    }
+
+    for (const entry of entries) {
+      if (!nextEntries.includes(entry)) disposeEntry(parent, entry)
+    }
+
+    let reference: VobsNode | null = marker
+    for (let index = nextEntries.length - 1; index >= 0; index--) {
+      insertBefore(parent, nextEntries[index].node, reference)
+      reference = nextEntries[index].node
+    }
+    entries = nextEntries
+  })
+}
+
+function reconcileKeyed<T>(
+  items: readonly T[],
+  entries: Array<ListEntry<T>>,
+  renderItem: (item: T, index: number) => VobsNode,
+  keyOf: (item: T, index: number) => unknown
+): Array<ListEntry<T>> {
+  const previous = new Map(entries.map(entry => [entry.key, entry]))
+  const seen = new Set<unknown>()
+  const nextEntries: Array<ListEntry<T>> = []
+
+  for (let index = 0; index < items.length; index++) {
+    const item = items[index]
+    const key = keyOf(item, index)
+    if (seen.has(key)) {
+      console.warn(`Vobs: 检测到重复的列表 key: ${String(key)}`)
+    }
+    seen.add(key)
+    if (previous.has(key)) {
+      const entry = previous.get(key)!
+      previous.delete(key)
+      if (isPrimitiveItem(item) && !Object.is(entry.value, item)) {
+        // 原始类型项在编译产物中被静态捕获，无法通过 item 信号刷新视图：值变化时必须重建行。
+        nextEntries.push(createListEntry(item, index, key, renderItem))
+        continue
+      }
+      entry.item.value = item
+      entry.value = item
+      nextEntries.push(entry)
+      continue
+    }
+    nextEntries.push(createListEntry(item, index, key, renderItem))
+  }
+
+  return nextEntries
+}
+
+function reconcileIndexed<T>(
+  items: readonly T[],
+  entries: Array<ListEntry<T>>,
+  renderItem: (item: T, index: number) => VobsNode
+): Array<ListEntry<T>> {
+  const nextEntries: Array<ListEntry<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)) {
+      // 原始类型项被编译产物静态捕获，值变化时必须重建行；旧行由主循环统一 dispose。
+      nextEntries.push(createListEntry(item, index, index, renderItem))
+      continue
+    }
+    if (entry) {
+      entry.item.value = item
+      entry.value = item
+      nextEntries.push(entry)
+      continue
+    }
+    nextEntries.push(createListEntry(item, index, index, renderItem))
+  }
+  return nextEntries
+}
+
+/** 原始类型（含 function）无法被 Proxy 响应化，只能整行重建。 */
+function isPrimitiveItem(item: unknown): boolean {
+  return item === null || typeof item !== 'object'
+}
+
+function createListEntry<T>(
+  item: T,
+  index: number,
+  key: unknown,
+  renderItem: (item: T, index: number) => VobsNode
+): ListEntry<T> {
+  const owner = createOwner()
+  let itemSignal!: Signal<T>
+  let viewOwner!: Owner
+  let node!: VobsNode
+  owner.run(() => {
+    itemSignal = state(item)
+    viewOwner = createOwner()
+    node = viewOwner.run(() => renderItem(toReactiveItem(itemSignal, item), index))
+  })
+  associateNodeOwner(node, viewOwner)
+  return { key, node, owner, viewOwner, item: itemSignal, value: item, index }
+}
+
+function refreshListEntry<T>(
+  parent: Node,
+  entry: ListEntry<T>,
+  index: number,
+  renderItem: (item: T, index: number) => VobsNode
+): void {
+  removeChild(parent, entry.node)
+  entry.index = index
+  const previousView = entry.viewOwner
+  entry.owner.run(() => {
+    entry.viewOwner = createOwner()
+    entry.node = entry.viewOwner.run(() => renderItem(
+      toReactiveItem(entry.item, entry.value),
+      index
+    ))
+  })
+  // 旧视图的 effect 仍订阅着 item 信号，必须 dispose，否则会写已脱离的 DOM（幽灵更新）。
+  previousView.dispose()
+  associateNodeOwner(entry.node, entry.viewOwner)
+}
+
+function toReactiveItem<T>(item: Signal<T>, initialValue: T): T {
+  if (typeof initialValue !== 'object' || initialValue === null) {
+    return initialValue
+  }
+
+  // 代理目标使用创建时的原始对象：避免在列表 effect 内读取 item 信号造成自依赖；
+  // 属性读取始终转发到 item.value，在行内绑定 effect 中被正常追踪。
+  return new Proxy(initialValue as object, {
+    get(_target, property, receiver) {
+      return Reflect.get(item.value as object, property, receiver)
+    },
+    has(_target, property) {
+      return property in (item.value as object)
+    },
+    ownKeys() {
+      return Reflect.ownKeys(item.value as object)
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      return Object.getOwnPropertyDescriptor(item.value as object, property)
+    }
+  }) as T
+}
+
+function disposeEntry(parent: Node, entry: ListEntry<unknown>): void {
+  removeChild(parent, entry.node)
+  entry.owner.dispose()
+}

package/src/error-boundary.ts

@@ -0,0 +1,35 @@
+import { createFragment, type VobsNode } from './fragment'
+import { insertBoundary, type BoundaryRetry } from './boundary'
+import type { NodeFactory } from './dynamic'
+
+export type ErrorBoundaryFallback = (
+  error: Error,
+  retry: BoundaryRetry
+) => ReturnType<NodeFactory>
+
+export interface ErrorBoundaryOptions {
+  children: NodeFactory
+  fallback: ErrorBoundaryFallback
+}
+
+export interface ErrorBoundaryProps {
+  children: NodeFactory
+  fallback: ErrorBoundaryFallback
+}
+
+/**
+ * Inserts an error boundary without adding a wrapper node. It captures errors
+ * from its child render branch and child-owned effects, then renders fallback.
+ */
+export function insertErrorBoundary(
+  parent: Node,
+  anchor: Node | null,
+  options: ErrorBoundaryOptions
+): void {
+  insertBoundary(parent, anchor, options)
+}
+
+/** Component-shaped API backed by the same no-wrapper host instruction. */
+export function ErrorBoundary(props: ErrorBoundaryProps): VobsNode {
+  return createFragment((parent, anchor) => insertErrorBoundary(parent, anchor, props))
+}

package/src/error.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { VobsError, formatVobsError, normalizeVobsError } from './error'
+
+describe('Vobs error protocol', () => {
+  it('normalizes unknown throws with a stable code', () => {
+    const error = normalizeVobsError('offline', { code: 'VOBS_H001', layer: 'http' })
+    expect(error).toBeInstanceOf(VobsError)
+    expect(error.code).toBe('VOBS_H001')
+    expect(error.layer).toBe('http')
+    expect(error.message).toBe('offline')
+  })
+
+  it('formats actionable development and production output', () => {
+    const error = new VobsError({
+      code: 'VOBS_R001',
+      message: 'Component render failed',
+      cause: new TypeError('missing data'),
+      fix: 'Guard the value before reading it.',
+      location: { file: 'src/App.tsx', line: 4, column: 9 }
+    })
+    const output = formatVobsError(error)
+    expect(output).toContain('Code: VOBS_R001')
+    expect(output).toContain('Location: src/App.tsx:4:9')
+    expect(output).toContain('Cause: TypeError: missing data')
+    expect(output).toContain('Fix: Guard the value before reading it.')
+    expect(formatVobsError(error, { environment: 'production' })).toBe('[Vobs VOBS_R001] Component render failed')
+  })
+})