@weasel-js/core 0.5.0

package/dist/DrawCommand-Dl0bXNfS.d.ts

@@ -0,0 +1,500 @@
+import { P as Path } from './types-B6MMiodD.js';
+import { T as TextureHandle } from './registerTexture-BzHTLhD9.js';
+
+/**
+ * 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;
+declare function identity(): Mat3;
+declare function multiply(out: Mat3, m: Mat3): Mat3;
+declare function translate(m: Mat3, tx: number, ty: number): Mat3;
+declare function scale(m: Mat3, sx: number, sy: number): Mat3;
+declare function apply(m: Mat3, x: number, y: number): [number, number];
+/**
+ * Map screen pixel coords (0..width on X, 0..height on Y, top-left origin)
+ * into clip space (-1..1 on X, 1..-1 on Y — note Y flip so screen-down
+ * matches clip-down).
+ */
+declare function screenToClip(width: number, height: number): Mat3;
+declare const mat3: {
+    identity: typeof identity;
+    multiply: typeof multiply;
+    translate: typeof translate;
+    scale: typeof scale;
+    apply: typeof apply;
+    screenToClip: typeof screenToClip;
+};
+
+/**
+ * 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 a `TextureHandle` (registered via
+ * `registerTexture()`). The kit-level factory `createTilePattern` (and the
+ * `patterns-builtin` catalog: `hatch`, `crosshatch`, `dots`, `chunks`)
+ * produces these handles by rendering a tile to an `OffscreenCanvas` and
+ * registering the resulting `ImageBitmap` as a GL texture.
+ */
+type FillStyle = {
+    fill?: 'solid';
+    color: string;
+    opacity?: number;
+} | {
+    fill: 'pattern';
+    pattern: TextureHandle;
+    opacity?: number;
+} | {
+    fill: 'linear-gradient';
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+    stops: GradStop[];
+    opacity?: number;
+} | {
+    fill: 'radial-gradient';
+    center: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+    stops: GradStop[];
+    opacity?: number;
+} | {
+    fill: 'conic-gradient';
+    center: {
+        x: number;
+        y: number;
+    };
+    angle: number;
+    stops: GradStop[];
+    opacity?: 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';
+/** Stroke style: a FillStyle plus structural line parameters. */
+interface Stroke {
+    paint: FillStyle;
+    width?: number;
+    /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
+    dash?: number[];
+    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 10
+     * (matching Canvas2D). SVG's default is 4; consumers that want SVG
+     * fidelity should set this explicitly when constructing strokes from
+     * SVG sources where the attribute was omitted.
+     */
+    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;
+}
+/**
+ * Inflate (positive) or deflate (negative) a rect to honor `align` when
+ * stroking it. Returns the rect to pass to a stroked-rect renderer. `width`
+ * is the stroke width (defaults to 1 to match canvas).
+ *
+ * Pure geometry helper — no rendering side effects. Used by path
+ * tessellation and the selection overlay to produce a rect whose
+ * center-aligned stroke visually coincides with the requested
+ * inner/outer-aligned stroke of the original rect.
+ */
+declare function alignedStrokeRect(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, align: StrokeAlign, width?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Region a fill is clipped to. */
+interface Region {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    shape: 'rectangle' | 'circle';
+}
+
+/**
+ * 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.
+ *
+ * `fill` follows the kit-wide `FillStyle` model — solid color or pattern. The
+ * contenteditable edit overlay flattens non-solid fills to `'#000'` for CSS
+ * since the browser can't paint with a texture handle.
+ */
+
+/** 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'`. */
+    align?: 'left' | 'center' | 'right';
+    /** Multiplier applied to `fontSize`. Default 1.2. */
+    lineHeight?: number;
+    /** Default `{ fill: 'solid', color: '#000' }`. */
+    fill?: FillStyle;
+    /**
+     * Caret color used by the edit overlay. Defaults to the text color when
+     * `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;
+}
+/** `TextStyle` with all fields filled in from defaults — what the renderer actually consumes. */
+interface ResolvedTextStyle {
+    fontSize: number;
+    fontFamily: string;
+    fontWeight: number | string;
+    fontStyle: 'normal' | 'italic';
+    align: 'left' | 'center' | 'right';
+    lineHeight: number;
+    fill: FillStyle;
+    caretColor: string;
+    selectionBackground: string | null;
+    selectionColor: string | null;
+}
+/** Default resolved style used when a `TextPose` omits `style`. */
+declare const DEFAULT_TEXT_STYLE: ResolvedTextStyle;
+/** Fill in a partial `TextStyle` with defaults from `DEFAULT_TEXT_STYLE`. */
+declare function resolveTextStyle(style?: TextStyle): ResolvedTextStyle;
+/** Build a CSS `font` shorthand suitable for `ctx.font`. */
+declare function fontString(s: ResolvedTextStyle): string;
+
+/**
+ * Canonical inline-styling primitive for text nodes. A node's text is
+ * either a plain `string` (treated as a single-run, default-styled fragment)
+ * or `StyledRun[]` for rich content. `toRuns` is the funnel that normalizes
+ * either form into the array shape used by the renderer.
+ *
+ * Every field except `text` is optional; missing fields fall back to the
+ * node-level `TextStyle`. `bold`/`italic` are toggles; richer weight axes
+ * (300/500/900) are out of scope for slice 1.
+ */
+
+interface StyledRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    fill?: FillStyle;
+}
+declare function toRuns(input: string | StyledRun[]): StyledRun[];
+declare function runsToPlainText(runs: readonly StyledRun[]): string;
+declare function runsToMarkdown(runs: readonly StyledRun[]): string;
+/**
+ * Parse a small markdown subset (`**bold**`, `*italic*`, `***both***`) into
+ * styled runs. Backslash escapes `\*` and `\\`. Newlines are preserved as
+ * literal characters inside a run — they're not run-boundary markers in
+ * this format.
+ */
+declare function markdownToRuns(input: string): StyledRun[];
+
+/**
+ * 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` on the run override the
+ * node-level value.
+ */
+
+interface ResolvedRun {
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic';
+    fill: FillStyle;
+}
+declare function resolveRuns(runs: readonly StyledRun[], style: ResolvedTextStyle): ResolvedRun[];
+
+/**
+ * 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';
+declare function verticalAlignOffset(align: TextVerticalAlign | undefined, boxHeight: number | undefined, textHeight: number): number;
+
+/**
+ * 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.
+ *
+ * Convention §9: 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;
+/**
+ * Register a custom shader program by id.
+ *
+ * Pass an empty string for `vert` to use the kit's default vertex shader
+ * (recommended). The kit's vertex shader exposes `v_uv`, `v_screen`, and
+ * `v_world` varyings plus `u_bounds` and `u_view` uniforms.
+ *
+ * **IMPORTANT — Premultiplied alpha (conventions §2):**
+ * Your fragment shader MUST output premultiplied alpha:
+ *   `outColor = vec4(rgb * a, a);`  ← correct
+ *   `outColor = vec4(rgb, a);`      ← WRONG — over-brightens translucent regions
+ *
+ * The renderer uses `gl.blendFunc(ONE, ONE_MINUS_SRC_ALPHA)` to match.
+ * Opaque fragments (a=1) are unaffected; only fragments with a < 1 differ.
+ *
+ * **Re-registration behavior:**
+ * - Dev mode (`NODE_ENV !== 'production'`): calling with an existing id replaces
+ *   the source (hot-reload). Each renderer must call `WeaselRenderer.registerProgram(handle)`
+ *   again to pick up the new source.
+ * - Prod mode: calling with an existing id throws.
+ *
+ * Actual GL compilation and `ShaderCompileError` throwing happen in
+ * `WeaselRenderer.registerProgram()`, not here.
+ *
+ * @experimental API may break before v2.
+ */
+declare function registerProgram(id: string, vert: string, frag: string): ShaderProgramHandle;
+
+/**
+ * Solid-fill paint variant (subset of the full `FillStyle` union from
+ * `@weasel-js/core`). 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 | ShaderDrawCommand;
+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[];
+}
+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;
+}
+/**
+ * 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, type FillStyle as F, type GradStop as G, type ImageDrawCommand as I, type Mat3 as M, type PathDrawCommand as P, type ResolvedTextStyle as R, type ShaderProgramHandle as S, type TextDrawCommand as T, type Stroke as a, type GroupDrawCommand as b, type ShaderDrawCommand as c, type ShaderUniform as d, type SolidPaint as e, type StyledRun as f, type TextStyle as g, type TextVerticalAlign as h, DEFAULT_TEXT_STYLE as i, type Region as j, type ResolvedRun as k, type StrokeAlign as l, mat3 as m, alignedStrokeRect as n, fontString as o, markdownToRuns as p, resolveRuns as q, registerProgram as r, resolveTextStyle as s, runsToMarkdown as t, runsToPlainText as u, toRuns as v, verticalAlignOffset as w };