@weasel-js/labkit 1.4.0-pre.1 → 1.4.1

package/dist/_dts/DrawCommand-B3bskUsC.d.ts

@@ -1,564 +0,0 @@
-import { P as Path } from './types-C-gh9Ap-.js';
-
-/**
- * Viewport state. `(view.x, view.y)` is the **world point currently
- * rendered at the canvas top-left**; `view.scale.x` / `view.scale.y` is
- * pixels per world unit on each axis (default `{ x: 1, y: 1 }`). So:
- *
- *   screenX = (worldX - view.x) * view.scale.x
- *   screenY = (worldY - view.y) * view.scale.y
- *   worldX  = screenX / view.scale.x + view.x
- *   worldY  = screenY / view.scale.y + view.y
- *
- * `scale` is always a 2-vector. Input convenience types
- * {@link ZoomFactor} and {@link ZoomBound} let callers pass a scalar
- * when they want both axes treated the same.
- */
-interface View {
-    x: number;
-    y: number;
-    scale: {
-        x: number;
-        y: number;
-    };
-}
-
-/**
- * A registered texture, named by the registry that holds it.
- *
- * The handle is here rather than beside the registry because `FillStyle`'s
- * pattern variant names it, and paint is a leaf: the registry lives in the
- * renderer and imports this back.
- */
-interface TextureHandle {
-    readonly id: string;
-}
-
-/**
- * FillStyle and Stroke types — the unified shape for "what color or texture
- * paints these pixels," modeled on SVG's paint-server concept.
- *
- * - `FillStyle` is a tagged union: solid color, pattern, or gradient. Used
- *   wherever a kit option previously took `fillStyle: string`.
- * - `Stroke` pairs a `FillStyle` with structural stroke parameters (width, dash,
- *   line cap/join, alignment).
- * - These types are consumed by the GL renderer's DrawCommand path fills
- *   and strokes.
- *
- * The 2D `applyPaint` / `applyStroke` / `renderFilledRegion` helpers that
- * formerly lived alongside these types were deleted with the 2D backend in
- * Step 10. `alignedStrokeRect` survives as a pure geometry helper used by
- * path tessellation and the selection overlay.
- */
-
-/**
- * Color/texture strategy for fills (and, via `Stroke.paint`, strokes).
- *
- * `fill` is optional and defaults to `'solid'` — `{ color: '#abc' }` is
- * equivalent to `{ fill: 'solid', color: '#abc' }`. Pattern paints must set
- * `fill: 'pattern'` explicitly.
- *
- * The `'pattern'` variant's payload is either a `TilePatternSpec` — plain
- * data naming one of the built-in tiles, which survives serialization — or a
- * `TextureHandle` for a tile the consumer built itself via
- * `createTilePattern()`. A handle is a session-scoped registry key, so a
- * paint carrying one cannot be persisted or exported; prefer the spec.
- *
- * `units` on a pattern names the space the tile's origin and scale live in,
- * not the space of any geometry (a pattern has none). Under `'bounds'` the
- * tile anchors to the painted node's box, so the pattern travels with the
- * node and a resize reveals more tiles rather than stretching them;
- * `fillInPoseFrame` resolves that to a `'local'` paint with an explicit
- * `origin` before the renderer sees it.
- */
-type FillStyle = {
-    fill?: 'solid';
-    color: string;
-    opacity?: number;
-} | {
-    fill: 'pattern';
-    pattern: TextureHandle | TilePatternSpec;
-    units?: GradientUnits;
-    origin?: {
-        x: number;
-        y: number;
-    };
-    opacity?: number;
-} | {
-    fill: 'linear-gradient';
-    from: {
-        x: number;
-        y: number;
-    };
-    to: {
-        x: number;
-        y: number;
-    };
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-} | {
-    fill: 'radial-gradient';
-    center: {
-        x: number;
-        y: number;
-    };
-    radius: number;
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-} | {
-    fill: 'conic-gradient';
-    center: {
-        x: number;
-        y: number;
-    };
-    angle: number;
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-};
-/**
- * Which coordinate space a gradient's geometry (`from`/`to`, `center`,
- * `radius`) is expressed in. SVG's `gradientUnits`, plus an option for
- * paints that are themselves viewport furniture.
- *
- * - `'bounds'`: fractions of the painted node's bounding box, `0..1` on each
- *   axis — SVG `objectBoundingBox`. Resolved by the node painter, before the
- *   renderer sees it, so the paint follows the node through moves, resizes
- *   and rotation. What a gradient on a scene node wants.
- * - `'local'`: the coordinate space the geometry was handed to the renderer
- *   in — the enclosing group's frame. For draw commands a consumer builds
- *   itself, where "the coordinates I just wrote" is the useful frame.
- * - `'world'`: scene coordinates. The paint stays put under pan and zoom
- *   while the geometry moves through it. SVG `userSpaceOnUse`. Requires the
- *   renderer to have been handed a view matrix; falls back to `'screen'`
- *   when it has not.
- * - `'screen'`: CSS pixels of the drawing surface. For overlays and
- *   viewport-fixed washes that should not move with the content at all.
- *
- * Defaults to `'screen'`, which is the behavior every gradient had before
- * this field existed.
- */
-type GradientUnits = 'bounds' | 'local' | 'world' | 'screen';
-/**
- * A built-in tile, described as plain data. The serializable half of the
- * pattern paint: `resolvePatternSpec()` turns one into a `TextureHandle`
- * at paint time, memoized so identical specs share a texture.
- *
- * `size` is the tile's edge length, and doubles as its extent in paint
- * space — a bigger `size` rasterizes a bigger tile rather than magnifying
- * a small one, which is why there is no separate scale field.
- */
-interface TilePatternSpec {
-    tile: 'hatch' | 'crosshatch' | 'dots' | 'chunks';
-    color: string;
-    /** `chunks` only — omit for a transparent tile background. */
-    bg?: string;
-    size?: number;
-    /** `hatch` / `crosshatch`. */
-    lineWidth?: number;
-    /** `dots`. */
-    radius?: number;
-    /** `chunks`. */
-    density?: number;
-    chunkSize?: number;
-    seed?: number;
-}
-/** A single color stop within a gradient. `offset` is in 0..1. */
-interface GradStop {
-    offset: number;
-    color: string;
-}
-/**
- * Where a stroke sits relative to the geometric edge it strokes.
- *
- * - `'center'` (default): canvas-native — half the stroke width sits inside
- *   the geometry, half outside.
- * - `'inner'`: the entire stroke lies inside the geometry. The outer edge of
- *   the stroke coincides with the geometric edge.
- * - `'outer'`: the entire stroke lies outside the geometry. The inner edge
- *   of the stroke coincides with the geometric edge.
- *
- * Mirrors the (proposed) SVG `stroke-alignment` property. Honoring `inner`
- * or `outer` is the renderer's responsibility — for axis-aligned rects, the
- * kit shifts coordinates by `width / 2`. For arbitrary paths, renderers
- * typically use a stencil mask of the stroked path against the geometry.
- */
-type StrokeAlign = 'center' | 'inner' | 'outer';
-/**
- * The kit's built-in marker vocabulary, open on the string the way
- * `PaintKind` is so a consumer's registered key typechecks.
- */
-type KitMarkerKey = 'arrow' | 'arrow-open' | 'arrow-concave' | 'diamond' | 'diamond-hollow' | 'circle' | 'square' | 'bar';
-type MarkerKey = KitMarkerKey | (string & {});
-/**
- * A marker on one end (or every interior vertex) of a stroke.
- *
- * `size` reuses `Stroke.width`'s unit system: a bare number scales with the
- * resolved stroke width, `{ px }` pins screen pixels. That is SVG's
- * `markerUnits` in the idiom this codebase already resolves at draw time.
- * Omitted, the marker is one stroke width per unit.
- */
-type MarkerRef = MarkerKey | {
-    key: MarkerKey;
-    size?: number | {
-        px: number;
-    };
-};
-/** Stroke style: a FillStyle plus structural line parameters. */
-interface Stroke {
-    paint: FillStyle;
-    /** World units, or `{ px }` for screen pixels — resolved against the
-     *  accumulated transform scale at draw time, so it holds its on-screen
-     *  thickness as the view zooms. */
-    width?: number | {
-        px: number;
-    };
-    /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
-    dash?: number[];
-    /** Marker at the first vertex of each open subpath, rotated to point back
-     *  along the line (SVG's `auto-start-reverse`, as the only behavior). */
-    markerStart?: MarkerRef;
-    /** Marker at every interior authored vertex, on the bisector of the
-     *  incoming and outgoing directions. Never insets the stroke. */
-    markerMid?: MarkerRef;
-    /** Marker at the last vertex of each open subpath. */
-    markerEnd?: MarkerRef;
-    cap?: 'butt' | 'round' | 'square';
-    join?: 'miter' | 'round' | 'bevel';
-    /**
-     * Miter join fallback threshold. When the miter length exceeds
-     * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,
-     * matching SVG — which is also what the kit's own serializer implies when
-     * it omits the attribute for an unset field. Canvas2D's 10 lets an acute
-     * corner throw a spike four times the half-width.
-     */
-    miterLimit?: number;
-    /** Where the stroke sits relative to the geometric edge. Default `'center'`. */
-    align?: StrokeAlign;
-    /**
-     * Per-anchor RGBA, flat (length = 4 × countPathAnchors(path)). Each
-     * value in 0..1. Arc-length interpolated across the tessellated ribbon
-     * between consecutive anchors. When set, `paint` is still required —
-     * its `opacity` (and color, as a placeholder) flow through the shader.
-     */
-    vertexColors?: number[];
-    /**
-     * Per-anchor stroke width (length = `countPathAnchors(path)`). When set,
-     * the tessellator interpolates half-widths along each segment to produce
-     * a tapered ribbon. `width` is used as the fallback for any anchor whose
-     * entry is missing or non-finite. Pressure-driven pencil strokes use
-     * this; pair with `pressureToWidth` to derive widths from stylus input.
-     *
-     * Joins between adjacent segments whose widths differ by more than
-     * `varyingWidthJoinThreshold` (default 1.5×) are forced to bevel
-     * regardless of the `join` setting — miter math is unstable when widths
-     * vary across the corner; smooth round joins with mismatched widths
-     * are a future enhancement.
-     */
-    vertexWidths?: number[];
-    /**
-     * Max width ratio (greater / lesser) at which a non-bevel join is
-     * preserved when `vertexWidths` causes adjacent segments to differ.
-     * Beyond this ratio the join falls back to bevel. Default 1.5. Ignored
-     * when `vertexWidths` is absent.
-     */
-    varyingWidthJoinThreshold?: number;
-}
-
-/**
- * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
- * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
- * array directly without a transpose flag.
- *
- * Layout (column-major):
- *   [m00, m10, 0,
- *    m01, m11, 0,
- *    tx,  ty,  1]
- *
- * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
- *                                              m10*x + m11*y + ty]`.
- */
-type Mat3 = Float32Array;
-
-/**
- * Typography for `TextPose` and friends. Every field is optional; consumers
- * pass `{}` or override the few they care about. Defaults live in
- * `DEFAULT_TEXT_STYLE` and are applied at render/measure time, never written
- * back to the pose.
- *
- * Paint is not typography and does not live here. A text node carries its
- * fill and stroke in `data.fill` / `data.stroke`, the slots every other node
- * kind uses; `resolveTextStyle` takes them as its second argument and
- * `StyledRun.fill` / `.stroke` override them per range.
- */
-
-/**
- * Horizontal alignment. `start` / `end` resolve against the reading direction;
- * `left` / `right` are absolute. Same five values as CSS `text-align`, with
- * the same split between the relative pair and the absolute pair.
- */
-type TextAlign = 'left' | 'center' | 'right' | 'start' | 'end';
-/** Reading direction, which is what gives `start` / `end` their meaning. */
-type TextDirection = 'ltr' | 'rtl';
-/** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
-interface TextStyle {
-    /** Font size in world units. Default 16. */
-    fontSize?: number;
-    /** Default `'sans-serif'`. */
-    fontFamily?: string;
-    /** Default 400. */
-    fontWeight?: number | string;
-    /** Default `'normal'`. */
-    fontStyle?: 'normal' | 'italic';
-    /** Default `'left'`. Pass `'start'` to align by reading order instead. */
-    align?: TextAlign;
-    /** Reading direction, resolving `align: 'start' | 'end'`. Default `'ltr'`. */
-    direction?: TextDirection;
-    /** Multiplier applied to `fontSize`. Default 1.2. */
-    lineHeight?: number;
-    /**
-     * Caret color used by the edit overlay. Defaults to the node's fill when
-     * that fill is solid; falls back to `#000` for non-solid paints.
-     */
-    caretColor?: string;
-    /**
-     * Selection background color used by the edit overlay's `::selection`
-     * pseudo-element. Defaults to a 25%-opacity tint of `caretColor` via CSS
-     * `color-mix`. Pass `'none'` to fall back to the browser-native highlight.
-     */
-    selectionBackground?: string;
-    /** Selection text color paired with `selectionBackground`. Default: inherits text color. */
-    selectionColor?: string;
-    /** Extra advance added after each glyph, in world units. Default 0. */
-    letterSpacing?: number;
-    /** Default `false`. */
-    underline?: boolean;
-    /** Default `false`. */
-    strikethrough?: boolean;
-    /** Default `false`. */
-    overline?: boolean;
-}
-
-/**
- * Apply node-level `ResolvedTextStyle` defaults to each `StyledRun`,
- * producing a fully-resolved run with every styling field set. Downstream
- * layout and draw never re-resolve defaults — `ResolvedRun` is the
- * canonical shape the renderer consumes.
- *
- * `bold`/`italic` toggles on a run are folded into `fontWeight`/`fontStyle`:
- * `bold: true` → fontWeight 700, `italic: true` → fontStyle 'italic'.
- * Explicit `fontFamily` / `fontSize` / `fill` / `letterSpacing` on the run
- * override the node-level value (`letterSpacing: 0` on a run is an override,
- * not an absence — it zeroes inherited tracking).
- *
- * `underline` / `strikethrough` / `overline` are *additive*, like
- * `bold`/`italic`: a run can turn a decoration on but never off, so they
- * resolve as `run.x || style.x` and not `run.x ?? style.x`. See the header of
- * `runs/rangeStyle.ts` for why the model collapses the tri-state.
- *
- * `script` is folded the same way the toggles are, into the two primitives it
- * is a preset over: `baselineShift` and `fontScale`. Both come out as one
- * world-unit `baselineShift` and a final `fontSize`, so layout never learns
- * that superscripts exist — it places a run against a baseline and an offset.
- */
-
-/** A run with every style resolved against the node's text style — no
- *  optional inheritance left. This is what layout and painting consume. */
-interface ResolvedRun {
-    text: string;
-    fontFamily: string;
-    fontSize: number;
-    fontWeight: number;
-    fontStyle: 'normal' | 'italic';
-    fill: FillStyle;
-    /** Outline over this run's glyphs, or absent for none. Painted only on the
-     *  outline tier — a distance field has no geometry to stroke. */
-    stroke?: Stroke;
-    /** Extra advance added after each glyph of this run, in world units. */
-    letterSpacing: number;
-    /** Draw a rule below this run's baseline. Additive over the node style. */
-    underline: boolean;
-    /** Draw a rule through this run's x-height. Additive over the node style. */
-    strikethrough: boolean;
-    /** Draw a rule above this run's ascent. Additive over the node style. */
-    overline: boolean;
-    /**
-     * How far this run sits off the line's shared baseline, in world units;
-     * positive raises. 0 for ordinary text.
-     *
-     * Already multiplied out against the inherited font size, and already
-     * carrying whatever `script` asked for — layout adds it to a baseline and
-     * asks nothing about where it came from.
-     */
-    baselineShift: number;
-}
-
-/**
- * Box vertical alignment for text draw commands. Given the command's box
- * `height` and the laid-out text block's height, returns the Y offset to
- * apply to every quad. `'top'` (or an undefined `align`, or a missing box
- * `height`) is the legacy behavior: offset 0.
- */
-type TextVerticalAlign = 'top' | 'center' | 'bottom';
-
-/**
- * registerProgram — public API for registering custom shader programs.
- *
- * Stores raw GLSL source strings in a module-level registry. GL compilation
- * happens on each WeaselRenderer via WeaselRenderer.registerProgram(), which
- * calls getProgramSource() and compiles the result. This keeps registerProgram
- * GL-context-agnostic — identical pattern to registerFont storing ImageBitmap.
- *
- * Module-level state = source strings only; compiled GL
- * programs live on each renderer's programRegistry (Map<id, ShaderProgram>).
- *
- * Lifecycle: program sources live for the module lifetime. No unregister in v1.
- */
-
-/** Opaque handle to a compiled custom shader program. */
-interface ShaderProgramHandle {
-    readonly id: string;
-}
-/**
- * Scalar and vector uniform types accepted by the custom shader uniform binder.
- *
- * | TS type                 | GL call                              |
- * |-------------------------|--------------------------------------|
- * | number                  | uniform1f                            |
- * | [n, n]                  | uniform2fv                           |
- * | [n, n, n]               | uniform3fv                           |
- * | [n, n, n, n]            | uniform4fv                           |
- * | Float32Array length 9   | uniformMatrix3fv (column-major)      |
- * | Float32Array length 16  | uniformMatrix4fv (column-major)      |
- * | TextureHandle           | bind to next tex unit + uniform1i    |
- */
-type ShaderUniform = number | [number, number] | [number, number, number] | [number, number, number, number] | Float32Array | TextureHandle;
-
-/** DrawCommand variants implemented through step 6. */
-type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | 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;
-    /** Any `FillStyle` variant: solid, pattern, or gradient (linear/radial/conic). */
-    fill?: FillStyle;
-    /** Stroke spec. Only solid `paint` supported through step 4. */
-    stroke?: Stroke;
-    /**
-     * 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?: Mat3;
-    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;
-    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[];
-    maxWidth?: number;
-    align?: 'left' | 'center' | 'right';
-    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;
-}
-/**
- * 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;
-    };
-}
-
-export type { DrawCommand as D, FillStyle as F, PathDrawCommand as P, Stroke as S, TextStyle as T, View as V };