@vobs/runtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @vobs/runtime
+
+The renderer-agnostic runtime of the vobs framework: DOM operations, compiled bindings, dynamic insertion, list reconciliation, and lifecycle boundaries.
+
+This package implements the operations the vobs compiler emits (`createElement`, `bindText`, `insertList`, ...) against a pluggable `VobsRenderer`, so the same component code runs under different rendering backends.
+
+## Install
+
+```bash
+npm install @vobs/runtime @vobs/reactivity
+```
+
+## Quick start
+
+### Boundaries (user-facing)
+
+```tsx
+import { ErrorBoundary, AsyncBoundary } from '@vobs/runtime'
+
+<ErrorBoundary fallback={(error, retry) => <button onClick={retry}>Retry</button>}>
+  <RiskyView />
+</ErrorBoundary>
+
+<AsyncBoundary fallback={<Spinner />}>
+  <SlowView />
+</AsyncBoundary>
+```
+
+### Dynamic children and lists
+
+```ts
+import { effect, state } from '@vobs/reactivity'
+import { insertDynamicValue, insertList, createFragment } from '@vobs/runtime'
+
+const view = state(<span>hello</span>)
+insertDynamicValue(parent, anchor, () => view.value)   // swaps nodes reactively
+
+const items = state(['a', 'b'])
+insertList(parent, anchor, () => items.value, {
+  key: item => item    // keyed reconciliation; indexed when omitted
+})
+```
+
+Reactive text binding:
+
+```ts
+import { bindText } from '@vobs/runtime'
+
+bindText(node, () => count.value)
+```
+
+### Custom renderers
+
+Implement `VobsRenderer` (node creation, insertion, removal, attribute/property/event application, clearing) and register it with `setRenderer`. All compiler-emitted operations route through it.
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `setRenderer(renderer)` / `getRenderer()` | Registers the active renderer backend. |
+| `createElement(tag)` / `createText(text)` / `createComment(text)` | Node factories (hydration-aware). |
+| `insertBefore(parent, node, anchor)` / `removeChild(parent, node)` | Tree mutation, fragment-aware. |
+| `setAttribute(node, name, value)` / `setProperty(node, name, value)` | Attribute vs property writes; `isPropertyKey` gates the property whitelist. |
+| `addEventListener(node, event, handler)` | Registers under the current owner — handlers get owner-scoped error isolation and are removed on owner dispose. |
+| `spreadProps(node, props)` / `setStaticProps(node, props)` | Apply prop objects; property keys accept `false`, attribute keys skip it. |
+| `bindText` / `bindAttribute` / `bindProperty` | Reactive one-way bindings to a node target. |
+| `ref(target)` / `setRef(node, target)` | Ref plumbing for element access. |
+| `insertDynamic(parent, anchor, factory)` / `insertDynamicValue(...)` | Reactive node swapping with full disposal of replaced subtrees. |
+| `insertList(parent, anchor, factory, options?)` | Keyed/indexed list reconciliation with per-row owners. |
+| `createFragment(render)` | Multi-root node container. |
+| `ErrorBoundary` / `insertErrorBoundary` | Catches child render/effect errors with retry. |
+| `insertBoundary` | Low-level boundary primitive (loading/error/empty switching). |
+| `AsyncBoundary` / `insertAsyncBoundary` | Async view swapping with fallback. |
+| `Profiler` / `insertProfiler` | Render timing instrumentation. |
+| HMR exports (`createHmrStateStore`, `registerHmrInstance`, `updateHmrModule`, ...) | Hot-reload state preservation. |
+
+## Types
+
+`VobsRenderer`, `VobsNode`, `VobsFragment`, `DynamicChild`, `NodeFactory`, `Ref`, plus option types for each boundary.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/runtime",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./error": "./src/error.ts"
+  },
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0"
+  }
+}

package/src/async-boundary.ts

@@ -0,0 +1,97 @@
+import { createOwner, state } from '@vobs/reactivity'
+import { insertDynamic, type NodeFactory } from './dynamic'
+import { createFragment, type VobsNode } from './fragment'
+
+export type AsyncBoundaryView = ReturnType<NodeFactory> | NodeFactory
+export type AsyncBoundaryFallback = (error: Error, retry: () => void) => ReturnType<NodeFactory>
+export interface AsyncBoundaryOptions<T> {
+  promise: PromiseLike<T> | (() => PromiseLike<T>)
+  children: (value: T) => ReturnType<NodeFactory>
+  loading?: AsyncBoundaryView
+  fallback?: AsyncBoundaryFallback
+  resetKey?: () => unknown
+}
+export interface AsyncBoundaryProps<T> extends AsyncBoundaryOptions<T> {}
+
+export function insertAsyncBoundary<T>(parent: Node, anchor: Node | null, options: AsyncBoundaryOptions<T>): void {
+  const boundary = createOwner()
+  boundary.run(() => {
+    const loading = state(true)
+    const data = state<T | undefined>(undefined)
+    const resolved = state(false)
+    const error = state<Error | null>(null)
+    let token = 0
+    let previousKey: unknown
+    let initialized = false
+    let fallbackActive = false
+    boundary.onError(reason => {
+      if (fallbackActive) throw reason
+      error.value = normalizeError(reason)
+      loading.value = false
+    })
+
+    const start = (): void => {
+      const current = ++token
+      loading.value = true
+      error.value = null
+      data.value = undefined
+      resolved.value = false
+      let promise: PromiseLike<T>
+      try {
+        promise = typeof options.promise === 'function' ? options.promise() : options.promise
+      } catch (reason) {
+        if (current === token) {
+          loading.value = false
+          error.value = normalizeError(reason)
+        }
+        return
+      }
+      Promise.resolve(promise).then(value => {
+        if (current !== token || boundary.disposed) return
+        data.value = value
+        resolved.value = true
+        loading.value = false
+      }, reason => {
+        if (current !== token || boundary.disposed) return
+        error.value = normalizeError(reason)
+        loading.value = false
+      })
+    }
+
+    const retry = (): void => start()
+    start()
+    insertDynamic(parent, anchor, () => {
+      const key = options.resetKey?.()
+      if (!initialized) {
+        initialized = true
+        previousKey = key
+      } else if (!Object.is(previousKey, key)) {
+        previousKey = key
+        start()
+      }
+      if (loading.value) {
+        fallbackActive = false
+        return resolveView(options.loading)
+      }
+      if (error.value) {
+        fallbackActive = true
+        return options.fallback?.(error.value, retry) ?? null
+      }
+      fallbackActive = false
+      return resolved.value ? options.children(data.value as T) : resolveView(options.loading)
+    })
+  })
+}
+
+export function AsyncBoundary<T>(props: AsyncBoundaryProps<T>): VobsNode {
+  return createFragment((parent, anchor) => insertAsyncBoundary(parent, anchor, props))
+}
+
+function resolveView(view: AsyncBoundaryView | undefined): ReturnType<NodeFactory> {
+  if (!view) return null
+  return typeof view === 'function' ? view() : view
+}
+
+function normalizeError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason))
+}

package/src/bind.ts

@@ -0,0 +1,47 @@
+// 动态绑定：将 Signal 绑定到 DOM 节点
+
+import { effect } from '@vobs/reactivity'
+import type { Signal } from '@vobs/reactivity'
+import { setAttribute, setProperty, setTextContent } from './ops'
+
+export type ValueSource<T> = Signal<T> | (() => T)
+
+function readSource<T>(source: ValueSource<T>): T {
+  return typeof source === 'function' ? source() : source.value
+}
+
+export function bindText(
+  node: Text,
+  source: ValueSource<unknown>
+): void {
+  effect(() => {
+    const value = readSource(source)
+    setTextContent(node, value === null || value === undefined || typeof value === 'boolean' ? '' : String(value))
+  })
+}
+
+export function bindAttribute(
+  node: Element,
+  key: string,
+  source: ValueSource<unknown>
+): void {
+  effect(() => {
+    const value = readSource(source)
+    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)
+        .map(([name, entry]) => `${name.replace(/[A-Z]/gu, match => `-${match.toLowerCase()}`)}:${String(entry)}`)
+        .join(';')
+      : String(value))
+  })
+}
+
+export function bindProperty(
+  node: Element,
+  key: string,
+  source: ValueSource<unknown>
+): void {
+  effect(() => {
+    setProperty(node, key, readSource(source))
+  })
+}

package/src/boundaries.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createDOMRenderer, createText, createVobs, Profiler, AsyncBoundary, state } from '@vobs/vobs'
+
+describe('AsyncBoundary and Profiler', () => {
+  it('renders loading then resolved content', async () => {
+    let resolve!: (value: string) => void
+    const promise = new Promise<string>(done => { resolve = done })
+    const host = document.createElement('div')
+    const app = createVobs({ renderer: createDOMRenderer(), render: () => AsyncBoundary({
+      promise,
+      loading: createText('loading'),
+      children: value => createText(value)
+    }) })
+    app.mount(host)
+    expect(host.textContent).toBe('loading')
+    resolve('ready')
+    await promise
+    await Promise.resolve()
+    expect(host.textContent).toBe('ready')
+    app.destroy()
+  })
+
+  it('ignores stale Promise results after a resetKey change', async () => {
+    let resolveFirst!: (value: string) => void
+    let resolveSecond!: (value: string) => void
+    const first = new Promise<string>(done => { resolveFirst = done })
+    const second = new Promise<string>(done => { resolveSecond = done })
+    const key = state(0)
+    const host = document.createElement('div')
+    const app = createVobs({ renderer: createDOMRenderer(), render: () => AsyncBoundary({
+      promise: () => key.value === 0 ? first : second,
+      resetKey: () => key.value,
+      children: value => createText(value)
+    }) })
+    app.mount(host)
+    key.value = 1
+    app.update()
+    resolveFirst('stale')
+    resolveSecond('fresh')
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(host.textContent).toBe('fresh')
+    app.destroy()
+  })
+
+  it('reports mount and update phases', () => {
+    const events: string[] = []
+    const host = document.createElement('div')
+    const app = createVobs({ renderer: createDOMRenderer(), render: () => Profiler({
+      id: 'demo',
+      onRender: info => events.push(info.phase),
+      children: () => createText('content')
+    }) })
+    app.mount(host)
+    expect(events).toEqual(['mount'])
+    app.destroy()
+    vi.restoreAllMocks()
+  })
+})

package/src/boundary.ts

@@ -0,0 +1,93 @@
+import { createOwner, state } from '@vobs/reactivity'
+import { invokeRuntimeDebug } from './debug'
+import { insertDynamic, type NodeFactory } from './dynamic'
+import { normalizeVobsError } from './error'
+
+export type BoundaryRetry = () => void | Promise<unknown>
+export type BoundaryFallback = (error: Error, retry: BoundaryRetry) => ReturnType<NodeFactory>
+
+export interface BoundaryOptions {
+  children: NodeFactory
+  fallback: BoundaryFallback
+  onRetry?: () => void | Promise<unknown>
+  resetKey?: () => unknown
+}
+
+/**
+ * Shared no-wrapper boundary protocol. The boundary owns its reactive error
+ * state and child branch, so replacing the branch also disposes its Owner.
+ */
+export function insertBoundary(
+  parent: Node,
+  anchor: Node | null,
+  options: BoundaryOptions
+): void {
+  const boundary = createOwner()
+  boundary.run(() => {
+    const error = state<Error | null>(null)
+    let fallbackActive = false
+    let lastError: Error | null = null
+    let initialized = false
+    let previousKey: unknown
+
+    boundary.onError(reason => {
+      if (fallbackActive) throw reason
+      const normalized = normalizeVobsError(reason, {
+        code: 'VOBS_R001',
+        layer: 'runtime',
+        fix: '检查组件渲染逻辑，或在边界 fallback 中提供恢复操作。'
+      })
+      lastError = normalized
+      invokeRuntimeDebug('error', {
+        error: normalized,
+        owner: boundary,
+        phase: 'boundary',
+        handled: true,
+        recovery: 'fallback'
+      })
+      error.value = normalized
+    })
+
+    const retry = (): void | Promise<unknown> => {
+      if (error.value) {
+        invokeRuntimeDebug('error', {
+          error: error.value,
+          owner: boundary,
+          phase: 'boundary',
+          handled: true,
+          recovery: 'retrying'
+        })
+      }
+      error.value = null
+      return options.onRetry?.()
+    }
+
+    insertDynamic(parent, anchor, () => {
+      const nextKey = options.resetKey?.()
+      if (!initialized || !Object.is(previousKey, nextKey)) {
+        initialized = true
+        previousKey = nextKey
+        if (error.value) error.value = null
+      }
+
+      const currentError = error.value
+      if (!currentError) {
+        if (fallbackActive && lastError) {
+          invokeRuntimeDebug('error', {
+            error: lastError,
+            owner: boundary,
+            phase: 'boundary',
+            handled: true,
+            recovery: 'recovered'
+          })
+          lastError = null
+        }
+        fallbackActive = false
+        return options.children()
+      }
+
+      fallbackActive = true
+      return options.fallback(currentError, retry)
+    })
+  })
+}

package/src/debug.ts

@@ -0,0 +1,146 @@
+import type { Owner } from '@vobs/reactivity'
+
+export type RuntimeDebugEnvironment = 'client' | 'server'
+
+/**
+ * Lightweight context copied onto debug events created synchronously inside a
+ * Router loader, Effect or SSR render. It is intentionally optional so the
+ * runtime remains useful without DevTools.
+ */
+export interface RuntimeDebugContext {
+  readonly environment?: RuntimeDebugEnvironment
+  readonly sessionId?: string
+  readonly route?: string
+  readonly navigationId?: number
+  readonly dataRequestId?: number
+  readonly updateId?: string
+  readonly effectId?: string
+  readonly source?: string
+}
+
+export interface RuntimeHydrationMismatch {
+  readonly kind: 'missing-node' | 'extra-node' | 'position' | 'content'
+  readonly expected: string
+  readonly actual: string
+  readonly path: string
+  readonly message: string
+}
+
+export type RuntimeDomMutationOperation = 'text' | 'property' | 'attribute' | 'insert' | 'remove'
+
+export interface RuntimeDomMutation {
+  readonly operation: RuntimeDomMutationOperation
+  readonly target: string
+  readonly parent?: string
+  readonly key?: string
+  readonly previousValue?: unknown
+  readonly nextValue?: unknown
+}
+
+export interface RuntimeErrorEvent {
+  readonly error: unknown
+  readonly owner: Owner
+  readonly phase: 'event' | 'boundary'
+  readonly handled: boolean
+  readonly recovery: 'propagated' | 'handled' | 'fallback' | 'retrying' | 'recovered'
+}
+
+export interface RuntimeDebugHooks {
+  domMutation?(mutation: RuntimeDomMutation): void
+  error?(event: RuntimeErrorEvent): void
+  hydrationMismatch?(event: RuntimeHydrationMismatch): void
+}
+
+let activeRuntimeDebugHooks: RuntimeDebugHooks | null = null
+let activeRuntimeDebugContext: RuntimeDebugContext | null = null
+
+export function setRuntimeDebugHooks(hooks: RuntimeDebugHooks | null): RuntimeDebugHooks | null {
+  const previous = activeRuntimeDebugHooks
+  activeRuntimeDebugHooks = hooks
+  return previous
+}
+
+export function getRuntimeDebugHooks(): RuntimeDebugHooks | null {
+  return activeRuntimeDebugHooks
+}
+
+export function getRuntimeDebugContext(): RuntimeDebugContext | null {
+  return activeRuntimeDebugContext
+}
+
+/** Run a synchronous operation with trace context, preserving async renders. */
+export function runWithRuntimeDebugContext<T>(context: RuntimeDebugContext, task: () => T): T {
+  const previous = activeRuntimeDebugContext
+  const next = { ...previous, ...context }
+  activeRuntimeDebugContext = next
+  let result: T
+  try {
+    result = task()
+  } catch (error) {
+    activeRuntimeDebugContext = previous
+    throw error
+  }
+  if (isPromiseLike(result)) {
+    return Promise.resolve(result).finally(() => {
+      if (activeRuntimeDebugContext === next) activeRuntimeDebugContext = previous
+    }) as T
+  }
+  activeRuntimeDebugContext = previous
+  return result
+}
+
+/** Keep a context active across callback boundaries such as Effect execution. */
+export function pushRuntimeDebugContext(context: RuntimeDebugContext): () => void {
+  const previous = activeRuntimeDebugContext
+  activeRuntimeDebugContext = { ...previous, ...context }
+  let restored = false
+  return () => {
+    if (restored) return
+    restored = true
+    activeRuntimeDebugContext = previous
+  }
+}
+
+export function invokeRuntimeDebug<K extends keyof RuntimeDebugHooks>(
+  name: K,
+  ...args: Parameters<NonNullable<RuntimeDebugHooks[K]>>
+): void {
+  const callback = activeRuntimeDebugHooks?.[name] as ((...values: unknown[]) => void) | undefined
+  if (!callback) return
+  try {
+    callback(...args)
+  } catch {
+    // Debug tooling must never change runtime behavior.
+  }
+}
+
+export function readDebugValue(read: () => unknown): unknown {
+  try {
+    return read()
+  } catch {
+    return '[Uninspectable]'
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return Boolean(value) && (typeof value === 'object' || typeof value === 'function')
+    && typeof (value as { then?: unknown }).then === 'function'
+}
+
+export function describeDebugNode(node: unknown): string {
+  if (!node || typeof node !== 'object') return 'node'
+  const value = node as {
+    readonly nodeName?: unknown
+    readonly tagName?: unknown
+    readonly id?: unknown
+    readonly className?: unknown
+  }
+  const name = typeof value.tagName === 'string'
+    ? value.tagName.toLowerCase()
+    : typeof value.nodeName === 'string' ? value.nodeName.toLowerCase() : 'node'
+  const id = typeof value.id === 'string' && value.id ? `#${value.id}` : ''
+  const className = typeof value.className === 'string' && value.className
+    ? `.${value.className.trim().split(/\s+/).filter(Boolean).join('.')}`
+    : ''
+  return `${name}${id}${className}`
+}