@weasel-js/renderer 1.9.4 → 1.10.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-import { S as ShaderProgramHandle, a as ShaderUniform, b as ShaderProgram, F as FillPoseBox } from './paintKinds-B2vEy9A4.js';
-export { P as PaintBindContext, c as PaintDrawKind, d as PaintDrawKindLoader, e as PaintProgram, f as PaintResources, g as ProgramSource, h as ShaderCompileError, i as fillInPoseFrame, j as fillToBoundsFrame, k as getPaintDrawKind, l as getProgramSource, m as isPaintKindKnown, p as paintDrawKindRegistry, n as programSourceRegistry, r as registerPaintDrawKind, o as registerPaintDrawKindLoader, q as registerProgram, w as warmPaintKinds } from './paintKinds-B2vEy9A4.js';
+import { S as ShaderProgramHandle, a as ShaderUniform, b as ShaderProgram, F as FillPoseBox } from './paintKinds-BmPAT51k.js';
+export { P as PaintBindContext, c as PaintDrawKind, d as PaintDrawKindLoader, e as PaintProgram, f as PaintResources, g as ProgramSource, h as ShaderCompileError, i as ShaderStage, U as UniformArray, j as fillInPoseFrame, k as fillToBoundsFrame, l as getPaintDrawKind, m as getProgramSource, n as isPaintKindKnown, p as paintDrawKindRegistry, o as programSourceRegistry, r as registerPaintDrawKind, q as registerPaintDrawKindLoader, s as registerProgram, w as warmPaintKinds } from './paintKinds-BmPAT51k.js';
 import { Mesh } from '@weasel-js/geom/tessellate';
 export { Mesh, TessellateOptions, tessellate } from '@weasel-js/geom/tessellate';
-import { GradStop, ColorSpace, CommandFill, CommandStroke, Stroke, FillStyle, TextureHandle } from '@weasel-js/paint';
-export { CommandFill, CommandPaintUnits, CommandStroke, PosedFill, SolidFill, TextureHandle } from '@weasel-js/paint';
+import { GradStop, ColorSpace, CommandFill, CommandStroke, Stroke, Fill, Paint, CommandPaint, TextureHandle } from '@weasel-js/paint';
+export { CommandFill, CommandPaint, CommandPaintUnits, CommandStroke, PosedPaint, SolidPaint, TextureHandle } from '@weasel-js/paint';
 import { GlMat3, Path } from '@weasel-js/geom';
 export { GlMat3, View as ViewLike, mat3, viewToMat3 } from '@weasel-js/geom';
 import { ResolvedRun, TextAlign, TextDirection, TextStyle, TextVerticalAlign, TextPaint, TextPose, StyledRun } from '@weasel-js/text';
-import { D as DrawBatch } from './imageCache-oJVgxhkr.js';
-export { I as ImageNodeData, a as ImageRasterSize, b as ImageStatus, T as TextureEntry, g as getImageBitmap, i as imageStatus, c as isPatternSpec, d as isVectorImageSrc, r as registerTexture, e as releaseImage, f as resolveFillPattern, h as resolvePatternSpec, j as retryImage, s as subscribeImageReady, t as textureRegistry, u as unregisterTexture } from './imageCache-oJVgxhkr.js';
+import { D as DrawBatch } from './imageCache-DYcWftY8.js';
+export { I as ImageNodeData, a as ImageRasterSize, b as ImageStatus, T as TextureEntry, g as getImageBitmap, i as imageStatus, c as isVectorImageSrc, r as registerTexture, d as releaseImage, e as resolveFillPattern, f as resolvePatternSpec, h as retryImage, s as setImageCacheBudget, j as subscribeImageReady, t as textureRegistry, u as unregisterTexture } from './imageCache-DYcWftY8.js';
 export { StrokeOptions, tessellateStroke } from '@weasel-js/stroke';
 export { RegisterFontOptions, canQueryLocalFonts, cssFontFamily, cssFontFamilyLoading, enableLocalFontOutlines, fontOutlineRegistry, fontRegistry, hasFontOutlines, isCanvasFont, listFontOutlines, loadFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
 import '@weasel-js/registry';
@@ -31,29 +31,16 @@ interface MeshResources {
  * Caches GL-side buffers + VAO per `Mesh` identity. Upload happens lazily
  * on first `handleFor(mesh)` call.
  *
- * **GC-aware cleanup (deferred-delete queue):** when a Mesh becomes
- * unreachable, the WeakMap entry is dropped automatically — but the
- * underlying GL resources (VAO, VBO, IBO) would leak forever without an
- * explicit `gl.delete*` call. We register each Mesh with a
+ * **GC-aware cleanup (deferred-delete queue):** we register each Mesh with a
  * `FinalizationRegistry`; when the Mesh is reclaimed, the finalizer pushes
- * the resources onto an internal queue. The renderer drains this queue at
- * the start of each `render()` call (via `drainPendingDeletes()`), when GL
- * is in a known state — no VAO bound, no draw mid-flight. Deleting from the
- * finalizer directly was racy (it could fire between two `gl.bindVertexArray`
- * calls inside `dispatch()`, sometimes corrupting the next draw); deferring
- * the actual delete to a known-safe point keeps the use-after-free risk to
- * zero.
- *
- * Caveats:
- *   - Finalizer timing is non-deterministic; resources may live for a frame
- *     or two beyond their Mesh, but they will be reclaimed.
- *   - If the GL context is lost between finalizer and drain, the drain
- *     no-ops safely (`gl.isContextLost()` makes deletes no-ops, and
- *     `gl.deleteBuffer(null)` is allowed).
+ * its GL resources (VAO, VBO, IBO) onto an internal queue. The renderer
+ * drains this queue at the start of each `render()` call (via
+ * `drainPendingDeletes()`), when GL is in a known state — no VAO bound, no
+ * draw mid-flight. Finalizer timing is non-deterministic; resources may live
+ * for a frame or two beyond their Mesh.
  *
  * The cache is GL-context-bound; if the context is lost and re-created, the
- * renderer should construct a new GLMeshCache. (Context loss handling lives
- * in `WeaselRenderer`.)
+ * renderer should construct a new GLMeshCache.
  */
 declare class GLMeshCache {
     private readonly gl;
@@ -70,11 +57,9 @@ declare class GLMeshCache {
     constructor(gl: WebGL2RenderingContext);
     handleFor(mesh: Mesh): GLMeshHandle;
     /**
-     * Upload a Mesh that the caller knows is single-use (e.g. the per-frame
-     * stroke ribbon from `tessellateStroke`). Returns a handle backed by fresh
-     * GL resources that the renderer will free deterministically at the end
-     * of the current frame via `freeTransient()`. Bypasses the WeakMap cache
-     * and the FinalizationRegistry, so transient meshes never wait on GC.
+     * Upload a Mesh that the caller knows is single-use. Returns a handle backed
+     * by fresh GL resources that the renderer frees at the end of the current
+     * frame via `freeTransient()`, so transient meshes never wait on GC.
      */
     uploadTransient(mesh: Mesh): GLMeshHandle;
     /**
@@ -112,19 +97,19 @@ declare class GLMeshCache {
     private upload;
 }
 
+/** A texture source the browser decodes. */
+type ImageTexSource = ImageBitmap | ImageData | HTMLCanvasElement | HTMLImageElement;
+
 /**
- * GL texture upload + cache for MSDF font atlases (and future images).
+ * GL texture upload + cache, keyed by a string id (the font family name or
+ * image id). The cache is GL-context-bound; discard and create a new one on
+ * context loss.
  *
- * Textures are keyed by a string id (the font family name or image id).
- * Pixels are uploaded once per id; a later upload of the same id reuses the
- * texture and only re-applies its wrap mode when that changed.
- * The cache is GL-context-bound; discard and create a new one on context loss.
- *
- * Atlas format: RGBA UNSIGNED_BYTE, linear filtering, no mipmaps.
- * Mipmap generation is deliberately skipped — MSDF works correctly with
- * linear filtering, and mipmap resampling corrupts the multi-channel SDF signal.
+ * Atlas format: RGBA UNSIGNED_BYTE, linear filtering, no mipmaps: mipmap
+ * resampling corrupts the multi-channel SDF signal.
  */
-type TexSource$1 = HTMLImageElement | ImageBitmap | ImageData | HTMLCanvasElement;
+
+type TexSource$1 = ImageTexSource;
 /** How a texture samples outside `0..1`. Pattern tiles need `'repeat'`;
  *  everything else clamps. WebGL2 allows `REPEAT` on NPOT textures, so a
  *  tile of any size tiles correctly. */
@@ -146,10 +131,12 @@ declare class GLTextureCache {
     /** Uploads the pixels once per id. `wrap` is re-applied whenever it differs
      *  from what the id was last uploaded under: the same registered image can
      *  be a clamped shader texture in one draw and a repeating pattern tile in
-     *  the next, and first-upload-wins gave the second one the first one's mode. */
+     *  the next. */
     upload(id: string, source: TexSource$1, wrap?: TextureWrap): string;
+    private ensure;
     /** `upload` for an id from the texture registry, whose image can be replaced
-     *  under the same id: a changed source sends its pixels again. */
+     *  under the same id: a changed source sends its pixels again. A registered
+     *  texture is an image, so its texels are premultiplied. */
     uploadRegistered(id: string, source: TexSource$1, wrap?: TextureWrap): string;
     /**
      * Delete the texture of every registry-backed id the registry has dropped.
@@ -164,38 +151,40 @@ declare class GLTextureCache {
     uploadR8(id: string, width: number, height: number, data: Uint8Array): void;
     /** Patch a rect of an existing R8 texture with tightly-packed w×h bytes. */
     subImageR8(id: string, x: number, y: number, w: number, h: number, data: Uint8Array): void;
+    /** Create a texture from premultiplied RGBA bytes that are a color: a page
+     *  of color glyphs. Mipmapped, as a font atlas must never be, because one is
+     *  drawn well below the size it was baked at. No-op if `id` already exists. */
+    uploadRGBA(id: string, width: number, height: number, data: Uint8Array): void;
+    /** Patch a rect of an existing RGBA texture with tightly-packed w×h texels. */
+    subImageRGBA(id: string, x: number, y: number, w: number, h: number, data: Uint8Array): void;
     bind(id: string, unit: number): void;
     /**
-     * Delete every uploaded GL texture and clear the map. Called by
-     * `WeaselRenderer.dispose()`. The cache is unusable but refillable
-     * afterward — a subsequent `upload()` for a previously-seen id re-creates
-     * the texture rather than restoring the deleted one.
+     * Delete every uploaded GL texture and clear the map. The cache is
+     * refillable afterward.
      */
     free(): void;
 }
 
 /**
- * GL texture upload cache for ImageBitmap objects.
+ * GL texture upload cache for ImageBitmap objects, keyed by source identity
+ * (WeakMap) so GC can reclaim unreferenced bitmaps. A collected source's
+ * texture is queued and deleted at the renderer's next frame; GC timing is
+ * not prompt, so a source's owner that knows it will never be drawn again
+ * frees it at once with {@link releaseImageSource}, and `dispose` frees them
+ * all.
  *
- * Key: ImageBitmap (or pattern source object) identity (WeakMap) — lets GC
- * reclaim unreferenced bitmaps. A collected source's texture is queued and
- * deleted at the renderer's next frame, the way `GLMeshCache` frees a mesh's
- * buffers; GC timing is not prompt, so a source's owner that knows it will
- * never be drawn again frees it at once with {@link releaseImageSource}, and
- * `dispose` frees them all.
- *
- * Wrapping is set once at upload time per the `repetition` parameter:
- *   - undefined / 'no-repeat' → CLAMP_TO_EDGE
- *   - 'repeat'   → REPEAT (both axes)
- *   - 'repeat-x' → REPEAT on S, CLAMP on T
- *   - 'repeat-y' → CLAMP on S, REPEAT on T
- *
- * Convention §2: texels stored straight; shader premultiplies.
+ * Wrapping is set once at upload time. Texels are stored premultiplied,
+ * whatever the source: see `uploadPremultiplied`.
  */
+
 type PatternRepetition = 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
-/** MIN_FILTER strategy for uploaded textures. */
-type ImageMinification = 'linear' | 'mipmap';
-type TexSource = ImageBitmap | ImageData | HTMLCanvasElement | HTMLImageElement;
+/**
+ * MIN_FILTER strategy for uploaded textures: `'linear'` never mipmaps,
+ * `'mipmap'` does at upload, and `'auto'` uploads linear and builds a
+ * texture's mipmaps the first time a frame draws it at half size or smaller.
+ */
+type ImageMinification = 'linear' | 'mipmap' | 'auto';
+type TexSource = ImageTexSource;
 /** Free `key`'s texture in every live renderer. For an owner that has replaced
  *  a source and will never draw the old one again — a later draw of it simply
  *  re-uploads. */
@@ -211,32 +200,30 @@ declare class GLImageCache {
     private readonly textures;
     /**
      * MAG_FILTER each texture currently carries, so a redundant write can be
-     * skipped.
-     *
-     * The batch sets this per flush — the same bitmap can be drawn at both
-     * filters in one frame, and the value has to be right at the draw rather than
-     * at upload. Filtering is state on the *texture object*, though, not on the
-     * unit, so re-asserting a value it already has is a write to a live texture
-     * for no reason. On a large sheet that is not free: a consumer's wall samples
-     * a 5652px-square atlas, 122MB resident, and measured `sampling: 'nearest'`
-     * costing up to 8x `'linear'` there — where the linear pass re-asserts the
-     * upload default and the nearest pass changes state on every draw.
-     *
-     * Whether that is the cause is unproven (see `docs/TODO.md`), but the write
-     * was redundant either way.
+     * skipped. The batch sets this per flush — the same bitmap can be drawn at
+     * both filters in one frame — but filtering is state on the *texture
+     * object*, not on the unit, so re-asserting a value it already has is a
+     * write to a live texture for no reason.
      */
     private readonly magFilters;
     private readonly finalizer;
     private readonly pendingDeletes;
+    /** Under `'auto'`, the sources whose mipmaps are built. */
+    private readonly mipped;
+    private frame;
+    private readonly lastDrawn;
     /** `minification` selects the MIN_FILTER strategy for uploaded textures.
-     *  `'linear'` (default) is the screen path's existing behavior. `'mipmap'`
-     *  generates mipmaps and filters LINEAR_MIPMAP_LINEAR — required for
-     *  quality minification when a large source bitmap is drawn small (the
-     *  headless print/export path); bilinear-only minification undersamples
-     *  and produces moiré. */
+     *  `'mipmap'` generates mipmaps and filters LINEAR_MIPMAP_LINEAR: when a
+     *  large source bitmap is drawn small, bilinear-only minification
+     *  undersamples and produces moiré. `'auto'` pays for that only on the
+     *  textures a frame draws small, when it first does. */
     constructor(gl: WebGL2RenderingContext, minification?: ImageMinification);
-    /** Delete the textures of sources collected since the last call. The
-     *  renderer calls this at the top of each `render()`. */
+    /** Open a frame: what {@link drewInLatestFrame} answers about from here on.
+     *  The renderer calls this at the top of each `render()`. */
+    beginFrame(): void;
+    /** Whether `key` was uploaded or bound since the last {@link beginFrame}. */
+    drewInLatestFrame(key: object): boolean;
+    /** Delete the textures of sources collected since the last call. */
     drainPendingDeletes(): void;
     /** Delete `key`'s texture, if it has one. */
     release(key: object): void;
@@ -247,6 +234,12 @@ declare class GLImageCache {
      *  its textures died with it. */
     abandon(): void;
     upload(key: object, source: TexSource, repetition?: PatternRepetition): WebGLTexture;
+    /** Whether `key` would gain from {@link buildMipmaps}: only under `'auto'`,
+     *  and only until they are built. */
+    lacksMipmaps(key: object): boolean;
+    /** Build `key`'s mipmaps and filter minification through them from here
+     *  on. Its texture must be uploaded. Leaves no texture bound. */
+    buildMipmaps(key: object): void;
     bind(key: object, unit: number): void;
     /** Set `key`'s MAG_FILTER, skipping the call when it already holds that
      *  value. Its texture must be bound to the active unit — callers pair this
@@ -264,8 +257,8 @@ declare class GLImageCache {
  * the same unit, so a run does not break per gradient. The atlas is
  * GL-context-bound; discard and recreate on context loss.
  *
- * Output convention §2: texels are stored as straight RGBA. The fragment
- * shader applies premultiplication before writing outColor.
+ * Texels are stored as straight RGBA. The fragment shader applies
+ * premultiplication before writing outColor.
  */
 
 /** Bake gradient stops into a 256-entry RGBA lookup strip, which the shader
@@ -319,10 +312,8 @@ declare class GradientRampAtlas {
     hitRate(): number;
     resetStats(): void;
     /**
-     * Delete the atlas texture and forget every row in it. Called by
-     * `WeaselRenderer.dispose()`. The CPU mirror goes with it, so the atlas is
-     * unusable but refillable afterward (stats are left as-is; call
-     * `resetStats()` separately if desired).
+     * Delete the atlas texture and forget every row in it. The CPU mirror goes
+     * with it, so the atlas is refillable afterward. Stats are left as-is.
      */
     free(): void;
     /** The row the next ramp is written to: a free one, a taller atlas, or the
@@ -351,16 +342,13 @@ declare class GroupState {
     get colorMatrix(): Float32Array;
     push(frame: GroupFrame): void;
     /**
-     * Push a frame whose children paint into a surface of their own.
-     *
-     * The transform still accumulates — the children draw where they would have
-     * drawn. Alpha and colour do not: they describe how the finished surface
-     * joins the frame, and applying them on the way in as well would fade the
-     * pixels an effect is about to read, then fade them again on the way out.
+     * Push a frame whose children paint into a surface of their own. The
+     * transform still accumulates. Alpha and color do not: applying them on the
+     * way in would fade the pixels an effect is about to read, then fade them
+     * again on the way out.
      *
      * Returns the pair the caller must apply at composite time — what `push`
-     * would have left on the stack — so the composition rules live here and not
-     * in the dispatcher.
+     * would have left on the stack.
      */
     pushIsolated(frame: GroupFrame): {
         alpha: number;
@@ -373,14 +361,10 @@ declare class GroupState {
 }
 
 /**
- * One full-screen pass over what a group has already drawn.
+ * One full-screen pass over what a group has already drawn. A group's effects
+ * run in order, each reading the previous one's output through `u_source`.
  *
- * The renderer runs a group's effects in order, each reading the previous
- * one's output through `u_source` and writing a whole new buffer — so an
- * effect is free to read neighbouring pixels, which is the entire point and
- * the one thing `colorMatrix` can never do.
- *
- * `uniforms` are the effect's own; `u_source`, `u_resolution` and `u_texel`
+ * `uniforms` are the effect's own; `u_source`, `u_resolution`, and `u_texel`
  * come from the renderer and must not be passed here.
  */
 interface Effect {
@@ -388,31 +372,34 @@ interface Effect {
     uniforms?: Record<string, ShaderUniform>;
 }
 /**
- * Register a fragment shader as an effect. Sugar over `registerProgram` with
- * the effect vertex shader, and the reason a consumer never imports the
- * prelude: an effect that registers with the *custom-shader* vertex shader
- * compiles, runs, and samples its source upside down.
+ * Register a fragment shader as an effect. An effect registered through
+ * `registerProgram` with the *custom-shader* vertex shader compiles, runs, and
+ * samples its source upside down.
  *
- * The fragment shader reads `v_uv` and `u_source`, and may declare
- * `u_resolution` / `u_texel`. See `effectPrelude.ts` for the full contract,
- * including the premultiplied-alpha requirement.
+ * The fragment shader reads `v_uv` and `u_source`, may declare `u_resolution` /
+ * `u_texel`, and must write premultiplied alpha. See `effectPrelude.ts`.
  *
  * @experimental
  */
 declare function registerEffect(id: string, frag: string): ShaderProgramHandle;
 
 /**
- * Solid-fill paint variant (subset of the full `FillStyle` union from
- * `@weasel-js/paint`). Kept for back-compat with step-1/2 consumers and
- * because some code reads `fill.color` directly. Through step 4, fills can
- * be any `FillStyle` variant — solid, pattern, or gradient.
+ * How an isolated group's finished surface joins what is already drawn.
+ *
+ * Every color the renderer writes is premultiplied, so each Porter-Duff
+ * operator is `source * Fa + destination * Fb` with both factors read off one
+ * alpha or the other, which is a blend function and needs no second pass.
  */
-interface SolidPaint {
-    fill?: 'solid';
-    /** Any CSS color string accepted by `parseColor`: hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`, named, or `transparent`. */
-    color: string;
-    opacity?: number;
+/** A Porter-Duff operator, named as canvas 2D's `globalCompositeOperation` names it. */
+type CompositeOp = 'source-over' | 'source-in' | 'source-out' | 'source-atop' | 'destination-over' | 'destination-in' | 'destination-out' | 'destination-atop' | 'xor' | 'lighter' | 'copy';
+/** What one side of the blend is scaled by. */
+type BlendFactor = 'zero' | 'one' | 'source-alpha' | 'one-minus-source-alpha' | 'destination-alpha' | 'one-minus-destination-alpha';
+/** An operator with no name: `source * source + destination * destination`, on premultiplied color. */
+interface BlendFactors {
+    source: BlendFactor;
+    destination: BlendFactor;
 }
+
 /** DrawCommand variants implemented through step 6. */
 type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | SpritesDrawCommand | ShaderDrawCommand;
 /** Draw a path, filled and/or stroked. The workhorse command: every shape the
@@ -421,22 +408,20 @@ interface PathDrawCommand {
     kind: 'path';
     path: Path;
     /** Solid, pattern, or gradient (linear/radial/conic), resolved for the
-     *  renderer: `commandFill` makes one from a node's `FillStyle`. */
+     *  renderer: `commandPaint` makes one from a node's `Paint`. */
     fill?: CommandFill;
     /** Stroke spec. Its `paint` takes what `fill` does. */
     stroke?: CommandStroke;
     /**
      * Optional flat RGBA-per-path-anchor color array (length =
-     * `4 × countPathAnchors(path)`, floats in 0..1). The renderer
-     * arc-length-interpolates these per-anchor colors across the
-     * flattened/triangulated mesh between consecutive anchors using the
-     * mesh's `anchorA` / `anchorB` / `anchorT` parameterization.
+     * `4 × countPathAnchors(path)`, floats in 0..1), arc-length-interpolated
+     * across the mesh between consecutive anchors.
      *
      * **`fill` must also be set when using `vertexColors`.** The renderer
      * only enters the per-vertex shader path when the command has a fill
-     * (the fill provides the opacity uniform; the vertex colors override
-     * the fill's color). Pass any solid `fill` (e.g. `{ color: '#fff' }`)
-     * as the placeholder; the per-vertex colors win in the shader.
+     * (the fill provides the opacity uniform). Pass any solid `fill` (e.g.
+     * `{ paint: { color: '#fff' } }`) as the placeholder; the per-vertex colors
+     * win in the shader.
      */
     vertexColors?: number[];
 }
@@ -473,16 +458,31 @@ interface GroupDrawCommand {
      * group asks for one.
      */
     effects?: readonly Effect[];
+    /**
+     * Draw the children into a buffer of their own and composite it once, the
+     * render-target boundary `effects` makes, with no pass run over it. `alpha`
+     * and `colorMatrix` then apply to the finished surface, so overlapping
+     * children do not show through each other as they do when each is faded on
+     * its own. Costs a device-resolution buffer and a full-screen composite.
+     */
+    isolate?: boolean;
+    /**
+     * How the group's finished surface joins what is already drawn. Default
+     * `source-over`. Any other operator isolates the group, and its composite
+     * covers the whole target inside the enclosing clip, so an operator that
+     * scales the destination by the source's alpha (`source-in`,
+     * `destination-in`, `destination-atop`, `copy`) also clears everything the
+     * group left empty. Operators reading the destination's alpha need a target
+     * that has one: a context created with `alpha: false` reads as opaque.
+     */
+    composite?: CompositeOp | BlendFactors;
     children: DrawCommand[];
 }
 /**
  * Text draw command. Renders one or more runs at (`x`, `y`) in screen
- * space, optionally word-wrapping at `maxWidth`. The renderer resolves
- * each run's `(fontFamily, fontWeight, fontStyle)` to an MSDF atlas via
- * `resolveFontVariant` and bucket-draws by atlas + color group.
- *
- * `style` carries node-level defaults (`lineHeight`, anti-alias width)
- * that don't belong on individual runs.
+ * space, optionally word-wrapping at `maxWidth`. `style` carries node-level
+ * defaults (`lineHeight`, anti-alias width) that don't belong on individual
+ * runs.
  */
 interface TextDrawCommand {
     kind: 'text';
@@ -510,11 +510,15 @@ interface TextDrawCommand {
 }
 /**
  * Image draw command — renders `image` at screen-space rect (x, y, w, h).
- * The image is stretched to fit; no tiling. Use a pattern FillStyle on a path
+ * The image is stretched to fit; no tiling. Use a pattern Paint on a path
  * for tiling.
  */
 interface ImageDrawCommand {
     kind: 'image';
+    /** A bitmap holding premultiplied pixels, which is what `createImageBitmap`
+     *  makes unless told otherwise. One made with `premultiplyAlpha: 'none'`
+     *  draws too bright wherever it is translucent: a browser uploads a bitmap
+     *  as it stands, and nothing reports which kind it is. */
     image: ImageBitmap;
     x: number;
     y: number;
@@ -547,15 +551,12 @@ declare const SPRITE_STRIDE = 9;
  * Draw many quads sampling one bitmap — an atlas, a sprite sheet, a wall of
  * thumbnails. The same picture as a run of `ImageDrawCommand`s the renderer
  * would coalesce anyway, handed over already packed so it never walks a
- * command object per quad.
- *
- * Reach for it past a few thousand sprites. Below that a plain run of image
- * commands merges into the same single draw and reads better; the packed form
- * exists because at 20,000 the object walk is about half the frame.
+ * command object per quad. Reach for it past a few thousand sprites: at
+ * 20,000 the object walk is about half the frame.
  *
  * The sprites are one run: they share a texture, a filter, and whatever group
- * transform, alpha, color matrix and clip are live, exactly as a merged run of
- * image commands would. Anything varying per sprite is in the array.
+ * transform, alpha, color matrix and clip are live. Anything varying per
+ * sprite is in the array.
  */
 interface SpritesDrawCommand {
     kind: 'sprites';
@@ -581,7 +582,9 @@ interface SpritesDrawCommand {
  * The kit automatically sets `u_bounds`, `u_view`, and `u_proj` — do not
  * declare those in `uniforms`.
  *
- * @experimental API may change before v2.
+ * `program` is the handle the module-level `registerProgram()` returned. Each
+ * renderer compiles it the first time it draws one, so a layer emits this
+ * command with nothing set up on the canvas or the renderer beforehand.
  */
 interface ShaderDrawCommand {
     kind: 'shader';
@@ -626,7 +629,8 @@ interface RenderStats {
 interface WeaselRendererOptions {
     /** A WebGL2 context to draw with. Wins over `canvas`. */
     gl?: WebGL2RenderingContext;
-    /** A canvas to open a stencil-backed WebGL2 context on, when `gl` is absent. */
+    /** A canvas to open a stencil-backed WebGL2 context on, when `gl` is absent.
+     *  The renderer sets its drawing buffer and never its CSS size. */
     canvas?: HTMLCanvasElement;
     /** Drawing size in CSS pixels. */
     width: number;
@@ -634,10 +638,10 @@ interface WeaselRendererOptions {
     height: number;
     /** Device pixels per CSS pixel. */
     dpr: number;
-    /** MIN_FILTER strategy for image/pattern textures (`GLImageCache`).
-     *  Default `'linear'` — the existing screen behavior. The headless
-     *  `renderSceneToPixels` path passes `'mipmap'` for print-quality
-     *  minification. Explicitly passing `'linear'` is always valid. */
+    /** MIN_FILTER strategy for image textures (`GLImageCache`). Default
+     *  `'linear'`. `'mipmap'` builds mipmaps for every image at upload, as
+     *  the headless `renderSceneToPixels` path does; `'auto'` builds them
+     *  for an image the first time a frame draws it at half size or smaller. */
     imageMinification?: ImageMinification;
     /** Flatness tolerance for curve tessellation, in WORLD units (see
      *  `TessellateOptions.flattenTolerance`). When set, path fills are
@@ -742,12 +746,11 @@ declare class WeaselRenderer {
     /**
      * Compile a consumer-registered shader program against this renderer's GL context.
      *
-     * Call once per renderer after the module-level `registerProgram()`.
-     * Throws `ShaderCompileError` if compilation fails.
+     * Optional: a program compiles on the first frame that draws with it. Call
+     * this after the module-level `registerProgram()` to pay for the compile
+     * before that frame, or to catch the `ShaderCompileError` it throws.
      *
      * In dev mode, calling again with the same handle replaces the compiled program.
-     *
-     * @experimental
      */
     registerProgram(handle: ShaderProgramHandle): void;
     private installProgram;
@@ -767,11 +770,11 @@ declare class WeaselRenderer {
      *  Applied per `render()` rather than once at construction because a
      *  co-tenant sharing this context moves all of it between our frames. */
     private applyGlState;
-    /** Viewport and scissor for this frame. Re-applied inside `render()` because
-     *  a co-tenant on the same context moves both between our frames. */
     /** This renderer's rect in device pixels, top-left origin. A tile rounds its
      *  edges rather than its size, so two that share a CSS edge share a device one. */
     private deviceRect;
+    /** Viewport and scissor for this frame. Re-applied inside `render()` because
+     *  a co-tenant on the same context moves both between our frames. */
     private applyTarget;
     /** Confine this renderer to a rect of its drawing buffer, or pass null to
      *  give it the whole buffer back. Takes effect from the next `render()`. */
@@ -781,14 +784,9 @@ declare class WeaselRenderer {
     private onContextLost;
     private onContextRestored;
     /** Free every GL resource this renderer created and detach its
-     *  context-loss listeners. Idempotent.
-     *
-     *  That covers the built-in and consumer-registered programs (their shaders
-     *  go with them), the shared quad geometry, the batch, the effect targets,
-     *  and every cache: atlas and gradient-ramp textures, bitmap and pattern
-     *  textures, and meshes — transient, persistent, and those whose Path was
-     *  already collected. The context itself is left alone, so a caller-owned
-     *  context can host renderer after renderer without accumulating anything.
+     *  context-loss listeners. Idempotent. The context itself is left alone, so
+     *  a caller-owned context can host renderer after renderer without
+     *  accumulating anything.
      *
      *  A disposed renderer ignores further `render()` and `registerProgram()`
      *  calls. */
@@ -881,14 +879,15 @@ interface CullRect {
  * caps included), images and sprites by their quads, and every bound is taken
  * through the accumulated transform as the AABB of its corners, so rotation
  * only enlarges it. Text and shader commands are always kept, and so is a
- * group with `effects` — an effect may move pixels. Clips are ignored, which
+ * group with `effects` — an effect may move pixels — or its own `composite`,
+ * which changes the destination even where the group drew nothing. Clips are ignored, which
  * can only keep more. A group whose children all go is dropped.
  *
  * Returns `cmds` itself when nothing was dropped.
  */
 declare function cullDrawCommands(cmds: DrawCommand[], transform: GlMat3, rect: CullRect): DrawCommand[];
 /**
- * {@link strokeReach} at a known world-to-screen scale — what a painter
+ * How far a stroke reaches past its geometry at a known world-to-screen scale — what a painter
  * bounding its own output before it paints can know. `least` is the scale
  * along the axis the transform shrinks most, where it differs from `scale`.
  *
@@ -957,12 +956,9 @@ declare function vignette({ amount, feather }: {
 /**
  * Kit-supplied vertex shader for a full-screen effect pass.
  *
- * Distinct from `CUSTOM_VERT_SRC` on purpose. That one places its quad through
- * `u_bounds` and `u_proj`, so its `v_uv` runs top-down in *screen* space; an
- * effect samples a texture the scene was just rendered into, whose v axis runs
- * the other way. Passing `a_position` straight to `gl_Position` and `a_uv`
- * straight out keeps the two aligned — `QUAD_VERTICES` already carries
- * `a_uv == (a_position + 1) / 2` on both axes.
+ * Distinct from `CUSTOM_VERT_SRC` on purpose. That one's `v_uv` runs top-down
+ * in *screen* space; an effect samples a texture the scene was just rendered
+ * into, whose v axis runs the other way.
  *
  * PUBLIC CONTRACT — what every effect fragment shader may read:
  *
@@ -971,11 +967,10 @@ declare function vignette({ amount, feather }: {
  *   uniform vec2  u_resolution   source size in device pixels
  *   uniform vec2  u_texel        1.0 / u_resolution — one texel step
  *
- * PREMULTIPLIED ALPHA: `u_source` holds premultiplied RGBA, because that is
- * what the scene blends into it. An effect that weights neighbouring samples
- * (a blur) is doing the right thing on premultiplied values; one that
- * manipulates rgb against a must premultiply its own output the same way the
- * custom-shader prelude requires.
+ * PREMULTIPLIED ALPHA: `u_source` holds premultiplied RGBA. An effect that
+ * weights neighboring samples (a blur) is doing the right thing on
+ * premultiplied values; one that manipulates rgb against a must premultiply
+ * its own output.
  */
 declare const EFFECT_VERT_SRC = "#version 300 es\nin vec2 a_position;\nin vec2 a_uv;\nout vec2 v_uv;\n\nvoid main() {\n  v_uv = a_uv;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
 /** Uniforms the renderer sets on every effect pass. An effect must not
@@ -988,26 +983,26 @@ declare const EFFECT_KIT_UNIFORMS: readonly ["u_source", "u_resolution", "u_texe
  */
 
 /**
- * `fill` as a draw command's fill: `'bounds'` units mapped onto `box`, and a
- * tile spec swapped for its texture. `null` when a spec cannot rasterize.
+ * `paint` as a draw command's paint: `'bounds'` units mapped onto `box`, and
+ * a tile kind swapped for its texture. `null` when a tile cannot rasterize.
  */
-declare function commandFill(fill: FillStyle, box: FillPoseBox): CommandFill | null;
+declare function commandPaint(paint: Paint, box: FillPoseBox): CommandPaint | null;
+/**
+ * `fill` as a draw command's fill, its paint resolved by {@link commandPaint}.
+ * `null` when the fill carries no paint, or its paint cannot be resolved.
+ */
+declare function commandFill(fill: Fill, box: FillPoseBox): CommandFill | null;
 /**
  * `stroke` as a draw command's stroke, its paint resolved as
- * {@link commandFill} resolves a fill. `null` when the stroke carries no
+ * {@link commandPaint} resolves one. `null` when the stroke carries no
  * paint, or its paint cannot be resolved.
  */
 declare function commandStroke(stroke: Stroke, box: FillPoseBox): CommandStroke | null;
 
 /**
  * Tile-pattern primitive — a small helper for building repeating texture
- * tiles from a draw callback. The result plugs into a `FillStyle` of
- * `{ fill: 'pattern', pattern }` (see `@weasel-js/paint`).
- *
- * GL-backed: the tile is rendered to an `OffscreenCanvas` (with a 2D fallback
- * to a regular `<canvas>` for environments without `OffscreenCanvas`),
- * converted to an `ImageBitmap`, and registered with `registerTexture()`.
- * The returned `TextureHandle` is what `FillStyle.pattern` accepts.
+ * tiles from a draw callback. The result plugs into a `Paint` of
+ * `{ kind: 'texture', texture }` (see `@weasel-js/paint`).
  *
  * For ready-to-use named patterns (hatch, crosshatch, dots, chunks),
  * see the `@weasel-js/renderer/patterns-builtin` subpath.
@@ -1017,25 +1012,22 @@ declare function commandStroke(stroke: Stroke, box: FillPoseBox): CommandStroke
 interface TilePatternOpts {
     /** Edge length (in pixels) of the square offscreen tile. */
     size: number;
-    /** FillStyle one tile at integer-pixel coordinates `(0, 0) .. (size, size)`. */
+    /** Paint one tile at integer-pixel coordinates `(0, 0) .. (size, size)`. */
     draw: (oc: CanvasRenderingContext2D, size: number) => void;
 }
 /**
- * Render a single tile to an offscreen canvas and register it as a GL
- * texture, returning a `TextureHandle` you can wrap in a `FillStyle` of
- * `{ fill: 'pattern', pattern }`. Returns `null` only when an
- * `OffscreenCanvas`/2D context can't be acquired (very rare; same fallback
- * semantics as the prior `CanvasPattern`-based implementation).
+ * Render a single tile and register it as a GL texture, returning a
+ * `TextureHandle` you can wrap in a `Paint` of
+ * `{ kind: 'texture', texture }`. Returns `null` only when an
+ * `OffscreenCanvas`/2D context can't be acquired.
  */
 declare function createTilePattern(opts: TilePatternOpts): TextureHandle | null;
 
 /**
  * Build a `TextDrawCommand`. `textCommandFromPose` is the command for a text
- * node — what `kit:text` and `createTextLayer` both emit. `textCommand` takes
- * a plain string and wraps it in one run; `textCommandFromRuns` takes the
- * styled runs directly, for text that has no pose. All three
- * resolve through `resolveTextStyle` + `resolveRuns`, so every emitter of a
- * text command derives `align` and per-run resolution the same way — a
+ * node; `textCommand` takes a plain string and wraps it in one run;
+ * `textCommandFromRuns` takes the styled runs directly, for text that has no
+ * pose. All three resolve through `resolveTextStyle` + `resolveRuns` — a
  * caller that assembles the command by hand is one field away from a
  * silently different result.
  *
@@ -1067,4 +1059,4 @@ declare function textCommand(x: number, y: number, text: string, style?: TextSty
  */
 declare function textCommandFromPose(pose: TextPose, scale?: number): TextDrawCommand;
 
-export { type CullRect, type DrawCommand, EFFECT_KIT_UNIFORMS, EFFECT_VERT_SRC, type Effect, FillPoseBox, type GroupDrawCommand, IDENTITY_COLOR_MATRIX, type ImageDrawCommand, type ImageMinification, OUTLINE_MIN_SCREEN_PX, type PathDrawCommand, type RenderOptions, type RenderSpan, type RenderSpanStats, type RenderStats, type RenderTarget, SPRITE_STRIDE, type ShaderDrawCommand, ShaderProgram, ShaderProgramHandle, ShaderUniform, type SolidPaint, type SpriteSheet, type SpritesDrawCommand, type TextDrawCommand, type TilePatternOpts, WeaselRenderer, type WeaselRendererOptions, blur, boundsMissRect, buildGradientRamp, commandFill, commandStroke, createTilePattern, cullDrawCommands, frameRect, registerEffect, releaseImageSource, strokeReachAt, textCommand, textCommandFromPose, textCommandFromRuns, vignette };
+export { type BlendFactor, type BlendFactors, type CompositeOp, type CullRect, type DrawCommand, EFFECT_KIT_UNIFORMS, EFFECT_VERT_SRC, type Effect, FillPoseBox, type GroupDrawCommand, IDENTITY_COLOR_MATRIX, type ImageDrawCommand, type ImageMinification, OUTLINE_MIN_SCREEN_PX, type PathDrawCommand, type RenderOptions, type RenderSpan, type RenderSpanStats, type RenderStats, type RenderTarget, SPRITE_STRIDE, type ShaderDrawCommand, ShaderProgram, ShaderProgramHandle, ShaderUniform, type SpriteSheet, type SpritesDrawCommand, type TextDrawCommand, type TilePatternOpts, WeaselRenderer, type WeaselRendererOptions, blur, boundsMissRect, buildGradientRamp, commandFill, commandPaint, commandStroke, createTilePattern, cullDrawCommands, frameRect, registerEffect, releaseImageSource, strokeReachAt, textCommand, textCommandFromPose, textCommandFromRuns, vignette };