@vobs/runtime 1.0.0

package/src/ops.ts

@@ -0,0 +1,377 @@
+// 编译产物调用的基础操作
+
+import { createOwner, getCurrentOwner, setOwnerDebugName, type Owner } from '@vobs/reactivity'
+import { isVobsFragment, type VobsNode } from './fragment'
+import { describeDebugNode, getRuntimeDebugHooks, invokeRuntimeDebug, readDebugValue } from './debug'
+import {
+  associateHmrInstance,
+  markHmrInstanceMounted,
+  registerHmrInstance,
+  type HmrInstance
+} from './hmr'
+import type { VobsRenderer } from './renderer'
+import { setRef } from './ref'
+
+type RuntimeRenderer = VobsRenderer<Node, Text, Element, Comment>
+
+let currentRenderer: RuntimeRenderer | null = null
+const nodeOwners = new WeakMap<object, Owner>()
+interface EventBinding {
+  readonly handler: EventListener
+  readonly owner: Owner | null
+  readonly original: EventListener
+}
+const eventBindings = new WeakMap<object, Map<string, EventBinding>>()
+
+export function setRenderer<
+  NodeType,
+  TextNode extends NodeType,
+  ElementNode extends NodeType,
+  CommentNode extends NodeType
+>(renderer: VobsRenderer<NodeType, TextNode, ElementNode, CommentNode>): void {
+  // 编译产物仍使用 DOM 节点声明；实际宿主类型由应用提供的渲染器决定。
+  currentRenderer = renderer as unknown as RuntimeRenderer
+}
+
+export function getRenderer(): RuntimeRenderer {
+  if (!currentRenderer) {
+    throw new Error('渲染器未初始化')
+  }
+  return currentRenderer
+}
+
+export function createText(content: string): Text {
+  return getRenderer().createText(content)
+}
+
+export function createElement(tag: string): Element {
+  return getRenderer().createElement(tag)
+}
+
+export function createComment(content: string): Comment {
+  return getRenderer().createComment(content)
+}
+
+export function insertBefore(
+  parent: Node,
+  child: VobsNode,
+  anchor: VobsNode | null
+): void {
+  if (isVobsFragment(child)) {
+    child.mount(parent, isVobsFragment(anchor) ? anchor.start : anchor)
+    return
+  }
+  getRenderer().insertBefore(parent, child, isVobsFragment(anchor) ? anchor.start : anchor)
+  markHmrInstanceMounted(child, parent)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'insert',
+      target: describeDebugNode(child),
+      parent: describeDebugNode(parent)
+    })
+  }
+}
+
+export function removeChild(
+  parent: Node,
+  child: VobsNode
+): void {
+  disposeNodeOwner(child)
+  if (isVobsFragment(child)) {
+    child.unmount(parent)
+    return
+  }
+  getRenderer().removeChild(parent, child)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'remove',
+      target: describeDebugNode(child),
+      parent: describeDebugNode(parent)
+    })
+  }
+}
+
+export function setTextContent(
+  node: Text,
+  content: string
+): void {
+  const previousValue = getRuntimeDebugHooks()
+    ? readDebugValue(() => node.textContent)
+    : undefined
+  getRenderer().setTextContent(node, content)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'text',
+      target: describeDebugNode(node),
+      previousValue,
+      nextValue: content
+    })
+  }
+}
+
+export function setProperty(
+  node: Element,
+  key: string,
+  value: unknown
+): void {
+  const previousValue = getRuntimeDebugHooks()
+    ? readDebugValue(() => Reflect.get(node, key))
+    : undefined
+  getRenderer().setProperty(node, key, value)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'property',
+      target: describeDebugNode(node),
+      key,
+      previousValue,
+      nextValue: value
+    })
+  }
+}
+
+export function setAttribute(
+  node: Element,
+  key: string,
+  value: string
+): void {
+  const previousValue = getRuntimeDebugHooks()
+    ? readDebugValue(() => typeof node.getAttribute === 'function' ? node.getAttribute(key) : undefined)
+    : undefined
+  getRenderer().setAttribute(node, key, value)
+  if (getRuntimeDebugHooks()) {
+    invokeRuntimeDebug('domMutation', {
+      operation: 'attribute',
+      target: describeDebugNode(node),
+      key,
+      previousValue,
+      nextValue: value
+    })
+  }
+}
+
+export function spreadProps(node: Element, props: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'key' || value === null || value === undefined) continue
+    if (key === 'ref') {
+      setRef(node, value)
+      continue
+    }
+    if (key.startsWith('on') && typeof value === 'function') addEventListener(node, key.slice(2).toLowerCase(), value as EventListener)
+    // property 键的 false 有语义（如 disabled={false} 必须清除），不能跳过；
+    // attribute 键的 false 表示“不设置”，与 HTML 语义一致。
+    else if (isPropertyKey(key)) setProperty(node, key, value)
+    else if (value === false) continue
+    else setAttribute(node, key === 'className' ? 'class' : key, key === 'style' && isStyleObject(value) ? formatStyle(value) : String(value))
+  }
+}
+
+/** Apply compile-time host properties in one renderer pass. */
+export function setStaticProps(node: Element, props: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'key' || key === 'ref' || key.startsWith('on')) continue
+    if (value === null || value === undefined) continue
+    if (isPropertyKey(key)) setProperty(node, key, value)
+    else if (value === false) continue
+    else setAttribute(node, key === 'className' ? 'class' : key, key === 'style' && isStyleObject(value) ? formatStyle(value) : String(value))
+  }
+}
+
+function isPropertyKey(key: string): boolean {
+  return key === 'value' || key === 'checked' || key === 'selected' || key === 'disabled'
+    || key === 'multiple' || key === 'readOnly' || key === 'required'
+    || key === 'autofocus' || key === 'hidden' || key === 'tabIndex'
+}
+
+function isStyleObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function formatStyle(value: Record<string, unknown>): string {
+  return Object.entries(value).filter(([, entry]) => entry !== null && entry !== undefined && entry !== false)
+    .map(([key, entry]) => `${key.replace(/[A-Z]/gu, match => `-${match.toLowerCase()}`)}:${String(entry)}`).join(';')
+}
+
+export function addEventListener(
+  node: Element,
+  event: string,
+  handler: EventListener
+): void {
+  const renderer = getRenderer()
+  const owner = getCurrentOwner()
+  let bindings = eventBindings.get(node)
+  if (!bindings) {
+    bindings = new Map()
+    eventBindings.set(node, bindings)
+  }
+  const previous = bindings.get(event)
+  if (previous && previous.original === handler && previous.owner === owner) return
+  if (previous) renderer.removeEventListener(node, event, previous.handler)
+  const listener = owner ? (reason: Event) => {
+    try {
+      owner.run(() => handler(reason))
+    } catch (error) {
+      const handled = owner.handleError(error)
+      invokeRuntimeDebug('error', {
+        error,
+        owner,
+        phase: 'event',
+        handled,
+        recovery: handled ? 'handled' : 'propagated'
+      })
+      if (!handled) throw error
+    }
+  } : handler
+  const binding: EventBinding = { handler: listener, owner, original: handler }
+  bindings.set(event, binding)
+  renderer.addEventListener(node, event, listener)
+  owner?.onDispose(() => {
+    if (bindings?.get(event) !== binding) return
+    bindings.delete(event)
+    renderer.removeEventListener(node, event, listener)
+  })
+}
+
+export function removeEventListener(
+  node: Element,
+  event: string,
+  handler: EventListener
+): void {
+  const renderer = getRenderer()
+  const binding = eventBindings.get(node)?.get(event)
+  renderer.removeEventListener(node, event, binding?.handler ?? handler)
+  eventBindings.get(node)?.delete(event)
+}
+
+export function clear(container: Node): void {
+  getRenderer().clear(container)
+}
+
+type VobsComponent = (...args: any[]) => VobsNode
+
+type ComponentProps<Component extends VobsComponent> = Component extends (
+  props: infer Props
+) => VobsNode
+  ? NonNullable<Props> extends object ? NonNullable<Props> : Record<string, never>
+  : Record<string, never>
+
+export function createComponent<Component extends VobsComponent>(
+  component: Component,
+  props: ComponentProps<Component>,
+  source?: VobsSourceLocation
+): VobsNode {
+  const owner = createOwner()
+  const componentName = (component as typeof component & { displayName?: string }).displayName
+    || component.name
+    || 'anonymous'
+  setOwnerDebugName(owner, source
+    ? `${componentName} (${source.file}:${source.line}:${source.column})`
+    : componentName)
+  owner.onError(reason => {
+    attachSourceLocation(reason, source)
+    attachComponentContext(reason, componentName, owner.id)
+    throw reason
+  })
+  let node: VobsNode
+  try {
+    node = owner.run(() => component(props))
+  } catch (error) {
+    owner.dispose()
+    attachSourceLocation(error, source)
+    attachComponentContext(error, componentName, owner.id)
+    throw error
+  }
+  associateNodeOwner(node, owner)
+  const hmrKey = (component as typeof component & { hmrKey?: string }).hmrKey
+  if (hmrKey) {
+    const instance: HmrInstance = {
+      node,
+      parent: null,
+      refresh(): void {
+        const previous = instance.node
+        const next = owner.run(() => component(props))
+        if (instance.parent && !isVobsFragment(previous) && !isVobsFragment(next)) {
+          getRenderer().insertBefore(instance.parent, next, previous)
+          getRenderer().removeChild(instance.parent, previous)
+        }
+        nodeOwners.delete(previous as object)
+        nodeOwners.set(next as object, owner)
+        associateHmrInstance(next, instance)
+        instance.node = next
+      }
+    }
+    associateHmrInstance(node, instance)
+    const separator = hmrKey.lastIndexOf(':')
+    const moduleId = separator < 0 ? hmrKey : hmrKey.slice(0, separator)
+    const cleanup = registerHmrInstance(moduleId, instance)
+    owner.onDispose(cleanup)
+  }
+  return node
+}
+
+export interface VobsSourceLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+export interface VobsLocatedError extends Error {
+  readonly vobsSource?: VobsSourceLocation
+  readonly vobsComponent?: string
+  readonly vobsOwnerId?: string
+}
+
+function attachSourceLocation(reason: unknown, source: VobsSourceLocation | undefined): void {
+  if (!source || (!reason || (typeof reason !== 'object' && typeof reason !== 'function'))) return
+  const error = reason as VobsLocatedError
+  if (error.vobsSource) return
+  try {
+    Object.defineProperty(error, 'vobsSource', {
+      configurable: true,
+      enumerable: false,
+      value: source,
+      writable: false
+    })
+  } catch {
+    // Frozen third-party errors still propagate with their original details.
+  }
+}
+
+function attachComponentContext(reason: unknown, component: string, ownerId: string): void {
+  if (!reason || (typeof reason !== 'object' && typeof reason !== 'function')) return
+  const error = reason as VobsLocatedError
+  try {
+    if (!error.vobsComponent) Object.defineProperty(error, 'vobsComponent', { configurable: true, enumerable: false, value: component, writable: false })
+    if (!error.vobsOwnerId) Object.defineProperty(error, 'vobsOwnerId', { configurable: true, enumerable: false, value: ownerId, writable: false })
+  } catch {
+    // Frozen third-party errors still propagate with their original details.
+  }
+}
+
+export function createBlock(factory: () => VobsNode | null | undefined | false): VobsNode | null {
+  const owner = createOwner()
+  setOwnerDebugName(owner, 'dynamic')
+  let node: VobsNode | null | undefined | false
+  try {
+    node = owner.run(factory)
+  } catch (error) {
+    owner.dispose()
+    throw error
+  }
+  if (!node) {
+    owner.dispose()
+    return null
+  }
+  associateNodeOwner(node, owner)
+  return node
+}
+
+export function associateNodeOwner(node: VobsNode, owner: Owner): void {
+  nodeOwners.set(node, owner)
+}
+
+export function disposeNodeOwner(node: VobsNode): void {
+  const owner = nodeOwners.get(node)
+  if (!owner) return
+  nodeOwners.delete(node)
+  owner.dispose()
+}

package/src/profiler.ts

@@ -0,0 +1,45 @@
+import { createFragment } from './fragment'
+import { insertDynamic, type NodeFactory } from './dynamic'
+import type { VobsNode } from './fragment'
+import { createOwner } from '@vobs/reactivity'
+
+export interface ProfilerRenderInfo {
+  readonly id: string
+  readonly phase: 'mount' | 'update'
+  readonly duration: number
+  readonly timestamp: number
+}
+export interface ProfilerOptions {
+  id: string
+  children: NodeFactory
+  onRender?: (info: ProfilerRenderInfo) => void
+}
+export interface ProfilerProps extends ProfilerOptions {}
+
+export function insertProfiler(parent: Node, anchor: Node | null, options: ProfilerOptions): void {
+  const profiler = createOwner()
+  let mounted = false
+  profiler.run(() => {
+    insertDynamic(parent, anchor, () => {
+      const started = now()
+      const value = options.children()
+      const info: ProfilerRenderInfo = {
+        id: options.id,
+        phase: mounted ? 'update' : 'mount',
+        duration: Math.max(0, now() - started),
+        timestamp: Date.now()
+      }
+      mounted = true
+      try { options.onRender?.(info) } catch { /* profiler callbacks are isolated */ }
+      return value
+    })
+  })
+}
+
+export function Profiler(props: ProfilerProps): VobsNode {
+  return createFragment((parent, anchor) => insertProfiler(parent, anchor, props))
+}
+
+function now(): number {
+  return typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance.now() : Date.now()
+}

package/src/props.test.ts

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createDOMRenderer, setRenderer } from '@vobs/vobs'
+import { setStaticProps, spreadProps } from './index'
+
+setRenderer(createDOMRenderer())
+
+describe('static and spread prop application', () => {
+  it('spreadProps applies false for property keys to clear them', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    node.disabled = true
+    spreadProps(node, { disabled: false })
+    expect(node.disabled).toBe(false)
+
+    node.readOnly = true
+    spreadProps(node, { readOnly: false })
+    expect(node.readOnly).toBe(false)
+  })
+
+  it('spreadProps applies true for property keys', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    spreadProps(node, { disabled: true })
+    expect(node.disabled).toBe(true)
+  })
+
+  it('spreadProps skips false for attribute keys', () => {
+    const node = document.createElement('div') as HTMLDivElement
+    spreadProps(node, { title: false, class: false, draggable: false })
+    expect(node.hasAttribute('title')).toBe(false)
+    expect(node.hasAttribute('class')).toBe(false)
+  })
+
+  it('spreadProps skips null and undefined for both key kinds', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    node.disabled = true
+    spreadProps(node, { disabled: null, title: undefined })
+    // null/undefined 表示“不提供值”，保持现状语义
+    expect(node.disabled).toBe(true)
+    expect(node.hasAttribute('title')).toBe(false)
+  })
+
+  it('setStaticProps applies false for property keys', () => {
+    const node = document.createElement('input') as HTMLInputElement
+    setStaticProps(node, { disabled: false, checked: false } as Record<string, unknown>)
+    expect(node.disabled).toBe(false)
+    expect(node.checked).toBe(false)
+  })
+
+  it('setStaticProps skips false for attribute keys', () => {
+    const node = document.createElement('div') as HTMLDivElement
+    setStaticProps(node, { title: false } as Record<string, unknown>)
+    expect(node.hasAttribute('title')).toBe(false)
+  })
+})

package/src/ref.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { createDOMRenderer, createVobs } from '@vobs/vobs'
+import { createElement, createText, insertBefore, ref, setRef } from './index'
+
+describe('ref', () => {
+  it('assigns host nodes and clears them when the app is destroyed', () => {
+    const target = document.createElement('div')
+    const nodeRef = ref<Element>()
+    const app = createVobs({
+      renderer: createDOMRenderer(),
+      render: () => {
+        const node = createElement('input')
+        setRef(node, nodeRef)
+        insertBefore(target, node, null)
+        return createText('')
+      }
+    })
+    app.mount(target)
+    expect(nodeRef.current).toBeInstanceOf(HTMLInputElement)
+    app.destroy()
+    expect(nodeRef.current).toBeNull()
+  })
+})

package/src/ref.ts

@@ -0,0 +1,50 @@
+import { getCurrentOwner } from '@vobs/reactivity'
+
+/** A mutable reference populated when a host node is mounted. */
+export interface Ref<T extends object = Node> {
+  current: T | null
+}
+
+export type RefTarget<T extends object = Node> = Ref<T> | ((value: T | null) => void)
+
+export function ref<T extends object = Node>(initialValue: T | null = null): Ref<T> {
+  return { current: initialValue }
+}
+
+/** Bind a host node to an object or callback ref and clear it with its Owner. */
+export function setRef<T extends object>(node: T, target: unknown): void {
+  if (!isRefTarget<T>(target)) return
+  // SSR's serializable nodes are never exposed as live refs. Custom renderers
+  // may use arbitrary host objects, so only exclude the known SSR shape.
+  if (isSSRNode(node)) return
+  const owner = getCurrentOwner()
+  assignRef(target, node)
+  owner?.onDispose(() => {
+    // Do not clear a ref that has since been reassigned to another node.
+    if (isObjectRef(target) && target.current !== node) return
+    assignRef(target, null)
+  })
+}
+
+function isSSRNode(value: object): boolean {
+  const type = (value as { type?: unknown }).type
+  return (type === 'element' || type === 'text' || type === 'comment')
+    && !('nodeType' in value)
+}
+
+function isObjectRef<T extends object>(value: unknown): value is Ref<T> {
+  return Boolean(value && typeof value === 'object' && 'current' in value)
+}
+
+function isRefTarget<T extends object>(value: unknown): value is RefTarget<T> {
+  return isObjectRef<T>(value) || typeof value === 'function'
+}
+
+function assignRef<T extends object>(target: RefTarget<T>, value: T | null): void {
+  try {
+    if (typeof target === 'function') target(value)
+    else target.current = value
+  } catch {
+    // Ref callbacks are user code; never make mounting fail because of them.
+  }
+}

package/src/renderer.ts

@@ -0,0 +1,21 @@
+export interface VobsRenderer<
+  NodeType = Node,
+  TextNode extends NodeType = NodeType,
+  ElementNode extends NodeType = NodeType,
+  CommentNode extends NodeType = NodeType
+> {
+  createText(content: string): TextNode
+  createElement(tag: string): ElementNode
+  createComment(content: string): CommentNode
+  insertBefore(parent: NodeType, child: NodeType, anchor: NodeType | null): void
+  removeChild(parent: NodeType, child: NodeType): void
+  setTextContent(node: TextNode, content: string): void
+  setProperty(node: ElementNode, key: string, value: unknown): void
+  setAttribute(node: ElementNode, key: string, value: string): void
+  addEventListener(node: ElementNode, event: string, handler: EventListener): void
+  removeEventListener(node: ElementNode, event: string, handler: EventListener): void
+  nextSibling(node: NodeType): NodeType | null
+  clear(container: NodeType): void
+  beginHydration?(): void
+  completeHydration?(): void
+}