# useVisibilityTransition Experimental first slice. `useVisibilityTransition({ initial, enter, exit, duration })` returns a stable controller. Bind `controller.binding` to one primitive's `style.transition`. `fade()` creates an inert, reusable effect definition. `exit` defaults to `enter`, `initial` defaults to true, and duration defaults to 300 milliseconds. Zero duration commits the requested endpoint without material animation; an effect's configured tail still runs. Configuration is mount-time in this slice; rerendering does not reconfigure an existing controller. A binding belongs to its hook owner and Pibbl root, and supports one mounted receiver. Wrap multiple children in a `Group` to transition them together. Managed Layers within that root are supported. Removing the receiver releases its binding; removing the hook owner disposes the controller. Effect definitions can be shared between independent controllers. `show()` and `hide()` return promises with a unique `requestId`, `phase` (`enter` or `exit`), and `status` (`finished`, `cancelled`, or `disposed`). A new request cancels the previous pending request. Reversing an active fade preserves its current progress. Finished results follow the final committed frame; removing the owner settles pending requests as disposed. `finish()` reaches the requested endpoint. Already-settled requests finish immediately. The readonly `visible` signal is the requested state; `progress` is the current material reveal fraction. It can reach its endpoint while particles remain airborne. `status` stays entering or exiting until the effect tail finishes, then becomes visible or hidden; removal changes it to disposed. The fade captures the receiving primitive and its descendants as one subject, so overlapping children fade uniformly. Ordinary native filters run before the fade. A fully visible fade adds no filter boundary. Mixing boundary executors, such as displacement with native filters, follows the existing filter restriction. This first slice does not change layout, pointer targeting, focus, or unmount semantics. Applications must explicitly disable input while hiding. Keep the subject mounted until `hide()` finishes, then remove it if it is still requested hidden. Canvas transitions do not support native HtmlBox content. `embers({ region, charDepth?, burnWidth?, wind?, seed?, linger? })` is an experimental second effect. Its region is explicit in local coordinates; it burns upward and captures arbitrary Canvas children. The region must enclose all subject paint. It uses reusable Canvas surfaces without pixel readback. The jagged edge evolves within a narrow band. Particles keep their emission positions and advance on an independent forward clock, including during reversal. `linger` is their maximum lifetime in milliseconds (default 700; zero disables the tail). Material motion uses the controller duration; airborne particles can outlive it. Completion waits for the tail, so awaiting `hide()` before unmounting preserves the ash. `finish()` skips the remaining material motion and tail. The Bifrost, Embers, and Hologram visual reference remains in Energy Transitions. Automatic visibility binding and automatic unmount retention are not yet implemented. `hologram({ region, entry?, hue?, brightness?, fog?, glitch?, seed? })` reconstructs the captured subject with a diffuse scan ring, fog, and interference that settles as it materializes. `bifrost({ region, entry?, brightness?, hue?, stretch?, glow?, seed? })` stretches a blurred white subject toward the entry point, compresses it into place, flashes, then restores its original colors. Both definitions require an enclosing local region and leave exact visible/hidden endpoints. Common definitions use the same binding, reversal, and completion behavior: - `slide({ x?, y? })` translates from an offset while fading (default 24 downward). - `zoom({ origin, from? })` fades and scales from a factor around a local origin (default 0.8). - `wipe({ region, direction? })` reveals from left, right, top, or bottom (default left). - `blurReveal({ radius? })` fades from blur into sharp content (default 16). - `dissolve({ region, cellSize?, seed? })` uses a repeatable scattered cell mask. Cell size is a minimum; the grid is bounded to 128 cells per axis. These change captured pixels only. Presentation transforms and regions do not alter layout, focus bounds, or pointer geometry. All numeric parameters must be finite; intensity, blur, and scale parameters must be nonnegative. Definitions snapshot options when created. ## Custom effects and WASM `defineTransition({ render, linger? })` makes an inert reusable definition. Pibbl owns capture, scheduling, completion, and pooled surfaces. `render(frame)` is synchronous and receives `progress`, `phase`, a forward `elapsed` clock, historical `progressAt(time)`, the borrowed `context` and `source`, local `sourceBounds`, and `drawSource()`. Settled endpoints bypass the callback. With a nonzero tail, the callback also runs at progress 0 or 1 until the tail finishes; it must keep the material hidden or visible appropriately while drawing its remaining particles. ```ts import { defineTransition } from "@pibbl/core"; const effect = defineTransition({ render({ context, progress, drawSource }) { context.globalAlpha = progress * progress; drawSource(); }, }); ``` The numeric calculation can call an already-initialized WASM export instead. WASM initialization happens before creating the definition; buffers/modules belong to the application. The browser Canvas drawing bridge remains JavaScript. Bifrost, Embers, and Hologram lazily load embedded WASM kernels for their patch, burn/particle, and fog/glitch calculations. Each used definition owns fixed memory with reused views and no network fetch: 128 KiB for Embers, 64 KiB for Bifrost and Hologram. Embers uses 1,200 airborne particle slots, with bright starts and gradual cooling and fading. Embers batches particle birth times into the JavaScript controller’s history lookup before sampling its WASM descriptors. Simple built-in effects remain JavaScript. WASM is not claimed to accelerate native Canvas drawing. Environments with a restrictive Content Security Policy must permit WebAssembly compilation (for example, `wasm-unsafe-eval`); compilation errors follow normal render failure cleanup. Callbacks must not write signals, start clocks, return promises, retain borrowed frames/surfaces, mutate the source canvas, or rely on an exact callback count. Keep computation seekable from the supplied inputs. When drawing `source` directly, map its pixels to `sourceBounds` in the local context. Pixels outside the current capture window are not available. Exceptions propagate through Pibbl's normal render failure handling. Layout and event geometry remain unchanged. `elapsed` and `progressAt(time)` use milliseconds from the current run's start. Reversals preserve the run clock and all earlier progress segments, including any hold until the scheduler accepts the reversal. A fresh run resets that history. Negative history times return the initial progress; inputs must be finite. Different enter and exit definitions use their own tail durations. A repeated request during a tail cancels the previous request and restarts that tail. Transitions compose with ordinary filters, clipping, transforms, and nested managed Layers under the existing filter executor restrictions. A custom-renderer failure follows normal Pibbl failure cleanup: the hook owner is torn down, pending requests resolve as `disposed`, and its animation participants are released. ## Opt-in Ember physics `embers({ region, linger: 1400, physics: { gravity: [0, 500], wind: [60, 0], drag: 4, restitution: 0.5, collide } })` opts into a controller-owned fixed-step particle simulation. Coordinates are local to the receiving primitive; forces use units/second², wind uses units/second, and drag uses inverse seconds. `linger` must be positive. Gravity defaults to `[0,-60]`, wind to `[0,-45]`, drag to 4, and restitution to 0.5. For a local physics world, use `physics: { obstacles: physicsObstacles2D(world) }` with `physicsObstacles2D` imported from `@pibbl/core/physics/2d`. The receiver and world must share local coordinates. The source is read once per advancing frame; changed packed geometry is copied directly into fixed WASM memory. All 1,200 particle sweeps and bounce calculations run in one WASM call per substep. Boxes, ellipses, polygons, and boxes with equal rounded corners are supported, with a maximum of 8,192 packed numbers; unsupported world shapes or capacity overflow report an error. Sensors are excluded. The source supplies committed geometry; particles do not push bodies or inherit obstacle velocity. A custom source must increment its `revision` when geometry changes. Its typed arrays are borrowed synchronously and never retained. The optional synchronous `collide(from, to)` callback receives a swept point segment and returns the closest `{ fraction, normal }` hit or `undefined`. It runs during Advance and must not write signals or retain borrowed data. Normal is a local outward vector, fraction is in `[0,1]`. Query a local physics world in this callback for custom obstacle interaction, but that performs JavaScript work per particle; prefer `obstacles` for large populations. `collide` and `obstacles` are mutually exclusive. This is one-way point collision: particles do not push bodies. Keep the receiver and queried world in the same coordinate space or explicitly convert points and normals. No physics-world import occurs implicitly. The simulation takes 1/60-second steps with at most four catch-up steps per frame; excess wall time is dropped. Reversal preserves existing motion; a fresh settled run starts a fresh simulation. Completion still waits for the particle tail, and owner disposal stops simulation. Physics owns 256 KiB fixed WASM memory per used controller. The existing analytic effect remains the default when physics is omitted. ## API details from source ### fade A uniform fade of the receiving primitive and all of its descendants together. ```ts fade: () => PibblTransitionEffect ``` Related API: [fade](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Returns A fade effect to use with a visibility transition. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/fade.ts:29](/source/packages/core/src/lib/transitions/fade-ts/#L29) ### PibblTransitionEffect Immutable, inert visual definition; mounted state belongs to its controller. ```ts interface PibblTransitionEffect ``` Related API: [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [fade](/reference/hooks/use-visibility-transition/) [PibblVisibilityTransitionOptions](/reference/hooks/use-visibility-transition/) [embers](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/fade.ts:14](/source/packages/core/src/lib/transitions/fade-ts/#L14) ### PibblTransitionBinding An opaque connection between one transition controller and its painted subject. ```ts interface PibblTransitionBinding ``` Related API: [PibblTransitionBinding](/reference/hooks/use-visibility-transition/). #### See also [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/binding.ts:13](/source/packages/core/src/lib/transitions/binding-ts/#L13) ### useVisibilityTransition Explicitly controlled visibility. It does not retain unmounted content or alter targeting. ```ts useVisibilityTransition: (options: PibblVisibilityTransitionOptions) => PibblVisibilityTransition ``` Related API: [useVisibilityTransition](/reference/hooks/use-visibility-transition/), [PibblVisibilityTransitionOptions](/reference/hooks/use-visibility-transition/), [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Visibility signal, effect, timing, and lifecycle options. See [PibblVisibilityTransitionOptions](/reference/hooks/use-visibility-transition/) . #### Returns Stable mount-owned controls for visibility and transition completion. See [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/) . #### See also [PibblVisibilityTransitionOptions](/reference/hooks/use-visibility-transition/) [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:113](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L113) ### PibblVisibilityTransition Mount-owned visibility controls, reactive progress and status, and a primitive presentation binding. ```ts interface PibblVisibilityTransition ``` Related API: [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/). #### See also [PibblTransitionBinding](/reference/hooks/use-visibility-transition/) [Signal](/reference/types/canvas-runtime/#signal) [PibblVisibilityTransitionStatus](/reference/hooks/use-visibility-transition/) [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/) [useVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:66](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L66) #### Properties and methods
binding ```ts readonly binding: PibblTransitionBinding ``` Related API: [PibblTransitionBinding](/reference/hooks/use-visibility-transition/). Presentation binding to assign to the receiving primitive's style.transition. See PibblTransitionBinding. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:71](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L71)
visible ```ts readonly visible: Signal ``` Related API: [Signal](/reference/types/canvas-runtime/#signal). Readonly view of the requested visibility target. See Signal. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:73](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L73)
progress ```ts readonly progress: Signal ``` Related API: [Signal](/reference/types/canvas-runtime/#signal). Normalized progress through the current animation or transition. See Signal. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:75](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L75)
status ```ts readonly status: Signal ``` Related API: [Signal](/reference/types/canvas-runtime/#signal), [PibblVisibilityTransitionStatus](/reference/hooks/use-visibility-transition/). Reactive visibility-transition lifecycle state. See Signal, PibblVisibilityTransitionStatus. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:80](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L80)
show ```ts show: () => Promise ``` Related API: [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/). Requests entry and resolves with the request's finished, cancelled, or disposed outcome. See PibblVisibilityTransitionResult. ##### Returns A promise settling with the request's completion or interruption result. See [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/) . [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:87](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L87)
hide ```ts hide: () => Promise ``` Related API: [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/). Requests exit and resolves with the request's finished, cancelled, or disposed outcome. See PibblVisibilityTransitionResult. ##### Returns A promise settling with the request's completion or interruption result. See [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/) . [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:94](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L94)
finish ```ts finish: () => void ``` Forces the currently requested transition to its endpoint. See PibblVisibilityTransition . [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:99](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L99)
### PibblVisibilityTransitionOptions Enter and exit effects and lifecycle configuration for visibility transitions. ```ts interface PibblVisibilityTransitionOptions ``` Related API: [PibblVisibilityTransitionOptions](/reference/hooks/use-visibility-transition/). #### See also [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [useVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:41](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L41) #### Properties and methods
initial (optional) ```ts readonly initial?: boolean | undefined ``` Mount-time options in the first slice. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:43](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L43)
enter ```ts readonly enter: PibblTransitionEffect ``` Related API: [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). Effect used when moving toward visible. See PibblTransitionEffect. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:45](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L45)
exit (optional) ```ts readonly exit?: PibblTransitionEffect | undefined ``` Related API: [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). Effect used when moving toward hidden; defaults to the enter effect. See PibblTransitionEffect. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:50](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L50)
duration (optional) ```ts readonly duration?: number | undefined ``` Transition duration in milliseconds; defaults to 300. See PibblVisibilityTransitionOptions. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:55](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L55)
### PibblVisibilityTransitionResult Settlement of one show or hide request, including its request identifier, phase, and outcome. ```ts interface PibblVisibilityTransitionResult ``` Related API: [PibblVisibilityTransitionResult](/reference/hooks/use-visibility-transition/). #### See also [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:24](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L24) #### Properties and methods
requestId ```ts readonly requestId: number ``` Monotonic identifier of the visibility request that produced this result. See PibblVisibilityTransitionResult. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:29](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L29)
phase ```ts readonly phase: "enter" | "exit" ``` Selects `"enter"`, `"exit"` for phase. See PibblVisibilityTransitionResult. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:31](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L31)
status ```ts readonly status: "cancelled" | "disposed" | "finished" ``` How this specific show or hide request settled. See PibblVisibilityTransitionResult. [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:33](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L33)
### PibblVisibilityTransitionStatus The current hidden, entering, visible, exiting, or disposed transition state. ```ts type PibblVisibilityTransitionStatus = 'hidden' | 'entering' | 'visible' | 'exiting' | 'disposed' ``` Related API: [PibblVisibilityTransitionStatus](/reference/hooks/use-visibility-transition/). #### See also [PibblVisibilityTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/hooks/use-visibility-transition.ts:18](/source/packages/core/src/lib/hooks/use-visibility-transition-ts/#L18) ### embers A seeded burn/char front over one captured subtree, with outward drifting fragments. ```ts embers: (options: PibblEmbersOptions) => PibblTransitionEffect ``` Related API: [embers](/reference/hooks/use-visibility-transition/), [PibblEmbersOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Ember emission, motion, appearance, and optional collision settings. See [PibblEmbersOptions](/reference/hooks/use-visibility-transition/) . #### Returns An ember transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblEmbersOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/embers.ts:106](/source/packages/core/src/lib/transitions/embers-ts/#L106) ### PibblEmbersOptions Appearance, motion, and timing controls for an ember visibility transition. ```ts interface PibblEmbersOptions ``` Related API: [PibblEmbersOptions](/reference/hooks/use-visibility-transition/). #### See also [PibblEmbersPhysicsOptions](/reference/hooks/use-visibility-transition/) [embers](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/embers.ts:20](/source/packages/core/src/lib/transitions/embers-ts/#L20) #### Properties and methods
region ```ts readonly region: Readonly<{ x: number; y: number; width: number; height: number; }> ``` Local coordinates enclosing the subject; the burn travels upward through this area. [View source — packages/core/src/lib/transitions/embers.ts:22](/source/packages/core/src/lib/transitions/embers-ts/#L22)
charDepth (optional) ```ts readonly charDepth?: number | undefined ``` Depth of the darkened char region along the ember transition boundary. See PibblEmbersOptions. [View source — packages/core/src/lib/transitions/embers.ts:48](/source/packages/core/src/lib/transitions/embers-ts/#L48)
burnWidth (optional) ```ts readonly burnWidth?: number | undefined ``` Width of the glowing burn region along the transition boundary. See PibblEmbersOptions. [View source — packages/core/src/lib/transitions/embers.ts:52](/source/packages/core/src/lib/transitions/embers-ts/#L52)
wind (optional) ```ts readonly wind?: number | undefined ``` Horizontal drift in local units; negative blows left. [View source — packages/core/src/lib/transitions/embers.ts:54](/source/packages/core/src/lib/transitions/embers-ts/#L54)
seed (optional) ```ts readonly seed?: number | undefined ``` Seed used for deterministic sampling or simulation initialization. See PibblEmbersOptions. [View source — packages/core/src/lib/transitions/embers.ts:59](/source/packages/core/src/lib/transitions/embers-ts/#L59)
linger (optional) ```ts readonly linger?: number | undefined ``` Maximum airborne particle lifetime in milliseconds; completion includes this tail. Default 700. [View source — packages/core/src/lib/transitions/embers.ts:64](/source/packages/core/src/lib/transitions/embers-ts/#L64)
physics (optional) ```ts readonly physics?: PibblEmbersPhysicsOptions | undefined ``` Related API: [PibblEmbersPhysicsOptions](/reference/hooks/use-visibility-transition/). Opt-in local force simulation and collision. Requires a positive linger. [View source — packages/core/src/lib/transitions/embers.ts:66](/source/packages/core/src/lib/transitions/embers-ts/#L66)
### hologram A diffuse scan reconstructs the captured subject while interference settles. ```ts hologram: (options: PibblHologramOptions) => PibblTransitionEffect ``` Related API: [hologram](/reference/hooks/use-visibility-transition/), [PibblHologramOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Hologram appearance and animation settings. See [PibblHologramOptions](/reference/hooks/use-visibility-transition/). #### Returns A hologram transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblHologramOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/hologram.ts:52](/source/packages/core/src/lib/transitions/hologram-ts/#L52) ### PibblHologramOptions Color, scanning, and distortion controls for a hologram visibility transition. ```ts interface PibblHologramOptions ``` Related API: [PibblHologramOptions](/reference/hooks/use-visibility-transition/). #### See also [hologram](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/hologram.ts:13](/source/packages/core/src/lib/transitions/hologram-ts/#L13) #### Properties and methods
region ```ts readonly region: TransitionRegion ``` Logical region over which the effect is evaluated. See TransitionRegion. [View source — packages/core/src/lib/transitions/hologram.ts:15](/source/packages/core/src/lib/transitions/hologram-ts/#L15)
entry (optional) ```ts readonly entry?: Readonly<{ x: number; y: number; }> | undefined ``` Entry location or direction used by the transition. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:17](/source/packages/core/src/lib/transitions/hologram-ts/#L17)
hue (optional) ```ts readonly hue?: number | undefined ``` Hue control for the transition's emitted color. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:30](/source/packages/core/src/lib/transitions/hologram-ts/#L30)
brightness (optional) ```ts readonly brightness?: number | undefined ``` Related API: [brightness](/reference/types/filters/#brightness). Brightness control for the transition effect. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:32](/source/packages/core/src/lib/transitions/hologram-ts/#L32)
fog (optional) ```ts readonly fog?: number | undefined ``` Fog intensity used by the hologram effect. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:34](/source/packages/core/src/lib/transitions/hologram-ts/#L34)
glitch (optional) ```ts readonly glitch?: number | undefined ``` Distortion intensity used by the hologram effect. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:36](/source/packages/core/src/lib/transitions/hologram-ts/#L36)
seed (optional) ```ts readonly seed?: number | undefined ``` Seed used for deterministic sampling or simulation initialization. See PibblHologramOptions. [View source — packages/core/src/lib/transitions/hologram.ts:41](/source/packages/core/src/lib/transitions/hologram-ts/#L41)
### bifrost A prismatic beam stretches a white-hot captured subject toward its entry point. ```ts bifrost: (options: PibblBifrostOptions) => PibblTransitionEffect ``` Related API: [bifrost](/reference/hooks/use-visibility-transition/), [PibblBifrostOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Bifrost appearance and animation settings. See [PibblBifrostOptions](/reference/hooks/use-visibility-transition/). #### Returns A bifrost transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblBifrostOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/bifrost.ts:50](/source/packages/core/src/lib/transitions/bifrost-ts/#L50) ### PibblBifrostOptions Color and motion controls for a bifrost visibility transition. ```ts interface PibblBifrostOptions ``` Related API: [PibblBifrostOptions](/reference/hooks/use-visibility-transition/). #### See also [bifrost](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/bifrost.ts:11](/source/packages/core/src/lib/transitions/bifrost-ts/#L11) #### Properties and methods
region ```ts readonly region: TransitionRegion ``` Logical region over which the effect is evaluated. See TransitionRegion. [View source — packages/core/src/lib/transitions/bifrost.ts:13](/source/packages/core/src/lib/transitions/bifrost-ts/#L13)
entry (optional) ```ts readonly entry?: Readonly<{ x: number; y: number; }> | undefined ``` Entry location or direction used by the transition. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:15](/source/packages/core/src/lib/transitions/bifrost-ts/#L15)
brightness (optional) ```ts readonly brightness?: number | undefined ``` Related API: [brightness](/reference/types/filters/#brightness). Brightness control for the transition effect. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:28](/source/packages/core/src/lib/transitions/bifrost-ts/#L28)
hue (optional) ```ts readonly hue?: number | undefined ``` Hue control for the transition's emitted color. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:30](/source/packages/core/src/lib/transitions/bifrost-ts/#L30)
stretch (optional) ```ts readonly stretch?: number | undefined ``` Amount of stretching applied by the transition. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:32](/source/packages/core/src/lib/transitions/bifrost-ts/#L32)
glow (optional) ```ts readonly glow?: number | undefined ``` Intensity of the electrical halo around the core. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:34](/source/packages/core/src/lib/transitions/bifrost-ts/#L34)
seed (optional) ```ts readonly seed?: number | undefined ``` Seed used for deterministic sampling or simulation initialization. See PibblBifrostOptions. [View source — packages/core/src/lib/transitions/bifrost.ts:39](/source/packages/core/src/lib/transitions/bifrost-ts/#L39)
### slide Translate from an offset while fading; exit follows the same path backward. ```ts slide: (options?: PibblSlideOptions) => PibblTransitionEffect ``` Related API: [slide](/reference/hooks/use-visibility-transition/), [PibblSlideOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Slide direction and displacement settings; defaults apply when omitted. See [PibblSlideOptions](/reference/hooks/use-visibility-transition/) . #### Returns A slide transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblSlideOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:93](/source/packages/core/src/lib/transitions/common-ts/#L93) ### zoom Scale around an explicit local origin while fading. ```ts zoom: (options: PibblZoomOptions) => PibblTransitionEffect ``` Related API: [zoom](/reference/hooks/use-visibility-transition/), [PibblZoomOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Zoom scale and origin settings. See [PibblZoomOptions](/reference/hooks/use-visibility-transition/). #### Returns A zoom transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblZoomOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:106](/source/packages/core/src/lib/transitions/common-ts/#L106) ### wipe Reveal from one side of an explicit local region. ```ts wipe: (options: PibblWipeOptions) => PibblTransitionEffect ``` Related API: [wipe](/reference/hooks/use-visibility-transition/), [PibblWipeOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Wipe direction and shape settings. See [PibblWipeOptions](/reference/hooks/use-visibility-transition/). #### Returns A wipe transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblWipeOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:119](/source/packages/core/src/lib/transitions/common-ts/#L119) ### blurReveal Resolve from a soft transparent image into crisp content using native filters. ```ts blurReveal: (options?: PibblBlurRevealOptions) => PibblTransitionEffect ``` Related API: [blurReveal](/reference/hooks/use-visibility-transition/), [PibblBlurRevealOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Blur settings; defaults apply when omitted. See [PibblBlurRevealOptions](/reference/hooks/use-visibility-transition/). #### Returns A blur-reveal transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblBlurRevealOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:137](/source/packages/core/src/lib/transitions/common-ts/#L137) ### dissolve A deterministic scattered reveal. Cell size is a minimum; the grid is capped at 128×128. ```ts dissolve: (options: PibblDissolveOptions) => PibblTransitionEffect ``` Related API: [dissolve](/reference/hooks/use-visibility-transition/), [PibblDissolveOptions](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`options`** — Dissolve sampling and appearance settings. See [PibblDissolveOptions](/reference/hooks/use-visibility-transition/). #### Returns A dissolve transition effect. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### See also [PibblDissolveOptions](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:150](/source/packages/core/src/lib/transitions/common-ts/#L150) ### PibblSlideOptions Direction and displacement controls for a sliding visibility transition. ```ts interface PibblSlideOptions ``` Related API: [PibblSlideOptions](/reference/hooks/use-visibility-transition/). #### See also [slide](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:10](/source/packages/core/src/lib/transitions/common-ts/#L10) #### Properties and methods
x (optional) ```ts readonly x?: number | undefined ``` Horizontal coordinate or displacement in the containing coordinate system. See PibblSlideOptions. [View source — packages/core/src/lib/transitions/common.ts:15](/source/packages/core/src/lib/transitions/common-ts/#L15)
y (optional) ```ts readonly y?: number | undefined ``` Vertical coordinate or displacement in the containing coordinate system. See PibblSlideOptions. [View source — packages/core/src/lib/transitions/common.ts:20](/source/packages/core/src/lib/transitions/common-ts/#L20)
### PibblZoomOptions Scale controls for a zooming visibility transition. ```ts interface PibblZoomOptions ``` Related API: [PibblZoomOptions](/reference/hooks/use-visibility-transition/). #### See also [zoom](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:27](/source/packages/core/src/lib/transitions/common-ts/#L27) #### Properties and methods
origin ```ts readonly origin: Readonly<{ x: number; y: number; }> ``` Origin of the transform or geometric query. See PibblZoomOptions. [View source — packages/core/src/lib/transitions/common.ts:29](/source/packages/core/src/lib/transitions/common-ts/#L29)
from (optional) ```ts readonly from?: number | undefined ``` Starting endpoint or value. See PibblZoomOptions. [View source — packages/core/src/lib/transitions/common.ts:42](/source/packages/core/src/lib/transitions/common-ts/#L42)
### PibblWipeOptions Direction and clipping controls for a wiping visibility transition. ```ts interface PibblWipeOptions ``` Related API: [PibblWipeOptions](/reference/hooks/use-visibility-transition/). #### See also [wipe](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:49](/source/packages/core/src/lib/transitions/common-ts/#L49) #### Properties and methods
region ```ts readonly region: TransitionRegion ``` Logical region over which the effect is evaluated. See TransitionRegion. [View source — packages/core/src/lib/transitions/common.ts:51](/source/packages/core/src/lib/transitions/common-ts/#L51)
direction (optional) ```ts readonly direction?: "bottom" | "left" | "right" | "top" | undefined ``` Direction in which this operation proceeds. See PibblWipeOptions. [View source — packages/core/src/lib/transitions/common.ts:53](/source/packages/core/src/lib/transitions/common-ts/#L53)
### PibblBlurRevealOptions Blur controls for a visibility reveal transition. ```ts interface PibblBlurRevealOptions ``` Related API: [PibblBlurRevealOptions](/reference/hooks/use-visibility-transition/). #### See also [blurReveal](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:60](/source/packages/core/src/lib/transitions/common-ts/#L60) #### Properties and methods
radius (optional) ```ts readonly radius?: number | undefined ``` Radius in the coordinate system of this geometry or effect. See PibblBlurRevealOptions. [View source — packages/core/src/lib/transitions/common.ts:64](/source/packages/core/src/lib/transitions/common-ts/#L64)
### PibblDissolveOptions Noise and threshold controls for a dissolving visibility transition. ```ts interface PibblDissolveOptions ``` Related API: [PibblDissolveOptions](/reference/hooks/use-visibility-transition/). #### See also [dissolve](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/common.ts:71](/source/packages/core/src/lib/transitions/common-ts/#L71) #### Properties and methods
region ```ts readonly region: TransitionRegion ``` Logical region over which the effect is evaluated. See TransitionRegion. [View source — packages/core/src/lib/transitions/common.ts:73](/source/packages/core/src/lib/transitions/common-ts/#L73)
cellSize (optional) ```ts readonly cellSize?: number | undefined ``` Size of the dissolve noise cells. See PibblDissolveOptions. [View source — packages/core/src/lib/transitions/common.ts:75](/source/packages/core/src/lib/transitions/common-ts/#L75)
seed (optional) ```ts readonly seed?: number | undefined ``` Seed used for deterministic sampling or simulation initialization. See PibblDissolveOptions. [View source — packages/core/src/lib/transitions/common.ts:80](/source/packages/core/src/lib/transitions/common-ts/#L80)
### defineTransition Inert custom definition. The callback may call synchronous JS or WASM kernels. ```ts defineTransition: (definition: PibblTransitionDefinition) => PibblTransitionEffect ``` Related API: [defineTransition](/reference/hooks/use-visibility-transition/), [PibblTransitionDefinition](/reference/hooks/use-visibility-transition/), [PibblTransitionEffect](/reference/hooks/use-visibility-transition/). #### Parameters - **`definition`** — Renderer and metadata defining the effect. See [PibblTransitionDefinition](/reference/hooks/use-visibility-transition/) . #### Returns A transition effect usable by the visibility transition hook. See [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) . #### See also [PibblTransitionDefinition](/reference/hooks/use-visibility-transition/) [PibblTransitionEffect](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/define-transition.ts:67](/source/packages/core/src/lib/transitions/define-transition-ts/#L67) ### PibblTransitionDefinition Synchronous transition rendering callback and optional post-transition linger duration. ```ts interface PibblTransitionDefinition ``` Related API: [PibblTransitionDefinition](/reference/hooks/use-visibility-transition/). #### See also [PibblTransitionRenderFrame](/reference/hooks/use-visibility-transition/) [defineTransition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/define-transition.ts:45](/source/packages/core/src/lib/transitions/define-transition-ts/#L45) #### Properties and methods
render ```ts readonly render: (frame: Readonly) => void ``` Related API: [PibblTransitionRenderFrame](/reference/hooks/use-visibility-transition/). Renders the current data or resources using the supplied context. See PibblTransitionRenderFrame. ##### Parameters - **`frame`** — Captured source, presentation context, progress, and timing services. See [PibblTransitionRenderFrame](/reference/hooks/use-visibility-transition/) . [View source — packages/core/src/lib/transitions/define-transition.ts:52](/source/packages/core/src/lib/transitions/define-transition-ts/#L52)
linger (optional) ```ts readonly linger?: number | undefined ``` Additional milliseconds after material reaches its target. Default zero. [View source — packages/core/src/lib/transitions/define-transition.ts:54](/source/packages/core/src/lib/transitions/define-transition-ts/#L54)
### PibblTransitionRenderFrame Progress, geometry, and drawing context supplied to a custom transition renderer. ```ts interface PibblTransitionRenderFrame ``` Related API: [PibblTransitionRenderFrame](/reference/hooks/use-visibility-transition/). #### See also [PibblTransitionDefinition](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/define-transition.ts:11](/source/packages/core/src/lib/transitions/define-transition-ts/#L11) #### Properties and methods
context ```ts readonly context: OffscreenCanvasRenderingContext2D ``` Borrowed for this synchronous callback only. Coordinates are receiver-local. [View source — packages/core/src/lib/transitions/define-transition.ts:13](/source/packages/core/src/lib/transitions/define-transition-ts/#L13)
source ```ts readonly source: OffscreenCanvas ``` Captured source pixels available during this synchronous rendering callback. See PibblTransitionRenderFrame. [View source — packages/core/src/lib/transitions/define-transition.ts:15](/source/packages/core/src/lib/transitions/define-transition-ts/#L15)
sourceBounds ```ts readonly sourceBounds: Readonly ``` Bounds of the source pixels supplied to the transition. See TransitionRegion. [View source — packages/core/src/lib/transitions/define-transition.ts:17](/source/packages/core/src/lib/transitions/define-transition-ts/#L17)
progress ```ts readonly progress: number ``` Normalized progress through the current animation or transition. See PibblTransitionRenderFrame. [View source — packages/core/src/lib/transitions/define-transition.ts:22](/source/packages/core/src/lib/transitions/define-transition-ts/#L22)
phase ```ts readonly phase: "enter" | "exit" ``` Selects `"enter"`, `"exit"` for phase. See PibblTransitionRenderFrame. [View source — packages/core/src/lib/transitions/define-transition.ts:24](/source/packages/core/src/lib/transitions/define-transition-ts/#L24)
elapsed ```ts readonly elapsed: number ``` Forward milliseconds since this run began, unaffected by reversals. [View source — packages/core/src/lib/transitions/define-transition.ts:26](/source/packages/core/src/lib/transitions/define-transition-ts/#L26)
progressAt ```ts readonly progressAt: (elapsed: number) => number ``` Material progress at an earlier time in this run (useful for particle births). ##### Parameters - **`elapsed`** — Elapsed transition time in milliseconds. ##### Returns Transition progress at the requested time. [View source — packages/core/src/lib/transitions/define-transition.ts:32](/source/packages/core/src/lib/transitions/define-transition-ts/#L32)
drawSource ```ts readonly drawSource: () => void ``` Draws the captured source into the transition's current rendering context. See PibblTransitionRenderFrame. [View source — packages/core/src/lib/transitions/define-transition.ts:37](/source/packages/core/src/lib/transitions/define-transition-ts/#L37)
### PibblEmbersPhysicsOptions Collision and physical motion options for transition embers. ```ts interface PibblEmbersPhysicsOptions ``` Related API: [PibblEmbersPhysicsOptions](/reference/hooks/use-visibility-transition/). #### See also [PibblEmberCollision](/reference/hooks/use-visibility-transition/) [PibblEmbersOptions](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/embers-physics.ts:21](/source/packages/core/src/lib/transitions/embers-physics-ts/#L21) #### Properties and methods
gravity (optional) ```ts readonly gravity?: readonly [number, number] | undefined ``` Local units/second². Default [0, -60]. [View source — packages/core/src/lib/transitions/embers-physics.ts:23](/source/packages/core/src/lib/transitions/embers-physics-ts/#L23)
wind (optional) ```ts readonly wind?: readonly [number, number] | undefined ``` Target air velocity in local units/second. Default [0, -45]. [View source — packages/core/src/lib/transitions/embers-physics.ts:25](/source/packages/core/src/lib/transitions/embers-physics-ts/#L25)
drag (optional) ```ts readonly drag?: number | undefined ``` Velocity damping per second. Default 4. [View source — packages/core/src/lib/transitions/embers-physics.ts:27](/source/packages/core/src/lib/transitions/embers-physics-ts/#L27)
restitution (optional) ```ts readonly restitution?: number | undefined ``` Bounce coefficient, zero to one. Default 0.5. [View source — packages/core/src/lib/transitions/embers-physics.ts:29](/source/packages/core/src/lib/transitions/embers-physics-ts/#L29)
obstacles (optional) ```ts readonly obstacles?: Readonly<{ read(): Readonly<{ revision: number; boxes: Float64Array; ellipses: Float64Array; polygons: Float64Array; }>; }> | undefined ``` Packed committed solids in receiver-local coordinates (e.g. physicsObstacles2D). Revision must change whenever data changes. Up to 8192 packed numbers. Sweeps run as one WASM batch; mutually exclusive with collide. [View source — packages/core/src/lib/transitions/embers-physics.ts:34](/source/packages/core/src/lib/transitions/embers-physics-ts/#L34)
collide (optional) ```ts readonly collide?: ((from: readonly [number, number], to: readonly [number, number]) => PibblEmberCollision | undefined) | undefined ``` Related API: [PibblEmberCollision](/reference/hooks/use-visibility-transition/). Synchronous point sweep, called in Advance. Return the closest hit, if any. ##### Parameters - **`from`** — Previous particle position. - **`to`** — Proposed particle position. ##### Returns Collision information, or undefined when motion is unobstructed. See [PibblEmberCollision](/reference/hooks/use-visibility-transition/) . [View source — packages/core/src/lib/transitions/embers-physics.ts:67](/source/packages/core/src/lib/transitions/embers-physics-ts/#L67)
### PibblEmberCollision Collision information produced by an ember's physical interaction. ```ts interface PibblEmberCollision ``` Related API: [PibblEmberCollision](/reference/hooks/use-visibility-transition/). #### See also [PibblEmbersPhysicsOptions](/reference/hooks/use-visibility-transition/) [View source — packages/core/src/lib/transitions/embers-physics.ts:9](/source/packages/core/src/lib/transitions/embers-physics-ts/#L9) #### Properties and methods
fraction ```ts readonly fraction: number ``` Fraction of the swept segment at impact, from zero to one. [View source — packages/core/src/lib/transitions/embers-physics.ts:11](/source/packages/core/src/lib/transitions/embers-physics-ts/#L11)
normal ```ts readonly normal: readonly [number, number] ``` Outward surface normal in the receiving primitive's local coordinates. [View source — packages/core/src/lib/transitions/embers-physics.ts:13](/source/packages/core/src/lib/transitions/embers-physics-ts/#L13)
## Implementation guidance for agents Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow. ## Complete minimal examples - [Define a custom transition](/minimal-examples/transitions/custom/): Render a captured subtree with a custom synchronous alpha curve. [Plain source](/minimal/transitions/custom.tsx) - [slide enter and exit](/minimal-examples/transitions/slide/): Show and hide a captured Pibbl subtree with the slide transition. [Plain source](/minimal/transitions/slide.tsx) - [zoom enter and exit](/minimal-examples/transitions/zoom/): Show and hide a captured Pibbl subtree with the zoom transition. [Plain source](/minimal/transitions/zoom.tsx) - [wipe enter and exit](/minimal-examples/transitions/wipe/): Show and hide a captured Pibbl subtree with the wipe transition. [Plain source](/minimal/transitions/wipe.tsx) - [blurReveal enter and exit](/minimal-examples/transitions/blur-reveal/): Show and hide a captured Pibbl subtree with the blurReveal transition. [Plain source](/minimal/transitions/blur-reveal.tsx) - [dissolve enter and exit](/minimal-examples/transitions/dissolve/): Show and hide a captured Pibbl subtree with the dissolve transition. [Plain source](/minimal/transitions/dissolve.tsx) - [hologram enter and exit](/minimal-examples/transitions/hologram/): Project a spacecraft with swept wings, a transparent window, and detached exhaust shapes. Hologram follows the painted silhouette, not a filled rectangle. The first entrance runs automatically; Show and Hide replay either direction. [Plain source](/minimal/transitions/hologram.tsx) - [bifrost enter and exit](/minimal-examples/transitions/bifrost/): Beam a transparent logo in and out with Bifrost, using a dark stage and space for its luminous trails. The first entrance runs automatically. [Plain source](/minimal/transitions/bifrost.tsx) - [embers enter and exit](/minimal-examples/transitions/embers/): Break a transparent logo into glowing Embers, with a dark stage and space for falling particles. The first entrance runs automatically. [Plain source](/minimal/transitions/embers.tsx) - [fade enter and exit](/minimal-examples/transitions/fade/): Show and hide a captured Pibbl subtree with the fade transition. [Plain source](/minimal/transitions/fade.tsx) ## Interactive examples - [Visibility Transitions](/examples/visibility-transitions/) · [Full page](/experience/visibility-transitions/) - [Embers Physics](/examples/embers-physics/) · [Full page](/experience/embers-physics/) ## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.