# VFX-JS

VFX-JS renders HTML elements (`<img>`, `<video>`, text, any element) through WebGL shaders.
The element keeps its place in the layout.
VFX-JS draws the effect on one canvas over the page and hides the original element.

Docs: https://amagi.dev/vfx-js/ · Examples: https://amagi.dev/vfx-js/examples · Transition demo: https://amagi.dev/vfx-js-transitions/

## Packages

| Package | Use it for |
| --- | --- |
| `@vfx-js/core` | The `VFX` class. Shader presets, custom shaders, the Effect API, `addTransition`. |
| `@vfx-js/react` | React components (`VFXImg`, `VFXVideo`, `VFXSpan`, `VFXDiv`, `VFXP`, `VFXCanvas`) and `<VFXTransition>`. Subpaths `/next`, `/react-router`. |
| `@vfx-js/vue` | Vue directive `v-vfx`, `VFXCanvas`, and `<VFXTransition>` from `/nuxt` or `/router`. |
| `@vfx-js/svelte` | Svelte 5 attachment `vfx`, `VFXCanvas`, and `<VFXTransition>` from `/sveltekit`. |
| `@vfx-js/astro` | Astro components (`VFXImg`, `VFXVideo`, `VFXSpan`, `VFXDiv`, `VFXP`), `<VFXTransition>`, `<TransitionIn>`. `registerVFX` from `/client`. |
| `@vfx-js/effects` | Prebuilt `Effect` classes (`BloomEffect`, `PixelateEffect`, ...). |
| `@vfx-js/transitions` | Transition presets (`Swipe`, `Glitch`, `Zoom`, ...). Experimental. |

## Pick the right API

| Goal | Use | Read |
| --- | --- | --- |
| Quick effect on an element | `vfx.add(el, { shader: "glitch" })` | below |
| Your own one-pass shader | `vfx.add(el, { shader: glslString })` | [references/shader.md](#custom-shaders-shader-option) |
| Multi-pass, feedback, simulation | `shader: VFXPass[]` | [references/shader.md](#custom-shaders-shader-option) |
| Prebuilt effects, chains, or reusable effect classes | `vfx.add(el, { effect })` | [references/effects.md](#effects-effect-option) |
| Effect over the whole page | `new VFX({ postEffect })` | [references/shader.md](#custom-shaders-shader-option) |
| Tabs, carousels, page transitions | `vfx.addTransition(el)` / `<VFXTransition>` | [references/transitions.md](#transitions-addtransition-vfx-jstransitions) |
| Your own transition | `class X extends ShaderTransition` | [references/transitions.md](#transitions-addtransition-vfx-jstransitions) |

## Quick start

```bash
npm i @vfx-js/core
```

```ts
import { VFX } from "@vfx-js/core";

const vfx = new VFX();
const img = document.querySelector("img")!;
await vfx.add(img, { shader: "rgbShift" });
```

Shader presets: `uvGradient`, `rainbow`, `glitch`, `rgbGlitch`, `rgbShift`, `shine`, `blink`, `spring`, `duotone`, `tritone`, `hueShift`, `sinewave`, `pixelate`, `halftone`, `invert`, `grayscale`, `vignette`, `chromatic`.
Scroll reveal presets animate in when the element enters the viewport, and out when it leaves: `slitScanReveal`, `warpReveal`, `pixelateReveal`, `focusReveal`.
The old names (`slitScanTransition`, `warpTransition`, `pixelateTransition`, `focusTransition`) still work.

Without a bundler:

```html
<script type="module">
  import { VFX } from "https://esm.sh/@vfx-js/core";
  const vfx = new VFX();
  vfx.add(document.querySelector("img"), { shader: "glitch", overflow: 100 });
</script>
```

### Common `vfx.add` options

```ts
vfx.add(el, {
    shader: "glitch",          // preset name, GLSL string, or VFXPass[]
    uniforms: {                // values for your shader; a function runs every frame
        amount: 0.5,
        scroll: () => window.scrollY,
    },
    overflow: 100,             // draw outside the element: px, [top, right, bottom, left], or true (fullscreen)
    overlay: true,             // keep the original element visible (default hides it)
    zIndex: 0,                 // draw order inside the canvas
    wrap: "clamp",             // texture wrap: "repeat" (default) | "clamp" | "mirror"
    intersection: { threshold: 0.5, duration: 1 }, // enter/leave timing; see references/shader.md
});
```

### `VFX` methods

- `add(el, props)` → `Promise<void>`. Start rendering an element.
- `addHTML(el, props)` → render any HTML subtree, with live updates (html-in-canvas, Chrome only, falls back to a slower capture). Check support with `supportsHtmlInCanvas()`.
- `remove(el)`, `update(el)` (re-capture after the content changes), `updateEffects(el, effects)`.
- `addTransition(el, opts)` → `TransitionHandle`. See [references/transitions.md](#transitions-addtransition-vfx-jstransitions).
- `play()`, `stop()`, `render()`, `destroy()`, `setTime(t)`, `timeScale`.

`new VFX(opts)` options: `pixelRatio`, `zIndex`, `autoplay`, `scrollPadding`, `wrapper`, `postEffect`, `preserveDrawingBuffer`, `timeScale`.

## React

```bash
npm i @vfx-js/core @vfx-js/react
```

```tsx
import { VFXImg, VFXSpan, VFXVideo } from "@vfx-js/react";

<VFXImg src="cat.png" shader="rgbShift" />
<VFXVideo src="clip.mp4" autoPlay muted loop playsInline shader="halftone" />
<VFXSpan shader="rainbow">Hello</VFXSpan>
```

- Every `vfx.add` option is a prop (`shader`, `effect`, `uniforms`, `overflow`, ...).
- No provider is needed. Components share one canvas. Set its options with `useVFXConfig({ pixelRatio, zIndex, postEffect })`.
- Use `<VFXProvider>` only for a separate canvas (e.g. a `wrapper`), and `VFXContext` to get the `VFX` instance.
- The package is `"use client"`. In Next.js App Router, use the components from a client component or directly in a Server Component (they cross as client references). Pass only serializable props from a Server Component: preset names, GLSL strings, plain uniforms.
- `<VFXCanvas shader="rainbow">...</VFXCanvas>` renders any markup, form controls included. With SSR it renders a `<div>` first and switches to `<canvas>` after hydration, so its children mount again once.

## Vue and Nuxt

```bash
npm i @vfx-js/core @vfx-js/vue
```

```vue
<script setup lang="ts">
import { vVfx } from "@vfx-js/vue";
</script>

<template>
    <img v-vfx="{ shader: 'rgbShift' }" src="cat.png" />
    <h1 v-vfx="{ shader: 'glitch', overflow: 30 }">Hello</h1>
</template>
```

- The value is `VFXProps`. `null` / `undefined` means no effect. Register it globally with `app.directive("vfx", vVfx)`.
- `VFXCanvas` renders any markup into a shader. `v-model:element` gives the element the effect is on.
- `useVFXConfig({ pixelRatio, zIndex, postEffect, autoplay })` in `setup` sets the shared canvas options. `useVFXInstance()` gives the `VFX` as a ref.
- Call `updateElement(el)` after changes the directive can't see, like an input's value.
- Works with SSR (Nuxt). No `<ClientOnly>` needed.

## Svelte and SvelteKit

Needs Svelte 5.29 or later.

```bash
npm i @vfx-js/core @vfx-js/svelte
```

```svelte
<script lang="ts">
    import { vfx } from "@vfx-js/svelte";
    let shader = $state("rgbShift");
</script>

<img {@attach vfx({ shader: "rgbShift" })} src="cat.png" alt="" />
<h1 {@attach vfx(() => ({ shader }))}>Hello</h1>
```

- Pass a getter (`() => ({ ... })`) for props that change. A plain object that reads state removes and re-adds the element on every change.
- `VFXCanvas` renders any markup into a shader. `bind:element` gives the element the effect is on.
- `vfxConfig({ ... })` sets the shared canvas options. `vfxInstance().current` is the `VFX`.
- Keep a `postEffect` object out of `$state`; every new proxy replaces the canvas.
- Call `updateElement(el)` after changes the attachment can't see.

## Astro

Needs Astro 5 or later. No framework island.

```bash
npm i @vfx-js/core @vfx-js/astro
```

```astro
---
import { VFXImg, VFXSpan } from "@vfx-js/astro";
---

<VFXImg src="/cat.png" alt="" shader="rgbShift" />
<VFXSpan shader="glitch" overflow={30}>Hello</VFXSpan>
```

- `VFXImg`, `VFXVideo`, `VFXSpan`, `VFXDiv`, `VFXP` take `VFXProps` that fit in HTML: `shader` is a preset, GLSL, or `"@name"` of a registered `VFXPass[]`; `uniforms` is plain numbers or the name of registered uniforms; no `effect`.
- The props become a `data-vfx` JSON attribute. Any element with `data-vfx` works, e.g. `<Image src={cat} alt="" data-vfx='{"shader":"rgbShift"}' />` from `astro:assets`.
- Register functions by name in a client `<script>` in the layout:

```ts
import { registerVFX } from "@vfx-js/astro/client";

registerVFX({
    uniforms: { mouse: { mouse: () => [mx, my] } },
    shaders: { blur: [pass1, pass2] },
    vfx: { pixelRatio: 1 },   // shared canvas options; only before the VFX is made
});
```

- An element whose name is not registered yet waits until it is.
- `getVFX()` from `@vfx-js/astro/client` gives the shared `VFX` (or `null` without WebGL). `install()` starts the `data-vfx` watcher; the components call it for you.
- Page transitions: see [references/transitions.md](#transitions-addtransition-vfx-jstransitions).

## Rules and pitfalls

- Browser only. `new VFX()` throws without `window`, and throws when WebGL is not available. Create it in client code (`useEffect`, `onMount`, `"use client"`), and wrap it in `try` / `catch` so the page still works as plain HTML.
- Make one `VFX` instance per page and reuse it.
- `add` is async. `await` it before you call `updateEffects` or `remove` on the same element.
- Text and plain elements are captured once. Call `vfx.update(el)` after their content changes, or after you change `img.src`.
- Images and videos from another origin need CORS (`crossorigin="anonymous"` and a server that allows it), or WebGL cannot read them.
- `VFXSpan` captures text only. Put links and other child elements outside it.
- Custom shaders default to GLSL ES 3.0. Write `out vec4 outColor;` and `texture()`, not `gl_FragColor` / `texture2D`. VFX-JS adds `#version 300 es` for you.
- A custom shader draws only inside the element unless you set `overflow`.
- `shader` and `effect` are mutually exclusive. `overflow` is ignored with `effect`; use `outputRect` instead.
- Never share one `Effect` instance between elements. Make a new one per element.
- Respect `prefers-reduced-motion`: skip `vfx.add` or use a still effect when it matches.
- Lower `pixelRatio` (e.g. `new VFX({ pixelRatio: 1 })`) if it runs slowly on high-DPI phones.

## Debugging

- A `shader` that fails to compile makes `vfx.add` reject with the GL error log and the full source. Catch and log it: `vfx.add(el, opts).catch(console.error)`.
- A transition shader that fails logs the error with line numbers in your `frag`, then cuts to the new content.
- A blank element usually means: the shader failed, the image is CORS-blocked, or the element has zero size.
- Test effects in a real browser (e.g. with Playwright and a screenshot). Headless browsers need WebGL enabled.

---

# Custom shaders (`shader` option)

Pass a GLSL fragment shader string as `shader`.
VFX-JS draws it over the element's rect, plus `overflow`.

## Template

```ts
const shader = `
precision highp float;
uniform sampler2D src;   // the element's texture
uniform vec2 resolution; // element size, physical px
uniform vec2 offset;     // element origin in the render target, physical px
uniform float time;      // seconds
uniform float amount;    // your uniform
out vec4 outColor;

void main() {
    vec2 uv = (gl_FragCoord.xy - offset) / resolution;
    uv.x += sin(uv.y * 20.0 + time) * 0.02 * amount;
    outColor = texture(src, uv);
}
`;

await vfx.add(el, { shader, uniforms: { amount: 1 } });
```

- `uv` is element space: (0, 0) bottom-left, (1, 1) top-right.
- GLSL ES 3.0 by default. VFX-JS adds `#version 300 es`. Write `out vec4 outColor` and `texture()`.
- A shader with `gl_FragColor` or `texture2D` is compiled as GLSL ES 1.0. Don't mix the two.
- Output is premultiplied alpha. For transparent pixels, scale `rgb` by `a`.

## Built-in uniforms

Declare only the ones you use.

| Uniform | Type | Meaning |
| --- | --- | --- |
| `src` | `sampler2D` | Element texture. In later passes, the previous pass. |
| `resolution` | `vec2` | Element size in physical px. |
| `offset` | `vec2` | Element origin in the render target, physical px. |
| `viewport` | `vec4` | Render target rect `(x, y, w, h)` in physical px. |
| `time` | `float` | Seconds since VFX started. |
| `mouse` | `vec2` | Mouse position in render target px (same space as `gl_FragCoord`). |
| `intersection` | `float` | How much of the element is in the viewport, 0..1. |
| `enterTime` | `float` | Seconds since the element entered the viewport. |
| `leaveTime` | `float` | Seconds since the element left the viewport. |
| `enterProgress` | `float` | Enter transition, 0..1. Plays backward if the element leaves mid-way. |
| `leaveProgress` | `float` | Leave transition, 0..1. Stays 0 until enter finishes. |
| `autoCrop` | `bool` | The `autoCrop` prop (default true). |
| `backbuffer` | `sampler2D` | Previous frame. Needs `backbuffer: true`. |
| `passIndex` | `int` | Index of the current pass. |

Use `enterProgress` and `leaveProgress` for enter and leave animations.
They turn back smoothly when the user scrolls back mid-way:

```glsl
float t = enterProgress * (1.0 - leaveProgress); // 0 hidden, 1 fully shown
```

Set the timing with `intersection`:

```ts
vfx.add(el, {
    shader,
    intersection: {
        threshold: 0.5,      // enter when half of the element is in view
        leaveThreshold: 0.2, // leave when less than 20% is in view (default: threshold)
        duration: 0.8,       // seconds for enter and leave (default: 1); keep `release` >= duration
    },
});
```

`leaveThreshold` can also be above `threshold`: the element enters at `threshold` when scrolling in, and leaves at `leaveThreshold` when scrolling out.
The visible ratio divides by the smaller of the element size and the viewport size (after `rootMargin`), on each axis.
So an element taller than the viewport can reach 1, and with a negative `rootMargin` a smaller element reaches 1 sooner.
Use `enterTime` / `leaveTime` for animations timed in seconds.

## Uniform values

```ts
uniforms: {
    f: 1,                       // float
    v2: [1, 2],                 // vec2
    color: [1, 0, 0, 1],        // vec4
    arr: new Float32Array(16),  // uniform vec4 arr[4]
    scroll: () => window.scrollY, // re-evaluated every frame
}
```

Booleans are not supported in `shader` uniforms; use `0` / `1` floats.

## Overflow

`overflow` lets the shader draw outside the element.
`uv` goes below 0 and above 1 there.

```ts
vfx.add(el, { shader, overflow: 50 });               // 50 px on every side
vfx.add(el, { shader, overflow: [0, 100, 200, 0] }); // top, right, bottom, left
vfx.add(el, { shader, overflow: true });             // whole canvas
```

The element texture is empty outside 0..1, but `wrap` defaults to `"repeat"`.
Guard reads outside the element, or use `wrap: "clamp"`:

```glsl
vec4 readTex(vec2 uv) {
    if (uv.x < 0. || uv.x > 1. || uv.y < 0. || uv.y > 1.) return vec4(0);
    return texture(src, uv);
}
```

## Feedback with `backbuffer`

```ts
vfx.add(el, { shader, backbuffer: true });
```

```glsl
uniform sampler2D backbuffer;
uniform vec4 viewport;
// backbuffer covers the whole render target, not just the element:
vec2 bufferUv = (gl_FragCoord.xy - viewport.xy) / viewport.zw;
vec4 prev = texture(backbuffer, bufferUv);
```

## Multipass

Pass an array of passes.
Each pass writes to `target`; later passes read it as `uniform sampler2D <target>`.
The last pass draws to the screen.

```ts
vfx.add(el, {
    shader: [
        { frag: blurShader, target: "blurH", uniforms: { direction: [1, 0] } },
        { frag: blurShader, uniforms: { direction: [0, 1] } },
    ],
});
```

```ts
type VFXPass = {
    frag: string;             // fragment shader (required)
    vert?: string;            // vertex shader
    target?: string;          // buffer name; omitted on a middle pass = "pass0", "pass1", ...
    persistent?: boolean;     // keep across frames; read last frame by the target name
    float?: boolean;          // 32-bit float buffer, for data outside 0..1
    size?: [number, number];  // fixed buffer size in px; then resolution = size, offset = 0
    uniforms?: VFXUniforms;   // per-pass uniforms
};
```

Persistent buffer (trail):

```glsl
uniform sampler2D src;
uniform sampler2D trail;   // last frame of this pass
uniform vec2 resolution;
uniform vec2 offset;
out vec4 outColor;
void main() {
    vec2 uv = (gl_FragCoord.xy - offset) / resolution;
    outColor = max(texture(src, uv), texture(trail, uv) * 0.95);
}
```

```ts
shader: [
    { frag: trailShader, target: "trail", persistent: true },
    { frag: displayShader },
]
```

With `overflow`, buffers that VFX-JS renders (`<target>`, `backbuffer`, `src` after the first pass) cover the whole buffer.
Read them with this helper:

```glsl
vec2 toBuffer(vec2 uv) {
    return (uv * resolution + (offset - viewport.xy)) / viewport.zw;
}
// texture(myTarget, toBuffer(uv))
```

Without overflow it returns `uv` unchanged, so it is always safe to use.

## Post effects

A post effect runs over the whole canvas after all elements are drawn.
`src` is the canvas, and `offset` is 0.

```ts
const vfx = new VFX({
    postEffect: { shader: "grayscale" },  // preset, GLSL string, or { effect }
});

const vfx2 = new VFX({
    postEffect: [                          // multipass, same VFXPass shape
        { frag: passA, target: "a" },
        { frag: passB },
    ],
});
```

Post effect options: `shader`, `uniforms`, `persistent` (previous frame as `backbuffer`), `float`, `effect`.

---

# Effects (`effect` option)

An `Effect` is a class with lifecycle hooks.
Use it for prebuilt effects, chains of effects, or your own reusable effect with several passes, persistent buffers, custom geometry, or output larger than the element.

## Prebuilt effects (`@vfx-js/effects`)

```bash
npm i @vfx-js/core @vfx-js/effects
```

```ts
import { VFX } from "@vfx-js/core";
import { BloomEffect, PixelateEffect, ScanlineEffect } from "@vfx-js/effects";

const vfx = new VFX();
await vfx.add(img, {
    effect: [
        new PixelateEffect({ size: 10 }),
        new ScanlineEffect({ spacing: 5 }),
        new BloomEffect({ intensity: 10 }),
    ],
});

// Swap the chain in place. Unchanged instances keep their state.
await vfx.updateEffects(img, [new BloomEffect({ intensity: 8 })]);
```

Each constructor takes a partial params object.
Most effects read `effect.params` every frame, so you can change it live (e.g. from a slider): `bloom.params.intensity = 3`.
For the exact params, read the `.d.ts` files in `node_modules/@vfx-js/effects/lib/esm/`.

| Effect | What it does |
| --- | --- |
| `AsciiEffect` | ASCII / glyph mosaic from a dark-to-light character ramp. |
| `BadJpegEffect` | JPEG degradation: chroma subsampling, blocky DCT, re-encode loss. |
| `BloomEffect` | Bloom with soft-knee threshold. Draws outside the element. |
| `ChromaticEffect` | Chromatic aberration. |
| `ColoredEdgesEffect` | Edge detection with two edge colors. |
| `DatamoshEffect` | Fake datamosh. Call `enable()` / `disable()`. |
| `DitherEffect` | Bayer / blue-noise dither with few color levels. |
| `DuotoneEffect` | Two-color map. |
| `FluidEffect` | Fluid simulation driven by the pointer. |
| `GlitchEffect` | Block shift and aberration glitch. |
| `GradientMapEffect` | Map luminance to a color gradient. |
| `HalftoneEffect` | RGB / CMYK halftone screen. |
| `HueShiftEffect` | Rotate hue. |
| `JPEGGlitchEffect` | Real JPEG glitch: corrupts the encoded bytes. |
| `LightStreakEffect` | Anamorphic flare / starburst streaks. |
| `MatrixEffect` | Digital rain of glyphs over the source. |
| `ParticleEffect` | GPU particles emitted from the mouse. |
| `ParticleExplodeEffect` | One-shot burst that shatters the element. Call `trigger()`. |
| `PatternRefractionEffect` | Refraction through ribbed glass: lenticular, waves or circular. |
| `PixelateEffect` | Pixelation. `size` in CSS px. |
| `PixelSortEffect` | Threshold pixel sort, any angle. |
| `PixelStretchEffect` | Smear one scan line across a band of the image. |
| `RainbowEffect` | Moving rainbow gradient. |
| `RgbGlitchEffect` | Block glitch with RGB split. |
| `RgbShiftEffect` | RGB channel shift. |
| `ScanlineEffect` | CRT scanlines. |
| `SinewaveEffect` | Sine wave distortion. |
| `SliceShiftEffect` | Split into strips and shift each toward the center. |
| `TilePixelateEffect` | Pixelate into shaped tiles. |
| `TritoneEffect` | Three-color map. |
| `VignetteEffect` | Vignette. |
| `VoronoiEffect` | Voronoi cells around the cursor. |
| `WarpEffect` | Sine wave, twist or ripple warp. |

Live demos: https://amagi.dev/vfx-js/storybook

## Writing an effect

```ts
import type { Effect, EffectContext } from "@vfx-js/core";

const FRAG = `#version 300 es
precision highp float;
in vec2 uvSrc;
out vec4 outColor;
uniform sampler2D src;
uniform float strength;
void main() {
    vec4 c = texture(src, uvSrc);
    float gray = dot(c.rgb, vec3(0.299, 0.587, 0.114));
    outColor = vec4(mix(c.rgb, vec3(gray), strength), c.a);
}
`;

export class DesaturateEffect implements Effect {
    constructor(public strength = 1) {}

    render(ctx: EffectContext) {
        ctx.draw({
            frag: FRAG,
            uniforms: { src: ctx.src, strength: this.strength },
            target: ctx.target,
        });
    }
}

vfx.add(img, { effect: new DesaturateEffect(0.8) });
```

### Lifecycle

```ts
interface Effect {
    enabled?: boolean;                        // false skips render (input passes through)
    init?(ctx): void | Promise<void>;         // once: allocate render targets, wrap textures
    update?(ctx): void;                       // every frame: state only, ctx.draw is ignored
    render?(ctx): void;                       // every frame: ctx.draw / ctx.blit
    dispose?(): void;                         // once on removal
    outputRect?(dims): [x, y, w, h] | undefined; // rect this stage draws into
}
```

### Default varyings

The default vertex shader gives three varyings, all 0..1:

- `uvSrc` — over the source texture. Use it to read `ctx.src`.
- `uvContent` — over the element. Outside 0..1 is the padding from `outputRect`.
- `uv` — over the whole destination buffer.

Always declare `#version 300 es` in `ctx.draw` shaders.

### Context

| Field | Notes |
| --- | --- |
| `time`, `deltaTime` | Seconds since start / since last frame. |
| `resolution` | Canvas size, physical px. |
| `mouse`, `mouseViewport` | Element-local / canvas-local px, bottom-left origin. |
| `intersection` | 0..1 viewport overlap. |
| `enterProgress`, `leaveProgress` | 0..1 enter / leave transition. Timing comes from the `intersection` option ([shader.md](shader.md#built-in-uniforms)). |
| `src`, `target` | Input texture / output for this stage. `target: null` is the canvas. |
| `uniforms` | User `uniforms` from `vfx.add`, evaluated each frame. |
| `dims` | Sizes: `elementPixel`, `canvasPixel`, `pixelRatio`, `contentRect`, `srcRect`, `canvasRect`. |
| `createRenderTarget(opts)` | `{ size?, float?, persistent?, wrap?, filter?, mipmap? }`. Call in `init`. |
| `wrapTexture(source, opts)` | Wrap an image, canvas, video or `WebGLTexture`. Call in `init`. With `autoUpdate: false`, call `tex.update()` after the source changes. |
| `draw(opts)` | `{ frag, vert?, geometry?, uniforms?, target?, blend?, swap? }`. |
| `blit(source, target?)` | Copy a texture into a target. |
| `clear(target?)` | Clear a render target. |
| `gl` | Raw `WebGL2RenderingContext`. |

### Two passes

```ts
class BlurEffect implements Effect {
    #tmp: EffectRenderTarget | null = null;

    init(ctx: EffectContext) {
        this.#tmp = ctx.createRenderTarget(); // follows the element size
    }

    render(ctx: EffectContext) {
        if (!this.#tmp) return;
        const [w, h] = ctx.dims.elementPixel;
        ctx.draw({ frag: BLUR, uniforms: { src: ctx.src, dir: [1 / w, 0] }, target: this.#tmp });
        ctx.draw({ frag: BLUR, uniforms: { src: this.#tmp, dir: [0, 1 / h] }, target: ctx.target });
    }
}
```

### Feedback (persistent render target)

A `persistent: true` target is ping-pong buffered.
Bound as a uniform, it reads last frame; drawn to, it writes the new frame.

```ts
init(ctx) { this.#buf = ctx.createRenderTarget({ persistent: true }); }
render(ctx) {
    ctx.draw({ frag: TRAIL, uniforms: { src: ctx.src, prev: this.#buf, decay: 0.92 }, target: this.#buf });
    ctx.blit(this.#buf, ctx.target);
}
```

### Drawing outside the element

`overflow` does not apply to effects. Return a bigger rect from `outputRect`:

```ts
outputRect(dims: EffectDims) {
    const px = 40 * dims.pixelRatio;
    const [w, h] = dims.elementPixel;
    return [-px, -px, w + 2 * px, h + 2 * px];
}
```

Return `dims.canvasRect` to cover the whole canvas.

### Rules

- One instance per element. Use a factory: `const make = () => new MyEffect()`.
- `shader` and `effect` are mutually exclusive.
- Free anything you allocate with raw `ctx.gl` in `dispose`, and rebuild it in `ctx.onContextRestored(cb)`.
- Use `ctx.dims` for pixel sizes. Don't read DOM sizes in `render`.

---

# Transitions (`addTransition`, `@vfx-js/transitions`)

> Experimental. The API may change in any 0.x release.

A transition animates an element from its old content to its new content with a shader.
Use it for tab panels, carousels, slideshows and page transitions.

A run:

1. VFX-JS snapshots the element.
2. Your callback changes the DOM.
3. VFX-JS captures the new content.
4. A shader mixes the two over `duration`.

The element is plain DOM at rest. VFX-JS wraps it in a canvas only during a run.

```bash
npm i @vfx-js/core @vfx-js/transitions
```

## Slides already in the DOM: `show`

```html
<nav>
    <button data-panel="#home">Home</button>
    <button data-panel="#about">About</button>
</nav>
<div id="panel" style="height: 400px">
    <section id="home">...</section>
    <section id="about" hidden>...</section>
</div>
```

```ts
import { VFX } from "@vfx-js/core";
import { Swipe } from "@vfx-js/transitions";

const vfx = new VFX();
const panel = document.querySelector<HTMLElement>("#panel")!;
const t = vfx.addTransition(panel, { transition: Swipe, duration: 0.6 });

for (const tab of document.querySelectorAll<HTMLElement>("[data-panel]")) {
    tab.addEventListener("click", () => t.show(tab.dataset.panel!));
}
```

- Slides are the container's direct children. `show` hides the others with `hidden`.
- `slide` is an element, an index, or a selector. A slide that is not a direct child throws a `TypeError`.
- `remove: true` removes the other slides instead of hiding them.
- Keep the buttons outside the container.

## Content built on the fly: `run`

```ts
await t.run(() => {
    panel.innerHTML = renderPage(next);
}, { transition: Glitch, params: { amount: 1.5 } });
```

`run(cb, opts)` works like `document.startViewTransition(cb)`: the DOM must be updated when `cb` resolves.
Both `show` and `run` resolve when the animation ends.
A new `run` during a run drops the old one, but its callback still runs.

## Options

```ts
const t = vfx.addTransition(el, {
    transition: Crossfade, // a class or an instance (default Crossfade)
    params: {},            // constructor params, only with a class
    duration: 0.6,         // seconds; 0 cuts without animation
    reverse: false,        // play backwards, old and new swapped
    ease: "smoothstep",    // "smoothstep" | "linear" | (x) => t
    overflow: undefined,   // true (whole canvas) | CSS px on every side
    keepWrapped: false,    // keep the canvas wrapper between runs
    waitFor: "media",      // wait for images / videos / fonts (~300 ms max) | "none" | (el) => Promise
    autoReverse: false,    // on back, replay the spec that entered, reversed (needs the Navigation API)
    slideSpec: undefined,  // (slide) => RunOpts | undefined: how each slide enters with show()
});
```

`run` and `show` take the same fields (except `keepWrapped`, `waitFor`, `autoReverse`, `slideSpec`).

`autoReverse` stores the spec that entered each history entry (by `navigation.currentEntry.key`).
Back plays the left entry's spec with `reverse: true`; the forward button replays the entered entry's spec.
On back the stored spec wins, even over `setNextTransition()`. No Navigation API: it does nothing. `show()` ignores it.
Every `<VFXTransition>` takes it as a prop (`auto-reverse` in Vue templates).
`show` puts its opts over the slide's `slideSpec`, then over the container's.
A run's fields win over the container's. A run that sets its own `transition` drops the container's `params`.

Handle: `show(slide, opts)`, `run(cb, opts)`, `cancel()`, `destroy()`, `running`.

## Presets

```ts
import {
    Crossfade, Crosszoom, Datamosh, DistortFade, Glitch, GlitchSlide,
    JpegGlitch, LensDistortion, PixelScan, PixelStretch, Pixelsort,
    SlitScan, Swipe, Tile, Zoom, ZoomBlur,
} from "@vfx-js/transitions";
```

| Preset | Params | Notes |
| --- | --- | --- |
| `Crossfade` | | Plain mix. Default. |
| `Swipe` | `direction`: `"left"` (default) / `"right"` / `"up"` / `"down"` | Content moves with motion blur. |
| `Zoom` | | Old content grows out; new grows from the center. |
| `ZoomBlur` | | Radial blur with RGB split. |
| `Crosszoom` | | Crossfade through a zoom blur. |
| `Glitch` | `amount`, `speed` (default 1) | Jittery RGB-split blocks. |
| `GlitchSlide` | | Sliding stripes with RGB split. |
| `JpegGlitch` | `iterations`, `quality` | Hard cut through a real JPEG glitch. |
| `Datamosh` | `blockSize` | Hard cut through a datamosh that heals block by block. |
| `Pixelsort` | `direction` | Melts into sorted streaks and sorts back. |
| `LensDistortion` | `strength`, `dispersion`, `zoom` | Lens warp with rainbow split. |
| `SlitScan` | | A scan line smears the content into stripes. |
| `PixelScan` | `direction` (incl. `"center"`), `blackout` | A front of glowing pixel cells sweeps across. |
| `PixelStretch` | | Content stretches into streaks from the top. |
| `DistortFade` | | Noise warp that peaks halfway. |
| `Tile` | `direction`, `shape` (`"hex"` / `"square"`), `count`, `shadow` | Content splits into shrinking tiles. |

Pass a class with `params`, or an instance to change params during a run:

```ts
t.show("#home", { transition: Swipe, params: { direction: "right" } });

const glitch = new Glitch({ amount: 1 });
t.show("#about", { transition: glitch });
glitch.params = { amount: 3 }; // live
```

An instance runs in one container at a time. A class can serve many containers.

### gl-transitions

Any shader from https://gl-transitions.com works:

```ts
import { createGLTransition } from "@vfx-js/transitions";
import transitions from "gl-transitions"; // npm i gl-transitions

const Cube = createGLTransition(transitions.find((t) => t.name === "Cube")!);
t.run(cb, { transition: Cube, params: { persp: 0.5 } });
```

Their `t` is linear; each shader eases itself.
Shaders that need extra textures (`LumaWipe`, `DisplacementMap`) throw.

## Custom transition: `ShaderTransition`

Most transitions are one shader.

```ts
import { ShaderTransition } from "@vfx-js/core";

export class Wipe extends ShaderTransition<{ softness?: number }> {
    readonly name = "wipe";
    readonly frag = `
uniform float softness;
vec4 transition(vec2 uv, float t) {
  float m = smoothstep(t - softness, t + softness, uv.x);
  return mix(readTo(uv), readFrom(uv), m);
}
`;
    // ease = "linear";   // default "smoothstep"
    // overflow = true;   // draw outside the element

    // Called every frame. Read this.params here.
    uniforms() {
        return { softness: this.params.softness ?? 0.05 };
    }
}

t.run(cb, { transition: Wipe, params: { softness: 0.1 } });
```

`frag` defines only `vec4 transition(vec2 uv, float t)`. VFX-JS adds the header and `main`. Don't write `#version`, `main` or `outColor`.

The prelude gives:

- `readFrom(p)` — the old content. `readTo(p)` — the new content. They swap when `reverse` is true, so write only the forward animation.
- `inRange(p)` — whether `p` is inside 0..1. Reads outside 0..1 return transparent black.
- Reads are premultiplied alpha, and the return value must be too. So `mix` and averages of reads just work.
- Uniforms: `t` (0→1, eased), `reverse`, `resolution` (element size, physical px), `time`.
- `uv` is element space, (0, 0) bottom-left. With `overflow`, `uv` goes outside 0..1.
- A shader that shifts or wraps `uv` should return `vec4(0.0)` when `!inRange(uv)`, so a container `overflow` doesn't draw content outside the element.
- At `t = 0` show only the old content, at `t = 1` only the new.
- Uniforms from `uniforms()` are numbers, vectors and arrays. No textures.

A compile error logs the error with line numbers in your `frag`, then cuts to the new content.

## Custom transition with several passes

Implement `Transition` directly. It is an `Effect` (see [effects.md](#effects-effect-option)) with run info on the context.

```ts
import type { EffectContext, EffectRenderTarget, Transition, TransitionEffectContext } from "@vfx-js/core";

export class BlurFade implements Transition {
    name = "blur_fade";
    #tmp: EffectRenderTarget | null = null;

    init(ctx: EffectContext) {
        this.#tmp = ctx.createRenderTarget();
    }

    render(ctx: TransitionEffectContext) {
        if (ctx.holding || !this.#tmp) {
            ctx.blit(ctx.src); // pass through while the old content is held
            return;
        }
        const { t } = ctx.progress;
        ctx.draw({ frag: PASS_A, uniforms: { src: ctx.src, from: ctx.from, mixT: t }, target: this.#tmp });
        ctx.draw({ frag: PASS_B, uniforms: { src: this.#tmp }, target: ctx.target });
    }
}
```

- `ctx.src` is the new content (read with `uvSrc`). `ctx.from` is the old snapshot (read with `uvContent`).
- `ctx.progress.t` is eased, `ctx.progress.x` linear. Both 0..1 and ignore `reverse`; check `ctx.reverse` yourself.
- `start(run)` runs once per run, `end()` once when it ends or is cancelled.
- `ctx.cut()` ends the run and shows the new content.
- The element is unwrapped between runs, so `dispose()` then `init()` run again.

## React

```bash
npm i @vfx-js/core @vfx-js/react @vfx-js/transitions
```

Page transitions: put one `<VFXTransition>` around the router outlet.
Pick the import for your router:

| Router | Import | Usage |
| --- | --- | --- |
| Next.js App Router | `@vfx-js/react/next` | `<VFXTransition>{children}</VFXTransition>` in `app/layout.tsx` |
| React Router 7 | `@vfx-js/react/react-router` | `<VFXTransition transition={Crossfade} />` in place of `<Outlet />` |
| Other | `@vfx-js/react` | `<VFXTransition pageKey={pathname}>{page}</VFXTransition>` |

```tsx
// React Router
import { VFXTransition } from "@vfx-js/react/react-router";
import { Crossfade } from "@vfx-js/transitions";

export function Layout() {
    return (
        <>
            <nav>...</nav>
            <VFXTransition transition={Crossfade} duration={0.6} />
        </>
    );
}
```

- The router versions use the pathname as the key. A search-only change does not run.
- With `@vfx-js/react`, a new `pageKey` starts a run. Without `pageKey` it never transitions.
- The target fills the viewport (`height: 100dvh; overflow: hidden`). Pages scroll inside it. Use a CSS reset (`body { margin: 0 }`).
- `fullscreen={false}` drops the default size; size it with `className` / `style`, e.g. `height: calc(100dvh - 64px)` under a header.
- React Router: the old page keeps its own route while it animates out, but `useLocation()` inside it reads the new location.

### Next.js App Router

```tsx
// app/layout.tsx
import { VFXTransition } from "@vfx-js/react/next";

export default function Layout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <body>
                <VFXTransition>{children}</VFXTransition>
            </body>
        </html>
    );
}
```

Import `VFXTransition` from `@vfx-js/react/next`. It uses `usePathname()` as the key. Import everything else from `@vfx-js/react`.

### Per page and per link

```tsx
// app/about/page.tsx (a Server Component is fine)
import { TransitionIn } from "@vfx-js/react";
import { Glitch } from "@vfx-js/transitions";

export default function AboutPage() {
    return (
        <>
            <TransitionIn transition={Glitch} params={{ amount: 1.5 }} />
            <h1>About</h1>
        </>
    );
}
```

```tsx
"use client";
import Link from "next/link";
import { transition } from "@vfx-js/react";
import { Swipe } from "@vfx-js/transitions";

export function NextLink() {
    return <Link href="/next" onClick={transition({ transition: Swipe })}>Next</Link>;
}
```

- Which spec wins: a link's `transition(spec)` or `setNextTransition(spec)`, then the page's `<TransitionIn>`, then the `<VFXTransition>` props.
- `useTransitionIn(spec)` is the hook form of `<TransitionIn>`. Only the spec at mount counts.
- `setNextTransition(spec)` before `router.push()` / `navigate()` for navigation from code.
- Import `Crossfade` from `@vfx-js/transitions`, not `@vfx-js/core`, in Server Components.
- Write custom transition classes in a file that starts with `"use client"`.
- An instance cannot cross from a Server Component. Make it in a client component with `useTransitionInstance(Class, params)`.

### Your own container

```tsx
import { useVFXTransition } from "@vfx-js/react";

const { ref, run } = useVFXTransition({ transition: Swipe });

<div ref={ref} style={{ height: 300 }}>{tab}</div>

await run(() => setTab(next), { reverse: true });
```

## Vue: Nuxt and Vue Router

```bash
npm i @vfx-js/core @vfx-js/vue @vfx-js/transitions
```

```vue
<!-- app/app.vue (Nuxt) -->
<script setup lang="ts">
import { Crossfade, Swipe } from "@vfx-js/transitions";
import { vTransition } from "@vfx-js/vue";
import { VFXTransition } from "@vfx-js/vue/nuxt";
</script>

<template>
    <nav>
        <NuxtLink to="/">Home</NuxtLink>
        <NuxtLink to="/gallery" v-transition="{ transition: Swipe }">Gallery</NuxtLink>
    </nav>
    <VFXTransition :transition="Crossfade" :duration="0.8">
        <NuxtPage />
    </VFXTransition>
</template>
```

```vue
<!-- app/pages/about.vue -->
<script setup lang="ts">
import { Glitch } from "@vfx-js/transitions";
import { useTransitionIn } from "@vfx-js/vue";

useTransitionIn({ transition: Glitch });
</script>
```

- Without Nuxt, import `VFXTransition` from `@vfx-js/vue/router` and wrap `<RouterView />`. It reads the router from `app.use(router)`.
- Each path is one page. The first navigation does not run.
- Which spec wins: the link's `v-transition`, then the page's `useTransitionIn`, then the `<VFXTransition>` props. Back does not reverse unless `autoReverse` is set.
- `setNextTransition(spec)` before `navigateTo()` / `router.push()`.
- In templates use `v-transition`, not `@click="transition(spec)"`; Vue wraps the handler, so it never runs.
- Props are the `addTransition` options plus `fullscreen`. `:fullscreen="false"` lets you size the target with CSS.
- A page with an async `setup` under your own `<Suspense>` may be captured early. Use `waitFor`.

## Svelte: SvelteKit

```bash
npm i @vfx-js/core @vfx-js/svelte @vfx-js/transitions
```

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
    import { transition } from "@vfx-js/svelte";
    import { VFXTransition } from "@vfx-js/svelte/sveltekit";
    import { Crossfade, Swipe } from "@vfx-js/transitions";

    let { children } = $props();
</script>

<nav>
    <a href="/">Home</a>
    <a href="/gallery" {@attach transition({ transition: Swipe })}>Gallery</a>
</nav>
<VFXTransition transition={Crossfade} duration={0.8}>
    {@render children()}
</VFXTransition>
```

```svelte
<!-- src/routes/about/+page.svelte -->
<script lang="ts">
    import { transitionIn } from "@vfx-js/svelte";
    import { Glitch } from "@vfx-js/transitions";

    transitionIn({ transition: Glitch });
</script>
```

- Needs Svelte 5.29 or later (`{@attach}`).
- Which spec wins: the link's `transition(spec)`, then the page's `transitionIn`, then the `<VFXTransition>` props. Back does not reverse unless `autoReverse` is set.
- `setNextTransition(spec)` before `goto()`.
- `fullscreen={false}` lets you size the target with CSS.

## Astro: ClientRouter

```bash
npm i @vfx-js/core @vfx-js/astro @vfx-js/transitions
```

```astro
---
// src/layouts/Layout.astro
import { ClientRouter } from "astro:transitions";
import { VFXTransition } from "@vfx-js/astro";
---

<html lang="en" transition:animate="none">
    <head><ClientRouter /></head>
    <body>
        <nav>
            <a href="/">Home</a>
            <a href="/gallery" data-vfx-transition="swipe">Gallery</a>
        </nav>
        <VFXTransition transition="crossfade" duration={0.8}>
            <slot />
        </VFXTransition>
    </body>
</html>
```

```astro
---
// src/pages/about.astro
import { TransitionIn } from "@vfx-js/astro";
---

<TransitionIn transition="glitch" />
```

- Needs `<ClientRouter />`. Without it links reload the page and nothing animates.
- `transition:animate="none"` turns off the browser's view transition; the shader is the animation.
- Transitions are names: lowercase class names from `@vfx-js/transitions` (`crossfade`, `swipe`, `glitch`, `pixelsort`, ...). Register others with `registerVFX({ transitions: { name: ClassOrInstance } })` from `@vfx-js/astro/client`. `ease` is `"smoothstep"`, `"linear"`, or a name from `registerVFX({ eases })`.
- A link spec is a name or JSON: `data-vfx-transition='{"transition":"swipe","params":{"direction":"left"}}'`.
- Which spec wins: the link's `data-vfx-transition`, then the page's `<TransitionIn>`, then the `<VFXTransition>` props. Back does not reverse unless `autoReverse` is set.
- `fullscreen={false}` lets you size the target with CSS.
- `installTransition({ swapFunctions })` from `@vfx-js/astro/client` is what `<VFXTransition>` calls. You rarely need it.

## Other routers

Turbo, htmx and others have no binding.
Use core `run(cb)`: hold the navigation until `run` has taken the snapshot, then let `cb` wait for the new page.

```ts
router.beforeNavigate(() =>
    new Promise<void>((snapshotTaken) => {
        t.run(() => {
            snapshotTaken();                 // the router may now swap the DOM
            return waitForNewPageInDom();    // resolve when the new page is in
        }).catch(console.error);
    }),
);
```

## Rules and pitfalls

- Give the target a fixed size (explicit height, or the viewport). Content of a different size does not animate between sizes; the box jumps after the run.
- Width rules: the target must fill its parent's width or have an inline px width. Put `max-width` or centering on a wrapper, not on the target.
- A `display` rule on a slide beats `hidden`. Add `[hidden] { display: none !important }`.
- `<body>` cannot be the target. Use the router outlet (`<main>`, `#app`).
- VFX elements inside the target freeze during a run.
- Next.js `loading.tsx` shows its fallback at once, so the transition lands on the skeleton.
- Multi-page (cross-document) navigation is not supported.
- Vue, Svelte and Astro `<VFXTransition>` render plain divs on the server. No client-only wrapper is needed.
- Respect `prefers-reduced-motion`: pass `duration: 0` when it matches.