@godot-scene-web/canvas 0.1.0

package/dist/glyph-pass-DfQlp_IH.d.ts

@@ -0,0 +1,882 @@
+import { ColorMatrix } from "@godot-scene-web/core";
+
+//#region src/damage.d.ts
+/** A top-left-origin, axis-aligned rectangle. It is used in design or backing
+ * pixel space; the caller decides which, and {@link transformDamageRect} moves
+ * between them conservatively. */
+interface DamageRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** Public retained-rendering vocabulary for a rectangle that needs repainting. */
+type DirtyRect = DamageRect;
+/** A conservative rectangle reported by one draw command when its extent is
+ * known. `commandDamageBounds` returns `null` for a full/direct fallback. */
+type CommandBounds = DamageRect;
+/** A tile selected by {@link DamageTiles}. */
+interface DamageTile extends DamageRect {
+  column: number;
+  row: number;
+}
+/** A tile accumulator for retaining a backing surface without retaining an
+ * unbounded list of tiny invalidations. */
+interface DamageTiles {
+  readonly width: number;
+  readonly height: number;
+  /** Physical backing pixels in one tile. Retained callers use 64×64 tiles. */
+  readonly tileWidth: number;
+  readonly tileHeight: number;
+  readonly columns: number;
+  readonly rows: number;
+  readonly tileCount: number;
+  readonly dirtyCount: number;
+  /** `dirtyCount / tileCount`, or zero for an empty surface. */
+  readonly coverage: number;
+  readonly dirty: boolean;
+  resize(width: number, height: number): void;
+  mark(rect: DamageRect | null): void;
+  clear(): void;
+  /** The exact backing-pixel tiles currently marked, in paint order. */
+  tiles(): readonly DamageTile[];
+  /**
+   * Visit marked tiles without materialising `DamageTile` objects. The same
+   * mutable tile view is passed each time, so read it synchronously and do not
+   * retain it. This is the retained-frame hot path; `tiles()` is only a
+   * diagnostics convenience.
+   */
+  forEach(callback: (tile: DamageTile) => void): void;
+  /**
+   * Visit an exact, non-overlapping rectangular cover of the marked tiles.
+   * Horizontally adjacent tiles are joined, then identical row runs are joined
+   * vertically. No clean pixel is included, so each region is safe to pass to
+   * a scissored retained replay independently. As with {@link forEach}, the
+   * rectangle is a reusable mutable view and must not be retained.
+   */
+  forEachRegion(callback: (region: DamageRect) => void): void;
+  /** Return the marked tiles and clear the accumulator. */
+  consume(): readonly DamageTile[];
+}
+/** Retained replay uses fixed physical-pixel tiles, never CSS pixels. */
+declare const RETAINED_DAMAGE_TILE_SIZE = 64;
+/** The largest tile coverage that is worth planning for retained replay. */
+declare const RETAINED_MAX_DAMAGE_COVERAGE = 0.2;
+/** A `Transform2D` mapping the rect's coordinates into another top-left space. */
+type DamageTransform = ArrayLike<number>;
+declare function createDamageRect(): DamageRect;
+declare function isDamageEmpty(rect: DamageRect): boolean;
+/** Expand in the rectangle's own coordinate space without mutating inputs. */
+declare function outsetDamageRect(rect: DamageRect, outset: number, out?: DamageRect): DamageRect | null;
+/** True when two half-open rectangles overlap. Touching edges do not repaint. */
+declare function damageIntersects(a: DamageRect, b: DamageRect): boolean;
+/** Expand `out` to cover both input rectangles. */
+declare function unionDamageRect(a: DamageRect, b: DamageRect, out?: DamageRect): DamageRect;
+/** Transform all four corners, returning the enclosing axis-aligned rectangle. */
+declare function transformDamageRect(rect: DamageRect, transform: DamageTransform, out?: DamageRect): DamageRect;
+/**
+ * Compute a conservative visual bound for one command. `null` means unknown,
+ * which callers must treat as intersecting every damage region. Glyphs are
+ * known only when their producer supplied explicit local ink bounds; guessing
+ * from pen positions or em size could leave stale ink on a retained surface.
+ */
+declare function commandDamageBounds<TTexture>(list: DrawList<TTexture>, index: number, out?: DamageRect): CommandBounds | null;
+declare function createDamageTiles(width: number, height: number, tileWidth?: number, tileHeight?: number): DamageTiles;
+//#endregion
+//#region src/draw-list.d.ts
+/**
+ * The draw-list IR for a Godot 2D scene: a flat, ordered recording of what one
+ * frame paints, produced by walking `CanvasItem`s in draw order and consumed by
+ * a GPU executor (a later wave). It is deliberately dumb — no scene concepts, no
+ * nodes, no styles, just quads, indexed textured meshes, nine-patches,
+ * polylines and clip pushes/pops in
+ * the order they must hit the framebuffer.
+ *
+ * Storage is a set of pooled parallel typed arrays, not an array of command
+ * objects:
+ *
+ * - `kinds` / `floatOffsets` / `intOffsets` are one entry per command,
+ * - `floats` and `ints` are arenas that every command's numeric payload is
+ *   appended into (a quad writes 16 floats + 3 ints, a polyline writes a
+ *   5-float header plus 2 floats per point, …),
+ * - `colorMatrices` is a side arena for the rare 3x3 color transform,
+ * - `textures` is the ONLY object side-array — a texture handle cannot live in
+ *   a typed array.
+ *
+ * That layout exists so a frame costs zero garbage: `reset()` rewinds the write
+ * cursors and the same buffers are refilled next frame, and reading a command
+ * back fills a caller-owned view instead of allocating one. Arrays grow on
+ * demand (capacity doubling) and never shrink.
+ *
+ * All geometry is in DESIGN space (the scene's own coordinate system); mapping
+ * design space to device pixels is the executor's job.
+ */
+/** A textured/solid rectangle: the workhorse command. */
+declare const DRAW_QUAD = 0;
+/** A 9-sliced rectangle; the executor expands it to up to 9 quads. */
+declare const DRAW_NINE_PATCH = 1;
+/** A flattened, constant-width line strip. */
+declare const DRAW_POLYLINE = 2;
+/** Push a scissor/clip rect; every later command is clipped until the pop. */
+declare const DRAW_CLIP_PUSH = 3;
+/** Pop the most recent clip rect. */
+declare const DRAW_CLIP_POP = 4;
+/**
+ * A run of glyphs from one face, at one size, in one colour.
+ *
+ * The ONLY command that is not reducible to a textured quad, which is why it
+ * exists as its own kind rather than as sugar over `pushQuad`. Its glyphs are
+ * outlines evaluated per fragment (see `@godot-scene-web/hb-gpu`), so they carry
+ * an atlas slot id instead of a source rect and stay crisp under rotation and
+ * scale — the whole reason for the kind. An executor with no glyph pass
+ * installed skips it.
+ */
+declare const DRAW_GLYPHS = 5;
+/** An arbitrary triangle list with one texture and per-mesh premultiplied tint. */
+declare const DRAW_TEXTURED_MESH = 6;
+/** A screen-dependent pass executed at this exact painter position. */
+declare const DRAW_SCREEN_EFFECT = 7;
+/** A caller-owned GPU pass executed directly into the current framebuffer. */
+declare const DRAW_EXTERNAL_EFFECT = 8;
+interface ScreenEffectDrawContext {
+  readonly gl: WebGL2RenderingContext;
+  readonly framebuffer: WebGLFramebuffer | null;
+  readonly width: number;
+  readonly height: number;
+  readonly damage?: DamageRect;
+  readonly scissor: Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+}
+/**
+ * The live painter target handed to an external pass. Unlike a screen effect,
+ * this pass does not imply a snapshot or read from the accumulated framebuffer.
+ */
+interface ExternalEffectDrawContext {
+  readonly gl: WebGL2RenderingContext;
+  readonly framebuffer: WebGLFramebuffer | null;
+  readonly width: number;
+  readonly height: number;
+  readonly damage?: DamageRect;
+  readonly scissor: Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+}
+/** A DOM-free pass that snapshots the executor's accumulated current target. */
+interface ScreenEffectDrawCommand {
+  readonly screenDependent: true;
+  execute(context: ScreenEffectDrawContext): boolean;
+}
+/** A DOM-free pass that paints directly into the executor's current target. */
+interface ExternalEffectDrawCommand {
+  execute(context: ExternalEffectDrawContext): boolean;
+}
+type DrawCommandKind = typeof DRAW_QUAD | typeof DRAW_NINE_PATCH | typeof DRAW_POLYLINE | typeof DRAW_CLIP_PUSH | typeof DRAW_CLIP_POP | typeof DRAW_GLYPHS | typeof DRAW_TEXTURED_MESH | typeof DRAW_SCREEN_EFFECT | typeof DRAW_EXTERNAL_EFFECT;
+type DrawCommandName = "quad" | "ninePatch" | "polyline" | "clipPush" | "clipPop" | "glyphs" | "texturedMesh" | "screenEffect" | "externalEffect";
+/** Indexed by {@link DrawCommandKind}; for debugging and test assertions. */
+declare const DRAW_COMMAND_NAMES: readonly DrawCommandName[];
+/** Godot `CanvasItemMaterial.BLEND_MODE_MIX`: normal alpha compositing. */
+declare const BLEND_MIX = 0;
+/** Godot `BLEND_MODE_ADD`. */
+declare const BLEND_ADD = 1;
+/** Godot `BLEND_MODE_SUB`. */
+declare const BLEND_SUB = 2;
+/** Godot `BLEND_MODE_MUL`. */
+declare const BLEND_MUL = 3;
+type BlendMode = typeof BLEND_MIX | typeof BLEND_ADD | typeof BLEND_SUB | typeof BLEND_MUL;
+/** Bit in a command's packed flags int: mirror the source rect horizontally. */
+declare const FLIP_H = 1;
+/** Bit in a command's packed flags int: mirror the source rect vertically. */
+declare const FLIP_V = 2;
+/**
+ * A quad's numeric payload. Views are caller-owned and reusable: fill one and
+ * hand it to `pushQuad`, or pass one to `readQuad` to have it filled in place.
+ * Nothing here is retained by the list — the push copies into the arenas.
+ */
+interface QuadView {
+  /**
+   * The 2x3 affine that maps the unit-ish quad into design space, in Godot
+   * `Transform2D` order: `[xx, xy, yx, yy, originX, originY]`, i.e.
+   * `x' = xx*x + yx*y + originX`, `y' = xy*x + yy*y + originY`. Length 6.
+   */
+  m: Float32Array;
+  /** Destination width in design units, before `m` is applied. */
+  w: number;
+  /** Destination height in design units, before `m` is applied. */
+  h: number;
+  /** Source rect on the texture page, in page pixels (not normalized). */
+  srcX: number;
+  srcY: number;
+  srcW: number;
+  srcH: number;
+  /** PREMULTIPLIED tint, linear 0..1 per channel (`rgb` already times `a`). */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+  blend: BlendMode;
+  flipH: boolean;
+  flipV: boolean;
+  /**
+   * Whether {@link QuadView.colorMatrix} is meaningful. Most quads carry no
+   * color transform at all (the field is the IR's "null"), so the matrix is
+   * stored in a side arena and skipped entirely when this is `false`.
+   */
+  hasColorMatrix: boolean;
+  /**
+   * Row-major 3x3 linear RGB transform (`out_rgb = m * in_rgb`, alpha
+   * untouched) — an HSV-style shader tint. Length 9. Ignored unless
+   * `hasColorMatrix`.
+   */
+  colorMatrix: Float32Array;
+}
+/**
+ * A nine-patch's payload: a quad plus the four stretch margins. `srcX..srcH` is
+ * the patch REGION on the page; the margins are insets into that region, in
+ * page pixels, exactly like Godot's `NinePatchRect.patch_margin_*`.
+ */
+interface NinePatchView extends QuadView {
+  marginLeft: number;
+  marginTop: number;
+  marginRight: number;
+  marginBottom: number;
+}
+/** A polyline's payload: a flattened `x, y, x, y, …` strip with one width. */
+interface PolylineView {
+  /**
+   * Flattened point coordinates in design space. Length is at least
+   * `pointCount * 2`; a longer buffer is allowed (and expected, since views are
+   * reused), only the first `pointCount * 2` entries are read.
+   */
+  points: Float32Array;
+  pointCount: number;
+  /** Stroke width in design units. */
+  width: number;
+  /** PREMULTIPLIED stroke color, linear 0..1 per channel. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+/**
+ * An indexed triangle list sampling one texture. Positions and UVs are paired
+ * by vertex index; positions are local design-space coordinates and `m` maps
+ * them to design space. UVs are normalized texture coordinates, intentionally
+ * not a quad source rect: arbitrary mesh topology must not be forced through a
+ * rectangle-shaped source contract.
+ */
+interface TexturedMeshView {
+  /** Godot `Transform2D` mapping local vertex positions into design space. */
+  m: Float32Array;
+  /** Flattened local `x, y` pairs. Only `vertexCount * 2` entries are read. */
+  positions: Float32Array;
+  /** Flattened normalized `u, v` pairs, one pair for every position. */
+  uvs: Float32Array;
+  vertexCount: number;
+  /** Triangle-list vertex indices. Only `indexCount` entries are read. */
+  indices: Uint32Array;
+  indexCount: number;
+  /** PREMULTIPLIED mesh tint, linear 0..1 per channel. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+  blend: BlendMode;
+}
+/**
+ * A glyph run's payload: one face, one size, one colour, N positioned glyphs.
+ *
+ * THE SLOT IDS ARE HANDLES, NOT ADDRESSES, and that distinction is the whole
+ * point of the indirection. A glyph atlas evicts — it is a fixed texture holding
+ * an unbounded pool — so recording a glyph's atlas OFFSET into a list that may be
+ * retained and repainted next frame is how you get a different glyph's outline
+ * drawn at the right size, in the right place, perfectly antialiased. Unreadable
+ * text that looks like working text. A slot id survives eviction because the
+ * atlas re-resolves it (re-uploading the outline if it has to) at draw time.
+ *
+ * Shaping is NOT this package's job. `positions` are pen positions a shaper
+ * produced; the list only records them.
+ */
+interface GlyphsView {
+  /**
+   * The 2x3 affine that maps the run's local space into design space, in the
+   * same Godot `Transform2D` order as {@link QuadView.m}. Length 6.
+   *
+   * ROTATION BELONGS HERE, NEVER IN `positions`. The glyph shader dilates each
+   * outline by half a SCREEN pixel and works out how far that is by pushing the
+   * quad's corner and its normal through this same matrix. Pen positions rotated
+   * on the CPU would be dilated along the wrong axes — a rim of clipped
+   * antialiasing on one side of every glyph.
+   */
+  m: Float32Array;
+  /**
+   * Design units per em: the font size in the run's local space.
+   *
+   * The rendered outline is resolution-independent, but its ANTIALIASING is not
+   * unconditionally so: HarfBuzz's coverage shader takes a five-tap branch below
+   * ppem 16, and measured against an 8x-downsampled reference that branch is
+   * blurrier than a baked atlas at the same size. The ppem that matters is this
+   * times the scale in {@link GlyphsView.m} times the device-pixel ratio: a
+   * caller's zoom rides the matrix, and the shader sees it — see
+   * `docs/text-rendering.md`.
+   */
+  pixelsPerEm: number;
+  /** PREMULTIPLIED colour, linear 0..1 per channel, for the whole run. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+  /**
+   * One atlas slot id per glyph. Length is at least {@link GlyphsView.glyphCount}
+   * — a longer buffer is allowed and expected, since views are reused.
+   */
+  slots: Int32Array;
+  /**
+   * Pen positions, flattened `x, y, x, y, …`, in the run's local space and
+   * BEFORE `m` is applied. Each is the glyph's em origin, i.e. a point on the
+   * baseline. Length is at least `glyphCount * 2`.
+   */
+  positions: Float32Array;
+  glyphCount: number;
+  /**
+   * Grow every glyph outward by this many design units before filling. `0` (the
+   * default) is a plain fill.
+   *
+   * AN OUTLINED LABEL IS TWO RUNS, NOT ONE: the same glyphs and pens in the
+   * outline colour with a spread, then again in the fill colour with none. This
+   * kind carries one colour and one spread by design — merging them would need
+   * two draw calls behind one command and would hide the ordering, which is the
+   * part a caller has to get right (outline UNDER fill).
+   *
+   * A CENTRED `strokeText` OF WIDTH `W` REACHES `W / 2` OUTWARD, so a caller
+   * matching one records `W / 2`. The arithmetic is the caller's: only it knows
+   * whether the stroke it is reproducing is centred, inner or outer.
+   *
+   * THE DILATION FILLS THE INTERIOR AND A STROKE DOES NOT. Identical under an
+   * opaque fill, which covers every pixel the two disagree about; visibly
+   * different under a TRANSLUCENT one, where the outline colour shows through
+   * the glyph's middle. Stated because it is a real limit of a coverage-max
+   * dilation rather than a rounding difference — see `HbGpuRenderer.setSpread`.
+   */
+  spreadPx: number;
+  /**
+   * The exact local-space rectangle containing the run's unspread glyph ink.
+   *
+   * These are optional for source compatibility with older producers. Omitting
+   * any one is deliberately an UNKNOWN bound, never an em-box estimate: a
+   * retained surface must repaint fully rather than leave stale text behind.
+   */
+  localInkX?: number;
+  localInkY?: number;
+  localInkWidth?: number;
+  localInkHeight?: number;
+  /** Additional local-space reach for effects and antialiasing. The draw list
+   * also adds its own `spreadPx`, so this is for reach beyond the unspread
+   * outline (for example a shadow or caller-measured coverage fringe). */
+  localInkOutset?: number;
+}
+/** A clip push's payload. */
+interface ClipRectView {
+  /** Clip rect in design space. */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /**
+   * Corner radius in design units; `0` (the common case) is a plain rect and
+   * lets the executor use a cheap scissor instead of a mask.
+   */
+  cornerRadius: number;
+  /**
+   * One-axis slack: widen the rect by `outsetX` on BOTH x edges, i.e. clip to
+   * `[x - outsetX, x + w + outsetX]` while `y`/`h` stay exact. `0` (the common
+   * case) clips to the rect itself. This exists because a re-laid-out scene can
+   * legitimately paint slightly wider than the clip that Godot recorded, and
+   * only ever on x.
+   */
+  outsetX: number;
+}
+interface DrawListOptions {
+  /** Initial command capacity (entries, not bytes). Grows on demand. */
+  commandCapacity?: number;
+  /** Initial float-arena capacity. Grows on demand. */
+  floatCapacity?: number;
+  /** Initial int-arena capacity. Grows on demand. */
+  intCapacity?: number;
+  /** Initial color-matrix capacity, in matrices. Grows on demand. */
+  colorMatrixCapacity?: number;
+  /** Retained in-place patch records for compiled consumers. */
+  patchJournalCapacity?: number;
+}
+/** Caller-owned, grow-only output for {@link DrawList.readPatchesSince}. */
+interface DrawListPatchView {
+  readonly indices: readonly number[];
+  readonly revision: number;
+  readonly overflowed: boolean;
+}
+/**
+ * A reusable, DOM- and GPU-ownership-free copy of a contiguous draw-list
+ * range. A fragment owns its arena bytes and command references, so it remains
+ * valid when the list it was captured from is reset, grows, or patched.
+ *
+ * Fragments deliberately retain texture and effect *references* rather than
+ * attempting to clone them: those handles are executor-owned identities, not
+ * draw-list data. Capturing and appending only copies the ordering and payload
+ * that names them.
+ */
+interface DrawListFragment<TTexture = unknown> {
+  /** Number of commands in the captured half-open source range. */
+  readonly count: number;
+  /** Always zero for a valid standalone fragment. */
+  readonly clipDepth: number;
+  /** Deepest clip nesting within the captured range. */
+  readonly maxClipDepth: number;
+  /** Forget the captured range but retain all backing storage for reuse. */
+  reset(): void;
+  /**
+   * Clone `[start, end)` from `source` into this fragment. The range must be
+   * independently clip-balanced; an unmatched pop or push is rejected rather
+   * than producing a fragment whose replay depends on hidden painter state.
+   */
+  capture(source: DrawList<TTexture>, start: number, end?: number): void;
+}
+/** One same-shaped retained-fragment replacement in a draw list. */
+interface DrawListFragmentPatch<TTexture = unknown> {
+  /** First destination command index. Patches are supplied in painter order. */
+  readonly start: number;
+  /** Replacement command payloads, captured through createDrawListFragment. */
+  readonly fragment: DrawListFragment<TTexture>;
+}
+declare function createDrawListPatchView(capacity?: number): DrawListPatchView;
+/**
+ * An ordered, poolable recording of one frame's draws.
+ *
+ * `TTexture` is whatever the executor's texture handle is (a `WebGLTexture`, a
+ * `GPUTexture`, an atlas page id, …); the list only stores and returns it.
+ */
+interface DrawList<TTexture = unknown> {
+  /** Number of commands recorded since the last `reset()`. */
+  readonly count: number;
+  /** Clip pushes that are currently open (0 at a balanced end of frame). */
+  readonly clipDepth: number;
+  /** Deepest clip nesting seen since `reset()` — sizes an executor's stack. */
+  readonly maxClipDepth: number;
+  /** Changes when commands are appended, removed, or their layout changes. */
+  readonly structuralRevision: number;
+  /** Changes for every structural or in-place command patch. */
+  readonly contentRevision: number;
+  /** Per-command patch generation, for retained compiled consumers. */
+  commandRevisionAt(index: number): number;
+  /** Fill reusable `out` with patches after `revision`; overflow means rebuild. */
+  readPatchesSince(revision: number, out: DrawListPatchView): DrawListPatchView;
+  /**
+   * The float arena. The identity of this array CHANGES when it grows, so an
+   * executor must re-read it (never cache it across pushes).
+   */
+  readonly floats: Float32Array;
+  /** The int arena. Same growth caveat as {@link DrawList.floats}. */
+  readonly ints: Int32Array;
+  /** The color-matrix arena, 9 floats per entry. Same growth caveat. */
+  readonly colorMatrices: Float32Array;
+  /** Rewind to an empty list, keeping (and reusing) the buffers. */
+  reset(): void;
+  /**
+   * Append a previously captured fragment in painter order and return the
+   * first destination command index. Empty fragments return `count` and do
+   * not change revisions.
+   */
+  appendFragment(fragment: DrawListFragment<TTexture>): number;
+  /**
+   * Atomically overwrite a same-shaped recorded range from a retained
+   * fragment. The fragment must fit at `start` and every command must retain
+   * its kind, numeric payload lengths, object-side payload shape, clip
+   * sequence, and colour-matrix presence. A mismatch leaves this list wholly
+   * unchanged and returns `false`; successful overwrites preserve command
+   * indices and structural revision while publishing ordinary content patches.
+   *
+   * An empty fragment is a successful no-op at any insertion index from `0`
+   * through `count`.
+   */
+  patchFragment(start: number, fragment: DrawListFragment<TTexture>): boolean;
+  /**
+   * Atomically apply non-overlapping same-shaped fragments in painter order.
+   * Every range is validated before any payload, reference, revision, or patch
+   * journal entry changes. Starts must be nondecreasing and non-empty ranges
+   * must not overlap.
+   */
+  patchFragments(patches: readonly DrawListFragmentPatch<TTexture>[]): boolean;
+  kindAt(index: number): DrawCommandKind;
+  kindNameAt(index: number): DrawCommandName;
+  /** The command's texture handle, or `null` for untextured/geometry commands. */
+  textureAt(index: number): TTexture | null;
+  /** Screen-dependent pass recorded at index, if this is one. */
+  screenEffectAt(index: number): ScreenEffectDrawCommand | null;
+  /** Direct framebuffer pass recorded at index, if this is one. */
+  externalEffectAt(index: number): ExternalEffectDrawCommand | null;
+  /** Start of the command's payload in {@link DrawList.floats}. */
+  floatOffsetAt(index: number): number;
+  /** Start of the command's payload in {@link DrawList.ints}. */
+  intOffsetAt(index: number): number;
+  /**
+   * Index of the command's color matrix in {@link DrawList.colorMatrices}
+   * (multiply by 9 for the float offset), or `-1` when it has none.
+   */
+  colorMatrixIndexAt(index: number): number;
+  /** Record a quad. Returns the command index. */
+  pushQuad(quad: QuadView, texture?: TTexture | null): number;
+  /** Record a nine-patch. Returns the command index. */
+  pushNinePatch(patch: NinePatchView, texture?: TTexture | null): number;
+  /** Record a polyline. Returns the command index. */
+  pushPolyline(line: PolylineView): number;
+  /** Record an indexed textured triangle mesh. Returns the command index. */
+  pushTexturedMesh(mesh: TexturedMeshView, texture?: TTexture | null): number;
+  /** Record a glyph run. Returns the command index. */
+  pushGlyphs(run: GlyphsView): number;
+  /** Record a pass that samples the accumulated framebuffer at this painter index. */
+  pushScreenEffect(command: ScreenEffectDrawCommand): number;
+  /** Record a direct framebuffer pass at this painter position. */
+  pushExternalEffect(command: ExternalEffectDrawCommand): number;
+  /** Open a clip rect. Returns the command index. */
+  pushClipRect(clip: ClipRectView): number;
+  /** Close the innermost clip rect. Returns the command index. */
+  popClip(): number;
+  /** Fill `out` from a `quad` command and return it. */
+  readQuad(index: number, out: QuadView): QuadView;
+  /** Fill `out` from a `ninePatch` command and return it. */
+  readNinePatch(index: number, out: NinePatchView): NinePatchView;
+  /**
+   * Fill `out` from a `polyline` command and return it. `out.points` is
+   * REPLACED by a larger buffer if it cannot hold the recorded points.
+   */
+  readPolyline(index: number, out: PolylineView): PolylineView;
+  /** Fill `out` from a textured mesh, growing its caller-owned arrays if needed. */
+  readTexturedMesh(index: number, out: TexturedMeshView): TexturedMeshView;
+  /**
+   * Fill `out` from a `glyphs` command and return it. `out.slots` and
+   * `out.positions` are REPLACED by larger buffers if they cannot hold the run.
+   */
+  readGlyphs(index: number, out: GlyphsView): GlyphsView;
+  /** Fill `out` from a `clipPush` command and return it. */
+  readClipRect(index: number, out: ClipRectView): ClipRectView;
+  /**
+   * Overwrite a recorded quad's transform IN PLACE, leaving the rest of its
+   * payload — size, source rect, colour, blend, flip flags, colour matrix —
+   * exactly as it was pushed.
+   *
+   * This exists for consumers that rebuild a whole frame today only because one
+   * node moved: they can keep last frame's list and repaint it, which is the
+   * point of a list that owns its storage. `m` is read in the same
+   * `Transform2D` order as {@link QuadView.m} and only its first 6 entries are
+   * used.
+   *
+   * PATCH THROUGH THIS METHOD, NEVER THROUGH A CACHED `floats`. The arenas are
+   * reallocated when they grow (see {@link DrawList.floats}), so a Float32Array
+   * captured before a `push` may be a DEAD copy — writing into it changes
+   * nothing that will be drawn, silently. The method re-reads the live arena on
+   * every call.
+   *
+   * Accepts `quad` and `ninePatch` commands (a nine-patch's payload IS a quad
+   * payload plus margins); anything else throws.
+   */
+  patchQuadTransform(index: number, m: ArrayLike<number>): void;
+  /**
+   * Overwrite a recorded quad's PREMULTIPLIED tint in place, leaving geometry,
+   * source rect, blend, flip flags and colour matrix alone.
+   *
+   * `rgb` must already be multiplied by `a`, exactly as {@link QuadView} states
+   * — this is a raw write into the arena, not a colour operation, so nothing
+   * here will premultiply on the caller's behalf.
+   *
+   * The same cached-arena hazard as {@link DrawList.patchQuadTransform}
+   * applies, and the same two kinds are accepted.
+   */
+  patchQuadColor(index: number, r: number, g: number, b: number, a: number): void;
+  /**
+   * Replace a quad-like command's texture and source rectangle without touching
+   * its destination geometry, tint, blend state, flags or colour matrix.
+   *
+   * Like the other patch methods this re-reads the current arenas. In
+   * particular, callers must not write source coordinates through a cached
+   * `floats` view: a later push may have grown that arena and made the cached
+   * view a detached copy.
+   */
+  patchQuadSource(index: number, texture: TTexture | null, srcX: number, srcY: number, srcW: number, srcH: number): void;
+  /** Replace the local positions of a mesh without changing its topology. */
+  patchTexturedMeshPositions(index: number, positions: Float32Array): void;
+  /** Replace the normalized UV pairs of a mesh without changing its topology. */
+  patchTexturedMeshUvs(index: number, uvs: Float32Array): void;
+  /** Replace a mesh's texture handle without changing geometry or UVs. */
+  patchTexturedMeshSource(index: number, texture: TTexture | null): void;
+  /** Replace a mesh's local-to-design transform. */
+  patchTexturedMeshTransform(index: number, m: ArrayLike<number>): void;
+  /** Replace a mesh's premultiplied tint. */
+  patchTexturedMeshColor(index: number, r: number, g: number, b: number, a: number): void;
+  /**
+   * Overwrite a recorded glyph run's transform in place, leaving its glyphs,
+   * size and colour alone.
+   *
+   * The counterpart of {@link DrawList.patchQuadTransform}, and the reason the
+   * glyph kind stores a transform at all instead of pre-transformed pen
+   * positions: a label that translates every frame re-records nothing, and the
+   * shader still sees the whole transform (which is what keeps its half-pixel
+   * dilation on the right axes). The same cached-arena hazard applies — patch
+   * through this method, never through a captured `floats`.
+   */
+  patchGlyphsTransform(index: number, m: ArrayLike<number>): void;
+  /**
+   * Overwrite a recorded glyph run's PREMULTIPLIED colour in place. `rgb` must
+   * already be multiplied by `a`, exactly as {@link GlyphsView} states.
+   */
+  patchGlyphsColor(index: number, r: number, g: number, b: number, a: number): void;
+}
+/** A fresh quad view: identity transform, opaque white, mix blend, no matrix. */
+declare function createQuadView(): QuadView;
+/** A fresh nine-patch view: a quad view with zero margins. */
+declare function createNinePatchView(): NinePatchView;
+/** A fresh polyline view with room for `pointCapacity` points. */
+declare function createPolylineView(pointCapacity?: number): PolylineView;
+/** A reusable textured mesh view with room for the requested topology. */
+declare function createTexturedMeshView(vertexCapacity?: number, indexCapacity?: number): TexturedMeshView;
+/** A fresh glyph-run view with room for `glyphCapacity` glyphs. */
+declare function createGlyphsView(glyphCapacity?: number): GlyphsView;
+/** A fresh clip-rect view: empty rect, square corners, no outset. */
+declare function createClipRectView(): ClipRectView;
+/**
+ * Copy an `html` {@link ColorMatrix} into a quad/nine-patch view and arm it.
+ * Passing `null` disarms the view's matrix (leaving its contents alone), which
+ * is the shape most callers have: a computed transform that is usually absent.
+ */
+declare function setViewColorMatrix(view: QuadView, matrix: ColorMatrix | null | undefined): void;
+/**
+ * Create reusable storage for a retained command fragment. The fragment holds
+ * only draw-list data and opaque caller references; it never creates or owns a
+ * DOM node, a WebGL object, or an executor.
+ */
+declare function createDrawListFragment<TTexture = unknown>(options?: DrawListOptions): DrawListFragment<TTexture>;
+/**
+ * Create an empty draw list. Capacities are only a starting point; every arena
+ * grows on demand, so a list settles at the high-water mark of the frames it
+ * has recorded and then allocates nothing.
+ */
+declare function createDrawList<TTexture = unknown>(options?: DrawListOptions): DrawList<TTexture>;
+//#endregion
+//#region src/present.d.ts
+/**
+ * The stage: a WebGL2 context of its OWN on a caller-supplied canvas, its exact
+ * backing-store size, the design->screen projection every other module in this
+ * package reads, and the context-loss plumbing.
+ *
+ * THE ONLY MODULE IN `@godot-scene-web/canvas` THAT TOUCHES A CANVAS. Everything
+ * else takes a `WebGL2RenderingContext` and does arithmetic; keeping the DOM
+ * surface to one file is what makes the rest of the package testable without a
+ * browser and reusable off the main thread.
+ *
+ * ITS OWN CONTEXT, not `html`'s shared one. The shared context exists so that N
+ * per-node effect canvases on one page do not each burn one of the browser's ~16
+ * live contexts; it renders offscreen and BLITS onto each node. The stage is the
+ * opposite shape — ONE canvas for the whole scene, presented directly — so it
+ * neither needs the blit nor wants to share a drawing buffer that is sized,
+ * cleared and grown by two other runtimes on their own schedule.
+ *
+ * THE CONTEXT ATTRIBUTES, and why each one:
+ *
+ * - `alpha: true` — the stage composites over whatever the page puts behind it
+ *   (letterbox bars, a background layer), so it must carry real transparency.
+ * - `premultipliedAlpha: true` — the contract stated end to end: textures upload
+ *   premultiplied (`./textures`), tints are premultiplied (the draw-list's own
+ *   documentation), every fragment emits `vec4(rgb*a, a)`, the MIX blend is
+ *   `(ONE, ONE_MINUS_SRC_ALPHA)`. This flag changes no byte in the drawing
+ *   buffer; it tells the compositor how to READ them. Declare it wrong and
+ *   nothing errors — the page simply multiplies by alpha a second time and every
+ *   translucent pixel comes out dark. `html/webgl/shared-gl.ts` has the long
+ *   version of this note and the bug that produced it.
+ * - `stencil: false`, `depth: false` — a painter's-algorithm 2D renderer uses
+ *   neither, and both cost drawing-buffer memory on every device.
+ * - `antialias: false` — there is no geometry to multisample: every edge in the
+ *   scene is a texture's own alpha, which LINEAR filtering already smooths. MSAA
+ *   here would allocate a multisample buffer and resolve it every frame to change
+ *   nothing.
+ * - `preserveDrawingBuffer: false` — the stage clears and repaints every frame,
+ *   and preserving forces the implementation to keep a copy. Measurement trap
+ *   that follows: once the stage is idle, a JS-side readback (`toDataURL`,
+ *   `drawImage` of the canvas) returns an EMPTY image while the composited
+ *   frame on screen is correct — the drawing buffer is gone after present, by
+ *   design. Judge presentation only by compositor capture (a real screenshot
+ *   of the tab), never by reading the canvas back.
+ * - `desynchronized` is deliberately NOT set. It can cut latency by letting the
+ *   canvas bypass the compositor, but it also makes readback and screenshot
+ *   behaviour implementation-defined — which is exactly what the pixel tests
+ *   assert on — and on several drivers it silently disables the alpha compositing
+ *   path the point above depends on. A latency measurement can turn it on later,
+ *   with a test that proves the composite still holds.
+ */
+/** The subset of a canvas the stage needs. Structural so that both an
+ *  `HTMLCanvasElement` and an `OffscreenCanvas` satisfy it. */
+interface StageCanvas {
+  width: number;
+  height: number;
+  getContext(contextId: "webgl2", options?: WebGLContextAttributes): WebGL2RenderingContext | null;
+  addEventListener(type: string, listener: (event: Event) => void): void;
+  removeEventListener(type: string, listener: (event: Event) => void): void;
+}
+/** How design coordinates reach the screen, in the two forms consumers need. */
+interface StageProjection {
+  /** Exact scene coordinate extent, independent of float32 matrix rounding. */
+  readonly designWidth: number;
+  readonly designHeight: number;
+  /**
+   * Design -> clip space as `(scaleX, scaleY, translateX, translateY)`:
+   * `clip = design * scale + translate`. `scaleY` is NEGATIVE — design space
+   * measures Y downwards and clip space upwards.
+   */
+  readonly toClip: Float32Array;
+  /**
+   * Design -> framebuffer pixels as a 2x3 in the draw-list's `Transform2D` order
+   * `[xx, xy, yx, yy, originX, originY]`, with Y measured DOWN from the top. This
+   * is what `./clip-stack` turns into a scissor box.
+   */
+  readonly toFramebuffer: Float32Array;
+  /** The drawing buffer's REAL size — see {@link CanvasStage.setStageSize}. */
+  readonly framebufferWidth: number;
+  readonly framebufferHeight: number;
+}
+interface CanvasStageOptions {
+  canvas: StageCanvas;
+  /** The scene's own coordinate extent, e.g. 1920x1080. */
+  designWidth: number;
+  designHeight: number;
+  /**
+   * Request an alpha-capable drawing buffer. Omitted preserves the stage's
+   * compositing default (`true`); an opaque scene may opt out when it paints
+   * every output pixel itself.
+   */
+  alpha?: boolean;
+  /**
+   * Called after `webglcontextlost`. Every GL object the caller holds is dead:
+   * drop programs, buffers and textures (`CanvasTextureCache.reset`,
+   * `CanvasExecutor.invalidate`) without calling into GL to free them.
+   */
+  onContextLost?(): void;
+  /** Called after `webglcontextrestored`: rebuild programs, buffers, textures. */
+  onContextRestored?(): void;
+}
+interface CanvasStage {
+  readonly canvas: StageCanvas;
+  readonly gl: WebGL2RenderingContext;
+  readonly designWidth: number;
+  readonly designHeight: number;
+  /** The drawing buffer's real width/height, which may be smaller than asked. */
+  readonly stageWidth: number;
+  readonly stageHeight: number;
+  /** True between `webglcontextlost` and `webglcontextrestored`. */
+  readonly contextLost: boolean;
+  /**
+   * Whether the context actually has an alpha channel. This is read from the
+   * created context when available, rather than assuming the request won.
+   */
+  readonly alpha: boolean;
+  /**
+   * Size the backing store EXACTLY. Not grow-only: a stage that kept the largest
+   * size it had ever been asked for would keep a 4K drawing buffer alive after a
+   * window shrank, and would leave `gl.viewport` and the projection describing a
+   * buffer bigger than the one being presented. Re-reads the ACHIEVED size
+   * afterwards, because setting `canvas.width` only REQUESTS an allocation — an
+   * implementation may return a smaller buffer, and trusting the attribute over
+   * the buffer is how a renderer ends up drawing into rows that do not exist.
+   */
+  setStageSize(width: number, height: number): void;
+  /** Change the design extent (a scene that re-lays-out for a new aspect). */
+  setDesignSize(width: number, height: number): void;
+  /** The current projection. The returned object is reused; read it, don't keep it. */
+  projection(): StageProjection;
+  /** Set `gl.viewport` to the whole drawing buffer. */
+  applyViewport(): void;
+  /** Detach the context-loss listeners. Does not delete the context. */
+  dispose(): void;
+}
+/** The attributes the stage asks for, exported so a test can assert the contract
+ *  rather than restate it. */
+declare const STAGE_CONTEXT_ATTRIBUTES: Readonly<WebGLContextAttributes>;
+/**
+ * Create a stage on `canvas`, or `null` when the browser gives no WebGL2 context.
+ *
+ * Note what is NOT here: no software-renderer refusal. `html`'s shared context
+ * declines SwiftShader/llvmpipe because running full-screen procedural fragment
+ * shaders on a CPU rasterizer costs more than the CSS fallback it has. The stage
+ * has no fallback to fall back TO — it is the renderer — and its fragment shader
+ * is a texture fetch and a multiply, which software GL runs perfectly well. The
+ * decision of whether this device should use the canvas renderer at all belongs
+ * to the consumer, one level up, where the alternative is known.
+ */
+declare function createCanvasStage(options: CanvasStageOptions): CanvasStage | null;
+//#endregion
+//#region src/glyph-pass.d.ts
+/**
+ * The seam between the executor and whatever draws glyph outlines.
+ *
+ * STRUCTURAL, AND IN THE CORE, SO THE BARREL STAYS FREE OF A GLYPH RENDERER. The only
+ * implementation this repo ships is backed by `@godot-scene-web/hb-gpu` and lives on the
+ * `./glyphs` subpath, for two reasons that are both about cost rather than taste: the main
+ * barrel's export list is mirrored by hand-maintained ambient `.d.ts` files in
+ * `../sts2-couch-coop` and `../spirectl` (see `AGENTS.md`), so every name added there is work
+ * downstream; and a scene with no text should not pull a glyph renderer, its wasm loader and its
+ * atlas into the bundle. A consumer that wants glyphs imports the adapter and injects it exactly
+ * the way `CanvasExecutorOptions.white` is injected today.
+ *
+ * ONE METHOD, AND NO FRAME LIFECYCLE. There is no `begin`/`end` here on purpose: the executor
+ * flushes its pending batch before calling {@link GlyphPass.drawRun} and restores its own GL state
+ * after, so a pass has nothing to get wrong about when a frame starts. Everything it needs about
+ * the frame is in the two arguments.
+ */
+interface GlyphPass {
+  /**
+   * Draw ONE glyph run, in the GL state the executor is currently in.
+   *
+   * ONE DRAW CALL PER RUN, and that is a property of the mechanism rather than a thing to optimise
+   * away later: hb-gpu's program carries the run's colour and its model matrix as UNIFORMS, so two
+   * runs can only share a draw when both are identical, and the model matrix in particular cannot
+   * be moved onto the instance without also moving the dilation `hb_gpu_dilate` computes through
+   * it. A caller that wants fewer draws should merge runs when it BUILDS the list.
+   *
+   * `run` is the executor's own reusable view and is valid only for the duration of the call —
+   * `run.slots` and `run.positions` are overwritten by the next `readGlyphs`. Read what is needed
+   * and return.
+   *
+   * `projection` is the frame's, and the pass is expected to honour BOTH halves of it: `toClip`
+   * maps design space (the space `run.positions` are in, after `run.m`) to clip space, and
+   * `framebufferWidth`/`framebufferHeight` is the achieved drawing buffer, which is what a
+   * resolution-independent glyph shader measures a screen pixel against. They differ by the
+   * device-pixel ratio and conflating them is a dilation error, not a placement error.
+   *
+   * WHAT THE PASS MAY ASSUME on entry: `BLEND` is enabled, `SCISSOR_TEST` is enabled and the
+   * scissor box is the frame's current clip, the viewport is the whole drawing buffer, and the
+   * pending quad batch has already been drawn. WHAT IT MAY LEAVE DIRTY: the program, the bound
+   * VAO, `ARRAY_BUFFER`, texture unit 0 and the blend equation/function — the executor rebinds and
+   * re-invalidates all of those. It must NOT clear, must NOT touch the viewport, and must NOT
+   * touch `SCISSOR_TEST` or the scissor box, because that is what clips the run.
+   */
+  drawRun(run: GlyphsView, projection: StageProjection): {
+    glyphs: number;
+    drawCalls: number;
+  };
+  /**
+   * Draw consecutive glyph commands as one ordered submission. Optional so existing passes keep
+   * their exact one-command path. The executor only calls this for physically adjacent glyph
+   * commands in an unbroken clip/mask scope; implementations must preserve the supplied order.
+   */
+  drawRuns?(runs: readonly GlyphsView[], projection: StageProjection): {
+    glyphs: number;
+    drawCalls: number;
+  };
+  /** Conservative residency admission for `drawRuns`; false keeps commands separate. */
+  canBatchRuns?(runs: readonly GlyphsView[]): boolean;
+}
+//#endregion
+export { DamageRect as $, DrawListPatchView as A, ScreenEffectDrawContext as B, DRAW_TEXTURED_MESH as C, DrawListFragment as D, DrawList as E, GlyphsView as F, createDrawListPatchView as G, createClipRectView as H, NinePatchView as I, createPolylineView as J, createGlyphsView as K, PolylineView as L, ExternalEffectDrawContext as M, FLIP_H as N, DrawListFragmentPatch as O, FLIP_V as P, CommandBounds as Q, QuadView as R, DRAW_SCREEN_EFFECT as S, DrawCommandName as T, createDrawList as U, TexturedMeshView as V, createDrawListFragment as W, createTexturedMeshView as X, createQuadView as Y, setViewColorMatrix as Z, DRAW_EXTERNAL_EFFECT as _, StageCanvas as a, RETAINED_MAX_DAMAGE_COVERAGE as at, DRAW_POLYLINE as b, BLEND_ADD as c, createDamageTiles as ct, BLEND_SUB as d, outsetDamageRect as dt, DamageTile as et, BlendMode as f, transformDamageRect as ft, DRAW_COMMAND_NAMES as g, DRAW_CLIP_PUSH as h, STAGE_CONTEXT_ATTRIBUTES as i, RETAINED_DAMAGE_TILE_SIZE as it, ExternalEffectDrawCommand as j, DrawListOptions as k, BLEND_MIX as l, damageIntersects as lt, DRAW_CLIP_POP as m, CanvasStage as n, DamageTransform as nt, StageProjection as o, commandDamageBounds as ot, ClipRectView as p, unionDamageRect as pt, createNinePatchView as q, CanvasStageOptions as r, DirtyRect as rt, createCanvasStage as s, createDamageRect as st, GlyphPass as t, DamageTiles as tt, BLEND_MUL as u, isDamageEmpty as ut, DRAW_GLYPHS as v, DrawCommandKind as w, DRAW_QUAD as x, DRAW_NINE_PATCH as y, ScreenEffectDrawCommand as z };
+//# sourceMappingURL=glyph-pass-DfQlp_IH.d.ts.map