@weasel-js/paint 1.9.3 → 1.10.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * A registered texture, named by the registry that holds it.
  *
- * The handle is here rather than beside the registry because `FillStyle`'s
+ * The handle is here rather than beside the registry because `Paint`'s
  * pattern variant names it, and paint is a leaf: the registry lives in the
  * renderer and imports this back.
  */
@@ -9,6 +9,124 @@ interface TextureHandle {
     readonly id: string;
 }
 
+/**
+ * A pattern tile's linear map into paint space: `[a, b, c, d]`, the first
+ * four entries of SVG's `matrix(a b c d e f)`. A tile point `(u, v)` lands at
+ * `origin + (a·u + c·v, b·u + d·v)`. Translation is the paint's `origin`, so
+ * it has no slot here.
+ */
+type PatternTransform = readonly [a: number, b: number, c: number, d: number];
+/**
+ * A {@link PatternTransform} as the parts an editor shows. Angles are radians.
+ * Applied in the order scale, then skew, then rotation — rotation outermost,
+ * so turning a skewed tile turns it whole.
+ */
+interface PatternTransformParts {
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+    /** Shear of the tile's y axis toward x, as SVG `skewX()`. */
+    skewX: number;
+}
+/** `R(rotation) · K(skewX) · S(scaleX, scaleY)`. Omitted parts are identity. */
+declare function composePatternTransform(parts: Partial<PatternTransformParts>): PatternTransform;
+/**
+ * Inverse of {@link composePatternTransform}. Any 2×2 matrix decomposes this
+ * way; a reflection comes back as a negative `scaleY`. `undefined` reads as the
+ * identity, which is what an absent `transform` means.
+ */
+declare function decomposePatternTransform(t: PatternTransform | undefined): PatternTransformParts;
+
+/**
+ * The pattern members of `Paint`: the built-in tiles, each its own kind, and
+ * `texture` for a tile the consumer rasterized itself.
+ */
+
+/**
+ * Where a pattern's tile sits, shared by every pattern kind.
+ *
+ * `units` 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.
+ *
+ * `transform` rotates, scales or skews the tile about `origin` (SVG's
+ * `patternTransform`, less its translation). See `PatternTransform`.
+ */
+interface PatternPlacement {
+    units?: PaintUnits;
+    origin?: {
+        x: number;
+        y: number;
+    };
+    transform?: PatternTransform;
+    opacity?: number;
+}
+/**
+ * A built-in tile, described as plain data: what a tile paint says about the
+ * tile itself, apart from where it sits. `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.
+ */
+type TilePatternSpec = {
+    kind: 'hatch';
+    color: string;
+    size?: number;
+    lineWidth?: number;
+} | {
+    kind: 'crosshatch';
+    color: string;
+    size?: number;
+    lineWidth?: number;
+} | {
+    kind: 'dots';
+    color: string;
+    size?: number;
+    radius?: number;
+} | {
+    kind: 'chunks';
+    color: string;
+    /** Omit for a transparent tile background. */
+    bg?: string;
+    size?: number;
+    density?: number;
+    chunkSize?: number;
+    seed?: number;
+};
+/** The built-in tile kinds. */
+type TileKind = TilePatternSpec['kind'];
+/** A paint of one of the built-in tiles. Plain data, so it survives
+ *  serialization. */
+type TilePaint = TilePatternSpec & PatternPlacement;
+/**
+ * A paint of a tile the consumer built itself via `createTilePattern()`. The
+ * handle is a session-scoped registry key, so a paint carrying one cannot be
+ * persisted or exported; prefer a tile kind.
+ */
+type TexturePaint = {
+    kind: 'texture';
+    texture: TextureHandle;
+} & PatternPlacement;
+/** Every paint that repeats a tile. */
+type PatternPaint = TilePaint | TexturePaint;
+/** The built-in tile kinds, in the order a picker offers them. */
+declare const TILE_KINDS: readonly TileKind[];
+/** Whether `kind` names a built-in tile. */
+declare function isTileKind(kind: string | undefined): kind is TileKind;
+/** Whether a paint is one of the built-in tiles. */
+declare function isTilePaint(paint: Paint): paint is TilePaint;
+/** Whether a paint repeats a tile: a built-in one or a consumer's texture. */
+declare function isPatternPaint(paint: Paint): paint is PatternPaint;
+/** A pattern paint's placement alone, holding only the fields it sets. */
+declare function patternPlacementOf(paint: PatternPaint): PatternPlacement;
+/** A tile paint's description of the tile alone, its placement left behind. */
+declare function tileSpecOf(paint: TilePaint): TilePatternSpec;
+
 /**
  * Convert a 0..1 float sRGB triple to OKLab — the renderer's own color space,
  * and what a caller holding a `resolveColor` result has. Rounds into the u8
@@ -77,7 +195,8 @@ interface OklchDeg {
  * is what lets a caller find a hue's ceiling by asking for far more than exists.
  */
 declare function oklchDegToHex(L: number, C: number, hueDeg: number): string;
-/** `#rrggbb` to OKLCh with the hue wrapped into 0..360. */
+/** A hex color (`#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa`, alpha ignored) to
+ *  OKLCh with the hue wrapped into 0..360. Throws on anything else. */
 declare function hexToOklchDeg(hex: string): OklchDeg;
 /** sRGB-encoded channel (0..1) to linear light. Unclamped; odd-symmetric
  *  below zero, as CSS `srgb-linear` extends it. */
@@ -102,7 +221,6 @@ type ColorInterpolationSpace = 'oklch' | 'oklab' | 'hsl' | 'srgb' | 'srgb-linear
 /** Which way a polar space's hue goes between two endpoints, as CSS
  *  `hue-interpolation-method`: the arc of at most 180°, or the other one. */
 type HueInterpolation = 'shorter' | 'longer';
-type Rgb = readonly [number, number, number];
 /**
  * Interpolate between two sRGB colors (0..1 floats) in `space`, at `t` in 0..1.
  * Float precision throughout, with no byte round-trip. The result is sRGB;
@@ -113,98 +231,34 @@ type Rgb = readonly [number, number, number];
  * or no saturation (HSL) borrows the other endpoint's hue, so a ramp to white
  * or black holds its hue instead of sweeping from red.
  */
-declare function interpolateSrgb(from: Rgb, to: Rgb, t: number, space?: ColorInterpolationSpace, hue?: HueInterpolation): [number, number, number];
-
-/**
- * A pattern tile's linear map into paint space: `[a, b, c, d]`, the first
- * four entries of SVG's `matrix(a b c d e f)`. A tile point `(u, v)` lands at
- * `origin + (a·u + c·v, b·u + d·v)`. Translation is the paint's `origin`, so
- * it has no slot here.
- */
-type PatternTransform = readonly [a: number, b: number, c: number, d: number];
-/**
- * A {@link PatternTransform} as the parts an editor shows. Angles are radians.
- * Applied in the order scale, then skew, then rotation — rotation outermost,
- * so turning a skewed tile turns it whole.
- */
-interface PatternTransformParts {
-    rotation: number;
-    scaleX: number;
-    scaleY: number;
-    /** Shear of the tile's y axis toward x, as SVG `skewX()`. */
-    skewX: number;
-}
-/** `R(rotation) · K(skewX) · S(scaleX, scaleY)`. Omitted parts are identity. */
-declare function composePatternTransform(parts: Partial<PatternTransformParts>): PatternTransform;
-/**
- * Inverse of {@link composePatternTransform}. Any 2×2 matrix decomposes this
- * way; a reflection comes back as a negative `scaleY`. `undefined` reads as the
- * identity, which is what an absent `transform` means.
- */
-declare function decomposePatternTransform(t: PatternTransform | undefined): PatternTransformParts;
+declare function interpolateSrgb(from: readonly [number, number, number], to: readonly [number, number, number], t: number, space?: ColorInterpolationSpace, hue?: HueInterpolation): [number, number, number];
 
 /**
- * FillStyle and Stroke types — the unified shape for "what color or texture
+ * Paint 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.
+ * `kind` is optional and defaults to `'solid'` — `{ color: '#abc' }` is
+ * equivalent to `{ kind: 'solid', color: '#abc' }`. Every other paint names
+ * its kind.
  *
- * 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.
+ * A pattern is one of the built-in tile kinds or a `texture`; see
+ * `PatternPaint`.
  *
  * `interpolate` on a gradient names the space its stops blend through, and
- * defaults to `'rgb'` — the channel-wise sRGB lerp every other vector format
- * means by a gradient. `'oklab'` spaces the blend perceptually; `'oklch'`
+ * defaults to `'rgb'`. `'oklab'` spaces the blend perceptually; `'oklch'`
  * additionally travels around the hue wheel, so red to blue stays saturated
  * instead of passing through a muddy purple. Alpha is linear in every space.
- *
- * `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.
- *
- * `transform` on a pattern rotates, scales or skews the tile about `origin`
- * (SVG's `patternTransform`, less its translation). See `PatternTransform`.
  */
-type FillStyle = {
-    fill?: 'solid';
+type Paint = {
+    kind?: 'solid';
     color: string;
     opacity?: number;
-} | {
-    fill: 'pattern';
-    pattern: TextureHandle | TilePatternSpec;
-    units?: GradientUnits;
-    origin?: {
-        x: number;
-        y: number;
-    };
-    transform?: PatternTransform;
-    opacity?: number;
-} | {
-    fill: 'linear-gradient';
+} | PatternPaint | {
+    kind: 'linear-gradient';
     from: {
         x: number;
         y: number;
@@ -214,105 +268,71 @@ type FillStyle = {
         y: number;
     };
     stops: GradStop[];
-    units?: GradientUnits;
+    units?: PaintUnits;
     interpolate?: ColorSpace;
     opacity?: number;
 } | {
-    fill: 'radial-gradient';
+    kind: 'radial-gradient';
     center: {
         x: number;
         y: number;
     };
     radius: number;
     stops: GradStop[];
-    units?: GradientUnits;
+    units?: PaintUnits;
     interpolate?: ColorSpace;
     opacity?: number;
 } | {
-    fill: 'conic-gradient';
+    kind: 'conic-gradient';
     center: {
         x: number;
         y: number;
     };
     angle: number;
     stops: GradStop[];
-    units?: GradientUnits;
+    units?: PaintUnits;
     interpolate?: ColorSpace;
     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.
+ * paints that are themselves viewport furniture. Defaults to `'screen'`.
  *
  * - `'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.
+ *   axis — SVG `objectBoundingBox`. The paint follows the node through moves,
+ *   resizes and rotation.
  * - `'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.
+ *   in — the enclosing group's 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;
-}
+type PaintUnits = 'bounds' | 'local' | 'world' | 'screen';
 /** A single color stop within a gradient. `offset` is in 0..1. */
 interface GradStop {
     offset: number;
     color: string;
 }
-/** The gradient members of `FillStyle`, as one type. What a gradient editor
+/** The gradient members of `Paint`, as one type. What a gradient editor
  *  edits, and what the gradient-specific helpers accept. */
-type GradientFill = Extract<FillStyle, {
-    fill: 'linear-gradient' | 'radial-gradient' | 'conic-gradient';
+type GradientPaint = Extract<Paint, {
+    kind: 'linear-gradient' | 'radial-gradient' | 'conic-gradient';
 }>;
-/** `GradientFill['fill']` — the three gradient discriminants on their own. */
-type GradientKind = GradientFill['fill'];
+/** `GradientPaint['kind']` — the three gradient discriminants on their own. */
+type GradientKind = GradientPaint['kind'];
 /**
  * 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.
+ * - `'center'` (default): half the stroke width sits inside the geometry,
+ *   half outside.
+ * - `'inner'`: the entire stroke lies inside the geometry.
+ * - `'outer'`: the entire stroke lies outside the geometry.
  *
- * 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.
+ * Mirrors the (proposed) SVG `stroke-alignment` property.
  */
 type StrokeAlign = 'center' | 'inner' | 'outer';
 /**
@@ -350,15 +370,23 @@ type ScreenLength = number | {
  * rather than becoming `Infinity`.
  */
 declare function resolveScreenLength(value: ScreenLength, scale: number): number;
-/** Stroke style: a FillStyle plus structural line parameters. */
+/**
+ * Fill style: the paint laid inside an outline. `Stroke`'s sibling, and the
+ * same shape: a record holding a `paint`, with room for what belongs to the
+ * fill rather than to the paint.
+ */
+interface Fill {
+    /** Omitted, the fill paints nothing, as a stroke with no paint does. */
+    paint?: Paint;
+}
+/** Stroke style: a Paint plus structural line parameters. */
 interface Stroke {
     /**
      * Omitted, the stroke paints nothing — the same "no paint" a `fill: null`
-     * says for a node's fill. Documents written before mid-2026 can hold a
-     * stroke whose other fields were seeded without one, and the type is
-     * optional so every reader has to answer for that rather than throw on it.
+     * says for a node's fill. Stored documents can hold a stroke without one,
+     * so every reader has to answer for that rather than throw on it.
      */
-    paint?: FillStyle;
+    paint?: Paint;
     /** World units, or `{ px }` for screen pixels — resolved against the
      *  accumulated transform at draw time, so it holds its on-screen thickness
      *  as the view zooms, in every direction even when one axis is zoomed more
@@ -400,14 +428,13 @@ interface Stroke {
      * the tessellator interpolates half-widths along each segment to produce
      * a tapered ribbon. Entries are world units, even on a `{ px }` stroke.
      * `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.
+     * non-finite. 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.
+     * vary across the corner.
      */
     vertexWidths?: number[];
     /**
@@ -420,13 +447,9 @@ interface Stroke {
 }
 /**
  * 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.
+ * stroking it: the returned rect's center-aligned stroke coincides with the
+ * requested inner/outer-aligned stroke of the original. `width` is the
+ * stroke width (defaults to 1 to match canvas).
  */
 declare function alignedStrokeRect(rect: {
     x: number;
@@ -483,6 +506,82 @@ interface Region {
     shape: 'rectangle' | 'circle';
 }
 
+/**
+ * The paint a draw command takes: `Paint` and `Stroke` narrowed to what a
+ * renderer can draw as it stands. A node's own paint may name its box
+ * (`units: 'bounds'`) or a tile by kind; a command has neither a node nor a
+ * rasterizer, so both are resolved before one is built.
+ */
+
+/** The spaces a draw command's paint can name. `'bounds'` is not one: it means
+ *  a node's box, and a command has no node. */
+type CommandPaintUnits = Exclude<PaintUnits, 'bounds'>;
+/** `F` with `'bounds'` units ruled out, where `F` is a paint that has units. */
+type InCommandUnits<F> = F extends {
+    units?: PaintUnits;
+} ? Omit<F, 'units'> & {
+    units?: CommandPaintUnits;
+} : F;
+/** A `Paint` placed in a frame a command can name. Its pattern may still
+ *  be a tile kind. */
+type PosedPaint = InCommandUnits<Paint>;
+/** A `Paint` a renderer can draw as it stands: no paint is in `'bounds'`
+ *  units, and a pattern is a registered `texture` rather than a tile kind. */
+type CommandPaint = Exclude<PosedPaint, {
+    kind: TileKind;
+}>;
+/** The solid member of `Paint`: a color and an opacity. */
+type SolidPaint = Extract<Paint, {
+    kind?: 'solid';
+}>;
+/** Whether a paint is the solid member. A tile paint carries a `color` too, so
+ *  the presence of one does not answer this. */
+declare function isSolidPaint(paint: Paint | null | undefined): paint is SolidPaint;
+/** A `Fill` whose paint is a {@link CommandPaint}. */
+interface CommandFill extends Omit<Fill, 'paint'> {
+    paint?: CommandPaint;
+}
+/** A `Stroke` whose paint is a {@link CommandPaint}. */
+type CommandStroke = Omit<Stroke, 'paint'> & {
+    paint?: CommandPaint;
+};
+
+/**
+ * Paint identity as a string: paints with equal keys draw the same, however
+ * they were built. Paint is plain data, so the comparison is structural.
+ */
+
+/**
+ * A key two paints share only if they draw the same. No paint at all is
+ * `'none'`. Two solids that draw the same always share one. A gradient or
+ * pattern keys by its fields as written, so one that spells out a default
+ * (`opacity: 1`, `units`) keys apart from one that omits it: that splits a
+ * group, where merging two that differ would draw one with the other's paint.
+ *
+ * A gradient or pattern is read once: changed in place after its first use,
+ * it keeps the key it had. A solid is read on every call.
+ */
+declare function paintKey(paint: Paint | null | undefined): string;
+/** Whether a fill puts ink down: it does not when it is absent or holds no paint. */
+declare function fillHasInk(fill: Fill | null | undefined): fill is Fill & {
+    paint: Paint;
+};
+/** Whether a stroke puts ink down: it does not when it is absent, holds no
+ *  paint, or has no width. */
+declare function strokeHasInk(stroke: Stroke | null | undefined): stroke is Stroke & {
+    paint: Paint;
+};
+/**
+ * A key two strokes share only if they draw the same ribbon over the same
+ * geometry. Every stroke that puts no ink down is `'none'`. A `{ px }` width
+ * keys apart from the equal world-unit number, which is a different ribbon.
+ *
+ * Everything but the paint is read once: a stroke whose width, dash, or other
+ * shape is changed in place keeps the key it had. Its paint is keyed on every
+ * call, as {@link paintKey} keys it.
+ */
+declare function strokeKey(stroke: Stroke | null | undefined): string;
+
 /**
  * A line color that reads against `background` — a grid, a rule, a guide
  * drawn over a surface whose color the document chooses, where theme tokens
@@ -495,6 +594,135 @@ interface Region {
  */
 declare function contrastLineColor(background: string, strength: number): string;
 
+/**
+ * The kit's one hex color reader: `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa`,
+ * in any case, as four 0..255 channels with alpha last (255 when the color
+ * names none). `null` for anything else, a missing `#` included.
+ */
+declare function parseHexBytes(input: string): [number, number, number, number] | null;
+/** A hex color's red, green, and blue as 0..255, its alpha dropped. Throws on anything {@link parseHexBytes} does not read. */
+declare function hexToRgbBytes(input: string): [number, number, number];
+
+/**
+ * Parse a CSS color string into [r, g, b, a] with 0..1 components.
+ *
+ * Supported forms:
+ *   - Hex: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` (any case)
+ *   - `rgb()` / `rgba()` with integer, float, or percent R/G/B; number or
+ *     percent alpha; commas or modern space-separated `R G B / A` syntax
+ *   - `hsl()` / `hsla()` with hue as a unitless number (deg) or with `deg`,
+ *     `rad`, `grad`, `turn` units; saturation/lightness as percent (or
+ *     unitless in the modern syntax); same alpha rules and separator rules
+ *     as `rgb()`
+ *   - The 148 CSS named colors plus `transparent`
+ *
+ * Not supported: `oklch()`, `lab()`, `color()`, `currentColor`, system
+ * colors. Throws on anything unrecognized.
+ *
+ * Results are cached by input-string identity. Callers MUST treat the
+ * returned tuple as read-only — mutation would corrupt the cache.
+ */
+declare function parseColor(input: string): [number, number, number, number];
+/** Cached `parseColor`. Use this from renderer hot paths (per-frame draw
+ *  callbacks, gradient ramp builds). The cache is capped at ~1024 entries and
+ *  cleared wholesale on overflow. */
+declare function resolveColor(input: string): readonly [number, number, number, number];
+/** Same as `parseColor` but returns integer 0..255 components. */
+declare function parseColorToRgba255(input: string): [number, number, number, number];
+/**
+ * Canonicalize a hex color string to lowercase `#rrggbb` or `#rrggbbaa`.
+ *
+ * Accepts: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, with or without the
+ * leading `#`, any case. Throws on other inputs.
+ */
+declare function normalizeHex(input: string): string;
+/**
+ * Parse a hex color into [r, g, b, a] with 0..1 components. Accepts the same
+ * forms as `normalizeHex`, including a missing leading `#`.
+ */
+declare function hexToRgba(input: string): [number, number, number, number];
+/**
+ * Format [r, g, b, a] (0..1 components) as a hex string. Emits `#rrggbb` when
+ * alpha is exactly 1 (or omitted), otherwise `#rrggbbaa`.
+ */
+declare function rgbaToHex(rgba: readonly [number, number, number, number] | readonly [number, number, number]): string;
+
+/**
+ * Gradient helpers shared by renderers, editors and exporters: reading a
+ * color out of a stop list, and moving a gradient between its three kinds.
+ */
+
+/** A stop with its color already parsed to 0..1 RGBA. */
+interface ResolvedGradientStop {
+    offset: number;
+    rgba: readonly [number, number, number, number];
+}
+/** Narrow a paint to the gradient members of `Paint`. */
+declare function isGradientPaint(fill: Paint | null | undefined): fill is GradientPaint;
+/**
+ * Sort a stop list by offset and parse each color to 0..1 RGBA, so a caller
+ * sampling many positions parses each color once. Colors go through
+ * `resolveColor`, so any CSS color the kit understands is a legal stop, not
+ * just hex.
+ */
+declare function resolveGradientStops(stops: readonly GradStop[]): ResolvedGradientStop[];
+/**
+ * RGBA (0..1) at position `t` along resolved stops: flat extension past
+ * either end, interpolation between neighbors in `space`, alpha included.
+ * The single definition of what a stop list means; a second implementation
+ * is a gradient that paints differently from its own swatch.
+ *
+ * `space` is a gradient's `interpolate`. Alpha is linear in every space —
+ * only the color channels travel through OKLab or OKLCh. Returns transparent
+ * black for an empty list.
+ */
+declare function sampleResolvedStops(stops: readonly ResolvedGradientStop[], t: number, space?: ColorSpace): readonly [number, number, number, number];
+/**
+ * Color at position `t` (0..1) along a stop list, as a hex string — the same
+ * sampling the GL ramp texture bakes, so an editor track and the painted
+ * gradient cannot disagree.
+ *
+ * Returns transparent black for an empty list.
+ */
+declare function sampleGradientStops(stops: readonly GradStop[], t: number, space?: ColorSpace): string;
+/**
+ * Retarget a gradient to a different kind, preserving stops, `units` and
+ * `opacity`. Linear carries a segment; radial and conic carry a center.
+ * Converting between them keeps the center fixed and reads the radius /
+ * angle off the segment.
+ *
+ * Lossy in both directions: a radial gradient stores no angle, so a round
+ * trip through one leaves the segment horizontal; a conic stores no radius,
+ * so a round trip through one resets the segment's length. An editor that
+ * wants a kind switch to be undoable should keep the original paint rather
+ * than converting back.
+ */
+declare function withGradientKind(fill: GradientPaint, kind: GradientKind): GradientPaint;
+/**
+ * Center / radius / angle for any gradient kind. For a linear gradient the
+ * center is the segment midpoint, the radius is half its length, and the
+ * angle is its direction.
+ */
+declare function gradientGeometry(fill: GradientPaint): {
+    center: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+    angle: number;
+};
+/**
+ * A gradient spanning a box left edge to right edge through its vertical
+ * center (linear) or filling it (radial / conic) — a starting geometry when
+ * only the shape's bounds are known.
+ */
+declare function gradientForBounds(kind: GradientKind, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, stops: GradStop[], units?: GradientPaint['units']): GradientPaint;
+
 /**
  * A color given directly. `coords` are in the order CSS Color 4 uses for
  * `space` — `srgb` as 0..1 r, g, b; `oklab` as L, a, b; `oklch` as L, C and a
@@ -557,7 +785,15 @@ declare function resolvePaletteColors(palette: Palette, name: string, external?:
 /** `#rrggbb`, or `#rrggbbaa` below full opacity. `null` for a space the kit
  *  cannot convert, or fewer than three coordinates. */
 declare function colorLiteralToHex(color: ColorLiteral): string | null;
+/**
+ * A literal as a CSS color: hex where `colorLiteralToHex` has one, else
+ * `color(<space> …)`, which is the form CSS gives every predefined space.
+ * `null` for fewer than three coordinates.
+ */
+declare function colorLiteralToCss(color: ColorLiteral): string | null;
+/** Any color string `parseColor` reads, as an `srgb` literal. Throws, as it does, on one it cannot. */
+declare function cssColorLiteral(css: string): ColorLiteral;
 /** `#rrggbb` or `#rrggbbaa` as an `srgb` literal; `null` for anything else. */
 declare function hexToColorLiteral(hex: string): ColorLiteral | null;
 
-export { type ColorFn, type ColorFnContext, type ColorInterpolationSpace, type ColorLiteral, type ColorRef, type ColorSeqFn, type ColorSource, type ColorSpace, type ExternalColors, type FillStyle, type GradStop, type GradientFill, type GradientKind, type GradientUnits, type HueInterpolation, type KitMarkerKey, type MarkerKey, type MarkerRef, type OklchDeg, type Palette, type PaletteEntry, type PatternTransform, type PatternTransformParts, type Region, STROKE_DASH_RATIOS, type ScreenLength, type Stroke, type StrokeAlign, type StrokeDashStyle, type TextureHandle, type TilePatternSpec, alignedStrokeRect, colorLiteralToHex, composePatternTransform, contrastLineColor, dashForStrokeStyle, decomposePatternTransform, hexToColorLiteral, hexToOklchDeg, hslToSrgb, interpolateSrgb, lerpColorArray, lerpOklab, lerpOklch, linearSrgbToOklab, linearToSrgb, mixOklab, oklabToLinearSrgb, oklabToOklch, oklabToSrgbU8, oklchDegToHex, oklchToOklab, resolvePaletteColor, resolvePaletteColors, resolveScreenLength, srgbFloatToOklab, srgbToHsl, srgbToLinear, srgbU8ToOklab, strokeDashStyleOf };
+export { type ColorFn, type ColorFnContext, type ColorInterpolationSpace, type ColorLiteral, type ColorRef, type ColorSeqFn, type ColorSource, type ColorSpace, type CommandFill, type CommandPaint, type CommandPaintUnits, type CommandStroke, type ExternalColors, type Fill, type GradStop, type GradientKind, type GradientPaint, type HueInterpolation, type InCommandUnits, type KitMarkerKey, type MarkerKey, type MarkerRef, type OklchDeg, type Paint, type PaintUnits, type Palette, type PaletteEntry, type PatternPaint, type PatternPlacement, type PatternTransform, type PatternTransformParts, type PosedPaint, type Region, type ResolvedGradientStop, STROKE_DASH_RATIOS, type ScreenLength, type SolidPaint, type Stroke, type StrokeAlign, type StrokeDashStyle, TILE_KINDS, type TextureHandle, type TexturePaint, type TileKind, type TilePaint, type TilePatternSpec, alignedStrokeRect, colorLiteralToCss, colorLiteralToHex, composePatternTransform, contrastLineColor, cssColorLiteral, dashForStrokeStyle, decomposePatternTransform, fillHasInk, gradientForBounds, gradientGeometry, hexToColorLiteral, hexToOklchDeg, hexToRgbBytes, hexToRgba, hslToSrgb, interpolateSrgb, isGradientPaint, isPatternPaint, isSolidPaint, isTileKind, isTilePaint, lerpColorArray, lerpOklab, lerpOklch, linearSrgbToOklab, linearToSrgb, mixOklab, normalizeHex, oklabToLinearSrgb, oklabToOklch, oklabToSrgbU8, oklchDegToHex, oklchToOklab, paintKey, parseColor, parseColorToRgba255, parseHexBytes, patternPlacementOf, resolveColor, resolveGradientStops, resolvePaletteColor, resolvePaletteColors, resolveScreenLength, rgbaToHex, sampleGradientStops, sampleResolvedStops, srgbFloatToOklab, srgbToHsl, srgbToLinear, srgbU8ToOklab, strokeDashStyleOf, strokeHasInk, strokeKey, tileSpecOf, withGradientKind };