@vobs/transition 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,50 @@
+# @vobs/transition
+
+Enter/leave transitions for vobs nodes: a CSS class lifecycle with optional inline from/to styles, cancellation when state flips mid-animation, `prefers-reduced-motion` support, and keyed list transitions.
+
+## Install
+
+```bash
+npm install @vobs/transition
+```
+
+## Quick start
+
+```ts
+import { state } from '@vobs/reactivity'
+import { createComponent, createDOMRenderer, createVobs, setRenderer } from '@vobs/vobs'
+import { Transition } from '@vobs/transition'
+
+setRenderer(createDOMRenderer())
+
+const show = state(true)
+
+const app = createVobs({
+  render: () => createComponent(Transition, {
+    get show() { return show.value },
+    name: 'fade',
+    duration: 120,
+    appear: true,
+    onAfterLeave: () => console.log('gone'),
+    children: 'Content'
+  })
+})
+
+app.mount(document.getElementById('app')!)
+```
+
+`name: 'fade'` drives `fade-enter-from`/`-active`/`-to` and `fade-leave-*` classes. During leave the node stays mounted until the animation ends, so owners and disposals survive until then; toggling `show` back before the leave finishes cancels it (`onLeaveCancelled`) and keeps the same node. When `prefers-reduced-motion` matches, enter and leave complete immediately.
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `Transition(props: TransitionProps)` | Wraps a single child. Omit `show` to render and enter once; `appear` animates the initial visible branch. `enter`/`leave` phases accept `{ duration, easing, from, to }` inline styles, restored after `transitionend` (or the shared `duration`). Callbacks: `onBeforeEnter`, `onEnter`, `onAfterEnter`, `onEnterCancelled`, and the matching leave hooks. `reducedMotion` respects the media query by default in DOM environments. |
+| `TransitionGroup<Item>(props: TransitionGroupProps<Item>)` | Keyed list transitions via `items` + `keyOf` + `renderItem`. Leaving items are removed only after their leave completes; `renderItem` receives a refreshed index after reorders; duplicate keys throw before the DOM is committed. A stable `children` array is also supported. |
+| `createCSSTransitionDriver()` / `cssTransitionDriver` | The built-in CSS driver. Pass a custom `TransitionDriver` — `run(node, phase, options, done)` returning a `TransitionRun` with `cancel()` — through the `driver` option for JS-driven animation. |
+
+SSR renders the current visible branch without touching the DOM and without emitting transition classes.
+
+## Types
+
+TransitionStyle, TransitionPhase, TransitionPhaseName, TransitionRun, TransitionDriver, TransitionDriverOptions, TransitionCallbacks, TransitionOptions, TransitionChildren, TransitionProps, TransitionGroupProps, TransitionStatus

package/package.json

@@ -0,0 +1,29 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/transition",
+  "version": "1.0.0",
+  "description": "Optional DOM transition lifecycle primitives for Vobs.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0",
+    "@vobs/runtime": "1.0.0",
+    "@vobs/vobs": "1.0.0"
+  },
+  "devDependencies": {
+    "@vobs/ssr": "1.0.0",
+    "@vobs/dom": "1.0.0"
+  },
+  "scripts": {
+    "test": "vitest --environment jsdom"
+  }
+}

package/src/driver.ts

@@ -0,0 +1,204 @@
+import { getRenderer, isVobsFragment, type VobsNode } from '@vobs/vobs'
+import type {
+  TransitionDriver,
+  TransitionDriverOptions,
+  TransitionOptions,
+  TransitionPhase,
+  TransitionRun,
+  TransitionStatus,
+  TransitionStyle
+} from './types'
+
+export function runTransition(
+  node: VobsNode,
+  status: Extract<TransitionStatus, 'entering' | 'leaving'>,
+  options: TransitionDriverOptions,
+  done: () => void
+): TransitionRun {
+  const elements = getTransitionElements(node)
+  if (elements.length === 0 || options.reducedMotion || !options.css && !hasStyles(options.phase)) {
+    done()
+    return { cancel() {} }
+  }
+
+  const phase = options.phase
+  const classes = options.css ? phaseClasses(options.name, status) : []
+  const restores = elements.map(element => applyInitialState(element, phase, classes, options.duration))
+  let finished = false
+  let frame: number | undefined
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  const ended = new Set<Element>()
+
+  const finish = (): void => {
+    if (finished) return
+    finished = true
+    if (frame !== undefined) cancelFrame(frame)
+    if (timeout !== undefined) clearTimeout(timeout)
+    for (const element of elements) {
+      element.removeEventListener('transitionend', onEnd)
+      element.removeEventListener('animationend', onEnd)
+    }
+    for (const restore of restores) restore()
+    done()
+  }
+
+  const onEnd = (event: Event): void => {
+    const target = event.target
+    if (!(target instanceof Element) || !elements.includes(target)) return
+    ended.add(target)
+    if (ended.size === elements.length) finish()
+  }
+
+  frame = scheduleFrame(() => {
+    if (finished) return
+    for (const element of elements) applyTargetState(element, phase, classes)
+    if (options.duration <= 0) {
+      finish()
+      return
+    }
+    for (const element of elements) {
+      element.addEventListener('transitionend', onEnd)
+      element.addEventListener('animationend', onEnd)
+    }
+    timeout = setTimeout(finish, options.duration + 50)
+  })
+
+  return {
+    cancel(): void {
+      if (finished) return
+      finished = true
+      if (frame !== undefined) cancelFrame(frame)
+      if (timeout !== undefined) clearTimeout(timeout)
+      for (const element of elements) {
+        element.removeEventListener('transitionend', onEnd)
+        element.removeEventListener('animationend', onEnd)
+      }
+      for (const restore of restores) restore()
+    }
+  }
+}
+
+export const cssTransitionDriver: TransitionDriver = {
+  run(node, phase, options, done) {
+    return runTransition(node, phase === 'enter' ? 'entering' : 'leaving', options, done)
+  }
+}
+
+export function createCSSTransitionDriver(): TransitionDriver {
+  return cssTransitionDriver
+}
+
+export function asTransitionElement(node: unknown): Element | null {
+  if (!node || typeof node !== 'object') return null
+  const candidate = node as Partial<Element>
+  return candidate.classList && typeof candidate.addEventListener === 'function' ? candidate as Element : null
+}
+
+export function resolveReducedMotion(options: TransitionOptions): boolean {
+  if (options.reducedMotion === true) return true
+  if (options.reducedMotion === false || typeof window === 'undefined' || !window.matchMedia) return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+function getTransitionElements(node: VobsNode): Element[] {
+  const element = asTransitionElement(node)
+  if (element) return [element]
+  if (!isVobsFragment(node)) return []
+
+  const elements: Element[] = []
+  const renderer = getRenderer()
+  let current = renderer.nextSibling(node.start)
+  while (current && current !== node.end) {
+    const child = asTransitionElement(current)
+    if (child) elements.push(child)
+    current = renderer.nextSibling(current)
+  }
+  return elements
+}
+
+function hasStyles(phase: TransitionPhase | undefined): boolean {
+  return Boolean(phase?.from || phase?.to)
+}
+
+function phaseClasses(prefix: string, status: TransitionStatus): readonly string[] {
+  const phase = status === 'entering' ? 'enter' : 'leave'
+  return [`${prefix}-${phase}-from`, `${prefix}-${phase}-active`, `${prefix}-${phase}-to`]
+}
+
+function applyInitialState(
+  element: Element,
+  phase: TransitionPhase | undefined,
+  classes: readonly string[],
+  duration: number
+): () => void {
+  const [from, active] = classes
+  if (from) element.classList.add(from)
+  if (active) element.classList.add(active)
+  const restoreStyles = applyInlineStyles(element, phase, duration)
+  return () => {
+    for (const className of classes) element.classList.remove(className)
+    restoreStyles()
+  }
+}
+
+function applyTargetState(element: Element, phase: TransitionPhase | undefined, classes: readonly string[]): void {
+  const [from, _active, to] = classes
+  if (from) element.classList.remove(from)
+  if (to) element.classList.add(to)
+  applyStyles(element, phase?.to)
+}
+
+function applyInlineStyles(element: Element, phase: TransitionPhase | undefined, duration: number): () => void {
+  const style = supportsInlineStyle(element) ? element.style : undefined
+  if (!style) return () => {}
+  const previous = new Map<string, string>()
+  const remember = (styles: TransitionStyle | undefined): void => {
+    for (const name of Object.keys(styles ?? {})) {
+      const property = stylePropertyName(name)
+      if (!previous.has(property)) previous.set(property, style.getPropertyValue(property))
+    }
+  }
+  remember(phase?.from)
+  remember(phase?.to)
+  if (hasStyles(phase) && duration > 0) {
+    previous.set('transition-property', style.getPropertyValue('transition-property'))
+    previous.set('transition-duration', style.getPropertyValue('transition-duration'))
+    previous.set('transition-timing-function', style.getPropertyValue('transition-timing-function'))
+    style.setProperty('transition-property', 'all')
+    style.setProperty('transition-duration', `${Math.max(0, duration)}ms`)
+    if (phase?.easing) style.setProperty('transition-timing-function', phase.easing)
+  }
+  applyStyles(element, phase?.from)
+  return () => {
+    for (const [name, value] of previous) style.setProperty(name, value)
+  }
+}
+
+function applyStyles(element: Element, styles: TransitionStyle | undefined): void {
+  if (!styles) return
+  const style = supportsInlineStyle(element) ? element.style : undefined
+  if (!style) return
+  for (const [name, value] of Object.entries(styles)) {
+    const property = stylePropertyName(name)
+    if (value === null || value === undefined) style.removeProperty(property)
+    else style.setProperty(property, String(value))
+  }
+}
+
+function stylePropertyName(name: string): string {
+  return name.startsWith('--') ? name : name.replace(/[A-Z]/gu, letter => `-${letter.toLowerCase()}`)
+}
+
+function supportsInlineStyle(element: Element): element is Element & { style: CSSStyleDeclaration } {
+  return 'style' in element && Boolean((element as Partial<Element & { style: CSSStyleDeclaration }>).style)
+}
+
+function scheduleFrame(callback: () => void): number {
+  if (typeof requestAnimationFrame === 'function') return requestAnimationFrame(callback)
+  return setTimeout(callback, 16) as unknown as number
+}
+
+function cancelFrame(handle: number): void {
+  if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(handle)
+  else clearTimeout(handle as unknown as ReturnType<typeof setTimeout>)
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { Transition, TransitionGroup } from './transition'
+export { createCSSTransitionDriver, cssTransitionDriver } from './driver'
+export type {
+  TransitionCallbacks,
+  TransitionChildren,
+  TransitionDriver,
+  TransitionDriverOptions,
+  TransitionGroupProps,
+  TransitionOptions,
+  TransitionPhase,
+  TransitionPhaseName,
+  TransitionProps,
+  TransitionRun,
+  TransitionStatus,
+  TransitionStyle
+} from './types'

package/src/transition.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { onDispose, state } from '@vobs/reactivity'
+import { createComponent, createElement, createText, createVobs, insertBefore, setRenderer } from '@vobs/vobs'
+import { createDOMRenderer } from '@vobs/dom'
+import { renderToString } from '@vobs/ssr'
+import { Transition, TransitionGroup } from './transition'
+import type { TransitionGroupProps } from './types'
+
+describe('@vobs/transition', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => setTimeout(() => callback(0), 16) as unknown as number)
+    vi.stubGlobal('cancelAnimationFrame', (handle: number) => clearTimeout(handle as unknown as ReturnType<typeof setTimeout>))
+    setRenderer(createDOMRenderer())
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('在节点插入后执行 enter class 生命周期并清理 class', () => {
+    const stages: string[] = []
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(Transition, {
+        name: 'fade',
+        duration: 0,
+        appear: true,
+        onBeforeEnter: () => stages.push('before-enter'),
+        onEnter: () => stages.push('enter'),
+        onAfterEnter: () => stages.push('after-enter'),
+        children: () => textNode('visible')
+      })
+    })
+    app.mount(container)
+
+    const node = container.querySelector('span')!
+    expect(node.classList.contains('fade-enter-from')).toBe(true)
+    expect(node.classList.contains('fade-enter-active')).toBe(true)
+    expect(stages).toEqual(['before-enter', 'enter'])
+
+    vi.advanceTimersByTime(16)
+    expect(node.className).toBe('')
+    expect(stages).toEqual(['before-enter', 'enter', 'after-enter'])
+    app.destroy()
+  })
+
+  it('使用 from/to 样式，并在 transitionend 后恢复原始 inline style', () => {
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(Transition, {
+        appear: true,
+        name: 'slide',
+        enter: {
+          duration: 120,
+          easing: 'ease-out',
+          from: { opacity: 0, transform: 'translateY(-4px)' },
+          to: { opacity: 1, transform: 'translateY(0)' }
+        },
+        children: () => textNode('visible')
+      })
+    })
+    app.mount(container)
+
+    const node = container.querySelector('span')!
+    expect(node.classList.contains('slide-enter-from')).toBe(true)
+    expect(node.style.opacity).toBe('0')
+    expect(node.style.transform).toBe('translateY(-4px)')
+
+    vi.advanceTimersByTime(16)
+    expect(node.classList.contains('slide-enter-to')).toBe(true)
+    expect(node.style.opacity).toBe('1')
+    expect(node.style.transitionDuration).toBe('120ms')
+    node.dispatchEvent(new Event('transitionend'))
+
+    expect(node.className).toBe('')
+    expect(node.style.opacity).toBe('')
+    expect(node.style.transform).toBe('')
+    expect(node.style.transitionDuration).toBe('')
+    app.destroy()
+  })
+
+  it('leave 完成前保留节点与 Owner，完成后才移除', () => {
+    const shown = state(true)
+    const stages: string[] = []
+    const disposals: string[] = []
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(Transition, {
+        get show() { return shown.value },
+        name: 'fade',
+        duration: 120,
+        onBeforeLeave: () => stages.push('before-leave'),
+        onAfterLeave: () => stages.push('after-leave'),
+        children: () => createComponent(DisposableContent, { onDispose: () => disposals.push('disposed') })
+      })
+    })
+    app.mount(container)
+    vi.advanceTimersByTime(16)
+
+    shown.value = false
+    app.update()
+    const node = container.querySelector('span')!
+    expect(node.classList.contains('fade-leave-from')).toBe(true)
+    expect(container.querySelector('span')).toBe(node)
+    expect(disposals).toEqual([])
+
+    vi.advanceTimersByTime(16)
+    expect(node.classList.contains('fade-leave-to')).toBe(true)
+    node.dispatchEvent(new Event('transitionend'))
+
+    expect(container.querySelector('span')).toBeNull()
+    expect(stages).toEqual(['before-leave', 'after-leave'])
+    expect(disposals).toEqual(['disposed'])
+    app.destroy()
+  })
+
+  it('遵循 prefers-reduced-motion 并立即完成 enter 和 leave', () => {
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue({ matches: true }))
+    const shown = state(true)
+    const stages: string[] = []
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(Transition, {
+        get show() { return shown.value },
+        appear: true,
+        name: 'fade',
+        duration: 120,
+        onAfterEnter: () => stages.push('after-enter'),
+        onAfterLeave: () => stages.push('after-leave'),
+        children: () => textNode('visible')
+      })
+    })
+    app.mount(container)
+
+    const node = container.querySelector('span')!
+    expect(node.className).toBe('')
+    expect(stages).toEqual(['after-enter'])
+
+    shown.value = false
+    app.update()
+    expect(container.querySelector('span')).toBeNull()
+    expect(stages).toEqual(['after-enter', 'after-leave'])
+    app.destroy()
+  })
+
+  it('show 在 leave 期间恢复时取消离开并保持同一节点', () => {
+    const shown = state(true)
+    const events: string[] = []
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(Transition, {
+        get show() { return shown.value },
+        name: 'fade',
+        duration: 120,
+        onLeaveCancelled: () => events.push('leave-cancelled'),
+        children: () => textNode('visible')
+      })
+    })
+    app.mount(container)
+    vi.advanceTimersByTime(16)
+    const node = container.querySelector('span')!
+
+    shown.value = false
+    app.update()
+    shown.value = true
+    app.update()
+
+    expect(container.querySelector('span')).toBe(node)
+    expect(events).toEqual(['leave-cancelled'])
+    expect(node.classList.contains('fade-leave-from')).toBe(false)
+    vi.advanceTimersByTime(16)
+    app.destroy()
+  })
+
+  it('TransitionGroup 以 key 追踪条目并在 leave 后删除', () => {
+    const people = state([
+      { id: 'ada', name: 'Ada' },
+      { id: 'lin', name: 'Lin' }
+    ])
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => {
+        const list = createElement('ul')
+        insertBefore(list, createComponent(People, {
+          get items() { return people.value },
+          keyOf: person => person.id,
+          renderItem: person => textNode(person.name),
+          duration: 0
+        }), null)
+        return list
+      }
+    })
+    app.mount(container)
+    vi.advanceTimersByTime(16)
+    expect(container.querySelectorAll('span')).toHaveLength(2)
+
+    people.value = [{ id: 'lin', name: 'Lin' }]
+    app.update()
+    expect(container.querySelectorAll('span')).toHaveLength(2)
+    vi.advanceTimersByTime(16)
+    expect([...container.querySelectorAll('span')].map(node => node.textContent)).toEqual(['Lin'])
+    app.destroy()
+  })
+
+  it('重复 key 在列表提交前报错并保留上一轮 DOM', () => {
+    const people = state([
+      { id: 'ada', name: 'Ada' },
+      { id: 'lin', name: 'Lin' }
+    ])
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(People, {
+        get items() { return people.value },
+        keyOf: person => person.id,
+        renderItem: person => textNode(person.name),
+        duration: 0
+      })
+    })
+    app.mount(container)
+
+    people.value = [
+      { id: 'ada', name: 'Ada 2' },
+      { id: 'ada', name: 'Ada 3' }
+    ]
+    expect(() => app.update()).toThrow('重复 key')
+    expect([...container.querySelectorAll('span')].map(node => node.textContent)).toEqual(['Ada', 'Lin'])
+    app.destroy()
+  })
+
+  it('renderItem 使用 index 时在重排后刷新索引', () => {
+    const people = state([
+      { id: 'ada', name: 'Ada' },
+      { id: 'lin', name: 'Lin' }
+    ])
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(People, {
+        get items() { return people.value },
+        keyOf: person => person.id,
+        renderItem: (person, index) => textNode(`${person.name}:${index}`),
+        duration: 0
+      })
+    })
+    app.mount(container)
+
+    people.value = [...people.value].reverse()
+    app.update()
+    expect([...container.querySelectorAll('span')].map(node => node.textContent)).toEqual(['Lin:0', 'Ada:1'])
+    app.destroy()
+  })
+
+  it('SSR 不访问 DOM，并直接输出当前可见分支', () => {
+    const visible = renderToString(() => createComponent(Transition, {
+      show: true,
+      name: 'fade',
+      children: () => textNode('server content')
+    }))
+    const hidden = renderToString(() => createComponent(Transition, {
+      show: false,
+      children: () => textNode('hidden content')
+    }))
+
+    expect(visible).toContain('server content')
+    expect(visible).not.toContain('fade-enter')
+    expect(hidden).not.toContain('hidden content')
+  })
+
+  it('children 数组入口可以保持稳定节点并执行 leave', () => {
+    const first = textNode('first')
+    const second = textNode('second')
+    const children = state<readonly Element[]>([first, second])
+    const container = document.createElement('main')
+    const app = createVobs({
+      render: () => createComponent(TransitionGroup, {
+        get children() { return children.value },
+        duration: 0
+      })
+    })
+    app.mount(container)
+    expect(container.querySelectorAll('span')).toHaveLength(2)
+
+    children.value = [second]
+    app.update()
+    expect(container.querySelectorAll('span')).toHaveLength(2)
+    vi.advanceTimersByTime(16)
+    expect([...container.querySelectorAll('span')].map(node => node.textContent)).toEqual(['second'])
+    app.destroy()
+  })
+})
+
+function textNode(value: string): Element {
+  const node = createElement('span')
+  insertBefore(node, createText(value), null)
+  return node
+}
+
+function DisposableContent(props: { readonly onDispose: () => void }): Element {
+  onDispose(props.onDispose)
+  return textNode('visible')
+}
+
+function People(props: TransitionGroupProps<{ id: string, name: string }>) {
+  return TransitionGroup(props)
+}

package/src/transition.ts

@@ -0,0 +1,356 @@
+import { createOwner, effect, onDispose, state, type Owner, type Signal } from '@vobs/reactivity'
+import {
+  createFragment,
+  createText,
+  insertBefore,
+  removeChild,
+  type VobsFragment,
+  type VobsNode
+} from '@vobs/vobs'
+import { createBlock } from '@vobs/runtime'
+import { asTransitionElement, cssTransitionDriver, resolveReducedMotion } from './driver'
+import type {
+  TransitionChildren,
+  TransitionDriver,
+  TransitionGroupProps,
+  TransitionOptions,
+  TransitionProps,
+  TransitionStatus
+} from './types'
+
+interface TransitionEntry {
+  node: VobsNode
+  status: TransitionStatus
+  run?: { readonly cancel: () => void }
+}
+
+interface GroupEntry extends TransitionEntry {
+  readonly key: unknown
+  readonly owner: Owner
+  readonly item: Signal<unknown>
+  rawItem: unknown
+  index: number
+}
+
+/**
+ * Delays branch disposal until the leave lifecycle has completed. It accepts
+ * Any rendered root is accepted; the default CSS driver animates element roots
+ * inside a Vobs fragment and leaves non-DOM renderers to complete immediately.
+ */
+export function Transition(props: TransitionProps = {}): VobsFragment {
+  return createFragment((parent, anchor) => {
+    let current: TransitionEntry | undefined
+    let disposed = false
+    let initialized = false
+
+    const stop = effect(() => {
+      const visible = readProp<boolean>(props, 'show', true) !== false
+      const initial = !initialized
+      initialized = true
+      if (visible) {
+        if (current) {
+          if (current.status === 'leaving') startEnter(current, props, true)
+          return
+        }
+
+        const node = createBlock(() => resolveChildren(readProp(props, 'children', undefined)))
+        if (!node) return
+        current = { node, status: 'entering' }
+        insertBefore(parent, node, anchor)
+        startEnter(current, props, !initial || readProp<boolean>(props, 'appear', false))
+        return
+      }
+
+      if (current && current.status !== 'leaving') {
+        const leaving = current
+        startLeave(current, props, () => {
+          if (current?.node !== leaving.node) return
+          current = undefined
+        })
+      }
+    })
+
+    // Keep an owner-scoped cleanup so an outer branch/app removal never leaves
+    // an animation timer or DOM event listener behind.
+    onDispose(() => {
+      disposed = true
+      stop.dispose()
+      current?.run?.cancel()
+    })
+
+    function startLeave(entry: TransitionEntry, options: TransitionOptions, afterLeave: () => void): void {
+      startLeaveEntry(entry, options, () => {
+        if (disposed || current?.node !== entry.node) return
+        removeChild(parent, entry.node)
+        afterLeave()
+      })
+    }
+  })
+}
+
+/**
+ * Transition a keyed collection. `items`, `keyOf` and `renderItem` are
+ * explicit so lifecycle ownership remains stable without compiler-only magic.
+ */
+export function TransitionGroup<Item>(props: TransitionGroupProps<Item>): VobsFragment {
+  return createFragment((parent, anchor) => {
+    const entries = new Map<unknown, GroupEntry>()
+    let disposed = false
+    let initialized = false
+    const stop = effect(() => {
+      const nextEntries: GroupEntry[] = []
+      const initial = !initialized
+      initialized = true
+      const descriptors = readGroupDescriptors(props)
+      validateGroupDescriptors(descriptors)
+      const nextKeys = new Set(descriptors.map(descriptor => descriptor.key))
+
+      for (let index = 0; index < descriptors.length; index++) {
+        const descriptor = descriptors[index]
+        const { item, key } = descriptor
+
+        let entry = entries.get(key)
+        if (entry) {
+          const changed = !Object.is(entry.rawItem, item)
+          const tracksIndex = descriptor.render.length >= 2
+          if (changed || tracksIndex && entry.index !== index) refreshGroupEntry(parent, entry, descriptor)
+          entry.index = index
+          if (entry.status === 'leaving') startEnter(entry, props, true)
+        } else {
+          entry = createGroupEntry(descriptor)
+          entries.set(key, entry)
+          insertBefore(parent, entry.node, anchor)
+          startEnter(entry, props, !initial || readProp<boolean>(props, 'appear', false))
+        }
+        nextEntries.push(entry)
+      }
+
+      for (const [key, entry] of [...entries]) {
+        if (nextKeys.has(key)) continue
+        if (entry.status !== 'leaving') {
+          startLeaveEntry(entry, props, () => {
+            if (disposed || entries.get(key) !== entry) return
+            removeChild(parent, entry.node)
+            entry.owner.dispose()
+            entries.delete(key)
+          })
+        }
+      }
+
+      let reference: VobsNode | null = anchor
+      for (let index = nextEntries.length - 1; index >= 0; index--) {
+        insertBefore(parent, nextEntries[index].node, reference)
+        reference = nextEntries[index].node
+      }
+    })
+
+    onDispose(() => {
+      disposed = true
+      stop.dispose()
+      for (const entry of entries.values()) entry.run?.cancel()
+      entries.clear()
+    })
+  })
+}
+
+function validateGroupDescriptors(descriptors: readonly GroupDescriptor[]): void {
+  const seen = new Set<unknown>()
+  for (const descriptor of descriptors) {
+    if (seen.has(descriptor.key)) throw new Error(`TransitionGroup: 检测到重复 key: ${String(descriptor.key)}`)
+    seen.add(descriptor.key)
+  }
+}
+
+function createGroupEntry(descriptor: GroupDescriptor): GroupEntry {
+  const owner = createOwner()
+  let itemSignal!: Signal<unknown>
+  let node!: VobsNode
+  try {
+    owner.run(() => {
+      itemSignal = state(descriptor.item)
+      node = renderGroupNode(itemSignal, descriptor, owner)
+    })
+  } catch (error) {
+    owner.dispose()
+    throw error
+  }
+  if (!node) {
+    owner.dispose()
+    throw new Error('TransitionGroup: renderItem 必须返回节点')
+  }
+  return {
+    key: descriptor.key,
+    node,
+    owner,
+    item: itemSignal,
+    rawItem: descriptor.item,
+    index: descriptor.index,
+    status: 'entering'
+  }
+}
+
+function refreshGroupEntry(parent: Node, entry: GroupEntry, descriptor: GroupDescriptor): void {
+  entry.run?.cancel()
+  entry.run = undefined
+  entry.item.value = descriptor.item
+  const previousNode = entry.node
+  const nextNode = renderGroupNode(entry.item, descriptor, entry.owner)
+  entry.node = nextNode
+  entry.rawItem = descriptor.item
+  entry.index = descriptor.index
+  removeChild(parent, previousNode)
+}
+
+function renderGroupNode(signal: Signal<unknown>, descriptor: GroupDescriptor, owner: Owner): VobsNode {
+  const node = owner.run(() => createBlock(() => resolveChildren(descriptor.render(toReactiveItem(signal, descriptor.item), descriptor.index))))
+  if (!node) throw new Error('TransitionGroup: renderItem 必须返回节点')
+  return node
+}
+
+interface GroupDescriptor {
+  readonly key: unknown
+  readonly item: unknown
+  readonly index: number
+  readonly render: (item: unknown, index: number) => TransitionChildren
+}
+
+function readGroupDescriptors<Item>(props: TransitionGroupProps<Item>): GroupDescriptor[] {
+  const items = readProp<readonly Item[] | undefined>(props, 'items', undefined)
+  if (items !== undefined) {
+    const keyOf = readProp<TransitionGroupProps<Item>['keyOf']>(props, 'keyOf', undefined)
+    const renderItem = readProp<TransitionGroupProps<Item>['renderItem']>(props, 'renderItem', undefined)
+    if (typeof keyOf !== 'function' || typeof renderItem !== 'function') {
+      throw new Error('TransitionGroup: 提供 items 时必须同时提供 keyOf 和 renderItem')
+    }
+    return items.map((item, index) => ({
+      key: keyOf(item, index),
+      item,
+      index,
+      render: renderItem as (value: unknown, position: number) => TransitionChildren
+    }))
+  }
+
+  const children: unknown[] = []
+  flattenChildren(readProp(props, 'children', undefined), children)
+  return children.map((child, index) => ({
+    key: typeof child === 'object' && child !== null ? child : index,
+    item: child,
+    index,
+    render: value => value as TransitionChildren
+  }))
+}
+
+function flattenChildren(value: unknown, result: unknown[]): void {
+  const resolved = typeof value === 'function' ? value() : value
+  if (resolved === null || resolved === undefined || resolved === false) return
+  if (Array.isArray(resolved)) {
+    for (const child of resolved) flattenChildren(child, result)
+    return
+  }
+  result.push(resolved)
+}
+
+function startEnter(entry: TransitionEntry, options: TransitionOptions, animate: boolean): void {
+  const element = asTransitionElement(entry.node)
+  if (entry.status === 'leaving') {
+    entry.run?.cancel()
+    invoke(options.onLeaveCancelled, element)
+  }
+  entry.status = 'entering'
+  if (!animate) {
+    entry.status = 'entered'
+    return
+  }
+  invoke(options.onBeforeEnter, element)
+  invoke(options.onEnter, element)
+  const run = runWithDriver(entry.node, 'enter', options, () => {
+    if (entry.status !== 'entering') return
+    entry.run = undefined
+    entry.status = 'entered'
+    invoke(options.onAfterEnter, element)
+  })
+  if (entry.status === 'entering') entry.run = run
+}
+
+function startLeaveEntry(entry: TransitionEntry, options: TransitionOptions, done: () => void): void {
+  if (entry.status === 'leaving') return
+  if (entry.status === 'entering') {
+    entry.run?.cancel()
+    invoke(options.onEnterCancelled, asTransitionElement(entry.node))
+  } else {
+    entry.run?.cancel()
+  }
+  entry.status = 'leaving'
+  const element = asTransitionElement(entry.node)
+  invoke(options.onBeforeLeave, element)
+  invoke(options.onLeave, element)
+  let active = true
+  const run = runWithDriver(entry.node, 'leave', options, () => {
+    active = false
+    if (entry.status !== 'leaving') return
+    entry.run = undefined
+    invoke(options.onAfterLeave, element)
+    done()
+  })
+  if (active && entry.status === 'leaving') entry.run = run
+}
+
+function runWithDriver(
+  node: VobsNode,
+  phase: 'enter' | 'leave',
+  options: TransitionOptions,
+  done: () => void
+): { readonly cancel: () => void } {
+  const driver = readProp<TransitionDriver>(options, 'driver', cssTransitionDriver)
+  const transitionPhase = phase === 'enter' ? options.enter : options.leave
+  const duration = Math.max(0, transitionPhase?.duration ?? options.duration ?? 0)
+  return driver.run(node, phase, {
+    name: readProp<string>(options, 'name', 'v'),
+    phase: transitionPhase,
+    duration,
+    css: readProp<boolean>(options, 'css', true),
+    reducedMotion: resolveReducedMotion(options)
+  }, done)
+}
+
+function resolveChildren(value: TransitionChildren): VobsNode | null {
+  const resolved = typeof value === 'function' ? resolveChildren(value()) : value
+  if (resolved === null || resolved === undefined || resolved === false) return null
+  if (typeof resolved === 'string' || typeof resolved === 'number') return createText(String(resolved))
+  if (Array.isArray(resolved)) {
+    return createFragment((parent, anchor) => {
+      for (const child of resolved) {
+        const node = resolveChildren(child)
+        if (node) insertBefore(parent, node, anchor)
+      }
+    })
+  }
+  return resolved as VobsNode
+}
+
+function readProp<T>(props: object, name: string, fallback: T): T {
+  const value = Reflect.get(props, name)
+  return (value === undefined ? fallback : value) as T
+}
+
+function invoke(callback: ((element: Element) => void) | undefined, element: Element | null): void {
+  if (callback && element) callback(element)
+}
+
+function toReactiveItem<Item>(signal: Signal<Item>, initialValue: Item): Item {
+  if (typeof initialValue !== 'object' || initialValue === null) return initialValue
+  return new Proxy(initialValue as object, {
+    get(_target, property, receiver) {
+      return Reflect.get(signal.value as object, property, receiver)
+    },
+    has(_target, property) {
+      return property in (signal.value as object)
+    },
+    ownKeys() {
+      return Reflect.ownKeys(signal.value as object)
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      return Object.getOwnPropertyDescriptor(signal.value as object, property)
+    }
+  }) as Item
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+import type { VobsNode } from '@vobs/vobs'
+
+export type TransitionStyle = Readonly<Record<string, string | number | null | undefined>>
+
+export interface TransitionPhase {
+  readonly duration?: number
+  readonly easing?: string
+  readonly from?: TransitionStyle
+  readonly to?: TransitionStyle
+}
+
+export type TransitionPhaseName = 'enter' | 'leave'
+
+export interface TransitionRun {
+  readonly cancel: () => void
+}
+
+export interface TransitionDriverOptions {
+  readonly name: string
+  readonly phase: TransitionPhase | undefined
+  readonly duration: number
+  readonly css: boolean
+  readonly reducedMotion: boolean
+}
+
+export interface TransitionDriver {
+  run(
+    node: VobsNode,
+    phase: TransitionPhaseName,
+    options: TransitionDriverOptions,
+    done: () => void
+  ): TransitionRun
+}
+
+export interface TransitionCallbacks {
+  readonly onBeforeEnter?: (element: Element) => void
+  readonly onEnter?: (element: Element) => void
+  readonly onAfterEnter?: (element: Element) => void
+  readonly onEnterCancelled?: (element: Element) => void
+  readonly onBeforeLeave?: (element: Element) => void
+  readonly onLeave?: (element: Element) => void
+  readonly onAfterLeave?: (element: Element) => void
+  readonly onLeaveCancelled?: (element: Element) => void
+}
+
+export interface TransitionOptions extends TransitionCallbacks {
+  /** CSS class prefix. `fade` produces `fade-enter-from`, `fade-leave-to`, etc. */
+  readonly name?: string
+  /** Applies CSS lifecycle classes. Defaults to true. */
+  readonly css?: boolean
+  /** Shared fallback duration in milliseconds when a phase has no duration. */
+  readonly duration?: number
+  readonly enter?: TransitionPhase
+  readonly leave?: TransitionPhase
+  readonly driver?: TransitionDriver
+  /** Respects `prefers-reduced-motion` by default in DOM environments. */
+  readonly reducedMotion?: boolean
+  /** Animates the initial visible branch when true. */
+  readonly appear?: boolean
+}
+
+export type TransitionChildren =
+  | VobsNode
+  | string
+  | number
+  | null
+  | undefined
+  | false
+  | readonly TransitionChildren[]
+  | (() => TransitionChildren)
+
+export interface TransitionProps extends TransitionOptions {
+  /** Omit `show` to render and enter once. */
+  readonly show?: boolean
+  readonly children?: TransitionChildren
+}
+
+export interface TransitionGroupProps<Item = unknown> extends TransitionOptions {
+  /** Explicit keyed input is the stable API for reactive lists. */
+  readonly items?: readonly Item[]
+  readonly keyOf?: (item: Item, index: number) => unknown
+  readonly renderItem?: (item: Item, index: number) => TransitionChildren
+  /** Compatibility input for a stable children array; explicit keys are preferred. */
+  readonly children?: TransitionChildren
+}
+
+export type TransitionStatus = 'entering' | 'entered' | 'leaving'