@weasel-js/renderer 0.0.0-stage → 1.9.4

package/dist/mesh.d.ts

@@ -0,0 +1,274 @@
+import { GradientUnits, ColorSpace, FillStyle, GradStop } from '@weasel-js/paint';
+import { c as PaintDrawKind } from './paintKinds-B2vEy9A4.js';
+import '@weasel-js/registry';
+import '@weasel-js/geom';
+
+/**
+ * Coons and tensor-product patch surfaces — PDF's shading types 6 and 7, as
+ * pure geometry.
+ *
+ * A patch is a curved quadrilateral: four cubic Bézier edges and a color at
+ * each corner. The interior is what the edges imply — a Coons patch reads it
+ * off the boundary alone; a tensor patch adds four interior control points
+ * that pull it around. Both evaluate at a `(u, v)` in the unit square, which
+ * is what lets the renderer subdivide a patch into as many triangles as it
+ * wants without the patch knowing.
+ *
+ * Nothing here touches GL, a color string, or a scene. `evalPatch` is the
+ * whole contract.
+ */
+/** A point in the patch's own space. */
+interface MeshPoint {
+    x: number;
+    y: number;
+}
+/**
+ * One patch.
+ *
+ * `points` walks the boundary: corner 0, the two control points of the edge
+ * leaving it, corner 1, its two, and so on — twelve points, ending with the
+ * two controls that return to corner 0. A tensor patch appends its four
+ * interior points, in the order `(1,1)`, `(1,2)`, `(2,2)`, `(2,1)` of the
+ * bicubic control net, which is PDF's own order.
+ *
+ * Twelve points is a Coons patch and sixteen is a tensor patch; there is no
+ * flag, because the count already says which it is.
+ *
+ * `colors` are the corner colors in the same walk order, as whatever color
+ * form the caller resolves — the renderer hands premultiplied RGBA in, the
+ * serializer hands CSS strings.
+ */
+interface MeshPatch<TColor = string> {
+    points: readonly MeshPoint[];
+    colors: readonly [TColor, TColor, TColor, TColor];
+}
+/** Corner `i` of the boundary walk. */
+declare function patchCorner(patch: MeshPatch<unknown>, i: number): MeshPoint;
+/** `true` when the patch carries the four interior points a tensor patch adds. */
+declare function isTensorPatch(patch: MeshPatch<unknown>): boolean;
+/** A patch is twelve boundary points, or sixteen with the interior. Anything
+ *  else cannot be evaluated, and saying so here beats painting nonsense. */
+declare function isValidPatch(patch: MeshPatch<unknown>): boolean;
+/**
+ * The patch surface at `(u, v)`, both in `0..1`.
+ *
+ * `u` runs along the edge leaving corner 0 and `v` along the edge leaving
+ * corner 1, so `(0,0)` is corner 0, `(1,0)` corner 1, `(1,1)` corner 2 and
+ * `(0,1)` corner 3 — the same walk `colors` is in.
+ */
+declare function evalPatch(patch: MeshPatch<unknown>, u: number, v: number): MeshPoint;
+/**
+ * The four corner weights at `(u, v)` — bilinear, in the corner walk order.
+ *
+ * Color is separate from position on purpose: it interpolates in whatever
+ * space the caller chose, which is not a thing the surface can do for it.
+ */
+declare function cornerWeights(u: number, v: number): [number, number, number, number];
+/** Axis-aligned bounds of a patch, sampled on a grid. Control points alone
+ *  bound a Bézier but not tightly, and a mesh paint is baked into a texture
+ *  sized from this — a loose box wastes texels on every side. */
+declare function patchBounds(patch: MeshPatch<unknown>, steps?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * The `mesh-gradient` paint kind — PDF's shading types 6 and 7 as a registered
+ * paint.
+ *
+ * A mesh gradient is a set of curved quadrilateral patches, each with a color
+ * at every corner. It is the paint SVG tried to standardize as
+ * `<meshgradient>` and abandoned, and the one PDF has had since 1993; what it
+ * buys over the three gradients is a color field that bends, so a highlight
+ * can follow a form instead of running straight across it.
+ *
+ * This is a registered kind rather than a sixth branch in the renderer, and
+ * deliberately: it uses only the slots `registerPaintKind` gives a consumer, so
+ * whatever it can do, a consumer's own kind can do too. Its one concession is
+ * living in this package, because that is where the shader registry is.
+ *
+ * `docs/proposals/2026-09-17-paint-kinds-beyond-svg.md` is the design.
+ */
+
+/**
+ * A mesh gradient paint.
+ *
+ * `patches` are in the space `units` names, the same way a gradient's
+ * geometry is — under `'bounds'` every point is a fraction of the painted
+ * node's box, which is what lets the paint survive a resize.
+ *
+ * `interpolate` is the space corner colors blend through, matching the three
+ * gradients. It is more visible here than there: a mesh blends in two
+ * directions at once, so an sRGB blend's muddy middle covers area rather than
+ * a line.
+ */
+interface MeshGradientFill {
+    fill: 'mesh-gradient';
+    patches: MeshPatch[];
+    units?: GradientUnits;
+    interpolate?: ColorSpace;
+    opacity?: number;
+}
+/** The kind's id, as `FillStyle['fill']` carries it. */
+declare const MESH_GRADIENT_KIND = "mesh-gradient";
+/** A mesh paint, narrowed. */
+declare function isMeshGradientFill(fill: FillStyle | null | undefined): fill is FillStyle & MeshGradientFill;
+/** A one-patch square covering the unit box, its four corners four readings of
+ *  `color` — a mesh seeded from a solid has to show *something* curved, or
+ *  switching kind looks like nothing happened. */
+declare function seedMeshPatch(color: string): MeshGradientFill;
+/**
+ * A stop list as a mesh: one full-height band per gap between neighboring
+ * stops, colored left to right. The bands blend exactly the way the ramp
+ * does, so a horizontal gradient survives the switch unchanged. A zero-width
+ * gap is a hard break and gets no band.
+ */
+declare function meshFromStops(stops: readonly GradStop[]): MeshGradientFill;
+/**
+ * A mesh read as a stop list: every patch's top edge — corner 0 to corner 1 —
+ * placed by its `x` across the mesh's horizontal extent. The inverse of
+ * `meshFromStops`, and for any other mesh the ramp across its top.
+ */
+declare function meshStops(mesh: MeshGradientFill): GradStop[];
+/** The kind's draw half, shader program included. Core adds the editor's
+ *  slots and registers the whole entry. */
+declare const meshDrawKind: PaintDrawKind;
+/**
+ * The `<defs>` entry for a mesh paint, in weasel's own namespace.
+ *
+ * Not SVG's abandoned `<meshgradient>`: that vocabulary only reaches Coons
+ * patches, shares patch edges implicitly — a reader that gets the sharing
+ * wrong tears the surface rather than failing outright — and has exactly one
+ * implementation in the world. Ours writes every patch's points in full.
+ * `@weasel-js/svg` puts the paint fallback color beside the reference, so a
+ * foreign renderer paints flat instead of nothing.
+ */
+declare function meshGradientXml(id: string, mesh: MeshGradientFill): string;
+
+/**
+ * A mesh paint baked into one RGBA bitmap.
+ *
+ * A patch is a surface over `(u, v)`, but a paint has to answer "what color is
+ * this fragment", which is the inverse question — and inverting a bicubic is
+ * Newton iteration per fragment. Every renderer that draws these instead
+ * subdivides the patch into small quads and rasterizes them forward, which is
+ * what this does, once per paint, into a texture the shader then samples. The
+ * cost is a texture and a resolution; the gain is that the paint composes with
+ * every fill the renderer already knows how to draw, clipping included.
+ *
+ * The bitmap is straight (non-premultiplied) RGBA, matching the ramp atlas;
+ * the fragment shader premultiplies.
+ */
+
+/** Texels on a side of a bake when the caller names no size. The renderer
+ *  sizes each bake from how large the paint draws — see `meshBakeSize`. */
+declare const MESH_BAKE_SIZE = 256;
+/** The box a bake covers, in the paint's own space. */
+interface MeshBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The bitmap `bakeMesh` produces, and the paint-space box it covers. */
+interface BakedMesh {
+    /** `size` × `size` texels, straight RGBA. */
+    pixels: Uint8ClampedArray;
+    /** Texels on a side; `MESH_BAKE_SIZE` unless the caller asked otherwise. */
+    size: number;
+    /** Where the bitmap sits in paint space, which is what the shader maps a
+     *  fragment through. */
+    box: MeshBox;
+}
+/** The union of every patch's bounds, or `null` when nothing is drawable. */
+declare function meshBounds(patches: readonly MeshPatch[]): MeshBox | null;
+/**
+ * Rasterize `patches` into a square bitmap covering their union.
+ *
+ * Returns `null` when no patch is drawable, which is the caller's cue to paint
+ * nothing rather than a blank square.
+ */
+declare function bakeMesh(patches: readonly MeshPatch[], space?: ColorSpace, size?: number): BakedMesh | null;
+
+/**
+ * How large a mesh bake is, and the bounded cache the bakes live in.
+ *
+ * A gradient's ramp is one-dimensional, so 256 texels cover it at any size. A
+ * mesh's bake is two-dimensional and is stretched over whatever the paint
+ * covers, so a fixed size shows its texels once the paint draws large. The
+ * bake is sized from the device pixels it covers instead, in power-of-two
+ * buckets so a zoom inside one bucket reuses the bake it already has.
+ */
+/** The smallest bake: below this a texture costs more in bookkeeping than in
+ *  bytes. */
+declare const MESH_BAKE_MIN = 32;
+/** The largest bake, whatever the context allows: 16 MiB of RGBA, and a bake
+ *  that already takes a noticeable moment on the CPU. */
+declare const MESH_BAKE_MAX = 2048;
+/**
+ * The bake side for a paint drawn `devicePx` device pixels across, on a
+ * context accepting `maxTextureSize`: the next power of two at or above it,
+ * clamped to `[MESH_BAKE_MIN, MESH_BAKE_MAX]` and to the context. A size that
+ * cannot be measured gets `MESH_BAKE_SIZE`.
+ */
+declare function meshBakeSize(devicePx: number, maxTextureSize: number): number;
+
+/**
+ * The draggable points of a mesh paint, as pure geometry — what an on-canvas
+ * editor lists, and what moving one of them does to the paint.
+ *
+ * Nothing here knows a frame: the handles are in whatever space the mesh's
+ * points are, so a caller resolves a `'bounds'` mesh onto its box first
+ * (`fillInPoseFrame`) and normalizes the result back (`fillToBoundsFrame`).
+ */
+
+/** What a handle moves: a patch corner, one of the two controls of an edge,
+ *  or one of a tensor patch's four interior points. */
+type MeshHandleKind = 'corner' | 'control' | 'interior';
+/** One stored point: `patches[patch].points[index]`. */
+interface MeshPointRef {
+    patch: number;
+    index: number;
+}
+/**
+ * One draggable point.
+ *
+ * Patches store their points in full rather than sharing edges, so two
+ * patches that meet each carry a copy of the corner and controls they meet
+ * at. Those copies are one handle, with a `ref` per copy — dragging one of
+ * them alone would tear the surface open along the seam.
+ */
+interface MeshHandle {
+    /** Stable while the handle moves: its first ref, as `"patch:index"`. */
+    id: string;
+    kind: MeshHandleKind;
+    at: MeshPoint;
+    refs: readonly MeshPointRef[];
+}
+/**
+ * Every draggable point of `mesh`, in walk order: each patch's corners and
+ * edge controls, then a tensor patch's interior. Coincident points of one
+ * kind merge into one handle. A patch that cannot be evaluated has none.
+ */
+declare function meshHandles(mesh: MeshGradientFill): MeshHandle[];
+/**
+ * `mesh` with `handle` moved to `to`. A corner carries its edge controls
+ * and interior neighbor along by the same offset, the way a path editor's
+ * anchor carries its handles; a control or interior point moves alone.
+ * Returns a new paint; `mesh` is not modified.
+ */
+declare function moveMeshHandle(mesh: MeshGradientFill, handle: MeshHandle, to: MeshPoint): MeshGradientFill;
+/** The lines an editor draws under the handles, as control polygons. */
+interface MeshGuides {
+    /** Every patch edge as its four cubic control points, from the corner it
+     *  leaves to the corner it reaches. */
+    edges: [MeshPoint, MeshPoint, MeshPoint, MeshPoint][];
+    /** Corner to each point it carries — an edge control or interior point. */
+    arms: [MeshPoint, MeshPoint][];
+}
+/** The guides for `mesh`'s valid patches. Shared edges appear once per patch. */
+declare function meshGuides(mesh: MeshGradientFill): MeshGuides;
+
+export { type BakedMesh, MESH_BAKE_MAX, MESH_BAKE_MIN, MESH_BAKE_SIZE, MESH_GRADIENT_KIND, type MeshBox, type MeshGradientFill, type MeshGuides, type MeshHandle, type MeshHandleKind, type MeshPatch, type MeshPoint, type MeshPointRef, bakeMesh, cornerWeights, evalPatch, isMeshGradientFill, isTensorPatch, isValidPatch, meshBakeSize, meshBounds, meshDrawKind, meshFromStops, meshGradientXml, meshGuides, meshHandles, meshStops, moveMeshHandle, patchBounds, patchCorner, seedMeshPatch };