@vielzeug/codex 26.11.1 → 26.11.3

package/data/packages/necromancer.json

@@ -1,9 +1,9 @@
 {
   "apiSource": "export { animate } from './animate';\nexport { animateEach } from './animate-each';\nexport { NecromancerConfigError, NecromancerError, NecromancerUnsupportedError } from './errors';\nexport { captureLayout } from './layout';\nexport { shouldReduceMotion } from './motion';\nexport type {\n  AnimateEachOptions,\n  AnimateOptions,\n  AnimationGroup,\n  AnimationHandle,\n  AnimationResult,\n  KeyframeFactory,\n  Keyframes,\n  LayoutAnimationOptions,\n  LayoutCaptureOptions,\n  LayoutTransition,\n  MotionMode,\n} from './types';\n",
   "docs": {
-    "index": "---\ntitle: 'Necromancer: Lifecycle-owned DOM animations'\ndescription: Lifecycle-owned Web Animations API primitives for native playback, groups, and additive FLIP transitions.\npackage: necromancer\ncategory: ui\nkeywords: [animation, web-animations-api, waapi, flip, stagger, reduced-motion]\nrelated: [orbit, ore]\nexports: [animate, animateEach, captureLayout]\nenvironments: [browser]\n---\n\n<!-- markdownlint-disable MD025 MD033 MD060 -->\n\n<PackageHero package=\"necromancer\" />\n\n## Why Necromancer?\n\nNative Web Animations API calls do not provide lifecycle ownership, reduced-motion policy, grouped playback, or layout transitions. Necromancer retains native keyframes and timing semantics while making ownership explicit for a component or DOM feature.\n\n```ts\n// Before\nconst animation = element.animate(keyframes, { duration: 180 });\nanimation.addEventListener('cancel', removeListeners);\n\n// After\nconst animation = animate(element, keyframes, { duration: 180 });\nanimation.dispose();\n```\n\n| Feature | Native WAAPI | Necromancer | Motion One |\n| --- | --- | --- | --- |\n| Bundle size | 0 B | <PackageInfo package=\"necromancer\" type=\"size\" /> | ~18 kB |\n| Root dependencies | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"x\" size=\"16\"></ore-icon> |\n| Lifecycle handle | Manual | `dispose()` | Library-specific controls |\n| Reduced motion | Manual | `motion: 'system'` default | Configuration required |\n| Layout transitions | Manual FLIP math | `captureLayout().animate()` | Separate API |\n\n<div class=\"decision-callout\">\n\n**Use Necromancer when** you need native browser animations with explicit cancellation, reduced-motion behavior, staggered groups, or positional FLIP transitions.\n\n**Consider CSS transitions when** a static style change needs no playback control, cleanup, or layout measurement.\n\n</div>\n\n## Installation\n\n::: code-group\n\n```sh [pnpm]\npnpm add @vielzeug/necromancer\n```\n\n```sh [npm]\nnpm install @vielzeug/necromancer\n```\n\n```sh [yarn]\nyarn add @vielzeug/necromancer\n```\n\n:::\n\n## Quick Start\n\nStart the animation after its DOM element mounts and release it when its UI owner is removed.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst notice = document.createElement('p');\nnotice.textContent = 'Saved';\ndocument.body.append(notice);\n\nconst animation = animate(\n  notice,\n  [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'translateY(0)' }],\n  { duration: 180, easing: 'ease-out' },\n);\n\nawait animation.result;\nanimation.dispose();\n```\n\n## Features\n\n<div class=\"features-grid\">\n\n- `animate()`: Native element animation with lifecycle ownership and direct native access\n- `animateEach()`: Group ownership with stable keyframe factories and `stagger`\n- `captureLayout()`: One-shot FLIP transition with additive `translate` (position) and `scale` (size)\n- `motion`: `'system'` reduced-motion support with explicit reduced outcomes\n- Native timing: Omitted timing fields retain Web Animations API behavior\n- `signal`: Abort a handle from its parent lifecycle\n- `dispose()`: Idempotent cleanup with `[Symbol.dispose]()`\n\n</div>\n\n## Deliberate Scope\n\nNecromancer owns explicit WAAPI keyframes. It does not generate CSS keyframes, observe CSS transitions, watch mutations, simulate springs, interpolate SVG paths, or run a JavaScript tween loop. Use CSS for declarative style changes and choose a dedicated tool when those capabilities are required.\n\n## Documentation\n\n<div class=\"doc-links\">\n\n- [Usage Guide](./usage.md)\n- [API Reference](./api.md)\n- [Examples](./examples.md)\n- [3.0 Migration](./migration.md)\n\n</div>\n\n## See Also\n\n<div class=\"see-also\">\n\n- [Orbit](/orbit/): Position floating UI before animating its appearance.\n- [Ore](/ore/): Own Necromancer handles in a custom element's mount and disposal lifecycle.\n</div>\n\n<!-- markdownlint-enable MD025 MD033 MD060 -->\n",
-    "api": "---\ntitle: 'Necromancer: API Reference'\ndescription: API reference for @vielzeug/necromancer animation ownership, groups, reduced motion, and FLIP transitions.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `animate()` | Animate one element | Sync | Omitted timing fields use native WAAPI behavior |\n| `animateEach()` | Animate a unique element group | Sync | Non-zero `stagger` needs numeric `delay` |\n| `captureLayout()` | Capture positions and create a one-shot FLIP transition | Sync | Capture before changing layout |\n| `shouldReduceMotion()` | Report whether a motion mode reduces visible movement | Sync | `'system'` reads `prefers-reduced-motion`; false without `matchMedia` |\n| `NecromancerError` | Base package error | Sync | Use `instanceof NecromancerError` to narrow unknown errors |\n\n## Package Entry Point\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/necromancer` | Animation functions, types, and errors |\n| `@vielzeug/necromancer/testing` | jsdom test fakes for `Element.animate()` and `getBoundingClientRect()` |\n\n## Animation Functions\n\n### `animate()`\n\n```ts\nfunction animate(element: Element, keyframes: Keyframes, options?: AnimateOptions): AnimationHandle;\n```\n\nStarts a lifecycle-owned native Web Animation. Native timing options, including an omitted or zero `duration`, are preserved.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `element` | `Element` | Element animated through its native `animate()` method. |\n| `keyframes` | `Keyframes` | Native keyframe array or property-indexed keyframes. |\n| `options` | `AnimateOptions` | Native timing plus motion and cancellation ownership. |\n\n**Returns:** An `AnimationHandle` with native playback access and explicit disposal.\n\n**Example:**\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\nhandle.animation.pause();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n---\n\n### `animateEach()`\n\n```ts\nfunction animateEach<ElementType extends Element>(\n  elements: Iterable<ElementType>,\n  keyframes: Keyframes | KeyframeFactory<ElementType>,\n  options?: AnimateEachOptions,\n): AnimationGroup;\n```\n\nStarts animations for unique elements in first-seen order. Necromancer resolves every keyframe factory before starting the first native animation.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `elements` | `Iterable<ElementType>` | Elements animated once in first-seen order. |\n| `keyframes` | `Keyframes \\| KeyframeFactory<ElementType>` | Shared keyframes or a subtype-preserving factory. |\n| `options` | `AnimateEachOptions` | Animation options plus a stagger interval. |\n\n**Returns:** An `AnimationGroup` containing child handles and ordered results.\n\n**Example:**\n\n```ts\nimport { animateEach } from '@vielzeug/necromancer';\n\nconst group = animateEach(document.querySelectorAll<HTMLElement>('.item'), [{ opacity: 0 }, { opacity: 1 }], {\n  duration: 180,\n  stagger: 30,\n});\nawait group.results;\n```\n\n### `shouldReduceMotion()`\n\n```ts\nfunction shouldReduceMotion(mode: MotionMode): boolean;\n```\n\nReports whether the requested motion preference reduces visible movement: the same check `animate()` applies internally, exposed so hand-rolled effects (scroll behavior, tweens) stay consistent with it. `'full'` is always `false`, `'reduced'` is always `true`, and `'system'` reads the `prefers-reduced-motion` media query (`false` where `matchMedia` is unavailable).\n\n```ts\nimport { shouldReduceMotion } from '@vielzeug/necromancer';\n\nelement.scrollIntoView({ behavior: shouldReduceMotion('system') ? 'auto' : 'smooth' });\n```\n\n## Layout Functions\n\n### `captureLayout()`\n\n```ts\nfunction captureLayout<ElementType extends Element>(\n  elements: Iterable<ElementType>,\n  options?: LayoutCaptureOptions<ElementType>,\n): LayoutTransition<ElementType>;\n```\n\nCaptures unique elements' positions and sizes and returns a one-shot transition. Rotation and other transforms are not captured or compensated.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `elements` | `Iterable<ElementType>` | Elements measured before a layout change. |\n| `options` | `LayoutCaptureOptions<ElementType>` | Optional stable key mapping for replacement nodes. |\n\n**Returns:** A `LayoutTransition<ElementType>` that measures committed layout once and creates an `AnimationGroup`.\n\n**Example:**\n\n```ts\nimport { captureLayout } from '@vielzeug/necromancer';\n\nconst transition = captureLayout(beforeItems, {\n  getKey: (element) => element.getAttribute('data-id')!,\n});\n\nrenderReorderedItems();\n\nconst group = transition.animate({\n  duration: 220,\n  easing: 'ease-out',\n  elements: afterItems,\n});\n```\n\nCalling `animate()` twice on the same transition throws `NecromancerConfigError`.\n\n## Types\n\n### `MotionMode`\n\n```ts\ntype MotionMode = 'full' | 'reduced' | 'system';\n```\n\n`'system'` is the default. Reduced motion preserves the supplied keyframes while normalizing delay, duration, and end delay to `0`, and iterations to `1`.\n\n### `AnimationResult`\n\n```ts\ntype AnimationResult =\n  | { readonly status: 'finished' }\n  | { readonly status: 'reduced' }\n  | { readonly reason?: unknown; readonly status: 'cancelled' };\n```\n\n`cancelled` describes native cancellation and includes its native rejection reason. A reason passed to `dispose()` or an abort signal takes precedence. The independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.\n\n### `AnimateOptions`\n\n```ts\ntype AnimateOptions = KeyframeAnimationOptions & {\n  readonly motion?: MotionMode;\n  readonly signal?: AbortSignal;\n};\n```\n\nNative timing fields pass through unchanged unless reduced motion normalizes timing. `signal` disposes the returned handle when aborted.\n\n### `AnimateEachOptions`\n\n```ts\ntype AnimateEachOptions = AnimateOptions & {\n  readonly stagger?: number;\n};\n```\n\n`stagger` is a finite, non-negative millisecond offset.\n\n### `LayoutCaptureOptions`\n\n```ts\ninterface LayoutCaptureOptions<ElementType extends Element = Element> {\n  readonly getKey?: (element: ElementType) => string;\n}\n```\n\n`getKey` maps a captured element and its committed replacement to the same stable, non-empty string. Duplicate or empty keys throw `NecromancerConfigError`.\n\n### `LayoutAnimationOptions`\n\n```ts\ntype LayoutAnimationOptions<ElementType extends Element = Element> = AnimateEachOptions & {\n  readonly elements?: Iterable<ElementType>;\n};\n```\n\n`elements` is the collection in its committed layout. Omit it to animate the same captured elements. With `getKey`, replacement elements animate from the positions of their captured predecessors. Unmatched, removed, and newly entered elements are ignored.\n\n### `Keyframes` and `KeyframeFactory`\n\n```ts\ntype Keyframes = readonly Keyframe[] | PropertyIndexedKeyframes;\ntype KeyframeFactory<ElementType extends Element = Element> = (\n  element: ElementType,\n  index: number,\n  total: number,\n) => Keyframes;\n```\n\nAccepts a `readonly` array so a reusable `as const` keyframe list can be passed without a cast.\n\n### `AnimationHandle`\n\n```ts\ninterface AnimationHandle {\n  readonly animation: Animation;\n  readonly result: Promise<AnimationResult>;\n  readonly disposed: boolean;\n  dispose(reason?: unknown): void;\n  [Symbol.dispose](): void;\n}\n```\n\n| Member | Description |\n| --- | --- |\n| `animation` | Owned native animation used for playback control. |\n| `result` | Resolves with the first terminal outcome. |\n| `disposed` | Reports explicit owner disposal. |\n| `dispose(reason?)` | Cancels the animation and releases its abort listener. |\n| `[Symbol.dispose]()` | Delegates to `dispose()`. |\n\n### `AnimationGroup`\n\n```ts\ninterface AnimationGroup {\n  readonly handles: readonly AnimationHandle[];\n  readonly results: Promise<readonly AnimationResult[]>;\n  readonly disposed: boolean;\n  dispose(reason?: unknown): void;\n  [Symbol.dispose](): void;\n}\n```\n\n| Member | Description |\n| --- | --- |\n| `handles` | Child handles in input order. |\n| `results` | Resolves with every child outcome in handle order. |\n| `disposed` | Reports explicit group disposal. |\n| `dispose(reason?)` | Disposes every child. |\n| `[Symbol.dispose]()` | Delegates to `dispose()`. |\n\n### `LayoutTransition`\n\n```ts\ninterface LayoutTransition<ElementType extends Element = Element> {\n  animate(options?: LayoutAnimationOptions<ElementType>): AnimationGroup;\n}\n```\n\n| Method | Description |\n| --- | --- |\n| `animate(options?)` | Measures committed elements and creates the one allowed layout animation group. |\n\n## Errors\n\n| Error | Trigger |\n| --- | --- |\n| `NecromancerError` | Base class for package errors |\n| `NecromancerConfigError` | Invalid stagger, incompatible delay, or reused layout transition |\n| `NecromancerUnsupportedError` | `Element.animate()` is unavailable |\n\n## Testing (`@vielzeug/necromancer/testing`)\n\njsdom (and most non-browser DOM environments) do not implement `Element.animate()`. Import these from the `/testing` sub-path, not the root entry point.\n\n### `AnimationCall`\n\n```ts\ntype AnimationCall = {\n  readonly animation: FakeAnimation;\n  readonly keyframes: Keyframe[] | PropertyIndexedKeyframes;\n  readonly options?: KeyframeAnimationOptions;\n};\n```\n\nOne recorded invocation of `Element.prototype.animate` from `installFakeAnimations()`.\n\n### `installFakeAnimations()`\n\n```ts\nfunction installFakeAnimations(): {\n  readonly calls: readonly AnimationCall[];\n  restore(): void;\n  [Symbol.dispose](): void;\n};\n```\n\nReplaces `Element.prototype.animate` with a deterministic lifecycle fake for the duration of a test. `calls` records every invocation in order. Call `restore()` or use an explicit resource-management `using` declaration to put the original implementation back. The fake does not implement native playback controls such as `pause()` or `reverse()`.\n\n```ts\nimport { installFakeAnimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installFakeAnimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\n### `FakeAnimation`\n\n```ts\nclass FakeAnimation {\n  cancelCallCount: number;\n  finishCallCount: number;\n  finished: Promise<void>;\n  cancel(): void;\n  finish(): void;\n}\n```\n\nA minimal `Animation` stand-in. `cancel()` rejects `finished` with an `AbortError`; `finish()` resolves it. `cancelCallCount`/`finishCallCount` track how many times each was called, in place of a test-runner-specific spy.\n\n### `createRect()`\n\n```ts\nfunction createRect(x: number, y: number, width?: number, height?: number): DOMRect;\n```\n\nBuilds a `DOMRect` for mocking `Element.getBoundingClientRect()` in `captureLayout()` tests. `width`/`height` default to `20`.\n",
-    "usage": "---\ntitle: 'Necromancer: Usage Guide'\ndescription: Animate DOM elements, coordinate groups, and create FLIP transitions with @vielzeug/necromancer.\n---\n\n[[toc]]\n\n## Basic Usage\n\nCreate an animation after its element mounts, control playback through the native `Animation`, and dispose its owner with the UI lifecycle.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(\n  element,\n  [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'translateY(0)' }],\n  { duration: 180, easing: 'ease-out', fill: 'both' },\n);\n\nhandle.animation.reverse();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n`result` distinguishes natural completion, reduced timing, and cancellation. `disposed` reports only whether the owner was explicitly disposed.\n\nOmitted timing fields retain native Web Animations API behavior. Pass an explicit `duration` when the animation should run over time.\n\n## Motion Preferences\n\nUse `motion` to select how the animation responds to the operating system preference.\n\n```ts\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], {\n  duration: 200,\n  motion: 'system',\n});\n\nconst result = await handle.result;\n```\n\n`'system'` is the default and reduces movement when `prefers-reduced-motion: reduce` matches. `'full'` preserves the requested timing, while `'reduced'` always reduces it.\n\nReduced motion keeps the supplied keyframes but normalizes delay, duration, and end delay to zero and iterations to one. The result is `{ status: 'reduced' }`, and `handle.animation` still represents the requested visual transition.\n\n## Parent Cancellation\n\nPass a parent `AbortSignal` to release an animation when its owning work is cancelled.\n\n```ts\nconst controller = new AbortController();\nconst handle = animate(element, [{ scale: 0.96 }, { scale: 1 }], {\n  duration: 160,\n  signal: controller.signal,\n});\n\ncontroller.abort('route changed');\nconst result = await handle.result;\n// { status: 'cancelled', reason: 'route changed' }\n```\n\nAn already-aborted signal throws its reason before an animation starts.\n\n## Staggering a Group\n\nPass an iterable of elements to `animateEach()`. Duplicate elements are animated once in first-seen order.\n\n```ts\nimport { animateEach } from '@vielzeug/necromancer';\n\nconst group = animateEach(\n  document.querySelectorAll('.card'),\n  (_card, index) => [\n    { opacity: 0, transform: `translateY(${12 + index * 2}px)` },\n    { opacity: 1, transform: 'translateY(0)' },\n  ],\n  { duration: 220, easing: 'ease-out', stagger: 45 },\n);\n\nconst results = await group.results;\ngroup.dispose();\n```\n\nA group owns child lifecycles only. `results` preserves every child result in handle order; use `group.handles` when native playback control is required.\n\n## Serial Application Flow\n\nJavaScript control flow is the clearest way to express serial, conditional, or branching animations:\n\n```ts\nfor (const step of steps) {\n  const handle = animate(step.element, step.keyframes, {\n    ...step.options,\n    signal: controller.signal,\n  });\n  const result = await handle.result;\n\n  if (result.status === 'cancelled') break;\n}\n```\n\nOne parent `AbortSignal` cancels the active step without introducing a separate timeline abstraction.\n\n## Animating a Reorder with FLIP\n\nCapture positions before changing layout, then animate through the returned one-shot transition.\n\n```ts\nimport { captureLayout } from '@vielzeug/necromancer';\n\nconst transition = captureLayout(items);\nlist.prepend(items[2]!);\n\nconst group = transition.animate({ duration: 220, easing: 'ease-out' });\nawait group.results;\ngroup.dispose();\n```\n\nThe transition only animates changed, connected elements and can be animated once. It additively composes the individual CSS `translate` and `scale` properties, preserving authored `transform`, `translate`, and `scale`. A resized element (for example a list item whose content changed) animates from its captured size as well as its captured position.\n\n### Replacing rendered elements\n\nWhen a framework replaces list nodes rather than reorders the captured elements, give `captureLayout()` a stable key and pass the committed nodes to `animate()`. Capture before updating state, then call `animate()` only after the renderer has committed the new DOM.\n\n```ts\nconst transition = captureLayout(beforeItems, {\n  getKey: (element) => element.getAttribute('data-id')!,\n});\n\nrenderReorderedItems();\n\ntransition.animate({\n  duration: 220,\n  easing: 'ease-out',\n  elements: afterItems,\n});\n```\n\nKeys must be unique, non-empty strings in both collections. Items with no matching predecessor are not enter animations; animate those explicitly with `animate()` or `animateEach()`.\n\nFor sortable lists, DnD exposes its pre-commit layout seam through `onBeforeReorder`; see the [DnD optimistic-reorder recipe](/dnd/examples/optimistic-reorder-with-revert.md).\n\n## Scope\n\nNecromancer creates and owns explicit Web Animations API work. It does not observe CSS-authored transitions or animations, inject `@keyframes`, watch DOM mutations, generate springs, interpolate SVG geometry, or provide a JavaScript tween fallback. Keep CSS as the owner of declarative component styling and use a dedicated charting or tweening tool when the animation needs capabilities beyond WAAPI keyframes.\n\n## Testing\n\njsdom does not implement `Element.animate()`, so lifecycle tests need a fake. `@vielzeug/necromancer/testing` has no test-runner import and supports explicit resource management.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\nimport { installFakeAnimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installFakeAnimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\nUse `restore()` when `using` is unavailable. The lifecycle fake supports `finish()`, `cancel()`, and `finished`; use browser tests for native playback controls. Use `createRect()` to mock `Element.getBoundingClientRect()` when testing code that calls `captureLayout()`.\n\n## Framework Integration\n\nCreate handles in a client mount lifecycle and dispose them during unmount. The same composition works with reactive effect systems: start the animation in the effect and return `handle.dispose()` as its cleanup.\n\n```tsx\nimport { useEffect, useRef } from 'react';\nimport { animate } from '@vielzeug/necromancer';\n\nexport function Notice() {\n  const elementRef = useRef<HTMLDivElement>(null);\n\n  useEffect(() => {\n    const element = elementRef.current;\n    if (!element) return;\n\n    const handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\n    return () => handle.dispose();\n  }, []);\n\n  return <div ref={elementRef}>Saved</div>;\n}\n```\n\n## Working with Other Vielzeug Libraries\n\nUse Dnd's `onBeforeReorder` hook to capture item layout before a sortable commits its DOM update. Animate the captured transition after `onReorder`; see the [optimistic reorder recipe](/dnd/examples/optimistic-reorder-with-revert.md).\n\n## Best Practices\n\n- Start animations only after their elements mount in the browser.\n- Set animation timing explicitly when native zero-duration behavior is not intended.\n- Dispose each handle or group with its UI owner.\n- Use native `Animation` objects for playback control.\n- Respect the default `'system'` motion setting unless movement is essential.\n- Use a parent `AbortSignal` for cancellable application flow.\n- Keep `delay` numeric when combining it with non-zero `stagger`.\n- Capture layout before mutation and animate each transition exactly once.\n",
+    "index": "---\ntitle: 'Necromancer: Lifecycle-owned DOM animations'\ndescription: Lifecycle-owned Web Animations API primitives for native playback, groups, and additive FLIP transitions.\npackage: necromancer\ncategory: ui\nkeywords: [animation, web-animations-api, waapi, flip, stagger, reduced-motion]\nrelated: [orbit, ore]\nexports: [animate, animateEach, captureLayout]\nenvironments: [browser]\n---\n\n<!-- markdownlint-disable MD025 MD033 MD060 -->\n\n<PackageHero package=\"necromancer\" />\n\n## Why Necromancer?\n\nNative Web Animations API calls do not provide lifecycle ownership, reduced-motion policy, grouped playback, or layout transitions. Necromancer retains native keyframes and timing semantics while making ownership explicit for a component or DOM feature.\n\n```ts\n// Before\nconst animation = element.animate(keyframes, { duration: 180 });\nanimation.addEventListener('cancel', removeListeners);\n\n// After\nconst animation = animate(element, keyframes, { duration: 180 });\nanimation.dispose();\n```\n\n| Feature | Native WAAPI | Necromancer | Motion One |\n| --- | --- | --- | --- |\n| Bundle size | 0 B | <PackageInfo package=\"necromancer\" type=\"size\" /> | ~18 kB |\n| Root dependencies | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"x\" size=\"16\"></ore-icon> |\n| Lifecycle handle | Manual | `dispose()` | Library-specific controls |\n| Reduced motion | Manual | `motion: 'system'` default | Configuration required |\n| Layout transitions | Manual FLIP math | `captureLayout().animate()` | Separate API |\n\n<div class=\"decision-callout\">\n\n**Use Necromancer when** you need native browser animations with explicit cancellation, reduced-motion behavior, staggered groups, or positional FLIP transitions.\n\n**Consider CSS transitions when** a static style change needs no playback control, cleanup, or layout measurement.\n\n</div>\n\n## Installation\n\n::: code-group\n\n```sh [pnpm]\npnpm add @vielzeug/necromancer\n```\n\n```sh [npm]\nnpm install @vielzeug/necromancer\n```\n\n```sh [yarn]\nyarn add @vielzeug/necromancer\n```\n\n:::\n\n## Quick Start\n\nStart the animation after its DOM element mounts and release it when its UI owner is removed.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst notice = document.createElement('p');\nnotice.textContent = 'Saved';\ndocument.body.append(notice);\n\nconst animation = animate(\n  notice,\n  [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'translateY(0)' }],\n  { duration: 180, easing: 'ease-out' },\n);\n\nawait animation.result;\nanimation.dispose();\n```\n\n## Features\n\n<div class=\"features-grid\">\n\n- `animate()`: Native element animation with lifecycle ownership and direct native access\n- `animateEach()`: Group ownership with stable keyframe factories and `stagger`\n- `captureLayout()`: One-shot FLIP transition with additive `translate` (position) and `scale` (size)\n- `motion`: `'system'` reduced-motion support with the same keyframes on instant timing\n- Native timing: Omitted timing fields retain Web Animations API behavior\n- `signal`: Abort a handle from its parent lifecycle\n- `dispose()`: Idempotent cleanup with `[Symbol.dispose]()`\n\n</div>\n\n## Deliberate Scope\n\nNecromancer owns explicit WAAPI keyframes. It does not generate CSS keyframes, observe CSS transitions, watch mutations, simulate springs, interpolate SVG paths, or run a JavaScript tween loop. Use CSS for declarative style changes and choose a dedicated tool when those capabilities are required.\n\n## Documentation\n\n<div class=\"doc-links\">\n\n- [Usage Guide](./usage.md)\n- [API Reference](./api.md)\n- [Examples](./examples.md)\n- [Migration Guide](./migration.md)\n\n</div>\n\n## See Also\n\n<div class=\"see-also\">\n\n- [Orbit](/orbit/): Position floating UI before animating its appearance.\n- [Ore](/ore/): Own Necromancer handles in a custom element's mount and disposal lifecycle.\n</div>\n\n<!-- markdownlint-enable MD025 MD033 MD060 -->\n",
+    "api": "---\ntitle: 'Necromancer: API Reference'\ndescription: API reference for @vielzeug/necromancer animation ownership, groups, reduced motion, and FLIP transitions.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `animate()` | Animate one element | Sync | Omitted timing fields use native WAAPI behavior |\n| `animateEach()` | Animate a unique element group | Sync | Non-zero `stagger` needs numeric `delay` |\n| `captureLayout()` | Capture positions and create a one-shot FLIP transition | Sync | Capture before changing layout |\n| `shouldReduceMotion()` | Report whether a motion mode reduces visible movement | Sync | `'system'` reads `prefers-reduced-motion`; false without `matchMedia` |\n| `NecromancerError` | Base package error | Sync | Use `instanceof NecromancerError` to narrow unknown errors |\n\n## Package Entry Point\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/necromancer` | Animation functions, types, and errors |\n| `@vielzeug/necromancer/testing` | jsdom test fakes for `Element.animate()` and `getBoundingClientRect()` |\n\n## Animation Functions\n\n### `animate()`\n\n```ts\nfunction animate(element: Element, keyframes: Keyframes, options?: AnimateOptions): AnimationHandle;\n```\n\nStarts a lifecycle-owned native Web Animation. Native timing options, including an omitted or zero `duration`, are preserved.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `element` | `Element` | Element animated through its native `animate()` method. |\n| `keyframes` | `Keyframes` | Native keyframe array or property-indexed keyframes. |\n| `options` | `AnimateOptions` | Native timing plus motion and cancellation ownership. |\n\n**Returns:** An `AnimationHandle` with native playback access and explicit disposal.\n\n**Example:**\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\nhandle.animation.pause();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n---\n\n### `animateEach()`\n\n```ts\nfunction animateEach<ElementType extends Element>(\n  elements: Iterable<ElementType>,\n  keyframes: Keyframes | KeyframeFactory<ElementType>,\n  options?: AnimateEachOptions,\n): AnimationGroup;\n```\n\nStarts animations for unique elements in first-seen order. Necromancer resolves every keyframe factory before starting the first native animation.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `elements` | `Iterable<ElementType>` | Elements animated once in first-seen order. |\n| `keyframes` | `Keyframes \\| KeyframeFactory<ElementType>` | Shared keyframes or a subtype-preserving factory. |\n| `options` | `AnimateEachOptions` | Animation options plus a stagger interval. |\n\n**Returns:** An `AnimationGroup` containing child handles and ordered results.\n\n**Example:**\n\n```ts\nimport { animateEach } from '@vielzeug/necromancer';\n\nconst group = animateEach(document.querySelectorAll<HTMLElement>('.item'), [{ opacity: 0 }, { opacity: 1 }], {\n  duration: 180,\n  stagger: 30,\n});\nawait group.results;\n```\n\n### `shouldReduceMotion()`\n\n```ts\nfunction shouldReduceMotion(mode: MotionMode): boolean;\n```\n\nReports whether the requested motion preference reduces visible movement: the same check `animate()` applies internally, exposed so hand-rolled effects (scroll behavior, tweens) stay consistent with it. `'full'` is always `false`, `'reduced'` is always `true`, and `'system'` reads the `prefers-reduced-motion` media query (`false` where `matchMedia` is unavailable).\n\n```ts\nimport { shouldReduceMotion } from '@vielzeug/necromancer';\n\nelement.scrollIntoView({ behavior: shouldReduceMotion('system') ? 'auto' : 'smooth' });\n```\n\n## Layout Functions\n\n### `captureLayout()`\n\n```ts\nfunction captureLayout<ElementType extends Element>(\n  elements: Iterable<ElementType>,\n  options?: LayoutCaptureOptions<ElementType>,\n): LayoutTransition<ElementType>;\n```\n\nCaptures unique elements' positions and sizes and returns a one-shot transition. Rotation and other transforms are not captured or compensated.\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `elements` | `Iterable<ElementType>` | Elements measured before a layout change. |\n| `options` | `LayoutCaptureOptions<ElementType>` | Optional stable key mapping for replacement nodes. |\n\n**Returns:** A `LayoutTransition<ElementType>` that measures committed layout once and creates an `AnimationGroup`.\n\n**Example:**\n\n```ts\nimport { captureLayout } from '@vielzeug/necromancer';\n\nconst transition = captureLayout(beforeItems, {\n  getKey: (element) => element.getAttribute('data-id')!,\n});\n\nrenderReorderedItems();\n\nconst group = transition.animate({\n  duration: 220,\n  easing: 'ease-out',\n  elements: afterItems,\n});\n```\n\nCalling `animate()` twice on the same transition throws `NecromancerConfigError`.\n\n## Types\n\n### `MotionMode`\n\n```ts\ntype MotionMode = 'full' | 'reduced' | 'system';\n```\n\n`'system'` is the default. Reduced motion preserves the supplied keyframes while normalizing delay, duration, and end delay to `0`, and iterations to `1`.\n\n### `AnimationResult`\n\n```ts\ntype AnimationResult =\n  | { readonly status: 'finished' }\n  | { readonly reason?: unknown; readonly status: 'cancelled' };\n```\n\nA reduced animation finishes: reduction is decided at call time and `shouldReduceMotion()` answers it, so the result reports only what the caller could not know. `cancelled` carries the reason the animation was cancelled: the value passed to `dispose()`, the abort reason of the owning `signal`, or the native rejection reason when something outside Necromancer cancelled the animation. A bare `dispose()` carries no reason. The independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.\n\n### `AnimateOptions`\n\n```ts\ntype AnimateOptions = KeyframeAnimationOptions & {\n  readonly motion?: MotionMode;\n  readonly signal?: AbortSignal;\n};\n```\n\nNative timing fields pass through unchanged unless reduced motion normalizes timing. `signal` disposes the returned handle when aborted.\n\n### `AnimateEachOptions`\n\n```ts\ntype AnimateEachOptions = AnimateOptions & {\n  readonly stagger?: number;\n};\n```\n\n`stagger` is a finite, non-negative millisecond offset.\n\n### `LayoutCaptureOptions`\n\n```ts\ninterface LayoutCaptureOptions<ElementType extends Element = Element> {\n  readonly getKey?: (element: ElementType) => string;\n}\n```\n\n`getKey` maps a captured element and its committed replacement to the same stable, non-empty string. Duplicate or empty keys throw `NecromancerConfigError`.\n\n### `LayoutAnimationOptions`\n\n```ts\ntype LayoutAnimationOptions<ElementType extends Element = Element> = AnimateEachOptions & {\n  readonly elements?: Iterable<ElementType>;\n};\n```\n\n`elements` is the collection in its committed layout. Omit it to animate the same captured elements. With `getKey`, replacement elements animate from the positions of their captured predecessors. Unmatched, removed, and newly entered elements are ignored.\n\n### `Keyframes` and `KeyframeFactory`\n\n```ts\ntype Keyframes = readonly Keyframe[] | PropertyIndexedKeyframes;\ntype KeyframeFactory<ElementType extends Element = Element> = (\n  element: ElementType,\n  index: number,\n  total: number,\n) => Keyframes;\n```\n\nAccepts a `readonly` array so a reusable `as const` keyframe list can be passed without a cast.\n\n### `AnimationHandle`\n\n```ts\ninterface AnimationHandle {\n  readonly animation: Animation;\n  readonly result: Promise<AnimationResult>;\n  readonly disposed: boolean;\n  dispose(reason?: unknown): void;\n  [Symbol.dispose](): void;\n}\n```\n\n| Member | Description |\n| --- | --- |\n| `animation` | Owned native animation used for playback control. |\n| `result` | Resolves with the first terminal outcome. |\n| `disposed` | Reports explicit owner disposal. |\n| `dispose(reason?)` | Cancels the animation and releases its abort listener. |\n| `[Symbol.dispose]()` | Delegates to `dispose()`. |\n\n### `AnimationGroup`\n\n```ts\ninterface AnimationGroup {\n  readonly handles: readonly AnimationHandle[];\n  readonly results: Promise<readonly AnimationResult[]>;\n  readonly disposed: boolean;\n  dispose(reason?: unknown): void;\n  [Symbol.dispose](): void;\n}\n```\n\n| Member | Description |\n| --- | --- |\n| `handles` | Child handles in input order. |\n| `results` | Resolves with every child outcome in handle order. |\n| `disposed` | Reports explicit group disposal. |\n| `dispose(reason?)` | Disposes every child. |\n| `[Symbol.dispose]()` | Delegates to `dispose()`. |\n\n### `LayoutTransition`\n\n```ts\ninterface LayoutTransition<ElementType extends Element = Element> {\n  animate(options?: LayoutAnimationOptions<ElementType>): AnimationGroup;\n}\n```\n\n| Method | Description |\n| --- | --- |\n| `animate(options?)` | Measures committed elements and creates the one allowed layout animation group. |\n\n## Errors\n\n| Error | Trigger |\n| --- | --- |\n| `NecromancerError` | Base class for package errors |\n| `NecromancerConfigError` | Invalid stagger, incompatible delay, or reused layout transition |\n| `NecromancerUnsupportedError` | `Element.animate()` is unavailable |\n\n## Testing (`@vielzeug/necromancer/testing`)\n\njsdom (and most non-browser DOM environments) do not implement `Element.animate()`. Import these from the `/testing` sub-path, not the root entry point.\n\n### `AnimationCall`\n\n```ts\ntype AnimationCall = {\n  readonly animation: FakeAnimation;\n  readonly keyframes: Keyframe[] | PropertyIndexedKeyframes;\n  readonly options?: KeyframeAnimationOptions;\n};\n```\n\nOne recorded invocation of `Element.prototype.animate` from `installFakeAnimations()`.\n\n### `installFakeAnimations()`\n\n```ts\nfunction installFakeAnimations(): {\n  readonly calls: readonly AnimationCall[];\n  restore(): void;\n  [Symbol.dispose](): void;\n};\n```\n\nReplaces `Element.prototype.animate` with a deterministic lifecycle fake for the duration of a test. `calls` records every invocation in order. Call `restore()` or use an explicit resource-management `using` declaration to put the original implementation back. The fake does not implement native playback controls such as `pause()` or `reverse()`.\n\n```ts\nimport { installFakeAnimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installFakeAnimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\n### `FakeAnimation`\n\n```ts\nclass FakeAnimation {\n  cancelCallCount: number;\n  finishCallCount: number;\n  finished: Promise<void>;\n  cancel(): void;\n  finish(): void;\n}\n```\n\nA minimal `Animation` stand-in. `cancel()` rejects `finished` with an `AbortError`; `finish()` resolves it. `cancelCallCount`/`finishCallCount` track how many times each was called, in place of a test-runner-specific spy.\n\n### `createRect()`\n\n```ts\nfunction createRect(x: number, y: number, width?: number, height?: number): DOMRect;\n```\n\nBuilds a `DOMRect` for mocking `Element.getBoundingClientRect()` in `captureLayout()` tests. `width`/`height` default to `20`.\n",
+    "usage": "---\ntitle: 'Necromancer: Usage Guide'\ndescription: Animate DOM elements, coordinate groups, and create FLIP transitions with @vielzeug/necromancer.\n---\n\n[[toc]]\n\n## Basic Usage\n\nCreate an animation after its element mounts, control playback through the native `Animation`, and dispose its owner with the UI lifecycle.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\n\nconst handle = animate(\n  element,\n  [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'translateY(0)' }],\n  { duration: 180, easing: 'ease-out', fill: 'both' },\n);\n\nhandle.animation.reverse();\nconst result = await handle.result;\nhandle.dispose();\n```\n\n`result` distinguishes natural completion from cancellation. `disposed` reports only whether the owner was explicitly disposed.\n\nOmitted timing fields retain native Web Animations API behavior. Pass an explicit `duration` when the animation should run over time.\n\n## Motion Preferences\n\nUse `motion` to select how the animation responds to the operating system preference.\n\n```ts\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], {\n  duration: 200,\n  motion: 'system',\n});\n\nconst result = await handle.result;\n```\n\n`'system'` is the default and reduces movement when `prefers-reduced-motion: reduce` matches. `'full'` preserves the requested timing, while `'reduced'` always reduces it.\n\nReduced motion keeps the supplied keyframes but normalizes delay, duration, and end delay to zero and iterations to one. The animation finishes immediately, so its result is `{ status: 'finished' }`; call `shouldReduceMotion()` with the same mode when your own code needs to know whether movement was reduced. `handle.animation` still represents the requested visual transition.\n\n## Parent Cancellation\n\nPass a parent `AbortSignal` to release an animation when its owning work is cancelled.\n\n```ts\nconst controller = new AbortController();\nconst handle = animate(element, [{ scale: 0.96 }, { scale: 1 }], {\n  duration: 160,\n  signal: controller.signal,\n});\n\ncontroller.abort('route changed');\nconst result = await handle.result;\n// { status: 'cancelled', reason: 'route changed' }\n```\n\nAn already-aborted signal throws its reason before an animation starts.\n\n## Staggering a Group\n\nPass an iterable of elements to `animateEach()`. Duplicate elements are animated once in first-seen order.\n\n```ts\nimport { animateEach } from '@vielzeug/necromancer';\n\nconst group = animateEach(\n  document.querySelectorAll('.card'),\n  (_card, index) => [\n    { opacity: 0, transform: `translateY(${12 + index * 2}px)` },\n    { opacity: 1, transform: 'translateY(0)' },\n  ],\n  { duration: 220, easing: 'ease-out', stagger: 45 },\n);\n\nconst results = await group.results;\ngroup.dispose();\n```\n\nA group owns child lifecycles only. `results` preserves every child result in handle order; use `group.handles` when native playback control is required.\n\n## Serial Application Flow\n\nJavaScript control flow is the clearest way to express serial, conditional, or branching animations:\n\n```ts\nfor (const step of steps) {\n  const handle = animate(step.element, step.keyframes, {\n    ...step.options,\n    signal: controller.signal,\n  });\n  const result = await handle.result;\n\n  if (result.status === 'cancelled') break;\n}\n```\n\nOne parent `AbortSignal` cancels the active step without introducing a separate timeline abstraction.\n\n## Animating a Reorder with FLIP\n\nCapture positions before changing layout, then animate through the returned one-shot transition.\n\n```ts\nimport { captureLayout } from '@vielzeug/necromancer';\n\nconst transition = captureLayout(items);\nlist.prepend(items[2]!);\n\nconst group = transition.animate({ duration: 220, easing: 'ease-out' });\nawait group.results;\ngroup.dispose();\n```\n\nThe transition only animates changed, connected elements and can be animated once. It additively composes the individual CSS `translate` and `scale` properties, preserving authored `transform`, `translate`, and `scale`. A resized element (for example a list item whose content changed) animates from its captured size as well as its captured position.\n\n### Replacing rendered elements\n\nWhen a framework replaces list nodes rather than reorders the captured elements, give `captureLayout()` a stable key and pass the committed nodes to `animate()`. Capture before updating state, then call `animate()` only after the renderer has committed the new DOM.\n\n```ts\nconst transition = captureLayout(beforeItems, {\n  getKey: (element) => element.getAttribute('data-id')!,\n});\n\nrenderReorderedItems();\n\ntransition.animate({\n  duration: 220,\n  easing: 'ease-out',\n  elements: afterItems,\n});\n```\n\nKeys must be unique, non-empty strings in both collections. Items with no matching predecessor are not enter animations; animate those explicitly with `animate()` or `animateEach()`.\n\nFor sortable lists, DnD exposes its pre-commit layout seam through `onBeforeReorder`; see the [DnD optimistic-reorder recipe](/dnd/examples/optimistic-reorder-with-revert.md).\n\n## Scope\n\nNecromancer creates and owns explicit Web Animations API work. It does not observe CSS-authored transitions or animations, inject `@keyframes`, watch DOM mutations, generate springs, interpolate SVG geometry, or provide a JavaScript tween fallback. Keep CSS as the owner of declarative component styling and use a dedicated charting or tweening tool when the animation needs capabilities beyond WAAPI keyframes.\n\n## Testing\n\njsdom does not implement `Element.animate()`, so lifecycle tests need a fake. `@vielzeug/necromancer/testing` has no test-runner import and supports explicit resource management.\n\n```ts\nimport { animate } from '@vielzeug/necromancer';\nimport { installFakeAnimations } from '@vielzeug/necromancer/testing';\n\nusing animations = installFakeAnimations();\nconst handle = animate(element, [{ opacity: 0 }, { opacity: 1 }]);\n\nanimations.calls[0]?.animation.finish();\nawait handle.result; // { status: 'finished' }\n```\n\nUse `restore()` when `using` is unavailable. The lifecycle fake supports `finish()`, `cancel()`, and `finished`; use browser tests for native playback controls. Use `createRect()` to mock `Element.getBoundingClientRect()` when testing code that calls `captureLayout()`.\n\n## Framework Integration\n\nCreate handles in a client mount lifecycle and dispose them during unmount. The same composition works with reactive effect systems: start the animation in the effect and return `handle.dispose()` as its cleanup.\n\n```tsx\nimport { useEffect, useRef } from 'react';\nimport { animate } from '@vielzeug/necromancer';\n\nexport function Notice() {\n  const elementRef = useRef<HTMLDivElement>(null);\n\n  useEffect(() => {\n    const element = elementRef.current;\n    if (!element) return;\n\n    const handle = animate(element, [{ opacity: 0 }, { opacity: 1 }], { duration: 180 });\n    return () => handle.dispose();\n  }, []);\n\n  return <div ref={elementRef}>Saved</div>;\n}\n```\n\n## Working with Other Vielzeug Libraries\n\nUse Dnd's `onBeforeReorder` hook to capture item layout before a sortable commits its DOM update. Animate the captured transition after `onReorder`; see the [optimistic reorder recipe](/dnd/examples/optimistic-reorder-with-revert.md).\n\n## Best Practices\n\n- Start animations only after their elements mount in the browser.\n- Set animation timing explicitly when native zero-duration behavior is not intended.\n- Dispose each handle or group with its UI owner.\n- Use native `Animation` objects for playback control.\n- Respect the default `'system'` motion setting unless movement is essential.\n- Use a parent `AbortSignal` for cancellable application flow.\n- Keep `delay` numeric when combining it with non-zero `stagger`.\n- Capture layout before mutation and animate each transition exactly once.\n",
     "examples": "---\ntitle: 'Necromancer: Examples'\ndescription: Practical animation and FLIP layout recipes for @vielzeug/necromancer.\n---\n\n## Examples\n\n- [Animate on Mount](./examples/animate-on-mount.md)\n- [Stagger a List](./examples/stagger-a-list.md)\n- [Animate a Reorder](./examples/animate-a-reorder.md)\n\n"
   },
   "examples": [
@@ -14,12 +14,12 @@
     },
     {
       "id": "lifecycle",
-      "code": "import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createElement('section')\npanel.style.cssText = 'display: grid; gap: 12px; max-width: 320px; padding: 20px; border: 1px solid #cbd5e1; border-radius: 12px; background: #fff;'\n\nconst card = document.createElement('div')\ncard.textContent = 'Lifecycle-owned animation'\ncard.style.cssText = 'padding: 18px; border-radius: 8px; color: #fff; background: #2563eb; font: 600 16px system-ui;'\n\nconst replay = document.createElement('button')\nreplay.textContent = 'Replay animation'\n\nconst status = document.createElement('output')\nstatus.textContent = 'Ready'\n\npanel.append(card, replay, status)\ndocument.body.appendChild(panel)\n\nlet current\n\nfunction run() {\n  current?.dispose('replayed')\n  current = animate(\n    card,\n    [\n      { opacity: 0, transform: 'translateY(14px) scale(.96)' },\n      { opacity: 1, transform: 'translateY(0) scale(1)' },\n    ],\n    { duration: 280, easing: 'ease-out', fill: 'both' },\n  )\n  status.textContent = 'Animating…'\n  current.result.then((result) => {\n    status.textContent = result.status === 'finished' ? 'Finished: handle remains disposable' : result.status === 'reduced' ? 'Finished with reduced timing' : 'Cancelled'\n  })\n}\n\nreplay.addEventListener('click', run)\n",
+      "code": "import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createElement('section')\npanel.style.cssText = 'display: grid; gap: 12px; max-width: 320px; padding: 20px; border: 1px solid #cbd5e1; border-radius: 12px; background: #fff;'\n\nconst card = document.createElement('div')\ncard.textContent = 'Lifecycle-owned animation'\ncard.style.cssText = 'padding: 18px; border-radius: 8px; color: #fff; background: #2563eb; font: 600 16px system-ui;'\n\nconst replay = document.createElement('button')\nreplay.textContent = 'Replay animation'\n\nconst status = document.createElement('output')\nstatus.textContent = 'Ready'\n\npanel.append(card, replay, status)\ndocument.body.appendChild(panel)\n\nlet current\n\nfunction run() {\n  current?.dispose('replayed')\n  current = animate(\n    card,\n    [\n      { opacity: 0, transform: 'translateY(14px) scale(.96)' },\n      { opacity: 1, transform: 'translateY(0) scale(1)' },\n    ],\n    { duration: 280, easing: 'ease-out', fill: 'both' },\n  )\n  status.textContent = 'Animating…'\n  current.result.then((result) => {\n    status.textContent = result.status === 'finished' ? 'Finished: handle remains disposable' : 'Cancelled'\n  })\n}\n\nreplay.addEventListener('click', run)\n",
       "name": "animate() - Lifecycle Handle"
     },
     {
       "id": "reduced-motion",
-      "code": "import { animate } from '@vielzeug/necromancer'\n\nconst panel = document.createElement('section')\npanel.style.cssText = 'display: grid; gap: 12px; max-width: 320px; padding: 20px; border: 1px solid #cbd5e1; border-radius: 12px; background: #fff;'\n\nconst card = document.createElement('div')\ncard.textContent = 'Motion preference'\ncard.style.cssText = 'padding: 18px; border-radius: 8px; color: #fff; background: #7c3aed; font: 600 16px system-ui;'\n\nconst systemButton = document.createElement('button')\nsystemButton.textContent = 'Animate with system preference'\n\nconst skipButton = document.createElement('button')\nskipButton.textContent = 'Use reduced motion'\n\nconst status = document.createElement('output')\nstatus.textContent = 'Choose a mode'\n\npanel.append(card, systemButton, skipButton, status)\ndocument.body.appendChild(panel)\n\nfunction run(motion) {\n  const handle = animate(\n    card,\n    [\n      { opacity: 0, transform: 'translateX(-18px)' },\n      { opacity: 1, transform: 'translateX(0)' },\n    ],\n    { duration: 320, easing: 'ease-out', motion, fill: 'both' },\n  )\n  status.textContent = 'Running with motion: ' + motion\n  handle.result.then((result) => {\n    status.textContent = result.status === 'reduced' ? 'Keyframes finished with reduced timing' : 'Finished'\n  })\n}\n\nsystemButton.addEventListener('click', () => run('system'))\nskipButton.addEventListener('click', () => run('reduced'))",
+      "code": "import { animate, shouldReduceMotion } from '@vielzeug/necromancer'\n\nconst panel = document.createElement('section')\npanel.style.cssText = 'display: grid; gap: 12px; max-width: 320px; padding: 20px; border: 1px solid #cbd5e1; border-radius: 12px; background: #fff;'\n\nconst card = document.createElement('div')\ncard.textContent = 'Motion preference'\ncard.style.cssText = 'padding: 18px; border-radius: 8px; color: #fff; background: #7c3aed; font: 600 16px system-ui;'\n\nconst systemButton = document.createElement('button')\nsystemButton.textContent = 'Animate with system preference'\n\nconst skipButton = document.createElement('button')\nskipButton.textContent = 'Use reduced motion'\n\nconst status = document.createElement('output')\nstatus.textContent = 'Choose a mode'\n\npanel.append(card, systemButton, skipButton, status)\ndocument.body.appendChild(panel)\n\nfunction run(motion) {\n  const handle = animate(\n    card,\n    [\n      { opacity: 0, transform: 'translateX(-18px)' },\n      { opacity: 1, transform: 'translateX(0)' },\n    ],\n    { duration: 320, easing: 'ease-out', motion, fill: 'both' },\n  )\n  status.textContent = 'Running with motion: ' + motion\n  handle.result.then((result) => {\n    status.textContent =\n      result.status === 'cancelled' ? 'Cancelled' : shouldReduceMotion(motion) ? 'Finished with reduced timing' : 'Finished'\n  })\n}\n\nsystemButton.addEventListener('click', () => run('system'))\nskipButton.addEventListener('click', () => run('reduced'))",
       "name": "motion - Reduced Motion"
     },
     {

package/data/refine.json

@@ -40,7 +40,7 @@
       "text": "['full', 'reduced', 'system']"
     },
     "default": "['full', 'reduced', 'system']",
-    "description": "App-level motion mode, mirroring `@vielzeug/necromancer`'s `MotionMode`:\nthe operating-system preference is the default, and an application with its\nown \"reduce motion\" setting can force either direction.\n\nThe mode is one attribute on `<html>` (`data-motion`), which the Reduced\nMotion block in `theme.css` reads: `'reduced'` zeroes every duration and\ntransition token and switches the `--_motion-*` escape hatches to `none`,\n`'full'` opts back in despite an OS-level reduction, and `'system'` (the\ndefault) removes the attribute. Because the tokens drive every CSS\nanimation and transition in the library, one call restyles all motion."
+    "description": "App-level motion mode, built on `@vielzeug/necromancer`'s `MotionMode`:\nthe operating-system preference is the default, and an application with its\nown \"reduce motion\" setting can force either direction.\n\nThe mode is one attribute on `<html>` (`data-motion`), which the Reduced\nMotion block in `theme.css` reads: `'reduced'` zeroes every duration and\ntransition token and switches the `--_motion-*` escape hatches to `none`,\n`'full'` opts back in despite an OS-level reduction, and `'system'` (the\ndefault) removes the attribute. Because the tokens drive every CSS\nanimation and transition in the library, one call restyles all motion."
   },
   {
     "kind": "function",
@@ -9079,6 +9079,10 @@
         "name": "viewfinder",
         "description": "Decorative scan frame over the preview"
       },
+      {
+        "name": "spinner",
+        "description": "Busy ring shown over the stage while the camera starts"
+      },
       {
         "name": "state",
         "description": "Idle/error/denied/unsupported/result panel"
@@ -11229,14 +11233,14 @@
       "text": "'ore-dock'"
     },
     "default": "'ore-dock'",
-    "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\n\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\n\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nPass `compact` when that hovering center is the bar's whole subject: the phone row then hugs its\ncontent instead of stretching edge to edge. Above the phone width every bar is a full-width strip.\n\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\n\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\n\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written."
+    "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\n\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\n\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nBy default, a phone row with one action zone hugs its content: `start` aligns to the leading\nedge, `commit` to the trailing edge, and tools to the middle. A lone `center` stays in the row.\nMultiple action zones and attached tools fill the row. `mobile-layout=\"full\"` always fills it;\n`mobile-layout=\"compact\"` always hugs and centers it. Above the phone width every bar is a\nfull-width strip.\n\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\n\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\n\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written."
   },
   {
     "kind": "class",
     "name": "OreDockElement",
     "tagName": "ore-dock",
     "customElement": true,
-    "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nPass `compact` when that hovering center is the bar's whole subject: the phone row then hugs its\ncontent instead of stretching edge to edge. Above the phone width every bar is a full-width strip.\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written.",
+    "description": "The navbar's other twin: a bar of actions that pins to a viewport edge while its container\nscrolls, and settles into the document flow once that container ends.\nThree named places and a tool row. `start` and `commit` are the flanks, `center` is the one\nplace allowed to carry a non-action (a clock, a stat block), and the default slot is the row\nof tools between them. A place nothing is assigned to leaves no gap and no flex line: the bar\ncollapses to the places it actually carries.\nWide, the bar is a full-width strip flush to its edge, wearing a hairline only while pinned.\nFrom the desktop width (1280 px) up, a claimed `center` sits dead-center because both sides of\nthe row take an equal share. Below the phone width (640 px) the bar becomes a single tool row in\nthe iOS toolbar grammar: the flanks stretch equally so the tools rest on the row's true middle,\nthe bar detaches from the viewport's foot, and `center` lifts out of the row to hover above it.\nBy default, a phone row with one action zone hugs its content: `start` aligns to the leading\nedge, `commit` to the trailing edge, and tools to the middle. A lone `center` stays in the row.\nMultiple action zones and attached tools fill the row. `mobile-layout=\"full\"` always fills it;\n`mobile-layout=\"compact\"` always hugs and centers it. Above the phone width every bar is a\nfull-width strip.\nThe bar's surface rides a pseudo-element, never the host: `backdrop-filter` on the host would\nmake it a containing block for `position: fixed` descendants, trapping any panel a slotted\ncontrol opens (a menu, a tooltip) inside the bar's own box.\nSizing reaches slotted content through custom properties only (`--dock-tool-flex`,\n`--dock-tool-radius`): a shadow-tree `::slotted()` declaration ranks below any document-tree\nrule on the same property, so a consumer that sets `flex` or `width` on a dock child outranks\nthe bar's own layout. Where a bar must stretch its tools (`attached`), it does so by reading\n`--dock-tool-flex`, so the consumer's lever is the property, not a fight with a declaration.\nEvery such rule is scoped through the zone that owns the slot, because `::slotted()` reaches the\nchildren of every slot the bar renders. The flanks keep their own shape.\nThe host reflects which places are filled as `data-start-claimed`, `data-center-claimed`,\n`data-tools-claimed`, and `data-commit-claimed`, plus `data-pinned` while the bar is holding its\nedge. Those exist because no selector can derive them: `:has()` cannot see slotted content and a\n`<slot>` always matches `:empty`. The phone layout needs no reflection: it is a plain media\nquery in the bar's own stylesheet, the same way every other refine breakpoint is written.",
     "summary": "",
     "attributes": [
       {
@@ -11261,11 +11265,11 @@
         "description": "Fuse the tool row into one segmented capsule"
       },
       {
-        "name": "compact",
+        "name": "mobile-layout",
         "type": {
-          "text": "boolean"
+          "text": "'full' | 'compact'"
         },
-        "description": "Shrink the phone row to its content and center it"
+        "description": "Phone sizing: 'auto' (default) | 'full' | 'compact'"
       },
       {
         "name": "label",
@@ -14438,109 +14442,6 @@
     "name": "MENU_CTX",
     "description": "Shared context propagated from `ore-menu` to its slotted `ore-menu-item` children."
   },
-  {
-    "kind": "variable",
-    "name": "MENU_ITEM_TAG",
-    "type": {
-      "text": "'ore-menu-item'"
-    },
-    "default": "'ore-menu-item'",
-    "description": "A selectable action item used inside `<ore-menu>`."
-  },
-  {
-    "kind": "class",
-    "name": "OreMenuItemElement",
-    "tagName": "ore-menu-item",
-    "customElement": true,
-    "description": "A selectable action item used inside `<ore-menu>`.",
-    "summary": "",
-    "attributes": [
-      {
-        "name": "checked",
-        "type": {
-          "text": "boolean"
-        },
-        "description": "Checked state for `checkbox` and `radio` item types"
-      },
-      {
-        "name": "disabled",
-        "type": {
-          "text": "boolean"
-        },
-        "description": "Disables selection and pointer interaction"
-      },
-      {
-        "name": "type",
-        "type": {
-          "text": "'checkbox'|'radio'"
-        },
-        "description": "Optional checkable menu item mode"
-      },
-      {
-        "name": "value",
-        "type": {
-          "text": "string"
-        },
-        "description": "Value emitted by parent menu on selection"
-      }
-    ],
-    "slots": [
-      {
-        "name": "",
-        "description": "Item label/content"
-      },
-      {
-        "name": "icon",
-        "description": "Optional leading icon content"
-      }
-    ],
-    "cssParts": [
-      {
-        "name": "item",
-        "description": "Root item container element."
-      },
-      {
-        "name": "item-label",
-        "description": "Label text container."
-      },
-      {
-        "name": "icon-slot",
-        "description": "Leading icon slot container."
-      }
-    ],
-    "cssProperties": [
-      {
-        "name": "--menu-item-hover-bg",
-        "description": "Background on hover"
-      },
-      {
-        "name": "--menu-item-focus-color",
-        "description": "Text color when keyboard-focused"
-      },
-      {
-        "name": "--menu-item-focus-bg",
-        "description": "Background when keyboard-focused"
-      },
-      {
-        "name": "--menu-item-selection-bg",
-        "description": "Background for checkbox/radio items (unselected)"
-      },
-      {
-        "name": "--menu-item-checked-color",
-        "description": "Text color when checked"
-      },
-      {
-        "name": "--menu-item-checked-bg",
-        "description": "Background when checked"
-      }
-    ],
-    "demos": [
-      {
-        "url": "",
-        "description": "```html\n<ore-menu-item value=\"edit\">Edit</ore-menu-item>\n<ore-menu-item value=\"delete\" disabled>Delete</ore-menu-item>\n<ore-menu-item type=\"checkbox\" value=\"wrap\" checked>Word wrap</ore-menu-item>\n<ore-menu-item type=\"radio\" value=\"left\">Align left</ore-menu-item>\n```"
-      }
-    ]
-  },
   {
     "kind": "variable",
     "name": "SEPARATOR_TAG",
@@ -14709,6 +14610,109 @@
       }
     ]
   },
+  {
+    "kind": "variable",
+    "name": "MENU_ITEM_TAG",
+    "type": {
+      "text": "'ore-menu-item'"
+    },
+    "default": "'ore-menu-item'",
+    "description": "A selectable action item used inside `<ore-menu>`."
+  },
+  {
+    "kind": "class",
+    "name": "OreMenuItemElement",
+    "tagName": "ore-menu-item",
+    "customElement": true,
+    "description": "A selectable action item used inside `<ore-menu>`.",
+    "summary": "",
+    "attributes": [
+      {
+        "name": "checked",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Checked state for `checkbox` and `radio` item types"
+      },
+      {
+        "name": "disabled",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Disables selection and pointer interaction"
+      },
+      {
+        "name": "type",
+        "type": {
+          "text": "'checkbox'|'radio'"
+        },
+        "description": "Optional checkable menu item mode"
+      },
+      {
+        "name": "value",
+        "type": {
+          "text": "string"
+        },
+        "description": "Value emitted by parent menu on selection"
+      }
+    ],
+    "slots": [
+      {
+        "name": "",
+        "description": "Item label/content"
+      },
+      {
+        "name": "icon",
+        "description": "Optional leading icon content"
+      }
+    ],
+    "cssParts": [
+      {
+        "name": "item",
+        "description": "Root item container element."
+      },
+      {
+        "name": "item-label",
+        "description": "Label text container."
+      },
+      {
+        "name": "icon-slot",
+        "description": "Leading icon slot container."
+      }
+    ],
+    "cssProperties": [
+      {
+        "name": "--menu-item-hover-bg",
+        "description": "Background on hover"
+      },
+      {
+        "name": "--menu-item-focus-color",
+        "description": "Text color when keyboard-focused"
+      },
+      {
+        "name": "--menu-item-focus-bg",
+        "description": "Background when keyboard-focused"
+      },
+      {
+        "name": "--menu-item-selection-bg",
+        "description": "Background for checkbox/radio items (unselected)"
+      },
+      {
+        "name": "--menu-item-checked-color",
+        "description": "Text color when checked"
+      },
+      {
+        "name": "--menu-item-checked-bg",
+        "description": "Background when checked"
+      }
+    ],
+    "demos": [
+      {
+        "url": "",
+        "description": "```html\n<ore-menu-item value=\"edit\">Edit</ore-menu-item>\n<ore-menu-item value=\"delete\" disabled>Delete</ore-menu-item>\n<ore-menu-item type=\"checkbox\" value=\"wrap\" checked>Word wrap</ore-menu-item>\n<ore-menu-item type=\"radio\" value=\"left\">Align left</ore-menu-item>\n```"
+      }
+    ]
+  },
   {
     "kind": "variable",
     "name": "POPOVER_TAG",