useVisibilityTransition

Read as Markdown

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.

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.

fade: () => PibblTransitionEffect

Related API: fade, PibblTransitionEffect.

Returns

A fade effect to use with a visibility transition. See PibblTransitionEffect.

PibblTransitionEffect

Immutable, inert visual definition; mounted state belongs to its controller.

interface PibblTransitionEffect

Related API: PibblTransitionEffect.

PibblTransitionBinding

An opaque connection between one transition controller and its painted subject.

interface PibblTransitionBinding

Related API: PibblTransitionBinding.

useVisibilityTransition

Explicitly controlled visibility. It does not retain unmounted content or alter targeting.

useVisibilityTransition: (options: PibblVisibilityTransitionOptions) => PibblVisibilityTransition

Parameters

options — Visibility signal, effect, timing, and lifecycle options. See PibblVisibilityTransitionOptions .

Returns

Stable mount-owned controls for visibility and transition completion. See PibblVisibilityTransition .

PibblVisibilityTransition

Mount-owned visibility controls, reactive progress and status, and a primitive presentation binding.

interface PibblVisibilityTransition

Related API: PibblVisibilityTransition.

Properties and methods

binding

readonly binding: PibblTransitionBinding

Related API: PibblTransitionBinding.

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

visible

readonly visible: Signal<boolean>

Related API: Signal.

Readonly view of the requested visibility target. See Signal.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:73

progress

readonly progress: Signal<number>

Related API: Signal.

Normalized progress through the current animation or transition. See Signal.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:75

status

readonly status: Signal<PibblVisibilityTransitionStatus>

Related API: Signal, PibblVisibilityTransitionStatus.

Reactive visibility-transition lifecycle state. See Signal, PibblVisibilityTransitionStatus.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:80

show

show: () => Promise<PibblVisibilityTransitionResult>

Related API: PibblVisibilityTransitionResult.

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 .

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:87

hide

hide: () => Promise<PibblVisibilityTransitionResult>

Related API: PibblVisibilityTransitionResult.

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 .

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:94

finish

finish: () => void

Forces the currently requested transition to its endpoint. See PibblVisibilityTransition .

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:99

PibblVisibilityTransitionOptions

Enter and exit effects and lifecycle configuration for visibility transitions.

interface PibblVisibilityTransitionOptions

Related API: PibblVisibilityTransitionOptions.

Properties and methods

initial (optional)

readonly initial?: boolean | undefined

Mount-time options in the first slice.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:43

enter

readonly enter: PibblTransitionEffect

Related API: PibblTransitionEffect.

Effect used when moving toward visible. See PibblTransitionEffect.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:45

exit (optional)

readonly exit?: PibblTransitionEffect | undefined

Related API: PibblTransitionEffect.

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

duration (optional)

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

PibblVisibilityTransitionResult

Settlement of one show or hide request, including its request identifier, phase, and outcome.

interface PibblVisibilityTransitionResult

Related API: PibblVisibilityTransitionResult.

Properties and methods

requestId

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

phase

readonly phase: "enter" | "exit"

Selects "enter", "exit" for phase. See PibblVisibilityTransitionResult.

View source — packages/core/src/lib/hooks/use-visibility-transition.ts:31

status

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

PibblVisibilityTransitionStatus

The current hidden, entering, visible, exiting, or disposed transition state.

type PibblVisibilityTransitionStatus = 'hidden' | 'entering' | 'visible' | 'exiting' | 'disposed'

Related API: PibblVisibilityTransitionStatus.

embers

A seeded burn/char front over one captured subtree, with outward drifting fragments.

embers: (options: PibblEmbersOptions) => PibblTransitionEffect

Parameters

options — Ember emission, motion, appearance, and optional collision settings. See PibblEmbersOptions .

Returns

An ember transition effect. See PibblTransitionEffect.

PibblEmbersOptions

Appearance, motion, and timing controls for an ember visibility transition.

interface PibblEmbersOptions

Related API: PibblEmbersOptions.

Properties and methods

region

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

charDepth (optional)

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

burnWidth (optional)

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

wind (optional)

readonly wind?: number | undefined

Horizontal drift in local units; negative blows left.

View source — packages/core/src/lib/transitions/embers.ts:54

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See PibblEmbersOptions.

View source — packages/core/src/lib/transitions/embers.ts:59

linger (optional)

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

physics (optional)

readonly physics?: PibblEmbersPhysicsOptions | undefined

Related API: PibblEmbersPhysicsOptions.

Opt-in local force simulation and collision. Requires a positive linger.

View source — packages/core/src/lib/transitions/embers.ts:66

hologram

A diffuse scan reconstructs the captured subject while interference settles.

hologram: (options: PibblHologramOptions) => PibblTransitionEffect

Parameters

options — Hologram appearance and animation settings. See PibblHologramOptions.

Returns

A hologram transition effect. See PibblTransitionEffect.

PibblHologramOptions

Color, scanning, and distortion controls for a hologram visibility transition.

interface PibblHologramOptions

Related API: PibblHologramOptions.

Properties and methods

region

readonly region: TransitionRegion

Logical region over which the effect is evaluated. See TransitionRegion.

View source — packages/core/src/lib/transitions/hologram.ts:15

entry (optional)

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

hue (optional)

readonly hue?: number | undefined

Hue control for the transition’s emitted color. See PibblHologramOptions.

View source — packages/core/src/lib/transitions/hologram.ts:30

brightness (optional)

readonly brightness?: number | undefined

Related API: brightness.

Brightness control for the transition effect. See PibblHologramOptions.

View source — packages/core/src/lib/transitions/hologram.ts:32

fog (optional)

readonly fog?: number | undefined

Fog intensity used by the hologram effect. See PibblHologramOptions.

View source — packages/core/src/lib/transitions/hologram.ts:34

glitch (optional)

readonly glitch?: number | undefined

Distortion intensity used by the hologram effect. See PibblHologramOptions.

View source — packages/core/src/lib/transitions/hologram.ts:36

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See PibblHologramOptions.

View source — packages/core/src/lib/transitions/hologram.ts:41

bifrost

A prismatic beam stretches a white-hot captured subject toward its entry point.

bifrost: (options: PibblBifrostOptions) => PibblTransitionEffect

Parameters

options — Bifrost appearance and animation settings. See PibblBifrostOptions.

Returns

A bifrost transition effect. See PibblTransitionEffect.

PibblBifrostOptions

Color and motion controls for a bifrost visibility transition.

interface PibblBifrostOptions

Related API: PibblBifrostOptions.

Properties and methods

region

readonly region: TransitionRegion

Logical region over which the effect is evaluated. See TransitionRegion.

View source — packages/core/src/lib/transitions/bifrost.ts:13

entry (optional)

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

brightness (optional)

readonly brightness?: number | undefined

Related API: brightness.

Brightness control for the transition effect. See PibblBifrostOptions.

View source — packages/core/src/lib/transitions/bifrost.ts:28

hue (optional)

readonly hue?: number | undefined

Hue control for the transition’s emitted color. See PibblBifrostOptions.

View source — packages/core/src/lib/transitions/bifrost.ts:30

stretch (optional)

readonly stretch?: number | undefined

Amount of stretching applied by the transition. See PibblBifrostOptions.

View source — packages/core/src/lib/transitions/bifrost.ts:32

glow (optional)

readonly glow?: number | undefined

Intensity of the electrical halo around the core. See PibblBifrostOptions.

View source — packages/core/src/lib/transitions/bifrost.ts:34

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See PibblBifrostOptions.

View source — packages/core/src/lib/transitions/bifrost.ts:39

slide

Translate from an offset while fading; exit follows the same path backward.

slide: (options?: PibblSlideOptions) => PibblTransitionEffect

Parameters

options — Slide direction and displacement settings; defaults apply when omitted. See PibblSlideOptions .

Returns

A slide transition effect. See PibblTransitionEffect.

zoom

Scale around an explicit local origin while fading.

zoom: (options: PibblZoomOptions) => PibblTransitionEffect

Related API: zoom, PibblZoomOptions, PibblTransitionEffect.

Parameters

options — Zoom scale and origin settings. See PibblZoomOptions.

Returns

A zoom transition effect. See PibblTransitionEffect.

wipe

Reveal from one side of an explicit local region.

wipe: (options: PibblWipeOptions) => PibblTransitionEffect

Related API: wipe, PibblWipeOptions, PibblTransitionEffect.

Parameters

options — Wipe direction and shape settings. See PibblWipeOptions.

Returns

A wipe transition effect. See PibblTransitionEffect.

blurReveal

Resolve from a soft transparent image into crisp content using native filters.

blurReveal: (options?: PibblBlurRevealOptions) => PibblTransitionEffect

Parameters

options — Blur settings; defaults apply when omitted. See PibblBlurRevealOptions.

Returns

A blur-reveal transition effect. See PibblTransitionEffect.

dissolve

A deterministic scattered reveal. Cell size is a minimum; the grid is capped at 128×128.

dissolve: (options: PibblDissolveOptions) => PibblTransitionEffect

Parameters

options — Dissolve sampling and appearance settings. See PibblDissolveOptions.

Returns

A dissolve transition effect. See PibblTransitionEffect.

PibblSlideOptions

Direction and displacement controls for a sliding visibility transition.

interface PibblSlideOptions

Related API: PibblSlideOptions.

Properties and methods

x (optional)

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

y (optional)

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

PibblZoomOptions

Scale controls for a zooming visibility transition.

interface PibblZoomOptions

Related API: PibblZoomOptions.

Properties and methods

origin

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

from (optional)

readonly from?: number | undefined

Starting endpoint or value. See PibblZoomOptions.

View source — packages/core/src/lib/transitions/common.ts:42

PibblWipeOptions

Direction and clipping controls for a wiping visibility transition.

interface PibblWipeOptions

Related API: PibblWipeOptions.

Properties and methods

region

readonly region: TransitionRegion

Logical region over which the effect is evaluated. See TransitionRegion.

View source — packages/core/src/lib/transitions/common.ts:51

direction (optional)

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

PibblBlurRevealOptions

Blur controls for a visibility reveal transition.

interface PibblBlurRevealOptions

Related API: PibblBlurRevealOptions.

Properties and methods

radius (optional)

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

PibblDissolveOptions

Noise and threshold controls for a dissolving visibility transition.

interface PibblDissolveOptions

Related API: PibblDissolveOptions.

Properties and methods

region

readonly region: TransitionRegion

Logical region over which the effect is evaluated. See TransitionRegion.

View source — packages/core/src/lib/transitions/common.ts:73

cellSize (optional)

readonly cellSize?: number | undefined

Size of the dissolve noise cells. See PibblDissolveOptions.

View source — packages/core/src/lib/transitions/common.ts:75

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See PibblDissolveOptions.

View source — packages/core/src/lib/transitions/common.ts:80

defineTransition

Inert custom definition. The callback may call synchronous JS or WASM kernels.

defineTransition: (definition: PibblTransitionDefinition) => PibblTransitionEffect

Parameters

definition — Renderer and metadata defining the effect. See PibblTransitionDefinition .

Returns

A transition effect usable by the visibility transition hook. See PibblTransitionEffect .

PibblTransitionDefinition

Synchronous transition rendering callback and optional post-transition linger duration.

interface PibblTransitionDefinition

Related API: PibblTransitionDefinition.

Properties and methods

render

readonly render: (frame: Readonly<PibblTransitionRenderFrame>) => void

Related API: PibblTransitionRenderFrame.

Renders the current data or resources using the supplied context. See PibblTransitionRenderFrame.

Parameters

frame — Captured source, presentation context, progress, and timing services. See PibblTransitionRenderFrame .

View source — packages/core/src/lib/transitions/define-transition.ts:52

linger (optional)

readonly linger?: number | undefined

Additional milliseconds after material reaches its target. Default zero.

View source — packages/core/src/lib/transitions/define-transition.ts:54

PibblTransitionRenderFrame

Progress, geometry, and drawing context supplied to a custom transition renderer.

interface PibblTransitionRenderFrame

Related API: PibblTransitionRenderFrame.

Properties and methods

context

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

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

sourceBounds

readonly sourceBounds: Readonly<TransitionRegion>

Bounds of the source pixels supplied to the transition. See TransitionRegion.

View source — packages/core/src/lib/transitions/define-transition.ts:17

progress

readonly progress: number

Normalized progress through the current animation or transition. See PibblTransitionRenderFrame.

View source — packages/core/src/lib/transitions/define-transition.ts:22

phase

readonly phase: "enter" | "exit"

Selects "enter", "exit" for phase. See PibblTransitionRenderFrame.

View source — packages/core/src/lib/transitions/define-transition.ts:24

elapsed

readonly elapsed: number

Forward milliseconds since this run began, unaffected by reversals.

View source — packages/core/src/lib/transitions/define-transition.ts:26

progressAt

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

drawSource

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

PibblEmbersPhysicsOptions

Collision and physical motion options for transition embers.

interface PibblEmbersPhysicsOptions

Related API: PibblEmbersPhysicsOptions.

Properties and methods

gravity (optional)

readonly gravity?: readonly [number, number] | undefined

Local units/second². Default [0, -60].

View source — packages/core/src/lib/transitions/embers-physics.ts:23

wind (optional)

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

drag (optional)

readonly drag?: number | undefined

Velocity damping per second. Default 4.

View source — packages/core/src/lib/transitions/embers-physics.ts:27

restitution (optional)

readonly restitution?: number | undefined

Bounce coefficient, zero to one. Default 0.5.

View source — packages/core/src/lib/transitions/embers-physics.ts:29

obstacles (optional)

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

collide (optional)

readonly collide?: ((from: readonly [number, number], to: readonly [number, number]) => PibblEmberCollision | undefined) | undefined

Related API: PibblEmberCollision.

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 .

View source — packages/core/src/lib/transitions/embers-physics.ts:67

PibblEmberCollision

Collision information produced by an ember’s physical interaction.

interface PibblEmberCollision

Related API: PibblEmberCollision.

Properties and methods

fraction

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

normal

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

Implementation guidance for agents

Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Define a custom transition: Render a captured subtree with a custom synchronous alpha curve. Plain source
slide enter and exit: Show and hide a captured Pibbl subtree with the slide transition. Plain source
zoom enter and exit: Show and hide a captured Pibbl subtree with the zoom transition. Plain source
wipe enter and exit: Show and hide a captured Pibbl subtree with the wipe transition. Plain source
blurReveal enter and exit: Show and hide a captured Pibbl subtree with the blurReveal transition. Plain source
dissolve enter and exit: Show and hide a captured Pibbl subtree with the dissolve transition. Plain source
hologram enter and exit: 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
bifrost enter and exit: 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
embers enter and exit: Break a transparent logo into glowing Embers, with a dark stage and space for falling particles. The first entrance runs automatically. Plain source
fade enter and exit: Show and hide a captured Pibbl subtree with the fade transition. Plain source

Interactive examples

Visibility Transitions · Full page
Embers Physics · Full page

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.

useVisibilityTransition

Custom effects and WASM

Opt-in Ember physics

API details from source

fade

Returns

See also

PibblTransitionEffect

See also

PibblTransitionBinding

See also

useVisibilityTransition

Parameters

Returns

See also

PibblVisibilityTransition

See also

Properties and methods

Returns

Returns

PibblVisibilityTransitionOptions

See also

Properties and methods

PibblVisibilityTransitionResult

See also

Properties and methods

PibblVisibilityTransitionStatus

See also

embers

Parameters

Returns

See also

PibblEmbersOptions

See also

Properties and methods

hologram

Parameters

Returns

See also

PibblHologramOptions

See also

Properties and methods

bifrost

Parameters

Returns

See also

PibblBifrostOptions

See also

Properties and methods

slide

Parameters

Returns

See also

zoom

Parameters

Returns

See also

wipe

Parameters

Returns

See also

blurReveal

Parameters

Returns

See also

dissolve

Parameters

Returns

See also

PibblSlideOptions

See also

Properties and methods

PibblZoomOptions

See also

Properties and methods

PibblWipeOptions

See also

Properties and methods

PibblBlurRevealOptions

See also