@vobs/runtime 1.0.0

package/src/error.ts

@@ -0,0 +1,175 @@
+/** Shared error protocol used by the runtime, compiler and DevTools. */
+export type VobsErrorSeverity = 'error' | 'warning' | 'info'
+export type VobsErrorLayer =
+  | 'compiler'
+  | 'runtime'
+  | 'constraint'
+  | 'permission'
+  | 'ssr'
+  | 'http'
+  | 'resource'
+
+export interface VobsErrorLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+export interface VobsErrorOptions {
+  readonly code: string
+  readonly message: string
+  readonly severity?: VobsErrorSeverity
+  readonly layer?: VobsErrorLayer
+  readonly cause?: unknown
+  readonly fix?: string
+  readonly location?: VobsErrorLocation
+  readonly trace?: readonly string[]
+  readonly example?: string
+  readonly docs?: string
+  readonly codeFrame?: string
+}
+
+export interface VobsErrorDefaults {
+  readonly code?: string
+  readonly severity?: VobsErrorSeverity
+  readonly layer?: VobsErrorLayer
+  readonly fix?: string
+}
+
+/** A framework error with stable machine-readable metadata. */
+export class VobsError extends Error {
+  readonly code: string
+  readonly severity: VobsErrorSeverity
+  readonly layer: VobsErrorLayer
+  readonly cause?: unknown
+  readonly fix?: string
+  readonly location?: VobsErrorLocation
+  readonly trace?: readonly string[]
+  readonly example?: string
+  readonly docs?: string
+  readonly codeFrame?: string
+
+  constructor(options: VobsErrorOptions) {
+    super(options.message)
+    this.name = 'VobsError'
+    this.code = options.code
+    this.severity = options.severity ?? 'error'
+    this.layer = options.layer ?? 'runtime'
+    this.cause = options.cause
+    this.fix = options.fix
+    this.location = options.location
+    this.trace = options.trace
+    this.example = options.example
+    this.docs = options.docs
+    this.codeFrame = options.codeFrame
+  }
+}
+
+export function createVobsError(options: VobsErrorOptions): VobsError {
+  return new VobsError(options)
+}
+
+export function isVobsError(value: unknown): value is VobsError {
+  return value instanceof VobsError
+    || Boolean(value && typeof value === 'object'
+      && typeof (value as { code?: unknown }).code === 'string'
+      && typeof (value as { message?: unknown }).message === 'string'
+      && typeof (value as { layer?: unknown }).layer === 'string')
+}
+
+/** Convert thrown strings and third-party errors without losing their message. */
+export function normalizeVobsError(value: unknown, defaults: VobsErrorDefaults = {}): VobsError {
+  if (value instanceof VobsError) return value
+  if (value instanceof Error) {
+    // Preserve the original Error identity so boundaries and DevTools can
+    // correlate event/effect phases without creating duplicate diagnostics.
+    const metadata = value as Error & {
+      readonly vobsCode?: unknown
+      readonly vobsHint?: unknown
+      readonly vobsSource?: unknown
+    }
+    const code = defaults.code ?? (typeof metadata.vobsCode === 'string' ? metadata.vobsCode : undefined)
+    if (code) defineErrorMetadata(value, 'code', code)
+    defineErrorMetadata(value, 'severity', defaults.severity ?? 'error')
+    defineErrorMetadata(value, 'layer', defaults.layer ?? 'runtime')
+    const fix = defaults.fix ?? (typeof metadata.vobsHint === 'string' ? metadata.vobsHint : undefined)
+    if (fix) defineErrorMetadata(value, 'fix', fix)
+    const source = metadata.vobsSource
+    if (source && typeof source === 'object'
+      && typeof (source as { file?: unknown }).file === 'string'
+      && typeof (source as { line?: unknown }).line === 'number'
+      && typeof (source as { column?: unknown }).column === 'number') {
+      defineErrorMetadata(value, 'location', source)
+    }
+    return value as VobsError
+  }
+  if (isVobsError(value)) {
+    const candidate = value as VobsErrorOptions & { severity?: VobsErrorSeverity; layer?: VobsErrorLayer }
+    return new VobsError({
+      code: candidate.code,
+      message: candidate.message,
+      severity: candidate.severity ?? defaults.severity,
+      layer: candidate.layer ?? defaults.layer,
+      cause: candidate.cause,
+      fix: candidate.fix ?? defaults.fix,
+      location: candidate.location,
+      trace: candidate.trace,
+      example: candidate.example,
+      docs: candidate.docs,
+      codeFrame: candidate.codeFrame
+    })
+  }
+  const message = String(value)
+  return new VobsError({
+    code: defaults.code ?? 'VOBS_UNKNOWN',
+    message,
+    severity: defaults.severity ?? 'error',
+    layer: defaults.layer ?? 'runtime',
+    cause: undefined,
+    fix: defaults.fix
+  })
+}
+
+function defineErrorMetadata(target: Error, key: string, value: unknown): void {
+  if (key in target) return
+  try {
+    Object.defineProperty(target, key, { configurable: true, enumerable: false, value, writable: true })
+  } catch {
+    // Frozen third-party errors still retain their original message and stack.
+  }
+}
+
+export interface FormatVobsErrorOptions {
+  readonly environment?: 'development' | 'production'
+  readonly includeStack?: boolean
+}
+
+/** Format a concise, actionable message for terminals and dev overlays. */
+export function formatVobsError(
+  value: unknown,
+  options: FormatVobsErrorOptions = {}
+): string {
+  const error = normalizeVobsError(value)
+  const code = error.code || 'VOBS_UNKNOWN'
+  const severity = error.severity || 'error'
+  if (options.environment === 'production') return `[Vobs ${code}] ${error.message}`
+
+  const lines = [`[Vobs ${capitalize(severity)}] ${error.message}`, `Code: ${code}`]
+  if (error.location) lines.push(`Location: ${error.location.file}:${error.location.line}:${error.location.column}`)
+  if (error.codeFrame) lines.push('', error.codeFrame)
+  if (error.cause !== undefined) lines.push(`Cause: ${formatCause(error.cause)}`)
+  if (error.trace?.length) lines.push('', `Trace: ${error.trace.join(' → ')}`)
+  if (error.fix) lines.push('', `Fix: ${error.fix}`)
+  if (error.example) lines.push('', `Example:\n${error.example}`)
+  if (error.docs) lines.push(`Docs: ${error.docs}`)
+  if (options.includeStack && error.stack) lines.push('', error.stack)
+  return lines.join('\n')
+}
+
+function formatCause(value: unknown): string {
+  return value instanceof Error ? `${value.name}: ${value.message}` : String(value)
+}
+
+function capitalize(value: string): string {
+  return value.slice(0, 1).toUpperCase() + value.slice(1)
+}

package/src/events.test.ts

@@ -0,0 +1,21 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createDOMRenderer, setRenderer } from '@vobs/vobs'
+import { addEventListener, createElement, removeEventListener } from './index'
+
+describe('event binding dedupe', () => {
+  it('replaces a previous binding for the same node and event', () => {
+    setRenderer(createDOMRenderer())
+    const node = createElement('button')
+    let first = 0
+    let second = 0
+    addEventListener(node, 'click', () => { first++ })
+    addEventListener(node, 'click', () => { second++ })
+    node.dispatchEvent(new MouseEvent('click'))
+    expect(first).toBe(0)
+    expect(second).toBe(1)
+    removeEventListener(node, 'click', (() => undefined) as EventListener)
+    node.dispatchEvent(new MouseEvent('click'))
+    expect(second).toBe(1)
+  })
+})

package/src/fragment.ts

@@ -0,0 +1,81 @@
+import { getCurrentOwner } from '@vobs/reactivity'
+import { createComment, getRenderer } from './ops'
+
+export interface VobsFragment {
+  readonly kind: 'vobs-fragment'
+  readonly start: Node
+  readonly end: Node
+  readonly mount: (parent: Node, anchor: Node | null) => void
+  readonly unmount: (parent: Node) => void
+}
+
+export type VobsNode = Node | VobsFragment
+export type FragmentFactory = (parent: Node, anchor: Node) => void
+
+export function createFragment(factory: FragmentFactory): VobsFragment {
+  const start = createComment('vobs:fragment:start')
+  const end = createComment('vobs:fragment:end')
+  let parent: Node | null = null
+  let initialized = false
+  const owner = getCurrentOwner()
+
+  const fragment: VobsFragment = {
+    kind: 'vobs-fragment',
+    start,
+    end,
+    mount(nextParent, anchor): void {
+      if (parent && parent !== nextParent) {
+        throw new Error('Vobs Fragment: 不能跨父节点移动 Fragment')
+      }
+
+      if (initialized) {
+        moveRange(nextParent, start, end, anchor)
+        return
+      }
+
+      const renderer = getRenderer()
+      renderer.insertBefore(nextParent, start, anchor)
+      renderer.insertBefore(nextParent, end, anchor)
+      parent = nextParent
+      initialized = true
+      if (owner) owner.run(() => factory(nextParent, end))
+      else factory(nextParent, end)
+    },
+    unmount(nextParent): void {
+      if (!initialized || parent !== nextParent) {
+        throw new Error('Vobs Fragment: Fragment 不属于指定父节点')
+      }
+      const renderer = getRenderer()
+      let current = renderer.nextSibling(start)
+      while (current && current !== end) {
+        const next = renderer.nextSibling(current)
+        renderer.removeChild(nextParent, current)
+        current = next
+      }
+      renderer.removeChild(nextParent, start)
+      renderer.removeChild(nextParent, end)
+      parent = null
+      initialized = false
+    }
+  }
+  return fragment
+}
+
+export function isVobsFragment(value: unknown): value is VobsFragment {
+  return Boolean(value) && typeof value === 'object' && (value as VobsFragment).kind === 'vobs-fragment'
+}
+
+function moveRange(parent: Node, start: Node, end: Node, anchor: Node | null): void {
+  const renderer = getRenderer()
+  const nodes: Node[] = [start]
+  let current = renderer.nextSibling(start)
+  while (current) {
+    nodes.push(current)
+    if (current === end) break
+    current = renderer.nextSibling(current)
+  }
+  if (nodes[nodes.length - 1] !== end) {
+    throw new Error('Vobs Fragment: 找不到结束锚点')
+  }
+  for (const node of nodes) renderer.insertBefore(parent, node, anchor)
+}

package/src/hmr.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createHmrStateStore,
+  disposeHmrModule,
+  resolveComponent,
+  updateHmrModule
+} from './hmr'
+import { createComponent, insertBefore, setRenderer } from './ops'
+
+describe('runtime HMR', () => {
+  it('刷新已挂载的组件节点时复用原 Owner', () => {
+    setRenderer<Node, Text, Element, Comment>({
+      createText: content => document.createTextNode(content),
+      createElement: tag => document.createElement(tag),
+      createComment: content => document.createComment(content),
+      insertBefore: (parent, child, anchor) => { parent.insertBefore(child, anchor) },
+      removeChild: (parent, child) => { parent.removeChild(child) },
+      setTextContent: (node, content) => { node.textContent = content },
+      setProperty: (node, key, value) => { (node as unknown as Record<string, unknown>)[key] = value },
+      setAttribute: (node, key, value) => { node.setAttribute(key, value) },
+      addEventListener: (node, event, handler) => { node.addEventListener(event, handler) },
+      removeEventListener: (node, event, handler) => { node.removeEventListener(event, handler) },
+      nextSibling: node => node.nextSibling,
+      clear: container => {
+        while (container.childNodes.length > 0) {
+          const child = container.childNodes[0]
+          if (child) container.removeChild(child)
+        }
+      }
+    })
+    const moduleId = `hmr-mounted-${Date.now()}-${Math.random()}`
+    const first = resolveComponent(() => document.createTextNode('first'), moduleId, 'Panel')
+    const node = createComponent(first, {})
+    const parent = document.createElement('div')
+    insertBefore(parent, node, null)
+
+    updateHmrModule(moduleId, { Panel: () => document.createTextNode('second') })
+
+    expect(parent.textContent).toBe('second')
+  })
+
+  it('更新组件代理时保留已有引用，并保留模块状态', () => {
+    const moduleId = `hmr-test-${Date.now()}-${Math.random()}`
+    const first = resolveComponent(() => ({ textContent: 'first' } as unknown as Node), moduleId, 'Panel')
+    const store = createHmrStateStore(moduleId)
+    store.set('count', 3)
+
+    updateHmrModule(moduleId, { Panel: () => ({ textContent: 'second' } as unknown as Node) })
+
+    expect(first({})).toHaveProperty('textContent', 'second')
+    expect(store.get('count', 0)).toBe(3)
+    disposeHmrModule(moduleId)
+    expect(createHmrStateStore(moduleId).get('count', 0)).toBe(3)
+  })
+})

package/src/hmr.ts

@@ -0,0 +1,123 @@
+import type { VobsNode } from './fragment'
+
+export type HmrComponent<Props extends object = Record<string, unknown>> =
+  (props: Props) => VobsNode
+
+export interface HmrStateStore {
+  get<T>(key: string, initial: T | (() => T)): T
+  set<T>(key: string, value: T): void
+  has(key: string): boolean
+  delete(key: string): void
+  clear(): void
+}
+
+export interface HmrInstance {
+  node: VobsNode
+  parent: Node | null
+  refresh(): void
+}
+
+interface HmrModuleState {
+  readonly components: Map<string, HmrComponent>
+  readonly state: Map<string, unknown>
+  readonly instances: Set<HmrInstance>
+}
+
+interface HmrGlobal {
+  modules: Map<string, HmrModuleState>
+}
+
+const globalTarget = globalThis as typeof globalThis & { __VOBS_HMR__?: HmrGlobal }
+const hmrGlobal = globalTarget.__VOBS_HMR__ ?? { modules: new Map<string, HmrModuleState>() }
+globalTarget.__VOBS_HMR__ = hmrGlobal
+
+export function resolveComponent<Props extends object>(
+  component: HmrComponent<Props>,
+  moduleId: string,
+  exportName: string
+): HmrComponent<Props> {
+  const module = getModule(moduleId)
+  const existing = module.components.get(exportName)
+  if (existing) return existing as HmrComponent<Props>
+
+  const proxy = ((props: Props) => {
+    const current = (proxy as HmrComponent<Props> & { current: HmrComponent<Props> }).current
+    return current(props)
+  }) as HmrComponent<Props> & { current: HmrComponent<Props> }
+  proxy.current = component
+  Object.defineProperties(proxy, {
+    displayName: { configurable: true, value: component.name || exportName },
+    hmrKey: { configurable: false, value: `${moduleId}:${exportName}` }
+  })
+  module.components.set(exportName, proxy as HmrComponent)
+  return proxy
+}
+
+export function updateHmrModule(_moduleId: string, nextModule: Record<string, unknown>): void {
+  const modules = [...hmrGlobal.modules.values()]
+  for (const module of modules) {
+    let changed = false
+    for (const [name, proxy] of module.components) {
+      const next = nextModule[name]
+      if (typeof next !== 'function') continue
+      const hmrProxy = proxy as HmrComponent & { current: HmrComponent; displayName?: string }
+      hmrProxy.current = next as HmrComponent
+      Object.defineProperty(hmrProxy, 'displayName', { configurable: true, value: next.name || name })
+      changed = true
+    }
+    if (!changed) continue
+    for (const instance of module.instances) {
+      try {
+        instance.refresh()
+      } catch {
+        // HMR failures remain application errors on the next normal render.
+      }
+    }
+  }
+}
+
+export function disposeHmrModule(_moduleId: string): void {
+  // State and component proxies intentionally survive module disposal.
+}
+
+export function createHmrStateStore(moduleId: string): HmrStateStore {
+  const state = getModule(moduleId).state
+  return {
+    get<T>(key: string, initial: T | (() => T)): T {
+      if (!state.has(key)) state.set(key, typeof initial === 'function' ? (initial as () => T)() : initial)
+      return state.get(key) as T
+    },
+    set<T>(key: string, value: T): void {
+      state.set(key, value)
+    },
+    has: key => state.has(key),
+    delete: key => { state.delete(key) },
+    clear: () => { state.clear() }
+  }
+}
+
+export function registerHmrInstance(moduleId: string, instance: HmrInstance): () => void {
+  const instances = getModule(moduleId).instances
+  instances.add(instance)
+  return () => instances.delete(instance)
+}
+
+export function markHmrInstanceMounted(node: VobsNode, parent: Node): void {
+  const instance = hmrInstances.get(node as object)
+  if (instance) instance.parent = parent
+}
+
+function getModule(moduleId: string): HmrModuleState {
+  let module = hmrGlobal.modules.get(moduleId)
+  if (!module) {
+    module = { components: new Map(), state: new Map(), instances: new Set() }
+    hmrGlobal.modules.set(moduleId, module)
+  }
+  return module
+}
+
+const hmrInstances = new WeakMap<object, HmrInstance>()
+
+export function associateHmrInstance(node: VobsNode, instance: HmrInstance): void {
+  hmrInstances.set(node as object, instance)
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+export type { VobsRenderer } from './renderer'
+export {
+  getRuntimeDebugContext,
+  getRuntimeDebugHooks,
+  invokeRuntimeDebug,
+  pushRuntimeDebugContext,
+  runWithRuntimeDebugContext,
+  setRuntimeDebugHooks,
+  describeDebugNode
+} from './debug'
+export type {
+  RuntimeDebugContext,
+  RuntimeDebugEnvironment,
+  RuntimeDebugHooks,
+  RuntimeDomMutation,
+  RuntimeDomMutationOperation,
+  RuntimeErrorEvent,
+  RuntimeHydrationMismatch
+} from './debug'
+export { createFragment, isVobsFragment } from './fragment'
+export type { FragmentFactory, VobsFragment, VobsNode } from './fragment'
+export {
+  setRenderer,
+  getRenderer,
+  createText,
+  createElement,
+  createComment,
+  insertBefore,
+  removeChild,
+  setTextContent,
+  setProperty,
+  setAttribute,
+  spreadProps,
+  setStaticProps,
+  addEventListener,
+  removeEventListener,
+  clear,
+  createComponent,
+  createBlock,
+  disposeNodeOwner
+} from './ops'
+export { bindText, bindAttribute, bindProperty } from './bind'
+export type { ValueSource } from './bind'
+export { ref, setRef } from './ref'
+export type { Ref, RefTarget } from './ref'
+export { insertDynamic, insertDynamicValue, insertList, normalizeDynamicChild } from './dynamic'
+export type { DynamicChild, NodeFactory } from './dynamic'
+export type { VobsLocatedError, VobsSourceLocation } from './ops'
+export {
+  VobsError,
+  createVobsError,
+  formatVobsError,
+  isVobsError,
+  normalizeVobsError
+} from './error'
+export type {
+  FormatVobsErrorOptions,
+  VobsErrorDefaults,
+  VobsErrorLayer,
+  VobsErrorLocation,
+  VobsErrorOptions,
+  VobsErrorSeverity
+} from './error'
+export {
+  createHmrStateStore,
+  disposeHmrModule,
+  markHmrInstanceMounted,
+  registerHmrInstance,
+  resolveComponent,
+  updateHmrModule
+} from './hmr'
+export type { HmrComponent, HmrInstance, HmrStateStore } from './hmr'
+export { insertErrorBoundary } from './error-boundary'
+export { ErrorBoundary } from './error-boundary'
+export type { ErrorBoundaryFallback, ErrorBoundaryOptions, ErrorBoundaryProps } from './error-boundary'
+export { insertBoundary } from './boundary'
+export type { BoundaryFallback, BoundaryOptions, BoundaryRetry } from './boundary'
+export { insertAsyncBoundary, AsyncBoundary } from './async-boundary'
+export type { AsyncBoundaryFallback, AsyncBoundaryOptions, AsyncBoundaryProps, AsyncBoundaryView } from './async-boundary'
+export { insertProfiler, Profiler } from './profiler'
+export type { ProfilerOptions, ProfilerProps, ProfilerRenderInfo } from './profiler'