# Sfuma — guide for coding agents Sfuma turns a JSON document into an animated, grainy gradient rendered on one canvas with WebGL2. It is meant for hero backgrounds and abstract decorative surfaces. This page is the complete reference. Everything below is current for the shipped package — the layer and effect tables are generated from the renderer's own capability metadata. - Site: https://sfuma.dev - Live editor: https://sfuma.dev/editor - Examples: https://sfuma.dev/examples ## How to use this document To build a composition for someone's project: 1. Take their brand colours. 2. Start from the closest recipe below. 3. Replace the colours, keeping the blend rule in "Ground and blend modes" — this is the single most common way to end up with a blank canvas. 4. Validate with `validateSfumaConfig` before shipping. It returns path-aware errors. ## Install ```bash npm install sfuma ``` The package has no framework dependency. It needs a WebGL2-capable canvas and nothing else. ## Minimal integration ```ts import { createSfuma } from "sfuma"; import composition from "./hero.json"; const canvas = document.querySelector("#hero") as HTMLCanvasElement; const sfuma = createSfuma({ canvas, config: composition }); sfuma.play(); new ResizeObserver(() => sfuma.resize()).observe(canvas); ``` The canvas should be sized by CSS; Sfuma reads that box and manages the drawing buffer itself. Give it `display: block; width: 100%; height: 100%` inside a positioned container. ### React ```tsx import { useEffect, useRef } from "react"; import { createSfuma, type SfumaConfig } from "sfuma"; export function SfumaBackground({ config }: { config: SfumaConfig }) { const canvas = useRef(null); useEffect(() => { if (!canvas.current) return; const sfuma = createSfuma({ canvas: canvas.current, config }); sfuma.play(); const observer = new ResizeObserver(() => sfuma.resize()); observer.observe(canvas.current); return () => { observer.disconnect(); sfuma.destroy(); }; }, [config]); return