# Ditherlab for coding agents

Use this page when a coding agent needs to add a Ditherlab-style procedural shader background to a website.

Canonical guide: https://ditherlab.app/agents/

Machine-readable contract: https://ditherlab.app/agent-kit/v1/manifest.json

Stable ES module: https://ditherlab.app/agent-kit/v1/ditherlab-background.js

Working example: https://ditherlab.app/agent-kit/v1/example.html

## Recommended agent instruction

> Use the Ditherlab agent kit at https://ditherlab.app/agent-kit/v1/manifest.json to add one shader background to this project. Match the existing stack and design. Preserve semantic HTML and interaction contrast; provide a static no-WebGL fallback, a reduced-motion state, visibility pause, resize handling, context-loss recovery, and cleanup. Do not import the full editor.

## Scope

The v1 kit is a dependency-free WebGL2 background renderer. It contains six procedural scene families and five palette/dither treatments adapted from Ditherlab. It is deliberately smaller than the editor: do not import, embed, or recreate the complete Ditherlab application.

Scenes: `mesh`, `neuro`, `warp`, `smoke`, `voronoi`, `blobs`.

Dither treatments: `quantize`, `bayer8`, `noise`, `halftone-dots`, `halftone-lines`.

Lifecycle methods: `start()`, `pause()`, `set(options)`, `resize()`, `destroy()`.

## Minimal integration

```html
<canvas id="dither-bg" aria-hidden="true"></canvas>

<style>
  .hero { position: relative; isolation: isolate; background: #050510; }
  #dither-bg { position: absolute; inset: 0; width: 100%; height: 100%; z-index: -1; }
</style>

<script type="module">
  import { createDitherlabBackground } from
    "https://ditherlab.app/agent-kit/v1/ditherlab-background.js";

  const shader = createDitherlabBackground(
    document.querySelector("#dither-bg"),
    {
      scene: "smoke",
      dither: "bayer8",
      palette: ["#050510", "#312e81", "#7c6cff", "#e0e7ff"],
      pixelSize: 4,
      speed: 0.11,
      seed: 0.42
    }
  );

  shader.start();
</script>
```

Remote import is suitable for prototypes. For production, vendor the module and retain:

- https://ditherlab.app/agent-kit/v1/LICENSE
- https://ditherlab.app/agent-kit/v1/NOTICE

## Integration requirements

- Keep content and controls as semantic HTML. The canvas is decorative and should use `aria-hidden="true"`.
- Preserve readable contrast through every frame; a shader should never make text or controls disappear.
- Provide a static CSS or image fallback for no JavaScript and no WebGL2.
- Respect `prefers-reduced-motion`. The kit renders a still frame by default in that mode.
- Pause rendering while the page is hidden.
- Resize with the container and clamp device pixel ratio for performance.
- Recover from WebGL context loss.
- Call `destroy()` when a component unmounts or the background is removed.
- Prefer one intentional shader surface per page. Do not turn every section into a moving canvas.

## Options

Consult the JSON manifest for types, defaults, ranges, enums, and default palettes:

https://ditherlab.app/agent-kit/v1/manifest.json

## Accuracy note

This is a web-background adaptation of Ditherlab's shader techniques, not a byte-identical export of the full editor renderer. The editor also includes CPU effects, error diffusion, ASCII rendering, and export orchestration that are intentionally outside this kit.

## Permission and provenance

The standalone Ditherlab Background Kit v1 is licensed under Apache-2.0 for personal, client, and commercial websites. This license applies to the kit, not to the complete Ditherlab editor.

The procedural scene work acknowledges Paper Shaders by paper.design. Preserve the bundled license and notice when redistributing the module.

- License: https://ditherlab.app/agent-kit/v1/LICENSE
- Notice: https://ditherlab.app/agent-kit/v1/NOTICE
- Paper Shaders: https://github.com/paper-design/shaders