@godot-scene-web/canvas 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1085 @@
+import { $ as DamageRect, A as DrawListPatchView, B as ScreenEffectDrawContext, C as DRAW_TEXTURED_MESH, D as DrawListFragment, E as DrawList, F as GlyphsView, G as createDrawListPatchView, H as createClipRectView, I as NinePatchView, J as createPolylineView, K as createGlyphsView, L as PolylineView, M as ExternalEffectDrawContext, N as FLIP_H, O as DrawListFragmentPatch, P as FLIP_V, Q as CommandBounds, R as QuadView, S as DRAW_SCREEN_EFFECT, T as DrawCommandName, U as createDrawList, V as TexturedMeshView, W as createDrawListFragment, X as createTexturedMeshView, Y as createQuadView, Z as setViewColorMatrix, _ as DRAW_EXTERNAL_EFFECT, a as StageCanvas, at as RETAINED_MAX_DAMAGE_COVERAGE, b as DRAW_POLYLINE, c as BLEND_ADD, ct as createDamageTiles, d as BLEND_SUB, dt as outsetDamageRect, et as DamageTile, f as BlendMode, ft as transformDamageRect, g as DRAW_COMMAND_NAMES, h as DRAW_CLIP_PUSH, i as STAGE_CONTEXT_ATTRIBUTES, it as RETAINED_DAMAGE_TILE_SIZE, j as ExternalEffectDrawCommand, k as DrawListOptions, l as BLEND_MIX, lt as damageIntersects, m as DRAW_CLIP_POP, n as CanvasStage, nt as DamageTransform, o as StageProjection, ot as commandDamageBounds, p as ClipRectView, pt as unionDamageRect, q as createNinePatchView, r as CanvasStageOptions, rt as DirtyRect, s as createCanvasStage, st as createDamageRect, t as GlyphPass, tt as DamageTiles, u as BLEND_MUL, ut as isDamageEmpty, v as DRAW_GLYPHS, w as DrawCommandKind, x as DRAW_QUAD, y as DRAW_NINE_PATCH, z as ScreenEffectDrawCommand } from "./glyph-pass-DfQlp_IH.js";
+import { HeadlessGodotParticleDirectPass, HeadlessGodotParticleDirectRenderInput, HeadlessShaderProducer, HeadlessShaderRenderInput } from "@godot-scene-web/canvas-effects/webgl";
+
+//#region src/batcher.d.ts
+/**
+ * The quad batcher: everything the executor knows about MERGING draws, with no
+ * GL in it, so the flush decisions — the thing that decides whether a frame is 20
+ * draw calls or 200 — are unit-testable rather than inferred from a profiler.
+ *
+ * WHY MULTI-TEXTURE BATCHING IS THE WHOLE POINT. Probing recorded scenes for
+ * batch runs (a run = a maximal span of consecutive painting nodes sharing
+ * texture + blend + clip + colour-matrix state) found combat at 152 runs over 183
+ * painting nodes — 1.2 nodes per batch, i.e. essentially no batching — and 151 of
+ * those 152 breaks were the TEXTURE alone. The map is the same story: 174 runs
+ * over 825 nodes, 173 texture breaks. But the number of DISTINCT textures per
+ * screen is only 24-65. So a batch that can hold many textures at once collapses
+ * the run count towards the number of times the state that a batch CANNOT hold
+ * changes — blend (0-16 per screen) and clip (0-26) — plus one flush per
+ * texture-table refill. That is the difference between "tens of draws" and "one
+ * draw per node", and it is why the slot table below is not an optimization to
+ * add later.
+ *
+ * HOW A TEXTURE STOPS BREAKING A BATCH. Each batch binds up to
+ * `maxTextureSlots` textures to consecutive texture units and each quad carries
+ * the INDEX of the one it samples. The fragment shader turns that index back into
+ * a sampler with a compiled `if` ladder (GLSL ES 3.00 forbids indexing a sampler
+ * array with anything but a constant). A quad whose texture is not in the table
+ * takes the next free slot; when the table is full the batch flushes and starts a
+ * new table.
+ *
+ * COLOUR MATRICES GET THE SAME TREATMENT, for the same reason at a smaller scale:
+ * the card screens carry 30-48 HSV-transformed quads, and one draw call each
+ * would undo the texture win. A batch holds up to `maxColorMatrices` matrices in
+ * a uniform array with the IDENTITY pinned at slot 0, so "no matrix" costs
+ * nothing and needs no separate program. Identical matrices share a slot (the
+ * table is deduped by value), which matters because those 30-48 quads are usually
+ * a handful of distinct tints applied to many cards.
+ *
+ * ORDER IS NEVER REORDERED. Instances are drawn in the order they were pushed —
+ * `drawArraysInstanced` rasterizes instance N before instance N+1, which is the
+ * property a painter's-algorithm 2D renderer with no depth buffer depends on. So
+ * this batcher only ever MERGES CONSECUTIVE commands; it never sorts, and it can
+ * therefore be dropped in front of any draw list without changing what the frame
+ * looks like. Bucketing non-adjacent commands by texture is a separate,
+ * order-unsafe transformation that belongs to whoever BUILDS the list and knows
+ * which spans are safe to permute.
+ *
+ * FOUR EXPLICIT CORNERS, NOT AN AFFINE BASIS. An instance carries `p0..p3`
+ * outright (8 floats) rather than a 2x3 transform (6). The two extra floats buy
+ * arbitrary quadrilaterals, which is what lets `./polyline`'s stroke segments AND
+ * its join wedges (a triangle spelled as a quad with two coincident corners) ride
+ * in the same buffer, the same shader and the same batch as every sprite. The
+ * alternative — a second program and a mid-frame break for every polyline — costs
+ * far more than 8 bytes per quad. The consequence to know about: UV interpolates
+ * affinely per triangle, so a NON-parallelogram textured quad would show a seam
+ * along the split diagonal. Nothing produces one (sprites and nine-patch bands
+ * are affine images of a rect; the non-affine quads are untextured stroke
+ * geometry), and if something ever does, the fix is to split it rather than to
+ * make every quad pay for projective interpolation.
+ */
+/** Floats per instance. See the field offsets below for the layout. */
+declare const INSTANCE_FLOATS = 18;
+/** Offset of `p0.x` — four `(x, y)` corners, in the unit-square order
+ *  `(0,0)`, `(1,0)`, `(1,1)`, `(0,1)`. Design space. */
+declare const INSTANCE_CORNERS_OFFSET = 0;
+/** Offset of the normalized source rect `(u0, v0, uSpan, vSpan)`. A span is
+ *  NEGATIVE for a flipped axis, which is how `FLIP_H`/`FLIP_V` are carried. */
+declare const INSTANCE_UV_OFFSET = 8;
+/** Offset of the PREMULTIPLIED tint, `(r, g, b, a)`. */
+declare const INSTANCE_COLOR_OFFSET = 12;
+/** Offset of `(textureSlot, colorMatrixSlot)`. Matrix slot 0 is the identity. */
+declare const INSTANCE_SLOTS_OFFSET = 16;
+/** Floats per colour-matrix slot. */
+declare const COLOR_MATRIX_FLOATS = 9;
+/** The most texture units this batcher will ever ask for, whatever the GPU
+ *  reports. Sixteen is the WebGL2 (GLES 3.0) guaranteed minimum for
+ *  `MAX_TEXTURE_IMAGE_UNITS`, so asking for more buys a shader that some
+ *  conformant device cannot link, in exchange for a batch boundary the measured
+ *  key counts (24-65 distinct textures per screen) would still hit. */
+declare const MAX_TEXTURE_SLOTS = 16;
+/** Default colour-matrix table size, including the identity at slot 0. */
+declare const DEFAULT_COLOR_MATRIX_SLOTS = 16;
+/** What a batch binds to a texture unit. Structural on purpose: the batcher only
+ *  needs the handle's IDENTITY to slot it, and a test can hand it a stand-in. */
+interface BatchTexture {
+  readonly texture: WebGLTexture;
+}
+/**
+ * The staging view a caller fills before {@link QuadBatcher.push}. Owned by the
+ * batcher and reused, so a frame's worth of quads allocates nothing.
+ */
+interface QuadInstance {
+  /** Corner at unit-square `(0, 0)`, design space. */
+  x0: number;
+  y0: number;
+  /** Corner at `(1, 0)`. */
+  x1: number;
+  y1: number;
+  /** Corner at `(1, 1)`. */
+  x2: number;
+  y2: number;
+  /** Corner at `(0, 1)`. */
+  x3: number;
+  y3: number;
+  /** Normalized source origin (the texel under corner `(0, 0)`). */
+  u0: number;
+  v0: number;
+  /** Normalized source span; negative mirrors the axis. */
+  uSpan: number;
+  vSpan: number;
+  /** PREMULTIPLIED tint. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+declare function createQuadInstance(): QuadInstance;
+type BatchFlushReason = /** The texture table was full and the next quad wanted a texture not in it. */"textureSlots" /** The colour-matrix table was full and the next quad wanted a new matrix. */ | "colorMatrices" /** The blend mode changed; GL blend state is per-draw, not per-instance. */ | "blend" /** The clip scope changed; the scissor box is per-draw too. */ | "clip"
+/**
+ * A glyph run interrupted the quads.
+ *
+ * Not a state change this batcher could hold: the glyph pass replaces the program and the vertex
+ * array outright, so the pending batch has to be DRAWN under the executor's state before the
+ * pass runs. Counted separately from `blend` and `clip` because it is the one break a consumer
+ * can remove by moving text, and a frame whose batching regressed should say so by axis.
+ */
+| "glyphs" /** A screen-dependent effect interrupted the instanced-quad program. */ | "effects" /** An indexed mesh interrupted the instanced-quad program. */ | "meshes" /** A retained compiled GPU run takes over after direct quad staging. */ | "compiled" /** End of the draw list (or an explicit flush by the caller). */ | "end";
+/**
+ * One batch, handed to the sink. Every array is the batcher's own live storage —
+ * valid only for the duration of the call, and only over the stated prefix.
+ */
+interface Batch {
+  /** Instance data: `quadCount * INSTANCE_FLOATS` floats from index 0. */
+  readonly instances: Float32Array;
+  readonly quadCount: number;
+  /** Texture table. Entries `0 .. textureCount - 1` are the units to bind;
+   *  everything past that is a stale `null` slot and must not be read. */
+  readonly textures: readonly (BatchTexture | null)[];
+  readonly textureCount: number;
+  /** `colorMatrixCount * COLOR_MATRIX_FLOATS` floats; slot 0 is the identity. */
+  readonly colorMatrices: Float32Array;
+  readonly colorMatrixCount: number;
+  readonly blend: BlendMode;
+  /** The clip scope this batch was accumulated under (see `./clip-stack`). */
+  readonly clipEpoch: number;
+  readonly reason: BatchFlushReason;
+}
+interface BatcherStats {
+  /** Batches emitted, i.e. draw calls the executor issues for quads. */
+  batches: number;
+  /** Instances pushed. */
+  quads: number;
+  /** Texture-unit binds — `textureCount` summed over batches. */
+  textureBinds: number;
+  /** Largest single batch, in instances. */
+  maxBatchQuads: number;
+  /** Times the instance arena had to grow (should settle at zero). */
+  arenaGrowths: number;
+  flushes: Record<BatchFlushReason, number>;
+}
+interface QuadBatcherOptions {
+  /** Where a finished batch goes. Called synchronously from `push`/`flush`. */
+  draw(batch: Batch): void;
+  /** Texture units per batch; clamped to `[1, MAX_TEXTURE_SLOTS]`. */
+  maxTextureSlots?: number;
+  /** Colour-matrix slots per batch INCLUDING the identity; at least 1. */
+  maxColorMatrices?: number;
+  /** Initial instance-arena capacity, in quads. */
+  quadCapacity?: number;
+}
+interface QuadBatcher {
+  readonly maxTextureSlots: number;
+  readonly maxColorMatrices: number;
+  /** Instances accumulated in the OPEN batch. */
+  readonly quadCount: number;
+  /** Texture slots taken in the open batch. */
+  readonly textureCount: number;
+  /** Colour-matrix slots taken in the open batch, including the identity. */
+  readonly colorMatrixCount: number;
+  readonly blend: BlendMode;
+  readonly stats: BatcherStats;
+  /** The reusable staging instance; fill it, then call {@link QuadBatcher.push}. */
+  readonly quad: QuadInstance;
+  /** Start a frame: drop any open batch WITHOUT drawing it, and zero the stats. */
+  reset(): void;
+  /** Flush first if the mode differs, then adopt it. */
+  setBlend(blend: BlendMode): void;
+  /** Flush first if the scope differs, then adopt it. */
+  setClipEpoch(epoch: number): void;
+  /**
+   * Commit {@link QuadBatcher.quad}. `colorMatrix` is 9 row-major floats at
+   * `colorMatrixOffset`, or `null` for the identity (which costs no slot).
+   */
+  push(texture: BatchTexture, colorMatrix?: ArrayLike<number> | null, colorMatrixOffset?: number): void;
+  /** Emit the open batch, if it has anything in it. */
+  flush(reason?: BatchFlushReason): void;
+}
+declare function createQuadBatcher(options: QuadBatcherOptions): QuadBatcher;
+//#endregion
+//#region src/clip-stack.d.ts
+/**
+ * The executor's clip scope: a stack of design-space rects, resolved to a GL
+ * scissor box and (for the rare rounded clip) to a pair of fragment uniforms.
+ *
+ * WHY DESIGN SPACE, INTERSECTED BEFORE INTEGERIZING. Each level's rect is
+ * intersected with its parent as FLOATS, in the scene's own coordinates, and only
+ * the final result is mapped to framebuffer pixels and snapped. Integerizing at
+ * every level instead would round the same edge repeatedly, and rounding OUTWARDS
+ * (which is what a clip must do — see below) compounds: three nested clips on the
+ * same edge would leak up to three pixels.
+ *
+ * WHY `floor(min)` / `ceil(max)`. A scissor box is whole pixels; the clip it
+ * approximates is not. Rounding outwards keeps every pixel the clip PARTIALLY
+ * covers, so content is never sheared off by a sub-pixel; the cost is that up to
+ * one pixel of overdraw survives on each edge. The other choice (round inwards)
+ * eats a visible line off the edge of every scrolling list, which is the failure
+ * a reader will actually notice.
+ *
+ * THE FLIPPED SCISSOR ORIGIN. `gl.scissor` measures Y from the BOTTOM of the
+ * drawing buffer; the design space here — like every 2D scene — measures it from
+ * the top. So the box's Y is `framebufferHeight - bottomEdge`, not `topEdge`, and
+ * getting it wrong produces a clip that is correct in size, correct in X, and
+ * mirrored about the middle of the screen — which looks like a layout bug rather
+ * than a scissor bug. `clip-stack.test.ts` pins the algebra and the pixel test
+ * `nested clips` pins it on a real GPU.
+ *
+ * ROUNDED CORNERS ARE FRAGMENT WORK, and only for the INNERMOST rounded clip. A
+ * scissor cannot express a radius, and a stencil pass per rounded scope would
+ * cost more than the feature is worth at the measured population (rounded clips
+ * are a handful per screen, nested rounded clips none). So the stack tracks the
+ * deepest rounded rect currently open and hands it to the shader as a rounded-rect
+ * distance test; every ancestor still clips squarely through the scissor, which is
+ * exact for all of them except an outer rounded one's four corners.
+ *
+ * NON-AXIS-ALIGNED CLIPS FALL BACK TO THEIR AABB. A scissor box is axis-aligned,
+ * so a clip can only be exact while the design->framebuffer transform is a scale
+ * and a translate. It always is today (see `./present`), and the measured
+ * population of rotated clips across the recorded scenes is zero — so rather than
+ * carry a stencil path for a case that does not occur, a transform with rotation
+ * or skew clips to the transformed rect's bounding box and increments
+ * {@link ClipStack.rotatedFallbacks}. A caller that ever sees that counter move
+ * has found the case that justifies the stencil.
+ */
+/** A resolved clip rect in DESIGN space. */
+interface ClipBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+/** The innermost rounded clip, in DESIGN space; `radius <= 0` means none is open. */
+interface RoundedClip {
+  centerX: number;
+  centerY: number;
+  halfWidth: number;
+  halfHeight: number;
+  radius: number;
+}
+/** A GL scissor box: framebuffer pixels, origin BOTTOM-LEFT. */
+interface ScissorBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * A design->framebuffer-pixel affine, in the draw-list's `Transform2D` order
+ * `[xx, xy, yx, yy, originX, originY]`: `px = xx*x + yx*y + ox`, `py = xy*x +
+ * yy*y + oy`, with `py` measured DOWN from the top of the buffer.
+ */
+type PixelTransform = ArrayLike<number>;
+interface ClipStack {
+  /** Open clip scopes. */
+  readonly depth: number;
+  /** Bumped by every push/pop/reset: the batcher's cheap "did the scope change". */
+  readonly epoch: number;
+  /** Clips that could not be expressed as an axis-aligned scissor (see the module note). */
+  readonly rotatedFallbacks: number;
+  /** The intersected clip in design space, or `null` when nothing is clipped. */
+  bounds(): ClipBounds | null;
+  /** The innermost rounded clip, or `null`. */
+  rounded(): RoundedClip | null;
+  push(clip: ClipRectView): void;
+  pop(): void;
+  /** Start a frame: drop every scope (a list may end unbalanced) AND the frame's
+   *  {@link ClipStack.rotatedFallbacks} count, which is per-frame like every
+   *  other executor statistic. */
+  reset(): void;
+  /**
+   * The current clip as a scissor box against a `width`x`height` framebuffer,
+   * written into `out`. With nothing clipped this is the whole framebuffer.
+   */
+  scissor(transform: PixelTransform, width: number, height: number, out: ScissorBox): ScissorBox;
+}
+declare function createScissorBox(): ScissorBox;
+/** True when `transform` is a pure scale + translate, i.e. a scissor can be exact. */
+declare function isAxisAligned(transform: PixelTransform): boolean;
+declare function createClipStack(): ClipStack;
+//#endregion
+//#region src/color.d.ts
+/**
+ * Premultiplied colour composition — the arithmetic the batcher writes into an
+ * instance and the fragment shader repeats on the GPU, in one place so the two
+ * can be checked against each other (and against `html`'s CPU tint bake).
+ *
+ * TWO CONVENTIONS MEET HERE, and mixing them up is the classic renderer bug:
+ *
+ * - a **premultiplied** colour carries `(r·a, g·a, b·a, a)`. That is what the
+ *   draw-list's tints are, what every texture in {@link ./textures} is uploaded
+ *   as, what the fragment emits, and what the canvas is declared as. Composing
+ *   two premultiplied colours is a plain componentwise multiply.
+ * - a **straight** colour carries `(r, g, b, a)` with the channels independent.
+ *   The only thing that wants straight colour is the 3x3 colour matrix, because
+ *   the matrix is defined on the texture's own RGB — multiply a premultiplied
+ *   colour by it and a 50%-alpha pixel is transformed as if it were half as
+ *   bright.
+ *
+ * Everything below is sRGB-domain: no linearization anywhere. That is not a
+ * shortcut, it is the contract — the matrices come from Godot HSV materials that
+ * Godot itself applies to sRGB texture bytes, and `html`'s
+ * `applyColorMatrixToPixels` (the CPU bake of the same transform, used by the DOM
+ * renderer) applies them to sRGB bytes too. Linearizing here would make the GPU
+ * path disagree with the DOM path it is meant to replace.
+ */
+/** Row-major 3x3 identity, the value slot 0 of a batch's matrix table holds. */
+declare const IDENTITY_COLOR_MATRIX: readonly number[];
+/** A straight or premultiplied RGBA colour, 0..1 per channel. */
+interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+declare function createRgba(): Rgba;
+declare function clamp01(value: number): number;
+/**
+ * Straight `(r,g,b,a)` -> premultiplied, clamped. The shape a producer has (a
+ * Godot `modulate` is straight) turned into the shape {@link QuadView} wants.
+ */
+declare function premultiply(r: number, g: number, b: number, a: number, out: Rgba): Rgba;
+/**
+ * Premultiplied -> straight, with the `a === 0` hole filled with black. The
+ * inverse of {@link premultiply} up to that hole (a fully transparent
+ * premultiplied pixel has forgotten its colour, so nothing can recover it).
+ */
+declare function unpremultiply(colour: Rgba, out: Rgba): Rgba;
+/**
+ * Compose two PREMULTIPLIED colours — a texel times its quad's tint. A plain
+ * componentwise multiply, which is the whole reason the premultiplied form is
+ * worth keeping: with straight colours this would need the alpha handled apart
+ * from the channels it has already scaled.
+ */
+declare function modulatePremultiplied(source: Rgba, tint: Rgba, out: Rgba): Rgba;
+/**
+ * Apply a row-major 3x3 to STRAIGHT sRGB channels in 0..1, clamped — the float
+ * twin of `html`'s `applyColorMatrixToPixels` (which works in 0..255 bytes and
+ * clamps because it writes a `Uint8ClampedArray`) and of the colour-matrix branch
+ * in the executor's fragment shader. All three must agree; `colour.test.ts`
+ * asserts the first two against each other pixel for pixel.
+ *
+ * Alpha is untouched, exactly as `feColorMatrix` with only the RGB rows set.
+ */
+declare function applyColorMatrix01(colour: Rgba, matrix: ArrayLike<number>, offset: number, out: Rgba): Rgba;
+/**
+ * The full per-fragment colour law, on the CPU: a PREMULTIPLIED texel, its
+ * optional colour matrix, and the quad's PREMULTIPLIED tint, in the order the
+ * shader applies them (un-premultiply, transform, re-premultiply, modulate).
+ *
+ * This exists so a pixel test can state the number it expects from the same
+ * expression the GPU evaluates rather than from a second, hand-derived one.
+ */
+declare function shadeQuadPixel(texel: Rgba, matrix: ArrayLike<number> | null, matrixOffset: number, tint: Rgba, out: Rgba): Rgba;
+/** True when the 9 floats at `offset` are the identity, i.e. a no-op slot. */
+declare function isIdentityColorMatrix(matrix: ArrayLike<number>, offset?: number): boolean;
+/**
+ * True when the 9 floats at `a`/`b` are equal — the batcher's matrix-table
+ * dedupe. EXACT equality, deliberately: the table's job is to notice that many
+ * cards carry the same computed tint, and an epsilon would merge two tints a
+ * scene meant to differ. The corollary is that a `Float32Array` and a plain
+ * `number[]` holding "the same" value do not match (`0.3` and its f32 round-trip
+ * are different numbers), so a caller that wants dedupe should keep one storage
+ * width — which the draw-list and this package both do.
+ */
+declare function colorMatricesEqual(a: ArrayLike<number>, aOffset: number, b: ArrayLike<number>, bOffset: number): boolean;
+//#endregion
+//#region src/replay.d.ts
+/** A sparse ordered command selection. The executor walks the original list in
+ * order, so batching and painter ordering remain exactly the direct path's. */
+interface CommandMask {
+  readonly count: number;
+  /** A screen-dependent command exists; partial retained replay must decline. */
+  readonly requiresFullReplay?: boolean;
+  includes(index: number): boolean;
+  indices(): readonly number[];
+}
+/** Retained replay must stay below this fraction of the complete painter list. */
+declare const RETAINED_MAX_REPLAY_FRACTION = 0.4;
+/**
+ * Largest command count that is strictly below the retained replay threshold.
+ * Clip pushes/pops are commands too: omitting them would not restore the
+ * original painter state, so they count against the same budget.
+ */
+declare function maxPartialReplayCommands(commandCount: number): number;
+declare const REPLAY_MASK_SCRATCH: unique symbol;
+interface ReplaySelectionOptions {
+  /** Map design-space command bounds into the damage rectangle's space. */
+  transform?: DamageTransform;
+  /**
+   * Final-damage-coordinate raster/effect reach added after `transform`.
+   * Defaults to one final pixel so antialiasing/filtering still selects a
+   * command whose geometry falls just beyond a tile edge. Use this for effects
+   * whose reach is known in final coordinates; producer-local effects belong
+   * in the command's own local bounds, not both places.
+   */
+  rasterOutset?: number;
+  /** Optional cached bounds provider. `null` takes the unknown-bounds policy. */
+  boundsAt?: (index: number, out: CommandBounds) => CommandBounds | null;
+  /** Decline instead of returning an unboundedly large partial replay. */
+  maxCommands?: number;
+  /** Unknown visual bounds cannot safely seed a damaged tile. The default is a
+   * full/direct fallback; `select` is available for callers that knowingly
+   * prefer conservative overdraw. */
+  unknownBounds?: "fullReplay" | "select";
+}
+/** Reusable storage for a replay selection. Its mask and `indices()` array keep
+ * identity across calls; after high-water growth selecting a tile allocates no
+ * arrays. A threshold/screen-effect decline clears the selection. */
+interface ReplayMaskScratch extends CommandMask {
+  readonly thresholdExceeded: boolean;
+  /** False until `select()` has validated this frame's complete list. */
+  readonly selected: boolean;
+  /** Internal nominal marker: only a validated selection may drive an FBO replay. */
+  readonly [REPLAY_MASK_SCRATCH]: true;
+  select<TTexture>(list: DrawList<TTexture>, damage: DamageRect, options?: ReplaySelectionOptions): ReplayMaskScratch;
+}
+/** True only for masks created by this module and safe for a partial FBO replay. */
+declare function isPartialReplayMask(mask: ReplayMaskScratch, list?: DrawList<unknown>): mask is ReplayMaskScratch;
+declare function createReplayMaskScratch(capacity?: number): ReplayMaskScratch;
+/**
+ * Select just the commands that can change `damage`, preserving all clip pushes
+ * and pops needed to replay them from an empty clip stack. Unknown bounds are
+ * selected conservatively. This is deliberately a mask rather than a copied
+ * command list: all reads stay in the original retained arenas.
+ */
+declare function createReplayMask<TTexture>(list: DrawList<TTexture>, damage: DamageRect, options?: ReplaySelectionOptions): ReplayMaskScratch;
+//#endregion
+//#region src/compiled-draw-list.d.ts
+/** A maximal run that can stay in the quad executor without a painter-order
+ * barrier. Texture/matrix slots deliberately are not included: those limits are
+ * context-specific and the live batcher remains their authority. */
+interface CompiledBatchDescriptor {
+  readonly start: number;
+  readonly end: number;
+  readonly blend: BlendMode;
+  readonly clipDepth: number;
+}
+interface CompiledDrawListDiagnostics {
+  planBuilds: number;
+  structuralInvalidations: number;
+  planReuses: number;
+  /** CPU template ranges refreshed after safe command patches. */
+  templateRangeUpdates: number;
+  reusedSelections: number;
+  reusedBatches: number;
+}
+interface CompiledRefreshResult {
+  readonly rebuilt: boolean;
+  readonly rangeUpdates: number;
+  /** Reused storage listing only commands patched since the prior refresh. */
+  readonly changedCommands: readonly number[];
+  /** Increments on every structural/overflow/context plan rebuild. */
+  readonly planGeneration: number;
+  /** Current DrawList content revision represented by this plan. */
+  readonly contentRevision: number;
+  /** Revision a cached consumer must match before applying this delta. */
+  readonly deltaBaseRevision: number;
+}
+/**
+ * A retained, allocation-free planning view of a stable draw list. It never
+ * owns GL objects: the executor's grow-only instance buffer remains the single
+ * GPU allocation authority. The WebGL executor may cache these templates in
+ * plan-keyed GPU buffers. Quad templates remove transform/source/tint decoding from replay;
+ * all non-quad commands deliberately take the direct executor path.
+ */
+interface CompiledDrawList<TTexture = unknown> {
+  readonly list: DrawList<TTexture>;
+  readonly batches: readonly CompiledBatchDescriptor[];
+  readonly diagnostics: CompiledDrawListDiagnostics;
+  refresh(): CompiledRefreshResult;
+  invalidate(): void;
+  /** Fill the batcher's reusable staging instance from a cached quad template. */
+  fillQuad(index: number, textureWidth: number, textureHeight: number, out: QuadInstance): boolean;
+  /** Fill `out` with a cached conservative bound, or return null for unknown. */
+  commandBounds(index: number, out: DamageRect): DamageRect | null;
+  /** Reuse caller-owned selection storage and cached bounds. */
+  select(damage: DamageRect, scratch: ReplayMaskScratch, options?: ReplaySelectionOptions): ReplayMaskScratch;
+}
+declare function compileDrawList<TTexture>(list: DrawList<TTexture>): CompiledDrawList<TTexture>;
+/** Convenience for consumers with no existing scratch. Retained loops should
+ * create one scratch once and call `plan.select` instead. */
+declare function createCompiledReplayMask<TTexture>(plan: CompiledDrawList<TTexture>, damage: DamageRect, options?: ReplaySelectionOptions): ReplayMaskScratch;
+//#endregion
+//#region src/textures.d.ts
+/**
+ * The executor's texture cache — PER CONTEXT, and its own rather than a
+ * generalization of `@godot-scene-web/html`'s.
+ *
+ * WHY NOT REUSE `html/webgl/shared-gl`'s CACHE. That module opens with a note
+ * saying its single context and its single module-scoped texture map are
+ * load-bearing: both live runtimes (shaders and particles) must share ONE
+ * WebGL2 context, because a page with many cards would otherwise walk into the
+ * browser's ~16-live-context limit, and ONE cache, so identical urls upload once.
+ * Threading a context parameter through it would turn a documented singleton into
+ * a keyed registry — a real change to an invariant two shipping runtimes rest on,
+ * to serve a consumer that wants DIFFERENT pixels anyway:
+ *
+ * - a `WebGLTexture` belongs to the context that made it and cannot be bound in
+ *   another, so the stage's own context could not use those entries even if it
+ *   could see them;
+ * - shared-gl uploads STRAIGHT alpha (`UNPACK_PREMULTIPLY_ALPHA_WEBGL` false),
+ *   because its shaders do Godot's multiply themselves; this cache uploads
+ *   PREMULTIPLIED (see below), which is a different byte in every texel;
+ * - shared-gl's entries are immortal and url-keyed with a load listener; a stage
+ *   that paints hundreds of megabytes of card atlas needs refcounts and a
+ *   `reset()` for context loss.
+ *
+ * So this is option (b) from the brief: a small cache of its own, ~150 lines, no
+ * change to a package two runtimes depend on.
+ *
+ * PREMULTIPLIED UPLOAD IS THE POINT, not a detail. `LINEAR` filtering blends
+ * texels; blending STRAIGHT colour weights a fully transparent texel's (usually
+ * black, or garbage) RGB equally with its opaque neighbour's, so every sprite
+ * edge gets a dark fringe and every atlas region bleeds its padding. Blending
+ * PREMULTIPLIED colour weights each texel's contribution by its own alpha, which
+ * is the arithmetic filtering is supposed to be doing. It also means a texel and
+ * the quad's tint compose with one componentwise multiply, and it is the same
+ * convention the stage canvas is declared with — one statement of the rule from
+ * the PNG to the compositor.
+ *
+ * SOURCES MUST BE READY. This module never decodes: it uploads what it is handed.
+ * A half-loaded `HTMLImageElement` uploads as nothing useful, so the caller
+ * decodes (`decode()`, `createImageBitmap`, a canvas it drew itself) and hands
+ * over a finished source. That keeps the whole package clear of DOM lifecycle —
+ * reading `.width` off an object someone else created is the only thing here that
+ * touches a DOM-shaped value.
+ */
+/** Anything WebGL can upload directly. */
+type CanvasTextureSource = TexImageSource;
+/** A cached texture. `width`/`height` are the UPLOADED pixel dimensions, which is
+ *  what normalizes a draw-list's page-pixel source rect into UVs. */
+interface CanvasTextureHandle {
+  readonly texture: WebGLTexture;
+  readonly width: number;
+  readonly height: number;
+}
+interface TextureCacheStats {
+  /** Live entries. */
+  entries: number;
+  /** Pixel uploads made: `texImage2D` calls plus the `texSubImage2D` re-uploads
+   *  {@link CanvasTextureCache.update} does into storage that already fits. */
+  uploads: number;
+  /** Of those, the ones that had to RE-SPECIFY the texture's storage — a first
+   *  upload, or an `update` whose source changed size. The difference between
+   *  this and `uploads` is how often the re-upload fast path was taken, which is
+   *  the number a consumer that streams into one key wants to watch. */
+  respecs: number;
+  /** Entries deleted because their last reference was released. */
+  evictions: number;
+  /** Resident RGBA bytes, including every generated mip level. */
+  bytes: number;
+}
+/** Sampling and source-alpha options shared by texture acquisition methods.
+ *
+ * Mipmaps make minification stable, but their filtered levels can sample pixels
+ * outside an atlas rect. Use them only for standalone images or padded atlases.
+ */
+interface CanvasTextureOptions {
+  /** `true` when the source already contains `rgb * a`. Defaults to false. */
+  premultiplied?: boolean;
+  /** Generate a complete mip chain. Not suitable for unpadded atlas pages. */
+  mipmap?: boolean;
+  /** Minification filter. Defaults to LINEAR, or LINEAR_MIPMAP_LINEAR with mips. */
+  minFilter?: number;
+  /** Magnification filter. Defaults to LINEAR; NEAREST is supported. */
+  magFilter?: number;
+}
+interface CanvasTextureCache {
+  readonly stats: TextureCacheStats;
+  /** The 1x1 opaque-white texel every untextured quad samples, so a solid fill
+   *  needs no second shader and no special slot. */
+  white(): CanvasTextureHandle;
+  /** Look up without uploading or retaining. */
+  peek(key: string): CanvasTextureHandle | undefined;
+  /**
+   * Upload `source` under `key` and take a reference. A key already present is
+   * NOT re-uploaded (that is the decode-once guarantee) — only referenced again;
+   * use {@link CanvasTextureCache.update} to replace its pixels.
+   */
+  acquire(key: string, source: CanvasTextureSource, options?: CanvasTextureOptions): CanvasTextureHandle;
+  /**
+   * Same, from raw RGBA bytes. `premultiplied` says whether `pixels` already
+   * carries `rgb*a`; when it does not, the multiply happens HERE in JS rather
+   * than through `UNPACK_PREMULTIPLY_ALPHA_WEBGL`, whose behaviour over an
+   * `ArrayBufferView` is not worth depending on.
+   */
+  acquireBytes(key: string, pixels: Uint8Array | Uint8ClampedArray, width: number, height: number, options?: CanvasTextureOptions): CanvasTextureHandle;
+  /** Take another reference to an existing key. Throws when it is not present. */
+  retain(key: string): CanvasTextureHandle;
+  /** Drop a reference; the entry is deleted when the last one goes. */
+  release(key: string): void;
+  /**
+   * Replace an existing (or create a new) entry's pixels, keeping its refcount.
+   *
+   * A source the same size as what the entry already holds is re-uploaded with
+   * `texSubImage2D`, INTO the storage that is already there; only a size change
+   * re-specifies it with `texImage2D`. That matters for a consumer streaming a
+   * live surface into one key every frame, which is the shape this method exists
+   * for: a re-spec frees the old mip level and allocates a new one on every call,
+   * so a same-size stream would churn a few megabytes of driver allocation per
+   * frame to write the same number of texels. See `stats.respecs`.
+   */
+  update(key: string, source: CanvasTextureSource): CanvasTextureHandle;
+  /**
+   * Write `source` into an EXISTING entry's storage at `(x, y)`, leaving the rest
+   * of it untouched. Nothing is allocated, nothing is re-specified, the refcount
+   * does not move, and the sampler parameters are not re-set.
+   *
+   * This is the ATLAS PAGE case, and it is why {@link CanvasTextureCache.update}
+   * is not enough for it. A page is one texture that many small sources are
+   * written into over time; `update` can only replace the whole thing, so a
+   * consumer holding a 1024x1024 page would have to re-upload all four megabytes
+   * every time one 40x18 label changed — which on a phone is tens of milliseconds
+   * for a few kilobytes of new pixels. Writing just the region is proportional to
+   * what actually changed.
+   *
+   * REFUSED, with `null` and no GL call at all, when the key is unknown or when
+   * the rect does not lie wholly inside the entry's real storage (see
+   * `Entry.storageW`, which is not always the entry's claimed size). Both would
+   * otherwise be a silent `INVALID_VALUE` on the context — an error the caller
+   * cannot see and the next draw cannot explain. A refusal is a fact the caller
+   * is expected to handle (re-allocate, or fall back), not an exception.
+   *
+   * Counted as one `uploads` and never a `respec`, which is the distinction the
+   * stat exists to make.
+   */
+  updateRegion(key: string, source: CanvasTextureSource, x: number, y: number): CanvasTextureHandle | null;
+  /** The context was lost: forget every entry WITHOUT touching the dead driver. */
+  reset(): void;
+  /** Delete every texture and empty the cache. */
+  dispose(): void;
+}
+declare function createTextureCache(gl: WebGL2RenderingContext): CanvasTextureCache;
+//#endregion
+//#region src/executor-webgl.d.ts
+/**
+ * The WebGL2 executor: a draw list in, GL draws out.
+ *
+ * ONE PROGRAM, ONE VERTEX FORMAT, ONE BUFFER for the whole scene. Every command
+ * kind is reduced to the same instanced quad — a sprite is one, a nine-patch is
+ * up to nine (`./nine-patch`), a polyline is one per segment plus one per join
+ * (`./polyline`), a solid fill is one sampling a 1x1 white texel. That is what
+ * lets `./batcher` merge across command kinds instead of only within them, and it
+ * is why there is no "solid" shader, no "line" shader and no per-kind draw path
+ * to keep in sync.
+ *
+ * WHAT BREAKS A BATCH, and what deliberately does not. GL state that lives on the
+ * DRAW rather than on the instance has to break one: the blend mode, the scissor
+ * box, and the rounded-clip uniforms. Everything else is per-instance data —
+ * transform, source rect, tint, texture (an index into the batch's slot table),
+ * colour matrix (an index into the batch's uniform table) — so it costs a few
+ * floats instead of a draw call. See `./batcher`'s note for the measurement that
+ * decided this.
+ *
+ * ORDER OF OPERATIONS AROUND A STATE CHANGE, which is the one genuinely subtle
+ * thing in this file. A flush DRAWS with whatever GL state is currently set, so
+ * the pending batch must be flushed BEFORE the new state is applied, never after.
+ * Every state change here therefore reads: tell the batcher (which flushes the
+ * old batch under the old GL state), then touch GL. Doing it the other way round
+ * is invisible in a screenshot of a static scene and produces a one-frame-late
+ * clip the moment anything moves.
+ *
+ * THE ONE COMMAND THAT IS NOT A QUAD. `glyphs` runs are outlines evaluated per fragment, which no
+ * amount of instancing turns into the program above, so they are delegated to an injected
+ * {@link GlyphPass} (`./glyph-pass`) and cost one draw call each. That makes them the only place
+ * this file hands the context to somebody else mid-frame, and the order-of-operations rule above is
+ * exactly what governs it: flush, then the pass, then rebind. `emitGlyphsCommand` is where that is
+ * written down.
+ *
+ * THE ALPHA CONTRACT, end to end: textures upload premultiplied (`./textures`),
+ * tints in the draw list are premultiplied, the fragment emits `vec4(rgb*a, a)`,
+ * the MIX blend is `(ONE, ONE_MINUS_SRC_ALPHA)`, and the canvas is declared
+ * `premultipliedAlpha: true` (`./present`). Any one of those five flipped on its
+ * own is silent — nothing errors, the picture is just wrong — which is why they
+ * are named together here.
+ */
+/** A texture handle the executor can draw: the GL object and the size its source
+ *  rects are measured against. `CanvasTextureHandle` satisfies it. */
+type ExecutorTexture = CanvasTextureHandle;
+/** GL blend state for a Godot blend mode, as ENUM NAMES so the mapping is pure
+ *  and unit-testable (the same trick `html`'s `blendFactorsFor` uses). */
+interface BlendState {
+  equationRgb: "FUNC_ADD" | "FUNC_REVERSE_SUBTRACT";
+  equationAlpha: "FUNC_ADD";
+  srcRgb: "ONE" | "DST_COLOR";
+  dstRgb: "ONE" | "ZERO" | "ONE_MINUS_SRC_ALPHA";
+  srcAlpha: "ONE" | "DST_ALPHA";
+  dstAlpha: "ONE" | "ZERO" | "ONE_MINUS_SRC_ALPHA";
+}
+/** The GL blend state a Godot `CanvasItemMaterial.BlendMode` maps to. */
+declare function blendStateFor(blend: BlendMode): BlendState;
+interface ExecutorStats {
+  /** Draw-list commands read. */
+  commands: number;
+  /** Quad instances pushed, including expanded nine-patch bands and stroke quads. */
+  quads: number;
+  /** `drawArraysInstanced` calls — the number this executor exists to keep small. */
+  batches: number;
+  /** Texture-unit binds summed over batches. */
+  textureBinds: number;
+  /** Times the scissor box actually changed. */
+  scissorChanges: number;
+  /** Times GL blend state actually changed. */
+  blendChanges: number;
+  ninePatches: number;
+  ninePatchQuads: number;
+  polylines: number;
+  polylineQuads: number;
+  /** Indexed textured-mesh commands executed. */
+  texturedMeshes: number;
+  /** Triangle-list primitives submitted by textured meshes. */
+  texturedMeshTriangles: number;
+  /** `drawElements` calls issued by textured meshes. */
+  texturedMeshDrawCalls: number;
+  /** `glyphs` commands handed to the installed {@link CanvasExecutorOptions.glyphs} pass. */
+  glyphRuns: number;
+  /** Glyphs the pass reported drawing, summed over runs. Excludes ones it skipped. */
+  glyphs: number;
+  /** Draw calls the pass reported. One per run, for the reason {@link GlyphPass.drawRun} gives. */
+  glyphDrawCalls: number;
+  glyphRunBatches: number;
+  glyphRunBatchFallbacks: number;
+  /**
+   * `glyphs` commands seen with NO pass installed.
+   *
+   * A NAMED NO-OP RATHER THAN A SILENT ONE. A list carrying text into an executor that cannot draw
+   * text is a wiring mistake — the consumer forgot to pass `glyphs` — and its symptom is a page
+   * that renders perfectly except for having no words on it. That is exactly the kind of failure
+   * a screenshot review passes and a counter catches.
+   */
+  glyphRunsDropped: number;
+  /** Screen-dependent passes executed at their recorded painter position. */
+  screenEffects: number;
+  /** Required screen passes that refused or failed at runtime. */
+  screenEffectFailures: number;
+  /** Direct external passes executed at their recorded painter position. */
+  externalEffects: number;
+  /** Required direct external passes that refused or failed at runtime. */
+  externalEffectFailures: number;
+  /** Clip rects that could not be an exact scissor (see `./clip-stack`). */
+  rotatedClipFallbacks: number;
+  /** `clipPop`s with nothing open — a malformed list, survived rather than thrown. */
+  unbalancedClipPops: number;
+  /**
+   * Commands whose kind this executor does not handle.
+   *
+   * The dispatch switch had no `default` for its first five kinds, so a sixth added to the IR fell
+   * through it silently while still counting in {@link ExecutorStats.commands} — a frame missing
+   * every command of the new kind, reported as a frame that drew everything.
+   */
+  unknownCommands: number;
+  /** Largest single batch, in instances. */
+  maxBatchQuads: number;
+  /** Why batches ended, so a regression in batching says which axis moved. */
+  flushes: Record<BatchFlushReason, number>;
+  /** Per-execution compiled-plan diagnostics; direct frames leave these zero. */
+  compiledPlanBuilds: number;
+  compiledPlanReuses: number;
+  compiledTemplateRangeUpdates: number;
+  reusedSelections: number;
+  reusedBatches: number;
+  compiledGpuFullUploads: number;
+  compiledGpuRangeUploads: number;
+  compiledCachedDrawCalls: number;
+}
+interface CanvasExecutorOptions {
+  gl: WebGL2RenderingContext;
+  /** The 1x1 white texel untextured quads sample. Defaults to one the executor
+   *  makes and owns; pass `CanvasTextureCache.white()` to share the cache's. */
+  white?: ExecutorTexture;
+  /**
+   * Who draws `glyphs` commands. Omitted means the executor cannot draw text.
+   *
+   * INJECTED, exactly like {@link CanvasExecutorOptions.white}, and for the reason
+   * {@link GlyphPass} states: the only implementation is backed by a glyph renderer that a scene
+   * with no text should not have to load, and the main barrel's export surface is mirrored by hand
+   * downstream. Import `@godot-scene-web/canvas/glyphs` and pass one when the scene has text.
+   *
+   * Leaving it out is not an error — plenty of draw lists have no glyph runs at all — but a list
+   * that DOES carry one then counts it in {@link ExecutorStats.glyphRunsDropped} rather than
+   * skipping it in silence.
+   */
+  glyphs?: GlyphPass;
+  /**
+   * Opt-in only: combine physically adjacent glyph commands when the injected pass exposes
+   * `drawRuns`. This never crosses a clip, a command-mask gap, or any non-glyph command.
+   */
+  batchAdjacentGlyphRuns?: boolean;
+  /** Texture units per batch. Clamped to the context's `MAX_TEXTURE_IMAGE_UNITS`
+   *  and to {@link MAX_TEXTURE_SLOTS}. */
+  maxTextureSlots?: number;
+  /** Colour-matrix slots per batch, including the identity at slot 0. */
+  maxColorMatrices?: number;
+  /** Initial instance-arena capacity, in quads. */
+  quadCapacity?: number;
+}
+interface ExecuteOptions {
+  /** Clear the framebuffer to transparent black before drawing. Default true. */
+  clear?: boolean;
+  /**
+   * Replacement clear colour for a full-frame stage pass. It is intentionally
+   * an execute option rather than a global GL mutation: retained FBO replays
+   * keep their transparent clear while an opaque presenter can establish its
+   * base pixels without a second fullscreen draw.
+   */
+  clearColor?: readonly [number, number, number, number];
+  /**
+   * Restrict both clearing and drawing to this top-left framebuffer-pixel
+   * rectangle. It is the retained-surface seam, but is also useful to any
+   * caller rendering into its own FBO; omitted keeps the direct full-frame
+   * executor path byte-for-byte in shape.
+   */
+  damage?: DamageRect;
+  /** Ordered replay selection. Clip closures are supplied by `createReplayMask`.
+   * Omitted means every command is executed, as direct frames always have. */
+  commandMask?: CommandMask;
+  /** Opt-in retained plan. Omitted direct frames do no compilation work. */
+  compiled?: CompiledDrawList<ExecutorTexture | null>;
+}
+interface CanvasExecutor {
+  readonly gl: WebGL2RenderingContext;
+  readonly stats: ExecutorStats;
+  /** Texture units a batch can hold on THIS context. */
+  readonly maxTextureSlots: number;
+  /** Build the program and buffers now, off whatever critical path the caller
+   *  cares about. `execute` does it lazily otherwise — and reading a shader's
+   *  compile status BLOCKS on the driver (~100-250 ms on a phone), so paying it
+   *  during the first frame is a visible hitch. */
+  warmUp(): boolean;
+  /** Draw one frame. Returns false when the program could not be built. */
+  execute(list: DrawList<ExecutorTexture | null>, projection: StageProjection, options?: ExecuteOptions): boolean;
+  /** Release executor-owned cached GPU buffers for one compiled plan. */
+  releaseCompiled(plan: CompiledDrawList<ExecutorTexture | null>): void;
+  /** The context is GONE: drop every GL object without calling into GL. The next
+   *  `execute` rebuilds them. */
+  invalidate(): void;
+  /** Delete every GL object this executor owns. */
+  dispose(): void;
+}
+declare function createCanvasExecutor(options: CanvasExecutorOptions): CanvasExecutor;
+//#endregion
+//#region src/headless-effects.d.ts
+/** Bind a GPU screen producer at one DrawList painter position. */
+declare function createHeadlessScreenEffectCommand(producer: HeadlessShaderProducer, input: HeadlessShaderRenderInput): ScreenEffectDrawCommand;
+/** Bind a direct GPU particle pass at one DrawList painter position. */
+declare function createHeadlessGodotParticleDirectEffect(pass: HeadlessGodotParticleDirectPass, input: HeadlessGodotParticleDirectRenderInput): ExternalEffectDrawCommand;
+//#endregion
+//#region src/nine-patch.d.ts
+/**
+ * Nine-patch band algebra: one `DRAW_NINE_PATCH` command -> up to nine plain
+ * quads. Pure (no GL, no state), so the geometry can be unit-tested on its own —
+ * it is the part of the executor most likely to be wrong by half a pixel and the
+ * part least able to say so on screen.
+ *
+ * WHERE THE RULES COME FROM. Godot does not expand a nine-patch into quads at
+ * all: it draws ONE quad and remaps each fragment's coordinate with
+ * `map_ninepatch_axis` (`drivers/gles3/shaders/canvas.glsl`). That function is
+ * this module's specification, per axis:
+ *
+ * - `pixel < margin_begin` -> source coordinate `pixel`, i.e. the leading corner
+ *   band is copied 1:1 at its native pixel size;
+ * - `pixel >= draw_size - margin_end` -> source `tex_size - (draw_size - pixel)`,
+ *   the trailing corner band, also 1:1;
+ * - otherwise the centre band, stretched from `[margin_begin, tex_size -
+ *   margin_end]` onto `[margin_begin, draw_size - margin_end]`.
+ *
+ * Expanding that into rects gives identical pixels for the STRETCH axis mode and
+ * costs a handful of extra quads that batch with everything else — much cheaper
+ * than the branchy per-fragment remap, and it keeps one shader for every command
+ * kind. Godot's TILE / TILE_FIT modes are NOT reachable from the draw-list IR
+ * (which carries no axis-stretch mode), so STRETCH — Godot's default — is what
+ * this implements.
+ *
+ * DEGENERATE MARGINS FOLLOW THE SAME SPECIFICATION rather than a clamp. Note the
+ * order of the branches above: when the two margins together exceed the
+ * destination, the LEADING band wins the overlap and the trailing band keeps only
+ * what is left. So this module truncates rather than rescaling the corners, which
+ * is what the shader does. Bands that come out empty are dropped, so a patch
+ * squeezed below its own margins expands to fewer than nine quads (down to one,
+ * or to none at all when it has no area).
+ *
+ * A SOURCE centre that is empty or inverted (the margins meet or cross inside the
+ * texture region) is dropped too. Godot's remap would produce a reversed source
+ * range there — a mirrored smear — which is nobody's intent.
+ */
+/** One expanded band: a destination rect in the command's LOCAL space (before the
+ *  quad's affine `m`), and the source rect it samples, in page pixels. */
+interface NinePatchBand {
+  /** Destination, local space: x in `[0, w]`, y in `[0, h]`. */
+  dstX: number;
+  dstY: number;
+  dstW: number;
+  dstH: number;
+  /** Source, page pixels — an absolute rect on the page, not relative to the region. */
+  srcX: number;
+  srcY: number;
+  srcW: number;
+  srcH: number;
+}
+/** The nine-patch inputs, matching `NinePatchView`'s fields. */
+interface NinePatchGeometry {
+  /** Destination size in local units. */
+  w: number;
+  h: number;
+  /** The patch REGION on the page, in page pixels. */
+  srcX: number;
+  srcY: number;
+  srcW: number;
+  srcH: number;
+  /** Insets into the region, page pixels (Godot `patch_margin_*`). */
+  marginLeft: number;
+  marginTop: number;
+  marginRight: number;
+  marginBottom: number;
+}
+declare function createNinePatchBand(): NinePatchBand;
+/** A reusable output buffer: nine bands is the hard maximum, so it never grows. */
+declare function createNinePatchBands(): NinePatchBand[];
+/**
+ * Expand a nine-patch into its bands, filling `out` (use
+ * {@link createNinePatchBands}, which is always big enough) and returning how
+ * many are live. `out` entries past the return value are stale and must not be
+ * read.
+ *
+ * Returns 0 for a patch with no area — a zero-size destination or a zero-size
+ * region draws nothing at all, which is not the same as drawing one empty band.
+ */
+declare function expandNinePatch(patch: NinePatchGeometry, out: NinePatchBand[]): number;
+//#endregion
+//#region src/polyline.d.ts
+/**
+ * Constant-width polyline -> quads, so a `DRAW_POLYLINE` goes through the SAME
+ * instance buffer, the same shader and the same batch as everything else instead
+ * of forcing a second program and a mid-frame draw break.
+ *
+ * That is possible because the batcher's instance carries four EXPLICIT corners
+ * rather than an affine basis (see `./batcher`): a quad instance is any
+ * quadrilateral, and a quadrilateral with its last two corners coincident is a
+ * triangle. So a stroke is emitted as
+ *
+ * - one parallelogram per segment (the segment offset by ±width/2 along its
+ *   normal), and
+ * - one triangle per interior vertex, filling the notch on the OUTSIDE of the
+ *   turn.
+ *
+ * JOINS ARE BEVEL, CAPS ARE BUTT — the first pass the wave-1 brief allows, and a
+ * deliberate choice rather than an oversight:
+ *
+ * - a MITER join needs the two segment edges extended to their intersection,
+ *   which runs away to infinity as the turn approaches a reversal and therefore
+ *   needs a miter limit that itself falls back to... a bevel. Two code paths for
+ *   a shape that differs from the bevel only inside a `width/2` disc.
+ * - a ROUND join needs an arc, i.e. a fan of triangles whose count depends on the
+ *   turn angle and the on-screen width — the one thing in this file that would
+ *   make its output size unpredictable.
+ *
+ * The bevel differs from both only within half a stroke width of a vertex, and
+ * the measured population of polylines in the recorded scenes this executor was
+ * sized against is ZERO (the paint-source mix is texture/text/particles/spine/
+ * solid). Upgrading to round joins is local to this file: emit a fan instead of
+ * the single wedge triangle in the interior-vertex loop.
+ *
+ * Self-overlap: at a sharp turn the two segment parallelograms overlap near the
+ * vertex, so a translucent stroke double-composites there. Godot's own
+ * `draw_polyline` has the same artefact; fixing it needs a stencil or a
+ * single-pass SDF, neither of which belongs in wave 1.
+ */
+/** Floats per emitted quad: four `(x, y)` corners in draw-list local space. */
+declare const POLYLINE_QUAD_FLOATS = 8;
+/**
+ * The most quads a `pointCount`-point stroke can produce: one per segment plus
+ * one per interior vertex. Sizes a caller's output buffer exactly.
+ */
+declare function polylineQuadCapacity(pointCount: number): number;
+/**
+ * Tessellate `points` (flattened `x, y, x, y, …`, the draw-list's own layout)
+ * into quads, writing `POLYLINE_QUAD_FLOATS` floats per quad into `out` from
+ * `outOffset`. Returns the number of quads written.
+ *
+ * Corners are written in the batcher's unit-square order — `(0,0)`, `(1,0)`,
+ * `(1,1)`, `(0,1)` — so a triangle is spelled by repeating the last corner.
+ *
+ * Zero-length segments are skipped (they have no direction to offset along, and
+ * a duplicated point is a common artefact of a resampled path); a vertex whose
+ * incoming or outgoing segment was skipped gets no join wedge, because there is
+ * no notch to fill.
+ */
+declare function expandPolyline(points: ArrayLike<number>, pointCount: number, width: number, out: Float32Array, outOffset?: number): number;
+//#endregion
+//#region src/retained-surface.d.ts
+/** An RGBA8 framebuffer that retains scene pixels between frames. */
+interface RetainedSurface {
+  readonly gl: WebGL2RenderingContext;
+  /** The achieved, integer backing dimensions. Zero means unallocated. */
+  readonly width: number;
+  readonly height: number;
+  /** GPU allocation is live. It says nothing about whether it contains a frame. */
+  readonly allocated: boolean;
+  /** True only after a full replay; `present` refuses unseeded pixels. */
+  readonly contentValid: boolean;
+  /**
+   * Allocate an RGBA8 texture/FBO at the exact snapped requested size. A size
+   * change discards old pixels, so callers must replay a full frame afterwards.
+   */
+  resize(width: number, height: number): boolean;
+  /**
+   * Replay into the retained target. `damage` is top-left framebuffer pixels;
+   * passing it restricts both clear and draw to that region. This operation is
+   * explicit: direct `CanvasExecutor.execute` calls can neither seed this FBO
+   * nor present it.
+   */
+  replay(executor: CanvasExecutor, list: DrawList<ExecutorTexture | null>, projection: StageProjection, options?: RetainedReplayOptions): boolean;
+  /**
+   * Replay a prevalidated exact cover into one retained target binding. Every
+   * region keeps its own damage scissor and clip-complete mask, so painter
+   * order, clips and blend modes are identical to individual partial replays.
+   * The whole set is validated before its first clear; any failure invalidates
+   * retained content and a caller must seed rather than present it.
+   */
+  replayRegions(executor: CanvasExecutor, list: DrawList<ExecutorTexture | null>, projection: StageProjection, regions: readonly RetainedReplayRegion[], options?: RetainedReplayRegionsOptions): boolean;
+  /** Blit the retained texture once, 1:1, to the default framebuffer. */
+  present(): boolean;
+  /** Forget retained pixels while keeping the allocated FBO for the next seed. */
+  invalidateContent(): void;
+  /** Drop dead context handles without calling GL after a context loss. */
+  invalidate(): void;
+  /** Delete owned GL resources while the context is live. */
+  dispose(): void;
+}
+interface RetainedReplayOptions {
+  /**
+   * A physical-pixel damage region. Partial retained replay deliberately
+   * requires one; an unbounded replay is a seed and therefore renders the
+   * complete list without a mask.
+   */
+  damage?: DamageRect;
+  /**
+   * A validated, clip-complete selection from `createReplayMaskScratch` or a
+   * compiled draw-list. A generic `CommandMask` is intentionally not accepted:
+   * it could omit an unknown or screen-dependent command and leave stale FBO
+   * pixels that `present()` would otherwise expose.
+   */
+  mask?: ReplayMaskScratch;
+  /** Forwarded only for rare custom executor behaviour; clear defaults to true. */
+  execute?: Omit<ExecuteOptions, "clear" | "damage" | "commandMask">;
+}
+/** One independently scissored, clip-complete member of a retained replay set. */
+interface RetainedReplayRegion {
+  damage: DamageRect;
+  mask: ReplayMaskScratch;
+}
+/** Shared executor options for every region in one retained replay set. */
+interface RetainedReplayRegionsOptions {
+  execute?: Omit<ExecuteOptions, "clear" | "damage" | "commandMask">;
+}
+/** Snap a CSS/device calculation once at the allocation boundary. */
+declare function snapRetainedSize(value: number): number;
+/**
+ * Create a retained RGBA8 texture/FBO. It deliberately does not create a
+ * canvas or context — a stage owns that DOM-facing concern — and it does not
+ * monkey-patch an executor. Retention is opt-in per replay/present call.
+ */
+declare function createRetainedSurface(gl: WebGL2RenderingContext): RetainedSurface;
+//#endregion
+export { BLEND_ADD, BLEND_MIX, BLEND_MUL, BLEND_SUB, type Batch, type BatchFlushReason, type BatchTexture, type BatcherStats, type BlendMode, type BlendState, COLOR_MATRIX_FLOATS, type CanvasExecutor, type CanvasExecutorOptions, type CanvasStage, type CanvasStageOptions, type CanvasTextureCache, type CanvasTextureHandle, type CanvasTextureOptions, type CanvasTextureSource, type ClipBounds, type ClipRectView, type ClipStack, type CommandBounds, type CommandMask, type CompiledBatchDescriptor, type CompiledDrawList, type CompiledDrawListDiagnostics, type CompiledRefreshResult, DEFAULT_COLOR_MATRIX_SLOTS, DRAW_CLIP_POP, DRAW_CLIP_PUSH, DRAW_COMMAND_NAMES, DRAW_EXTERNAL_EFFECT, DRAW_GLYPHS, DRAW_NINE_PATCH, DRAW_POLYLINE, DRAW_QUAD, DRAW_SCREEN_EFFECT, DRAW_TEXTURED_MESH, type DamageRect, type DamageTile, type DamageTiles, type DamageTransform, type DirtyRect, type DrawCommandKind, type DrawCommandName, type DrawList, type DrawListFragment, type DrawListFragmentPatch, type DrawListOptions, type DrawListPatchView, type ExecuteOptions, type ExecutorStats, type ExecutorTexture, type ExternalEffectDrawCommand, type ExternalEffectDrawContext, FLIP_H, FLIP_V, type GlyphPass, type GlyphsView, IDENTITY_COLOR_MATRIX, INSTANCE_COLOR_OFFSET, INSTANCE_CORNERS_OFFSET, INSTANCE_FLOATS, INSTANCE_SLOTS_OFFSET, INSTANCE_UV_OFFSET, MAX_TEXTURE_SLOTS, type NinePatchBand, type NinePatchGeometry, type NinePatchView, POLYLINE_QUAD_FLOATS, type PixelTransform, type PolylineView, type QuadBatcher, type QuadBatcherOptions, type QuadInstance, type QuadView, RETAINED_DAMAGE_TILE_SIZE, RETAINED_MAX_DAMAGE_COVERAGE, RETAINED_MAX_REPLAY_FRACTION, type ReplayMaskScratch, type ReplaySelectionOptions, type RetainedReplayOptions, type RetainedReplayRegion, type RetainedReplayRegionsOptions, type RetainedSurface, type Rgba, type RoundedClip, STAGE_CONTEXT_ATTRIBUTES, type ScissorBox, type ScreenEffectDrawCommand, type ScreenEffectDrawContext, type StageCanvas, type StageProjection, type TextureCacheStats, type TexturedMeshView, applyColorMatrix01, blendStateFor, clamp01, colorMatricesEqual, commandDamageBounds, compileDrawList, createCanvasExecutor, createCanvasStage, createClipRectView, createClipStack, createCompiledReplayMask, createDamageRect, createDamageTiles, createDrawList, createDrawListFragment, createDrawListPatchView, createGlyphsView, createHeadlessGodotParticleDirectEffect, createHeadlessScreenEffectCommand, createNinePatchBand, createNinePatchBands, createNinePatchView, createPolylineView, createQuadBatcher, createQuadInstance, createQuadView, createReplayMask, createReplayMaskScratch, createRetainedSurface, createRgba, createScissorBox, createTextureCache, createTexturedMeshView, damageIntersects, expandNinePatch, expandPolyline, isAxisAligned, isDamageEmpty, isIdentityColorMatrix, isPartialReplayMask, maxPartialReplayCommands, modulatePremultiplied, outsetDamageRect, polylineQuadCapacity, premultiply, setViewColorMatrix, shadeQuadPixel, snapRetainedSize, transformDamageRect, unionDamageRect, unpremultiply };
+//# sourceMappingURL=index.d.ts.map