@weasel-js/renderer 0.0.0-stage → 1.9.4

package/dist/index.d.ts

@@ -0,0 +1,1070 @@
+import { S as ShaderProgramHandle, a as ShaderUniform, b as ShaderProgram, F as FillPoseBox } from './paintKinds-B2vEy9A4.js';
+export { P as PaintBindContext, c as PaintDrawKind, d as PaintDrawKindLoader, e as PaintProgram, f as PaintResources, g as ProgramSource, h as ShaderCompileError, i as fillInPoseFrame, j as fillToBoundsFrame, k as getPaintDrawKind, l as getProgramSource, m as isPaintKindKnown, p as paintDrawKindRegistry, n as programSourceRegistry, r as registerPaintDrawKind, o as registerPaintDrawKindLoader, q as registerProgram, w as warmPaintKinds } from './paintKinds-B2vEy9A4.js';
+import { Mesh } from '@weasel-js/geom/tessellate';
+export { Mesh, TessellateOptions, tessellate } from '@weasel-js/geom/tessellate';
+import { GradStop, ColorSpace, CommandFill, CommandStroke, Stroke, FillStyle, TextureHandle } from '@weasel-js/paint';
+export { CommandFill, CommandPaintUnits, CommandStroke, PosedFill, SolidFill, TextureHandle } from '@weasel-js/paint';
+import { GlMat3, Path } from '@weasel-js/geom';
+export { GlMat3, View as ViewLike, mat3, viewToMat3 } from '@weasel-js/geom';
+import { ResolvedRun, TextAlign, TextDirection, TextStyle, TextVerticalAlign, TextPaint, TextPose, StyledRun } from '@weasel-js/text';
+import { D as DrawBatch } from './imageCache-oJVgxhkr.js';
+export { I as ImageNodeData, a as ImageRasterSize, b as ImageStatus, T as TextureEntry, g as getImageBitmap, i as imageStatus, c as isPatternSpec, d as isVectorImageSrc, r as registerTexture, e as releaseImage, f as resolveFillPattern, h as resolvePatternSpec, j as retryImage, s as subscribeImageReady, t as textureRegistry, u as unregisterTexture } from './imageCache-oJVgxhkr.js';
+export { StrokeOptions, tessellateStroke } from '@weasel-js/stroke';
+export { RegisterFontOptions, canQueryLocalFonts, cssFontFamily, cssFontFamilyLoading, enableLocalFontOutlines, fontOutlineRegistry, fontRegistry, hasFontOutlines, isCanvasFont, listFontOutlines, loadFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
+import '@weasel-js/registry';
+
+interface GLMeshHandle {
+    readonly vao: WebGLVertexArrayObject;
+    readonly indexCount: number;
+    readonly requiresStencil: boolean;
+    readonly anchorA?: Uint32Array;
+    readonly anchorB?: Uint32Array;
+    readonly anchorT?: Float32Array;
+}
+/** Resources to release when a Mesh is reclaimed by GC. */
+interface MeshResources {
+    vao: WebGLVertexArrayObject;
+    vbo: WebGLBuffer;
+    ibo: WebGLBuffer;
+}
+/**
+ * Caches GL-side buffers + VAO per `Mesh` identity. Upload happens lazily
+ * on first `handleFor(mesh)` call.
+ *
+ * **GC-aware cleanup (deferred-delete queue):** when a Mesh becomes
+ * unreachable, the WeakMap entry is dropped automatically — but the
+ * underlying GL resources (VAO, VBO, IBO) would leak forever without an
+ * explicit `gl.delete*` call. We register each Mesh with a
+ * `FinalizationRegistry`; when the Mesh is reclaimed, the finalizer pushes
+ * the resources onto an internal queue. The renderer drains this queue at
+ * the start of each `render()` call (via `drainPendingDeletes()`), when GL
+ * is in a known state — no VAO bound, no draw mid-flight. Deleting from the
+ * finalizer directly was racy (it could fire between two `gl.bindVertexArray`
+ * calls inside `dispatch()`, sometimes corrupting the next draw); deferring
+ * the actual delete to a known-safe point keeps the use-after-free risk to
+ * zero.
+ *
+ * Caveats:
+ *   - Finalizer timing is non-deterministic; resources may live for a frame
+ *     or two beyond their Mesh, but they will be reclaimed.
+ *   - If the GL context is lost between finalizer and drain, the drain
+ *     no-ops safely (`gl.isContextLost()` makes deletes no-ops, and
+ *     `gl.deleteBuffer(null)` is allowed).
+ *
+ * The cache is GL-context-bound; if the context is lost and re-created, the
+ * renderer should construct a new GLMeshCache. (Context loss handling lives
+ * in `WeaselRenderer`.)
+ */
+declare class GLMeshCache {
+    private readonly gl;
+    private readonly map;
+    /** Meshes this context has drawn at least once; see `uploadRecurring`. */
+    private readonly seen;
+    private readonly finalizer;
+    /** Every persistent upload not yet freed, so `dispose` can reach them. */
+    private readonly persistent;
+    private readonly pendingDeletes;
+    private disposed;
+    /** Transient resources allocated this frame; freed at end of render(). */
+    private readonly transientThisFrame;
+    constructor(gl: WebGL2RenderingContext);
+    handleFor(mesh: Mesh): GLMeshHandle;
+    /**
+     * Upload a Mesh that the caller knows is single-use (e.g. the per-frame
+     * stroke ribbon from `tessellateStroke`). Returns a handle backed by fresh
+     * GL resources that the renderer will free deterministically at the end
+     * of the current frame via `freeTransient()`. Bypasses the WeakMap cache
+     * and the FinalizationRegistry, so transient meshes never wait on GC.
+     */
+    uploadTransient(mesh: Mesh): GLMeshHandle;
+    /**
+     * Upload a Mesh that may or may not recur across frames. Its first sight in
+     * *this* context takes `uploadTransient`; every later one takes the
+     * persistent handle. One transient upload to find out is cheaper than
+     * stranding a persistent VAO on a mesh that never returns, whose release
+     * would wait on GC. The transient upload does not populate the persistent
+     * map, so steady-state reuse begins on the third frame.
+     */
+    uploadRecurring(mesh: Mesh): GLMeshHandle;
+    /**
+     * Free all transient resources allocated since the last call. Called by
+     * the renderer at the end of each `render()`. Safe under context loss.
+     */
+    freeTransient(): void;
+    /** @internal — for tests asserting the transient-list size. */
+    _transientCount(): number;
+    /**
+     * Free GL resources whose Mesh has been GC'd since the last drain.
+     * Called by the renderer at the top of each `render()`, before any draws.
+     */
+    drainPendingDeletes(): void;
+    /**
+     * Free every GL resource this cache holds — persistent, pending and
+     * transient — and ignore finalizers from here on. Idempotent. Unlike the
+     * other paths this does not wait on GC, which is what lets a renderer on a
+     * context it does not own give back everything it uploaded.
+     */
+    dispose(): void;
+    /** @internal — for tests asserting the queue size. */
+    _pendingDeleteCount(): number;
+    /** @internal — for tests that need to simulate the finalizer firing. */
+    _enqueueDeleteForTest(resources: MeshResources): void;
+    private upload;
+}
+
+/**
+ * GL texture upload + cache for MSDF font atlases (and future images).
+ *
+ * Textures are keyed by a string id (the font family name or image id).
+ * Pixels are uploaded once per id; a later upload of the same id reuses the
+ * texture and only re-applies its wrap mode when that changed.
+ * The cache is GL-context-bound; discard and create a new one on context loss.
+ *
+ * Atlas format: RGBA UNSIGNED_BYTE, linear filtering, no mipmaps.
+ * Mipmap generation is deliberately skipped — MSDF works correctly with
+ * linear filtering, and mipmap resampling corrupts the multi-channel SDF signal.
+ */
+type TexSource$1 = HTMLImageElement | ImageBitmap | ImageData | HTMLCanvasElement;
+/** How a texture samples outside `0..1`. Pattern tiles need `'repeat'`;
+ *  everything else clamps. WebGL2 allows `REPEAT` on NPOT textures, so a
+ *  tile of any size tiles correctly. */
+type TextureWrap = 'clamp' | 'repeat';
+/** The part of the texture registry a sweep reads. */
+interface RegisteredTextureIds {
+    getVersion(): number;
+    has(id: string): boolean;
+}
+declare class GLTextureCache {
+    private readonly gl;
+    private readonly map;
+    private readonly wraps;
+    /** The source each registry-backed id was last uploaded from. */
+    private readonly registered;
+    private sweptVersion;
+    constructor(gl: WebGL2RenderingContext);
+    has(id: string): boolean;
+    /** Uploads the pixels once per id. `wrap` is re-applied whenever it differs
+     *  from what the id was last uploaded under: the same registered image can
+     *  be a clamped shader texture in one draw and a repeating pattern tile in
+     *  the next, and first-upload-wins gave the second one the first one's mode. */
+    upload(id: string, source: TexSource$1, wrap?: TextureWrap): string;
+    /** `upload` for an id from the texture registry, whose image can be replaced
+     *  under the same id: a changed source sends its pixels again. */
+    uploadRegistered(id: string, source: TexSource$1, wrap?: TextureWrap): string;
+    /**
+     * Delete the texture of every registry-backed id the registry has dropped.
+     * The renderer calls this at the top of `render()`, before any draw, so a
+     * texture is never deleted under a draw that has it bound.
+     */
+    sweep(registry: RegisteredTextureIds): void;
+    private applyWrap;
+    /** Create a single-channel R8 texture from raw bytes (full upload).
+     *  No-op if `id` already exists. Same LINEAR/CLAMP params as `upload`;
+     *  UNPACK_ALIGNMENT dropped to 1 for non-4-aligned row widths. */
+    uploadR8(id: string, width: number, height: number, data: Uint8Array): void;
+    /** Patch a rect of an existing R8 texture with tightly-packed w×h bytes. */
+    subImageR8(id: string, x: number, y: number, w: number, h: number, data: Uint8Array): void;
+    bind(id: string, unit: number): void;
+    /**
+     * Delete every uploaded GL texture and clear the map. Called by
+     * `WeaselRenderer.dispose()`. The cache is unusable but refillable
+     * afterward — a subsequent `upload()` for a previously-seen id re-creates
+     * the texture rather than restoring the deleted one.
+     */
+    free(): void;
+}
+
+/**
+ * GL texture upload cache for ImageBitmap objects.
+ *
+ * Key: ImageBitmap (or pattern source object) identity (WeakMap) — lets GC
+ * reclaim unreferenced bitmaps. A collected source's texture is queued and
+ * deleted at the renderer's next frame, the way `GLMeshCache` frees a mesh's
+ * buffers; GC timing is not prompt, so a source's owner that knows it will
+ * never be drawn again frees it at once with {@link releaseImageSource}, and
+ * `dispose` frees them all.
+ *
+ * Wrapping is set once at upload time per the `repetition` parameter:
+ *   - undefined / 'no-repeat' → CLAMP_TO_EDGE
+ *   - 'repeat'   → REPEAT (both axes)
+ *   - 'repeat-x' → REPEAT on S, CLAMP on T
+ *   - 'repeat-y' → CLAMP on S, REPEAT on T
+ *
+ * Convention §2: texels stored straight; shader premultiplies.
+ */
+type PatternRepetition = 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+/** MIN_FILTER strategy for uploaded textures. */
+type ImageMinification = 'linear' | 'mipmap';
+type TexSource = ImageBitmap | ImageData | HTMLCanvasElement | HTMLImageElement;
+/** Free `key`'s texture in every live renderer. For an owner that has replaced
+ *  a source and will never draw the old one again — a later draw of it simply
+ *  re-uploads. */
+declare function releaseImageSource(key: object): void;
+declare class GLImageCache {
+    private readonly gl;
+    private readonly minification;
+    /** This context's `MAX_TEXTURE_SIZE`. */
+    readonly maxTextureSide: number;
+    private readonly map;
+    /** Every texture `map` holds, so `dispose` can reach them — a WeakMap
+     *  cannot be enumerated. */
+    private readonly textures;
+    /**
+     * MAG_FILTER each texture currently carries, so a redundant write can be
+     * skipped.
+     *
+     * The batch sets this per flush — the same bitmap can be drawn at both
+     * filters in one frame, and the value has to be right at the draw rather than
+     * at upload. Filtering is state on the *texture object*, though, not on the
+     * unit, so re-asserting a value it already has is a write to a live texture
+     * for no reason. On a large sheet that is not free: a consumer's wall samples
+     * a 5652px-square atlas, 122MB resident, and measured `sampling: 'nearest'`
+     * costing up to 8x `'linear'` there — where the linear pass re-asserts the
+     * upload default and the nearest pass changes state on every draw.
+     *
+     * Whether that is the cause is unproven (see `docs/TODO.md`), but the write
+     * was redundant either way.
+     */
+    private readonly magFilters;
+    private readonly finalizer;
+    private readonly pendingDeletes;
+    /** `minification` selects the MIN_FILTER strategy for uploaded textures.
+     *  `'linear'` (default) is the screen path's existing behavior. `'mipmap'`
+     *  generates mipmaps and filters LINEAR_MIPMAP_LINEAR — required for
+     *  quality minification when a large source bitmap is drawn small (the
+     *  headless print/export path); bilinear-only minification undersamples
+     *  and produces moiré. */
+    constructor(gl: WebGL2RenderingContext, minification?: ImageMinification);
+    /** Delete the textures of sources collected since the last call. The
+     *  renderer calls this at the top of each `render()`. */
+    drainPendingDeletes(): void;
+    /** Delete `key`'s texture, if it has one. */
+    release(key: object): void;
+    /** Delete every texture this cache uploaded and stop answering
+     *  {@link releaseImageSource} and {@link maxImageTextureSide}. Idempotent. */
+    dispose(): void;
+    /** {@link dispose} without the deletes, for a cache whose context was lost:
+     *  its textures died with it. */
+    abandon(): void;
+    upload(key: object, source: TexSource, repetition?: PatternRepetition): WebGLTexture;
+    bind(key: object, unit: number): void;
+    /** Set `key`'s MAG_FILTER, skipping the call when it already holds that
+     *  value. Its texture must be bound to the active unit — callers pair this
+     *  with `bind`. */
+    setMagFilter(key: object, filter: number): void;
+}
+
+/**
+ * CPU gradient-ramp builder + the GL texture every baked ramp lives in.
+ *
+ * Each unique stop list is baked once into a 256-texel strip and written to its
+ * own **row** of one RGBA texture, keyed by `JSON.stringify(stops)`. One
+ * texture rather than one per ramp is what lets a gradient take a batch texture
+ * slot the way a bitmap or a font atlas does: every gradient in a frame samples
+ * the same unit, so a run does not break per gradient. The atlas is
+ * GL-context-bound; discard and recreate on context loss.
+ *
+ * Output convention §2: texels are stored as straight RGBA. The fragment
+ * shader applies premultiplication before writing outColor.
+ */
+
+/** Bake gradient stops into a 256-entry RGBA lookup strip, which the shader
+ *  samples instead of evaluating stops per fragment. `space` is the gradient's
+ *  `interpolate` — the ramp is where a non-sRGB blend is paid for, once. */
+declare function buildGradientRamp(stops: GradStop[], space?: ColorSpace): Uint8ClampedArray;
+declare class GradientRampAtlas {
+    private readonly gl;
+    /** Row per stop list, in least-recently-used order: a hit re-inserts, so the
+     *  first entry is the row a full atlas recycles. */
+    private readonly rowByKey;
+    private texture;
+    private rows;
+    /** Mirror of the texture, so growth can respecify it without re-baking every
+     *  ramp it already holds. */
+    private pixels;
+    private totalQueries;
+    private cacheHits;
+    constructor(gl: WebGL2RenderingContext);
+    /** Rows the atlas currently holds — its texture height. */
+    get height(): number;
+    /**
+     * Bake `stops` into a row and return it, reusing the row an identical stop
+     * list already holds.
+     *
+     * **A returned row outlives the frame only while the atlas has room.** Past
+     * `RAMP_ATLAS_MAX_ROWS` an upload recycles the least recently used row, which
+     * rewrites texels a row handed out earlier still names. Nothing that defers
+     * its draw past this call may hold a row across another `upload` without
+     * arranging to be flushed first.
+     */
+    upload(stops: GradStop[], space?: ColorSpace): number;
+    /**
+     * Whether uploading `stops` would move where existing rows sit — by growing
+     * the atlas, which changes every row's `v`, or by recycling one, which
+     * rewrites its texels.
+     *
+     * Anything holding a row past this call asks first and gets itself out of
+     * the way, because neither can be undone once it has happened.
+     */
+    wouldReshape(stops: GradStop[], space?: ColorSpace): boolean;
+    /**
+     * The `v` a row is sampled at — its center.
+     *
+     * The center is load-bearing: the atlas filters LINEAR, so a `v` anywhere
+     * else blends the ramp beside it into this one. At the center the neighbor's
+     * weight is exactly zero.
+     */
+    rowV(row: number): number;
+    bind(unit: number): void;
+    hitRate(): number;
+    resetStats(): void;
+    /**
+     * Delete the atlas texture and forget every row in it. Called by
+     * `WeaselRenderer.dispose()`. The CPU mirror goes with it, so the atlas is
+     * unusable but refillable afterward (stats are left as-is; call
+     * `resetStats()` separately if desired).
+     */
+    free(): void;
+    /** The row the next ramp is written to: a free one, a taller atlas, or the
+     *  least recently used row of a full one. */
+    private claimRow;
+    /** Grow to `rows`, keeping every row at the index it already had — a row
+     *  index is a stable name, and callers hold them. */
+    private resize;
+    private writeRow;
+}
+
+/** Row-major 4×5 color matrix identity. */
+declare const IDENTITY_COLOR_MATRIX: Float32Array<ArrayBuffer>;
+interface GroupFrame {
+    transform?: GlMat3;
+    alpha?: number;
+    /** Row-major 4×5 color matrix (20 floats). Absent leaves the stack unchanged. */
+    colorMatrix?: Float32Array | number[];
+}
+declare class GroupState {
+    private transformStack;
+    private alphaStack;
+    private colorMatrixStack;
+    get transform(): GlMat3;
+    get alpha(): number;
+    get colorMatrix(): Float32Array;
+    push(frame: GroupFrame): void;
+    /**
+     * Push a frame whose children paint into a surface of their own.
+     *
+     * The transform still accumulates — the children draw where they would have
+     * drawn. Alpha and colour do not: they describe how the finished surface
+     * joins the frame, and applying them on the way in as well would fade the
+     * pixels an effect is about to read, then fade them again on the way out.
+     *
+     * Returns the pair the caller must apply at composite time — what `push`
+     * would have left on the stack — so the composition rules live here and not
+     * in the dispatcher.
+     */
+    pushIsolated(frame: GroupFrame): {
+        alpha: number;
+        colorMatrix: Float32Array;
+    };
+    /** Drop every pushed frame, leaving the root. A frame that throws part-way
+     *  down the tree never pops, and the next frame would draw under leftovers. */
+    reset(): void;
+    pop(): void;
+}
+
+/**
+ * One full-screen pass over what a group has already drawn.
+ *
+ * The renderer runs a group's effects in order, each reading the previous
+ * one's output through `u_source` and writing a whole new buffer — so an
+ * effect is free to read neighbouring pixels, which is the entire point and
+ * the one thing `colorMatrix` can never do.
+ *
+ * `uniforms` are the effect's own; `u_source`, `u_resolution` and `u_texel`
+ * come from the renderer and must not be passed here.
+ */
+interface Effect {
+    program: ShaderProgramHandle;
+    uniforms?: Record<string, ShaderUniform>;
+}
+/**
+ * Register a fragment shader as an effect. Sugar over `registerProgram` with
+ * the effect vertex shader, and the reason a consumer never imports the
+ * prelude: an effect that registers with the *custom-shader* vertex shader
+ * compiles, runs, and samples its source upside down.
+ *
+ * The fragment shader reads `v_uv` and `u_source`, and may declare
+ * `u_resolution` / `u_texel`. See `effectPrelude.ts` for the full contract,
+ * including the premultiplied-alpha requirement.
+ *
+ * @experimental
+ */
+declare function registerEffect(id: string, frag: string): ShaderProgramHandle;
+
+/**
+ * Solid-fill paint variant (subset of the full `FillStyle` union from
+ * `@weasel-js/paint`). Kept for back-compat with step-1/2 consumers and
+ * because some code reads `fill.color` directly. Through step 4, fills can
+ * be any `FillStyle` variant — solid, pattern, or gradient.
+ */
+interface SolidPaint {
+    fill?: 'solid';
+    /** Any CSS color string accepted by `parseColor`: hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`, named, or `transparent`. */
+    color: string;
+    opacity?: number;
+}
+/** DrawCommand variants implemented through step 6. */
+type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | SpritesDrawCommand | ShaderDrawCommand;
+/** Draw a path, filled and/or stroked. The workhorse command: every shape the
+ *  kit draws that is not text, an image, or a custom shader is one of these. */
+interface PathDrawCommand {
+    kind: 'path';
+    path: Path;
+    /** Solid, pattern, or gradient (linear/radial/conic), resolved for the
+     *  renderer: `commandFill` makes one from a node's `FillStyle`. */
+    fill?: CommandFill;
+    /** Stroke spec. Its `paint` takes what `fill` does. */
+    stroke?: CommandStroke;
+    /**
+     * Optional flat RGBA-per-path-anchor color array (length =
+     * `4 × countPathAnchors(path)`, floats in 0..1). The renderer
+     * arc-length-interpolates these per-anchor colors across the
+     * flattened/triangulated mesh between consecutive anchors using the
+     * mesh's `anchorA` / `anchorB` / `anchorT` parameterization.
+     *
+     * **`fill` must also be set when using `vertexColors`.** The renderer
+     * only enters the per-vertex shader path when the command has a fill
+     * (the fill provides the opacity uniform; the vertex colors override
+     * the fill's color). Pass any solid `fill` (e.g. `{ color: '#fff' }`)
+     * as the placeholder; the per-vertex colors win in the shader.
+     */
+    vertexColors?: number[];
+}
+/** Draw a list of commands under a shared transform, opacity, color matrix
+ *  and clip. Groups nest, and their effects accumulate down the stack — this
+ *  is how a container node's transform reaches its descendants. */
+interface GroupDrawCommand {
+    kind: 'group';
+    transform?: GlMat3;
+    alpha?: number;
+    /**
+     * Optional 4×5 color matrix (row-major, 20 numbers) — `out = M₄ₓ₄ * in + bias`.
+     * Accumulated multiplicatively down the group stack. Defaults to identity.
+     */
+    colorMatrix?: number[];
+    /** Optional clip path. When set, the renderer rasterizes this path into
+     *  the stencil buffer before drawing `children`; the children paint only
+     *  where the clip covers. Nested groups with clips intersect — a child
+     *  cannot escape an ancestor's clip. Max 7 nesting levels; the renderer
+     *  throws if exceeded. */
+    clip?: Path;
+    /**
+     * Full-screen passes run over this group's own pixels, in order, before it
+     * is composited into its parent.
+     *
+     * Unlike every other field here, this does not accumulate down the group
+     * stack — it is a render-target boundary. The children draw into a buffer of
+     * their own, each effect reads the previous one's output, and the result is
+     * composited back under this group's `transform`, `alpha`, `colorMatrix` and
+     * whatever clip encloses it. So a blur here blurs this group and nothing
+     * around it, which is what a CSS `filter` on the canvas cannot do.
+     *
+     * An empty or absent list costs nothing: no buffer is allocated until a
+     * group asks for one.
+     */
+    effects?: readonly Effect[];
+    children: DrawCommand[];
+}
+/**
+ * Text draw command. Renders one or more runs at (`x`, `y`) in screen
+ * space, optionally word-wrapping at `maxWidth`. The renderer resolves
+ * each run's `(fontFamily, fontWeight, fontStyle)` to an MSDF atlas via
+ * `resolveFontVariant` and bucket-draws by atlas + color group.
+ *
+ * `style` carries node-level defaults (`lineHeight`, anti-alias width)
+ * that don't belong on individual runs.
+ */
+interface TextDrawCommand {
+    kind: 'text';
+    x: number;
+    y: number;
+    runs: ResolvedRun[];
+    /** Wrap width. Absent never wraps. */
+    maxWidth?: number;
+    align?: TextAlign;
+    /** What `start` / `end` resolve against, and the base direction of bidi
+     *  reordering — see `LayoutRunsOpts.direction`. Default `style`'s. */
+    direction?: TextDirection | 'auto';
+    /** Spread each wrapped line across `width` — see `LayoutRunsOpts.justify`.
+     *  `align` then sets only the lines it does not spread. Default `false`. */
+    justify?: boolean;
+    /** Box width `align` resolves within, from `x`. Default `maxWidth`; with
+     *  neither, `x` is the line's left edge, midpoint or right edge. */
+    width?: number;
+    style: TextStyle;
+    /** Box height for vertical alignment. When set with `verticalAlign`,
+     *  the laid-out block shifts within `[y, y+height]`. */
+    height?: number;
+    /** Default 'top' — the legacy top-anchored behavior. */
+    verticalAlign?: TextVerticalAlign;
+}
+/**
+ * Image draw command — renders `image` at screen-space rect (x, y, w, h).
+ * The image is stretched to fit; no tiling. Use a pattern FillStyle on a path
+ * for tiling.
+ */
+interface ImageDrawCommand {
+    kind: 'image';
+    image: ImageBitmap;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    opacity?: number;
+    /** Magnification filter. `'linear'` (default) smooths; `'nearest'` shows
+     *  device pixels as hard squares — required by anything magnifying a
+     *  framebuffer readback, where blur destroys the point of the readback. */
+    sampling?: 'linear' | 'nearest';
+    /** Sub-rectangle of `image` to draw, in bitmap pixels from the top-left.
+     *  Omitted draws the whole bitmap. Not range-checked: a rect past the edge
+     *  samples outside [0..1], which CLAMP_TO_EDGE smears. With
+     *  `sampling: 'linear'` the filter reaches half a texel beyond `source`, so
+     *  atlas frames need a gutter (see `SpriteSheet.spacing`) or `'nearest'`. */
+    source?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Mirror the sampled region within the destination rect. The quad does not
+     *  move — a flipped draw covers exactly the pixels an unflipped one does. */
+    flipX?: boolean;
+    flipY?: boolean;
+}
+/** Floats per sprite in `SpritesDrawCommand.sprites`. */
+declare const SPRITE_STRIDE = 9;
+/**
+ * Draw many quads sampling one bitmap — an atlas, a sprite sheet, a wall of
+ * thumbnails. The same picture as a run of `ImageDrawCommand`s the renderer
+ * would coalesce anyway, handed over already packed so it never walks a
+ * command object per quad.
+ *
+ * Reach for it past a few thousand sprites. Below that a plain run of image
+ * commands merges into the same single draw and reads better; the packed form
+ * exists because at 20,000 the object walk is about half the frame.
+ *
+ * The sprites are one run: they share a texture, a filter, and whatever group
+ * transform, alpha, color matrix and clip are live, exactly as a merged run of
+ * image commands would. Anything varying per sprite is in the array.
+ */
+interface SpritesDrawCommand {
+    kind: 'sprites';
+    image: ImageBitmap;
+    /** Magnification filter for the whole run, as `ImageDrawCommand.sampling`. */
+    sampling?: 'linear' | 'nearest';
+    /**
+     * `SPRITE_STRIDE` floats per sprite:
+     * `dx, dy, dw, dh, sx, sy, sw, sh, opacity`.
+     *
+     * Destination is in the group's coordinates; source is in bitmap pixels,
+     * like `ImageDrawCommand.source`. A negative `sw` or `sh` mirrors that axis
+     * within the source rect, which is what `flipX` / `flipY` do. A trailing
+     * partial sprite is ignored.
+     */
+    sprites: Float32Array;
+}
+/**
+ * Custom shader draw command. The renderer generates a quad over `bounds`
+ * and dispatches the consumer's fragment shader with the kit's vertex prelude.
+ *
+ * `uniforms` keys must match names declared in the consumer's fragment shader.
+ * The kit automatically sets `u_bounds`, `u_view`, and `u_proj` — do not
+ * declare those in `uniforms`.
+ *
+ * @experimental API may change before v2.
+ */
+interface ShaderDrawCommand {
+    kind: 'shader';
+    program: ShaderProgramHandle;
+    uniforms: Record<string, ShaderUniform>;
+    /** Screen-space bounding rect in CSS pixels. */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+
+/** A run of top-level commands, `[start, end)` by index, that
+ *  {@link WeaselRenderer.lastFrameStats} accounts for separately — one render
+ *  layer's commands, say. Spans are in order and do not overlap. */
+interface RenderSpan {
+    id: string;
+    start: number;
+    end: number;
+}
+/** Per-frame options for {@link WeaselRenderer.render}. */
+interface RenderOptions {
+    spans?: readonly RenderSpan[];
+}
+/** What one span cost. A batched run is drawn when something closes it, so
+ *  its draw call counts toward the span that closed it. */
+interface RenderSpanStats {
+    id: string;
+    drawCalls: number;
+    ms: number;
+}
+/** What one `render()` cost. See {@link WeaselRenderer.lastFrameStats}. */
+interface RenderStats {
+    drawCalls: number;
+    ms: number;
+    spans: RenderSpanStats[];
+}
+/** Construction options for {@link WeaselRenderer}. Pass `gl` or `canvas`;
+ *  a context passed in must have a stencil buffer. */
+interface WeaselRendererOptions {
+    /** A WebGL2 context to draw with. Wins over `canvas`. */
+    gl?: WebGL2RenderingContext;
+    /** A canvas to open a stencil-backed WebGL2 context on, when `gl` is absent. */
+    canvas?: HTMLCanvasElement;
+    /** Drawing size in CSS pixels. */
+    width: number;
+    /** Drawing size in CSS pixels. */
+    height: number;
+    /** Device pixels per CSS pixel. */
+    dpr: number;
+    /** MIN_FILTER strategy for image/pattern textures (`GLImageCache`).
+     *  Default `'linear'` — the existing screen behavior. The headless
+     *  `renderSceneToPixels` path passes `'mipmap'` for print-quality
+     *  minification. Explicitly passing `'linear'` is always valid. */
+    imageMinification?: ImageMinification;
+    /** Flatness tolerance for curve tessellation, in WORLD units (see
+     *  `TessellateOptions.flattenTolerance`). When set, path fills are
+     *  tessellated fresh at this tolerance per frame (transient pool) instead
+     *  of served from the Path-identity mesh cache — the cache key does not
+     *  include tolerance. Default: unset — the existing cached behavior at
+     *  `DEFAULT_FLATTEN_TOLERANCE`. The headless path derives this from the
+     *  requested output scale; screen callers normally leave it unset. */
+    flattenTolerance?: number;
+    /** Per-render synchronous bake budget for dynamic canvas-SDF glyphs.
+     *  Default DEFAULT_BAKE_BUDGET (16). The headless renderSceneToPixels
+     *  path passes Infinity so print never defers a glyph. */
+    bakeBudget?: number;
+    /** On-screen glyph size, in CSS pixels, at or above which text renders from
+     *  tessellated font outlines instead of a distance field — see
+     *  `OUTLINE_MIN_SCREEN_PX`. Only faces registered with
+     *  `registerFontOutlines` are affected; everything else keeps its SDF tier
+     *  whatever this says. Pass `Infinity` to disable the tier outright, or 0
+     *  to use outlines wherever they exist (what the headless path does, since
+     *  print has no reason to sample a field it could evaluate exactly). */
+    textOutlineMinScreenSize?: number;
+}
+/** Where a renderer draws inside a buffer it does not own.
+ *
+ *  The rect's SIZE is the renderer's own `width`/`height` — `resize()` owns
+ *  that, and a second copy here could disagree with the one `DrawContext`
+ *  reports to screen-space layers. */
+interface RenderTarget {
+    /** Top-left of this renderer's output within the drawing buffer, in CSS
+     *  pixels, with the origin at the buffer's top-left. GL's bottom-left origin
+     *  is handled internally. */
+    origin: {
+        x: number;
+        y: number;
+    };
+    /** Clear colour and stencil within the rect before drawing. Default true.
+     *  Pass false only when the caller clears the whole buffer itself on behalf
+     *  of every co-tenant — a frame that clears neither inherits its neighbour's
+     *  stencil bits, and even-odd fills then fill their holes. */
+    clear?: boolean;
+}
+/**
+ * The WebGL2 renderer: takes a list of draw commands and paints them.
+ *
+ * It knows nothing about the scene — commands are the whole interface, which
+ * is what lets layers, HUD widgets and overlays all draw through the same
+ * pipeline. GPU resources (meshes, textures, gradient ramps) are cached across
+ * frames and keyed by identity, so re-issuing the same command is cheap.
+ */
+declare class WeaselRenderer {
+    private readonly gl;
+    private stats;
+    private pathFill;
+    private pathFillVColor;
+    private batchFill;
+    private gradFill;
+    private patternFill;
+    /** Compiled on first use: only atlas text under a texture paint needs one. */
+    private glyphPaintPrograms;
+    private meshCache;
+    private textureCache;
+    private imageCache;
+    private gradRamps;
+    private programRegistry;
+    /** The source each compiled custom program was built from — or, after a
+     *  failed recompile, the source that failed, so it is not retried every frame. */
+    private programSources;
+    private quadVbo;
+    private quadIbo;
+    private drawBatch;
+    /** 1x1 white, so a batch flush sampling no image still samples something —
+     *  see `shaders/batchFill.ts`. */
+    private whiteTexture;
+    private readonly groupState;
+    private widthCss;
+    private heightCss;
+    private dpr;
+    private canvas;
+    /** Where context loss is announced: the context's own canvas, which the
+     *  renderer need not own the size of. */
+    private lossTarget;
+    private target;
+    /** Offscreen buffers for group effects. Allocates nothing until a group
+     *  with effects asks, so a canvas without them pays no memory. */
+    private readonly effectTargets;
+    private readonly paintScratch;
+    private readonly imageMinification;
+    private flattenTolerance?;
+    private readonly bakeBudget;
+    private readonly textOutlineMinScreenSize;
+    private contextLost;
+    private boundOnLost;
+    private boundOnRestored;
+    /** True after `dispose()`. A disposed renderer ignores further `render()`
+     *  calls and `registerProgram()` calls. */
+    private disposed;
+    /** What registered paint kinds hang their GPU state on. One per context
+     *  generation: a restore releases it and opens the next. */
+    private paintResources;
+    constructor(opts: WeaselRendererOptions);
+    private uploadQuadGeometry;
+    /**
+     * Compile a consumer-registered shader program against this renderer's GL context.
+     *
+     * Call once per renderer after the module-level `registerProgram()`.
+     * Throws `ShaderCompileError` if compilation fails.
+     *
+     * In dev mode, calling again with the same handle replaces the compiled program.
+     *
+     * @experimental
+     */
+    registerProgram(handle: ShaderProgramHandle): void;
+    private installProgram;
+    /** Recompile every program whose module-level source was re-registered
+     *  since it was compiled. A source that fails keeps the old program drawing. */
+    private refreshPrograms;
+    /**
+     * The compiled program for `id`, compiling it against this context on first
+     * use. Unlike {@link registerProgram} this neither throws on a missing
+     * source nor on a compile failure: a paint kind asking for a program it
+     * never registered must decline the paint, not take down the frame.
+     */
+    private ensureProgram;
+    private glyphPaintProgram;
+    /** The blend, depth, cull, clear-color, color-mask, VAO, and unpack-flip
+     *  state every frame assumes.
+     *  Applied per `render()` rather than once at construction because a
+     *  co-tenant sharing this context moves all of it between our frames. */
+    private applyGlState;
+    /** Viewport and scissor for this frame. Re-applied inside `render()` because
+     *  a co-tenant on the same context moves both between our frames. */
+    /** This renderer's rect in device pixels, top-left origin. A tile rounds its
+     *  edges rather than its size, so two that share a CSS edge share a device one. */
+    private deviceRect;
+    private applyTarget;
+    /** Confine this renderer to a rect of its drawing buffer, or pass null to
+     *  give it the whole buffer back. Takes effect from the next `render()`. */
+    setTarget(target: RenderTarget | null): void;
+    getTarget(): RenderTarget | null;
+    isContextLost(): boolean;
+    private onContextLost;
+    private onContextRestored;
+    /** Free every GL resource this renderer created and detach its
+     *  context-loss listeners. Idempotent.
+     *
+     *  That covers the built-in and consumer-registered programs (their shaders
+     *  go with them), the shared quad geometry, the batch, the effect targets,
+     *  and every cache: atlas and gradient-ramp textures, bitmap and pattern
+     *  textures, and meshes — transient, persistent, and those whose Path was
+     *  already collected. The context itself is left alone, so a caller-owned
+     *  context can host renderer after renderer without accumulating anything.
+     *
+     *  A disposed renderer ignores further `render()` and `registerProgram()`
+     *  calls. */
+    dispose(): void;
+    /**
+     * Draw one frame.
+     *
+     * `viewMatrix` is the frame's world→screen transform. It is only consulted
+     * by `units: 'world'` gradients, which fall back to screen space without
+     * it — every other command carries its own transform in the stream, so
+     * callers with no view concept can keep calling `render(commands)`.
+     */
+    render(commands: DrawCommand[], viewMatrix?: GlMat3, opts?: RenderOptions): void;
+    /** What the last `render()` cost: GL draw calls issued and CPU milliseconds
+     *  spent issuing them, in total and per requested span. GPU time is not
+     *  measured; the GPU runs asynchronously. */
+    lastFrameStats(): RenderStats;
+    /** Change the curve-flattening tolerance after construction. `undefined`
+     *  restores the cached `DEFAULT_FLATTEN_TOLERANCE` route. */
+    setFlattenTolerance(tolerance: number | undefined): void;
+    resize(dims: {
+        width: number;
+        height: number;
+        dpr: number;
+    }): void;
+    /** @internal */ _gl(): WebGL2RenderingContext;
+    /** @internal */ _pathFill(): ShaderProgram;
+    /** @internal */ _pathFillVColor(): ShaderProgram;
+    /** @internal */ _drawBatch(): DrawBatch;
+    /** @internal */ _batchFill(): ShaderProgram;
+    /** @internal */ _gradFill(): ShaderProgram;
+    /** @internal */ _patternFill(): ShaderProgram;
+    /** @internal */ _meshCache(): GLMeshCache;
+    /** @internal */ _textureCache(): GLTextureCache;
+    /** @internal */ _imageCache(): GLImageCache;
+    /** @internal */ _gradRamps(): GradientRampAtlas;
+    /** @internal */ _groupState(): GroupState;
+    /** @internal */ _widthCss(): number;
+    /** @internal */ _heightCss(): number;
+    /** @internal */ _dpr(): number;
+}
+
+/**
+ * Uniform-grid sprite sheet layout — frame index to the source rect an
+ * `ImageDrawCommand` samples. Pure arithmetic over the grid description; it
+ * never touches the bitmap.
+ */
+/** A sprite sheet's grid. `margin` and `spacing` follow the Tiled / Aseprite
+ *  tileset convention, so a sheet exported from either describes itself here. */
+interface SpriteSheet {
+    frameWidth: number;
+    frameHeight: number;
+    columns: number;
+    /** Empty pixels around the whole grid. Default 0. */
+    margin?: number;
+    /** Empty pixels between adjacent cells — the gutter that keeps linear
+     *  sampling off the neighboring frame. Default 0. */
+    spacing?: number;
+}
+/**
+ * Row-major source rect for frame `index`, counting from 0 at the top-left.
+ *
+ * `index` is not range-checked and does not wrap: past the last cell this
+ * returns a rect below the sheet, which draws as an edge smear. Wrapping is
+ * the animation's business (`frameRect(sheet, tick % count)`) — a sheet does
+ * not know how many of its cells are filled.
+ */
+declare function frameRect(sheet: SpriteSheet, index: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+
+/** A screen-space rectangle, CSS pixels. */
+interface CullRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * `cmds` without the commands that cannot put a pixel inside `rect`, where
+ * `transform` maps the commands' space to screen space — `viewToMat3(view)`
+ * for a world-space layer.
+ *
+ * Conservative by construction: a command is dropped only when a bound that
+ * encloses everything it can paint misses `rect`. Paths are bounded by their
+ * control hull plus the farthest a stroke can reach (miter spikes and square
+ * caps included), images and sprites by their quads, and every bound is taken
+ * through the accumulated transform as the AABB of its corners, so rotation
+ * only enlarges it. Text and shader commands are always kept, and so is a
+ * group with `effects` — an effect may move pixels. Clips are ignored, which
+ * can only keep more. A group whose children all go is dropped.
+ *
+ * Returns `cmds` itself when nothing was dropped.
+ */
+declare function cullDrawCommands(cmds: DrawCommand[], transform: GlMat3, rect: CullRect): DrawCommand[];
+/**
+ * {@link strokeReach} at a known world-to-screen scale — what a painter
+ * bounding its own output before it paints can know. `least` is the scale
+ * along the axis the transform shrinks most, where it differs from `scale`.
+ *
+ * A `{ px }` ribbon or head is built to its screen size in every direction,
+ * so in world it reaches farthest along that axis. A head with a world size is
+ * built in world, whatever the line's width is in.
+ */
+declare function strokeReachAt(stroke: Stroke, scale: number, least?: number): number;
+/**
+ * True when `bounds`, taken through `transform` to screen space, cannot put a
+ * pixel inside `rect` — the per-command test above, for a caller holding a box
+ * rather than a command. Same slack, same NaN-keeps rule.
+ */
+declare function boundsMissRect(bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, transform: GlMat3, rect: CullRect): boolean;
+
+/**
+ * On-screen glyph size (CSS px) at or above which a face with registered
+ * outlines is drawn as geometry instead of sampled from a distance field.
+ *
+ * 48 is the dynamic tier's own `BAKE_SIZE`, which makes it the size at which
+ * that tier stops being an interpolation and starts being a magnification:
+ * `glyphRasterizer.ts` measures coverage error bottoming out *at* the bake
+ * size and rising on both sides, and past a few times it the reconstructed
+ * field shows the raster as contour wobble. The same number is a safe
+ * crossing for the baked MSDF atlas, which is still crisp here — outlines are
+ * exact, so switching early costs nothing but the tessellation, and the
+ * hinting the atlas has and outlines don't stopped mattering well below this.
+ */
+declare const OUTLINE_MIN_SCREEN_PX = 48;
+
+/**
+ * Effects that ship with the kit.
+ *
+ * Each is a function returning `Effect[]`, not a single `Effect`, because a
+ * separable kernel is genuinely two passes and hiding that behind one entry
+ * would make the cost invisible at the callsite:
+ *
+ *   effects={[...blur({ radius: 4 }), ...vignette({ amount: 0.6 })]}
+ */
+
+/**
+ * Gaussian blur, as a horizontal pass followed by a vertical one.
+ *
+ * `radius` is in device pixels and is the distance of the outermost tap, not a
+ * standard deviation — 0 is a copy, and the falloff is the same nine-tap
+ * kernel at every radius, so a large one is a wide blur rather than a better
+ * one. Two passes at O(9) beat one at O(81) and look the same.
+ */
+declare function blur({ radius }: {
+    radius: number;
+}): Effect[];
+/**
+ * Darken toward the corners. `amount` is how dark the corner gets (0..1) and
+ * `feather` how much of the radius the falloff occupies.
+ */
+declare function vignette({ amount, feather }: {
+    amount: number;
+    feather?: number;
+}): Effect[];
+
+/**
+ * Kit-supplied vertex shader for a full-screen effect pass.
+ *
+ * Distinct from `CUSTOM_VERT_SRC` on purpose. That one places its quad through
+ * `u_bounds` and `u_proj`, so its `v_uv` runs top-down in *screen* space; an
+ * effect samples a texture the scene was just rendered into, whose v axis runs
+ * the other way. Passing `a_position` straight to `gl_Position` and `a_uv`
+ * straight out keeps the two aligned — `QUAD_VERTICES` already carries
+ * `a_uv == (a_position + 1) / 2` on both axes.
+ *
+ * PUBLIC CONTRACT — what every effect fragment shader may read:
+ *
+ *   in  vec2      v_uv           0..1 across the source texture
+ *   uniform sampler2D u_source   what has been drawn so far
+ *   uniform vec2  u_resolution   source size in device pixels
+ *   uniform vec2  u_texel        1.0 / u_resolution — one texel step
+ *
+ * PREMULTIPLIED ALPHA: `u_source` holds premultiplied RGBA, because that is
+ * what the scene blends into it. An effect that weights neighbouring samples
+ * (a blur) is doing the right thing on premultiplied values; one that
+ * manipulates rgb against a must premultiply its own output the same way the
+ * custom-shader prelude requires.
+ */
+declare const EFFECT_VERT_SRC = "#version 300 es\nin vec2 a_position;\nin vec2 a_uv;\nout vec2 v_uv;\n\nvoid main() {\n  v_uv = a_uv;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
+/** Uniforms the renderer sets on every effect pass. An effect must not
+ *  redeclare them with different meanings; it may leave any of them out. */
+declare const EFFECT_KIT_UNIFORMS: readonly ["u_source", "u_resolution", "u_texel"];
+
+/**
+ * A node's paint, resolved into what a draw command takes. One place composes
+ * the two resolutions so every painter and layer applies both.
+ */
+
+/**
+ * `fill` as a draw command's fill: `'bounds'` units mapped onto `box`, and a
+ * tile spec swapped for its texture. `null` when a spec cannot rasterize.
+ */
+declare function commandFill(fill: FillStyle, box: FillPoseBox): CommandFill | null;
+/**
+ * `stroke` as a draw command's stroke, its paint resolved as
+ * {@link commandFill} resolves a fill. `null` when the stroke carries no
+ * paint, or its paint cannot be resolved.
+ */
+declare function commandStroke(stroke: Stroke, box: FillPoseBox): CommandStroke | null;
+
+/**
+ * Tile-pattern primitive — a small helper for building repeating texture
+ * tiles from a draw callback. The result plugs into a `FillStyle` of
+ * `{ fill: 'pattern', pattern }` (see `@weasel-js/paint`).
+ *
+ * GL-backed: the tile is rendered to an `OffscreenCanvas` (with a 2D fallback
+ * to a regular `<canvas>` for environments without `OffscreenCanvas`),
+ * converted to an `ImageBitmap`, and registered with `registerTexture()`.
+ * The returned `TextureHandle` is what `FillStyle.pattern` accepts.
+ *
+ * For ready-to-use named patterns (hatch, crosshatch, dots, chunks),
+ * see the `@weasel-js/renderer/patterns-builtin` subpath.
+ */
+
+/** Options for `createTilePattern`. */
+interface TilePatternOpts {
+    /** Edge length (in pixels) of the square offscreen tile. */
+    size: number;
+    /** FillStyle one tile at integer-pixel coordinates `(0, 0) .. (size, size)`. */
+    draw: (oc: CanvasRenderingContext2D, size: number) => void;
+}
+/**
+ * Render a single tile to an offscreen canvas and register it as a GL
+ * texture, returning a `TextureHandle` you can wrap in a `FillStyle` of
+ * `{ fill: 'pattern', pattern }`. Returns `null` only when an
+ * `OffscreenCanvas`/2D context can't be acquired (very rare; same fallback
+ * semantics as the prior `CanvasPattern`-based implementation).
+ */
+declare function createTilePattern(opts: TilePatternOpts): TextureHandle | null;
+
+/**
+ * Build a `TextDrawCommand`. `textCommandFromPose` is the command for a text
+ * node — what `kit:text` and `createTextLayer` both emit. `textCommand` takes
+ * a plain string and wraps it in one run; `textCommandFromRuns` takes the
+ * styled runs directly, for text that has no pose. All three
+ * resolve through `resolveTextStyle` + `resolveRuns`, so every emitter of a
+ * text command derives `align` and per-run resolution the same way — a
+ * caller that assembles the command by hand is one field away from a
+ * silently different result.
+ *
+ * `paint` is the node's `data.fill` / `data.stroke`. A caller with no node —
+ * a HUD widget, a debug overlay — states its color on the run instead.
+ *
+ * `scale` is the view scale a `{ px }` `fontSize` or `letterSpacing` resolves
+ * against — for a world-space layer, the mean of `view.scale.x` and
+ * `view.scale.y`. It has to be applied here and not at draw time, because a
+ * screen-pixel size moves the glyph advances and so the wrap points.
+ */
+
+/** Build a draw command from styled runs, for text with no pose. `style`
+ *  supplies the defaults each run inherits; the rest match `textCommand`. */
+declare function textCommandFromRuns(x: number, y: number, runs: readonly StyledRun[], style?: TextStyle, maxWidth?: number, height?: number, verticalAlign?: TextVerticalAlign, paint?: TextPaint, width?: number, scale?: number): DrawCommand;
+/** Build a draw command for a single unstyled string. Text is laid out with
+ *  the registered font's metrics, wrapped at `maxWidth`, aligned across
+ *  `width` (default `maxWidth`) and within `height` when `verticalAlign` is
+ *  given. */
+declare function textCommand(x: number, y: number, text: string, style?: TextStyle, maxWidth?: number, height?: number, verticalAlign?: TextVerticalAlign, paint?: TextPaint, width?: number, scale?: number): DrawCommand;
+/**
+ * The draw command for a text pose. Its wrap width, alignment box and runs
+ * come from `textPoseLayoutInput`, so the renderer lays it out into exactly
+ * the lines `layoutTextPose` reports for the same pose.
+ *
+ * Each run's paints are resolved against the pose box the way every other
+ * node's are — a `'bounds'` paint mapped onto it, a pattern spec swapped for
+ * its texture — since the renderer can do neither.
+ */
+declare function textCommandFromPose(pose: TextPose, scale?: number): TextDrawCommand;
+
+export { type CullRect, type DrawCommand, EFFECT_KIT_UNIFORMS, EFFECT_VERT_SRC, type Effect, FillPoseBox, type GroupDrawCommand, IDENTITY_COLOR_MATRIX, type ImageDrawCommand, type ImageMinification, OUTLINE_MIN_SCREEN_PX, type PathDrawCommand, type RenderOptions, type RenderSpan, type RenderSpanStats, type RenderStats, type RenderTarget, SPRITE_STRIDE, type ShaderDrawCommand, ShaderProgram, ShaderProgramHandle, ShaderUniform, type SolidPaint, type SpriteSheet, type SpritesDrawCommand, type TextDrawCommand, type TilePatternOpts, WeaselRenderer, type WeaselRendererOptions, blur, boundsMissRect, buildGradientRamp, commandFill, commandStroke, createTilePattern, cullDrawCommands, frameRect, registerEffect, releaseImageSource, strokeReachAt, textCommand, textCommandFromPose, textCommandFromRuns, vignette };