@weasel-js/renderer 1.9.4 → 1.10.0

package/dist/{imageCache-oJVgxhkr.d.ts → imageCache-DYcWftY8.d.ts}

@@ -1,19 +1,13 @@
-import { TextureHandle, TilePatternSpec, PosedFill, CommandFill, FillStyle } from '@weasel-js/paint';
+import { TextureHandle, PosedPaint, CommandPaint, Paint, TilePatternSpec } from '@weasel-js/paint';
 import { Reflection } from '@weasel-js/registry';
 import { Mesh } from '@weasel-js/geom/tessellate';
 import { GlMat3 } from '@weasel-js/geom';
-import { b as ShaderProgram } from './paintKinds-B2vEy9A4.js';
+import { b as ShaderProgram } from './paintKinds-BmPAT51k.js';
 
 /**
- * registerTexture — accepts an image source, assigns an opaque id, stores in
- * a module-level registry. Actual GL upload happens lazily at draw time in
- * drawShader() via GLTextureCache.upload (which is idempotent).
- *
- * Lifecycle: a texture lives until `unregisterTexture`. Each renderer frees
- * its own GL copy at the top of its next frame.
- *
- * Convention §9: this registry stores image data only — no per-renderer state.
- * Each WeaselRenderer's GLTextureCache does its own dedup by id and source.
+ * A module-level registry of image sources by opaque id. It stores image data
+ * only — no per-renderer state; each renderer uploads to GL lazily at draw
+ * time. A texture lives until `unregisterTexture`.
  */
 
 /** A registered texture's image source, uploaded to GL lazily at first draw. */
@@ -25,13 +19,14 @@ declare const textureRegistry: Reflection<TextureEntry>;
 /** @internal Test helper — do not call from product code. */
 declare function _resetTextureRegistryForTests(): void;
 /**
- * Register an image for use as a shader texture uniform.
+ * Register an image for use as a shader texture uniform. Returns a
+ * TextureHandle whose `id` can be passed as a ShaderUniform value.
  *
- * Returns a TextureHandle whose `id` can be passed as a ShaderUniform value.
- * The handle is valid for the lifetime of the renderer it will be used with.
+ * The texture holds premultiplied texels whichever source it came from, so a
+ * shader sampling one reads `vec4(rgb * a, a)`, the form its own output takes.
  *
- * @param image  The image to register. HTMLImageElement must be fully loaded.
- * @returns      Opaque TextureHandle.
+ * @param image  HTMLImageElement must be fully loaded. An ImageBitmap must
+ *               hold premultiplied pixels, the `createImageBitmap` default.
  */
 declare function registerTexture(image: HTMLImageElement | ImageBitmap): TextureHandle;
 /**
@@ -48,8 +43,7 @@ declare function unregisterTexture(handle: TextureHandle): boolean;
  * needs no stencil and does not break the run.
  *
  * A stencil clip is GL state, so content inside one cannot share a draw with
- * content outside it, and every clipped group paid a flush on the way in and
- * another on the way out. A rect under a transform that keeps it axis-aligned
+ * content outside it. A rect under a transform that keeps it axis-aligned
  * is the common clip, and for that one the clip can ride the geometry instead:
  * cut each staged polygon to the rect before it joins the run.
  *
@@ -70,47 +64,32 @@ interface ClipRect {
 
 /**
  * Growable vertex staging for a run of solid-fill geometry, image quads and
- * glyphs.
- *
- * Geometry only: `draw.ts` owns when a run starts, what breaks it, and the
- * uniforms the flush draws under.
+ * glyphs. Geometry only: the caller owns when a run starts, what breaks it, and
+ * the uniforms the flush draws under.
  *
- * **One batch for all three, because a page interleaves them.** A grid of
- * thumbnails is a ground rect under an atlas quad under a caption, per cell,
- * and while each kind staged separately every one had to drain the others
- * before it could stage — so a shape that batches perfectly in any one half
- * alone paid a flush per command. Everything a vertex needs to say which it is
- * fits in the same vertex: solids carry the UV of a 1x1 white texel and are
- * their own color, quads carry their atlas UV and a white color, glyphs carry
- * a font atlas UV, their text color, and a paint mode saying the texel is a
- * distance field rather than a color. Gradients join as a fourth off the ramp
- * atlas — a linear one without a mode of its own, since (ramp position, row) is
- * what the plain mode already samples, and a radial or conic one with a mode
- * that says its UV is a gradient-space coordinate to take a `length` or an
- * `atan` of. See `shaders/batchFill.ts`.
+ * One batch for all of them, because a page interleaves them. Everything a
+ * vertex needs to say which it is fits in the same vertex: solids carry the UV
+ * of a 1x1 white texel and are their own color, quads carry their atlas UV and
+ * a white color, glyphs carry a font atlas UV, their text color, and a paint
+ * mode saying the texel is a distance field rather than a color. Gradients
+ * sample the ramp atlas. See `shaders/batchFill.ts`.
  *
- * Colors ride the vertices because shapes in a run differ in color and a merged
- * draw has one set of uniforms — and so does the model transform, applied here
- * rather than uploaded, so shapes under different transforms still share a
- * draw. The texture rides them too, as a slot index into the units the flush
- * binds: slot 0 is the white texel every solid samples, and `draw.ts` hands out
- * the rest per bitmap. A run holds as many bitmaps as there are slots, so an
- * atlas is what makes a wall of one sheet coalesce and a handful of loose
- * bitmaps no longer breaks a run per command.
+ * The model transform is applied here rather than uploaded, so shapes under
+ * different transforms still share a draw. The texture rides the vertices as a
+ * slot index into the units the flush binds: slot 0 is the white texel every
+ * solid samples.
  */
 
 /** vec2 a_position + vec4 a_vertexColor + vec2 a_uv + float a_post + float
- *  a_texSlot. Exported so the buffer-replay tests read fields by name rather
- *  than by a stride they repeat — a hard-coded one silently reads a different
- *  field when the vertex grows, instead of failing. */
+ *  a_texSlot. */
 declare const FLOATS_PER_VERTEX = 10;
 /**
  * A gradient vertex's `a_uv`, each channel affine in the coordinates the
  * geometry arrives in: `u = ux*x + uy*y + u0`, and the same for `v`.
  *
- * One shape for all three gradients. A linear one's `v` row is the constant
- * atlas row and its `u` row is the ramp position; a radial or conic one's two
- * rows are the gradient-space coordinate, and the row rides `a_post` instead.
+ * A linear gradient's `v` row is the constant atlas row and its `u` row is the
+ * ramp position; a radial or conic one's two rows are the gradient-space
+ * coordinate, and the atlas row rides `a_post` instead.
  */
 interface GradientUV {
     ux: number;
@@ -141,8 +120,7 @@ declare class DrawBatch {
     /** Whether the staged run is quads alone, so its indices are the canonical
      *  pattern and a slot already holding that pattern needs no upload. */
     private pureRects;
-    /** The rect every push is cut to, or `null`. `draw.ts` sets it as rect
-     *  clips enter and leave — see `batchClip.ts`. A push returns `false`, having
+    /** The rect every push is cut to, or `null`. A push returns `false`, having
      *  staged nothing, for geometry it cannot cut exactly; see `clipQuad`. */
     clip: ClipRect | null;
     /** Polygon scratch for `clip`: a quad cut by four edges has at most eight
@@ -156,44 +134,31 @@ declare class DrawBatch {
     wouldOverflow(vertices: number): boolean;
     /**
      * Append one rect's four corners through `m`, all carrying `rgba` (straight
-     * alpha). An affine maps a rect to a parallelogram, so two triangles still
-     * cover it and the batch draws at `u_model` identity.
+     * alpha).
      */
     pushRect(x: number, y: number, w: number, h: number, m: GlMat3, r: number, g: number, b: number, a: number): boolean;
     /**
      * Append one image quad: the destination rect `(x, y, w, h)` mapped through
      * `m`, sampling `(u0, v0)`-`(u1, v1)`, every corner carrying `post` as the
-     * after-the-color-matrix alpha factor.
+     * after-the-color-matrix alpha factor and `rgb` as the scale on its texel.
+     * `slot` is the texture unit the corners sample.
      *
-     * Corners wind top-left, top-right, bottom-right, bottom-left with UVs
-     * following — the same winding `pushRect` uses, which is what lets a run of
-     * mixed rects and quads keep the canonical index pattern. The flips a command
-     * asks for are already in the `u` / `v` the caller passes.
-     *
-     * `slot` is the texture unit the corners sample, which `draw.ts` assigns per
-     * bitmap within the run.
+     * Corners wind top-left, top-right, bottom-right, bottom-left — the same
+     * winding `pushRect` uses, which is what lets a run of mixed rects and quads
+     * keep the canonical index pattern.
      */
-    pushQuad(x: number, y: number, w: number, h: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, post: number, slot: number): boolean;
+    pushQuad(x: number, y: number, w: number, h: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, post: number, slot: number, r?: number, g?: number, b?: number): boolean;
     /**
      * Append one glyph quad: the box `(x0, y0)`-`(x1, y1)` mapped through `m`,
      * sampling `(u0, v0)`-`(u1, v1)` of the font atlas at `slot`, painted in
      * `rgba`.
      *
      * `mode` says which channels of that atlas carry the distance field, and
-     * rides the vertices packed into the slot — so a run off a baked MSDF atlas
-     * and one off the runtime canvas bake still share a draw. The synthetic-bold
-     * threshold does not: it is `u_synthBold`, and `draw.ts` breaks the run when
-     * it changes.
-     *
-     * **A synthetic oblique is sheared here rather than in the shader.** The old
-     * text program carried the baseline per vertex and skewed against
-     * `u_synthItalic`; the batch places its own corners, so the shear is one
-     * multiply while they are being placed, and `tanItalic` is 0 for an upright
-     * face. It has to happen before `m`, which is where the shader had it too.
+     * rides the vertices packed into the slot. The synthetic-bold threshold does
+     * not: it is `u_synthBold`, and the caller breaks the run when it changes.
      *
-     * Corners wind top-left, top-right, bottom-right, bottom-left — `pushQuad`'s
-     * winding, which is what lets a run of mixed rects, image quads and glyphs
-     * keep the canonical index pattern.
+     * A synthetic oblique is sheared here, before `m`; `tanItalic` is 0 for an
+     * upright face. Corners wind as `pushQuad`'s do.
      */
     pushGlyph(x0: number, y0: number, x1: number, y1: number, baselineY: number, tanItalic: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, r: number, g: number, b: number, a: number, slot: number, mode: number): boolean;
     /**
@@ -201,16 +166,10 @@ declare class DrawBatch {
      * through `m`, sampling the ramp atlas at `slot`.
      *
      * `uv` gives each channel of `a_uv` as an affine function of the coordinates
-     * the corners arrive in, which is what lets a gradient ride the vertices at
-     * all: a linear one's ramp position is affine in position outright, and a
-     * radial or conic one's gradient-space *coordinate* is, even though the ramp
-     * position it yields is not. Either way the rasterizer's interpolation across
-     * a triangle is exact. `mode` says which of the two the fragment shader is
-     * looking at, and `post` carries the atlas row for the modes that read it —
-     * see `shaders/batchFill.ts`.
-     *
-     * Values outside 0..1 are the sampler's business; the atlas clamps to the
-     * edge texel, which is what the gradient shader's own `clamp` did.
+     * the corners arrive in. `mode` says whether that is a ramp position or a
+     * gradient-space coordinate, and `post` carries the atlas row for the modes
+     * that read it — see `shaders/batchFill.ts`. Values outside 0..1 clamp to
+     * the atlas's edge texel.
      */
     pushGradientRect(x: number, y: number, w: number, h: number, m: GlMat3, uv: GradientUV, post: number, slot: number, mode: number, r: number, g: number, b: number, a: number): boolean;
     /** `pushMesh` for a mesh filled by a gradient — see `pushGradientRect` for
@@ -235,9 +194,7 @@ declare class DrawBatch {
      * subpixel grid the rasterizer snaps to, and the shortened edge then covers
      * different samples than the whole one did; along an axis the cut edge is
      * the same line exactly. So a slanted quad that crosses is rolled back and
-     * refused, for `draw.ts` to clip through the stencil instead.
-     *
-     * A cut axis-aligned quad is still four corners, so the run stays pure.
+     * refused, for the caller to clip through the stencil instead.
      */
     private clipQuad;
     /** `clipQuad` for a mesh staged from `v0`. A mesh's edges are slanted in
@@ -256,8 +213,8 @@ declare class DrawBatch {
 }
 
 /**
- * `TilePatternSpec` → `TextureHandle`. The bridge between the serializable
- * half of a pattern paint and the GL texture that paints it.
+ * `TilePatternSpec` → `TextureHandle`. The bridge between a tile paint and the
+ * GL texture that paints it.
  *
  * Memoized on the spec's field values, so identical specs across nodes share
  * one texture and a re-render never re-rasterizes. The memo keeps the
@@ -273,34 +230,27 @@ declare function _resetPatternSpecCacheForTests(): void;
  * can't be rasterized — no `OffscreenCanvas`, same as `createTilePattern`.
  */
 declare function resolvePatternSpec(spec: TilePatternSpec): TextureHandle | null;
-/** Whether a pattern payload is a spec rather than an already-built handle. */
-declare function isPatternSpec(payload: TextureHandle | TilePatternSpec): payload is TilePatternSpec;
 /**
- * Swap a pattern paint's spec payload for the texture that paints it,
+ * Swap a tile paint for the `texture` paint that draws it, placement kept,
  * leaving every other fill untouched. The built-in painters run this
  * alongside `fillInPoseFrame`; a consumer emitting its own draw commands
  * runs it at the same place it runs that one.
  *
- * A spec that can't rasterize drops the fill rather than painting garbage.
+ * A tile that can't rasterize drops the fill rather than painting garbage.
  */
-declare function resolveFillPattern(fill: PosedFill): CommandFill | null;
-declare function resolveFillPattern(fill: FillStyle): FillStyle | null;
+declare function resolveFillPattern(fill: PosedPaint): CommandPaint | null;
+declare function resolveFillPattern(fill: Paint): Paint | null;
 
 /**
- * imageCache — the kit's per-`src` image loader + cache.
- *
- * The shape-painter chain (`kit:image` in `NodeShape.ts`) is synchronous, but
- * decoding an image is async. This module bridges the two: `getImageBitmap` is
- * a synchronous read that returns the decoded `ImageBitmap` when ready, and
- * otherwise returns `undefined` and lazily kicks off a de-duped async load.
- * When a load resolves (or errors), every `subscribeImageReady` listener fires
- * — `<SceneCanvas>` subscribes and calls `requestRedraw()`, so the painter
- * re-runs and emits the now-ready bitmap.
+ * The kit's per-`src` image loader + cache. Shape painters are synchronous
+ * and decoding an image is async, so `getImageBitmap` is a synchronous read
+ * that returns the decoded `ImageBitmap` when ready, and otherwise returns
+ * `undefined` and lazily kicks off a de-duped async load. When a load
+ * resolves (or errors), every `subscribeImageReady` listener fires.
  *
  * `src` is any browser-loadable image string: a remote URL, a `blob:` URL, or
- * a `data:image/…;base64,…` URI (the embedded-bytes path). The decoded bitmap
- * lives only here, keyed by `src` — never in node `data` — so `scene.toJSON()`
- * round-trips the (serializable) `src` string untouched.
+ * a `data:image/…;base64,…` URI. The decoded bitmap lives only here, keyed by
+ * `src` — never in node `data`.
  */
 /** Public shape of an image node's `data`. `src` round-trips through
  *  serialization; the decoded bitmap is held in this cache, not on the node. */
@@ -338,6 +288,13 @@ type Loader = (src: string, size?: ImageRasterSize) => Promise<ImageBitmap>;
  *  at; everything else decodes once. A `blob:` URL carries no type and counts
  *  as raster. */
 declare function isVectorImageSrc(src: string): boolean;
+/**
+ * Set how many bytes of decoded RGBA the cache may hold, and return the
+ * previous value. Default 256MB; `Infinity` never drops anything. Takes
+ * effect when the next image lands. A dropped image loads again on its next
+ * {@link getImageBitmap}, as one never requested does.
+ */
+declare function setImageCacheBudget(bytes: number): number;
 /** Synchronous read. Returns the decoded bitmap when ready; otherwise returns
  *  `undefined` and lazily starts a de-duped async load for `src`.
  *
@@ -369,4 +326,4 @@ declare function __setImageLoaderForTests(fn: Loader): void;
  *  loader. Not part of the public barrel. */
 declare function _resetImageCacheForTests(): void;
 
-export { DrawBatch as D, FLOATS_PER_VERTEX as F, type ImageNodeData as I, type TextureEntry as T, __setImageLoaderForTests as _, type ImageRasterSize as a, type ImageStatus as b, isPatternSpec as c, isVectorImageSrc as d, releaseImage as e, resolveFillPattern as f, getImageBitmap as g, resolvePatternSpec as h, imageStatus as i, retryImage as j, _resetImageCacheForTests as k, _resetPatternSpecCacheForTests as l, _resetTextureRegistryForTests as m, registerTexture as r, subscribeImageReady as s, textureRegistry as t, unregisterTexture as u };
+export { DrawBatch as D, FLOATS_PER_VERTEX as F, type ImageNodeData as I, type TextureEntry as T, __setImageLoaderForTests as _, type ImageRasterSize as a, type ImageStatus as b, isVectorImageSrc as c, releaseImage as d, resolveFillPattern as e, resolvePatternSpec as f, getImageBitmap as g, retryImage as h, imageStatus as i, subscribeImageReady as j, _resetImageCacheForTests as k, _resetPatternSpecCacheForTests as l, _resetTextureRegistryForTests as m, registerTexture as r, setImageCacheBudget as s, textureRegistry as t, unregisterTexture as u };