@weasel-js/paint 1.2.0 → 1.3.0-pre.0

package/dist/index.d.ts

@@ -168,6 +168,26 @@ type GradientKind = GradientFill['fill'];
  * 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;
@@ -179,6 +199,14 @@ interface Stroke {
     };
     /** 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';
     /**
@@ -285,4 +313,4 @@ interface Region {
     shape: 'rectangle' | 'circle';
 }
 
-export { type FillStyle, type GradStop, type GradientFill, type GradientKind, type GradientUnits, type Region, STROKE_DASH_RATIOS, type Stroke, type StrokeAlign, type StrokeDashStyle, type TextureHandle, type TilePatternSpec, alignedStrokeRect, dashForStrokeStyle, strokeDashStyleOf };
+export { type FillStyle, type GradStop, type GradientFill, type GradientKind, type GradientUnits, type KitMarkerKey, type MarkerKey, type MarkerRef, type Region, STROKE_DASH_RATIOS, type Stroke, type StrokeAlign, type StrokeDashStyle, type TextureHandle, type TilePatternSpec, alignedStrokeRect, dashForStrokeStyle, strokeDashStyleOf };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/paint.ts"],"names":[],"mappings":";AA6LO,SAAS,iBAAA,CACd,IAAA,EACA,KAAA,EACA,KAAA,GAAQ,CAAA,EACiD;AACzD,EAAA,IAAI,KAAA,KAAU,UAAU,OAAO,IAAA;AAG/B,EAAA,MAAM,IAAA,GAAO,KAAA,KAAU,OAAA,GAAU,EAAA,GAAK,CAAA;AACtC,EAAA,MAAM,CAAA,GAAK,OAAO,KAAA,GAAS,CAAA;AAC3B,EAAA,OAAO;AAAA,IACL,CAAA,EAAG,KAAK,CAAA,GAAI,CAAA;AAAA,IACZ,CAAA,EAAG,KAAK,CAAA,GAAI,CAAA;AAAA,IACZ,KAAA,EAAO,IAAA,CAAK,KAAA,GAAQ,CAAA,GAAI,CAAA;AAAA,IACxB,MAAA,EAAQ,IAAA,CAAK,MAAA,GAAS,CAAA,GAAI;AAAA,GAC5B;AACF;AAiBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,MAAA,EAAQ,CAAC,CAAA,EAAG,CAAC,CAAA;AAAA,EACb,MAAA,EAAQ,CAAC,CAAA,EAAG,CAAC;AACf;AAIA,SAAS,UAAU,KAAA,EAAoD;AACrE,EAAA,MAAM,IAAI,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,CAAM,KAAM,KAAA,IAAS,CAAA;AAC3D,EAAA,OAAO,OAAO,QAAA,CAAS,CAAC,CAAA,IAAK,CAAA,GAAI,IAAI,CAAA,GAAI,CAAA;AAC3C;AASO,SAAS,kBAAA,CACd,OACA,KAAA,EACsB;AACtB,EAAA,IAAI,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,QAAA,EAAU,OAAO,MAAA;AACrD,EAAA,MAAM,CAAA,GAAI,UAAU,KAAK,CAAA;AACzB,EAAA,OAAO,mBAAmB,KAAK,CAAA,CAAE,IAAI,CAAC,CAAA,KAAM,IAAI,CAAC,CAAA;AACnD;AAMO,SAAS,iBAAA,CACd,MACA,KAAA,EACiB;AACjB,EAAA,IAAI,IAAA,KAAS,MAAA,IAAa,IAAA,CAAK,MAAA,KAAW,CAAA,IAAK,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,KAAM,CAAA,KAAM,CAAC,CAAA,EAAG,OAAO,OAAA;AAClF,EAAA,MAAM,CAAA,GAAI,UAAU,KAAK,CAAA;AACzB,EAAA,KAAA,MAAW,KAAA,IAAS,CAAC,QAAA,EAAU,QAAQ,CAAA,EAAY;AACjD,IAAA,MAAM,MAAA,GAAS,mBAAmB,KAAK,CAAA;AAGvC,IAAA,IAAI,KAAK,MAAA,KAAW,MAAA,CAAO,UAAU,MAAA,CAAO,KAAA,CAAM,CAAC,CAAA,EAAG,CAAA,KAAM,KAAK,GAAA,CAAI,IAAA,CAAK,CAAC,CAAA,GAAI,CAAA,GAAI,CAAC,CAAA,IAAK,CAAA,GAAI,IAAI,CAAA,EAAG;AAClG,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT","file":"index.js","sourcesContent":["/**\n * FillStyle and Stroke types — the unified shape for \"what color or texture\n * paints these pixels,\" modeled on SVG's paint-server concept.\n *\n * - `FillStyle` is a tagged union: solid color, pattern, or gradient. Used\n *   wherever a kit option previously took `fillStyle: string`.\n * - `Stroke` pairs a `FillStyle` with structural stroke parameters (width, dash,\n *   line cap/join, alignment).\n * - These types are consumed by the GL renderer's DrawCommand path fills\n *   and strokes.\n *\n * The 2D `applyPaint` / `applyStroke` / `renderFilledRegion` helpers that\n * formerly lived alongside these types were deleted with the 2D backend in\n * Step 10. `alignedStrokeRect` survives as a pure geometry helper used by\n * path tessellation and the selection overlay.\n */\n\nimport type { TextureHandle } from './texture';\n\n/**\n * Color/texture strategy for fills (and, via `Stroke.paint`, strokes).\n *\n * `fill` is optional and defaults to `'solid'` — `{ color: '#abc' }` is\n * equivalent to `{ fill: 'solid', color: '#abc' }`. Pattern paints must set\n * `fill: 'pattern'` explicitly.\n *\n * The `'pattern'` variant's payload is either a `TilePatternSpec` — plain\n * data naming one of the built-in tiles, which survives serialization — or a\n * `TextureHandle` for a tile the consumer built itself via\n * `createTilePattern()`. A handle is a session-scoped registry key, so a\n * paint carrying one cannot be persisted or exported; prefer the spec.\n *\n * `units` on a pattern names the space the tile's origin and scale live in,\n * not the space of any geometry (a pattern has none). Under `'bounds'` the\n * tile anchors to the painted node's box, so the pattern travels with the\n * node and a resize reveals more tiles rather than stretching them;\n * `fillInPoseFrame` resolves that to a `'local'` paint with an explicit\n * `origin` before the renderer sees it.\n */\nexport type FillStyle =\n  | { fill?: 'solid'; color: string; opacity?: number }\n  | { fill: 'pattern'; pattern: TextureHandle | TilePatternSpec; units?: GradientUnits; origin?: { x: number; y: number }; opacity?: number }\n  | { fill: 'linear-gradient'; from: { x: number; y: number }; to: { x: number; y: number }; stops: GradStop[]; units?: GradientUnits; opacity?: number }\n  | { fill: 'radial-gradient'; center: { x: number; y: number }; radius: number; stops: GradStop[]; units?: GradientUnits; opacity?: number }\n  | { fill: 'conic-gradient'; center: { x: number; y: number }; angle: number; stops: GradStop[]; units?: GradientUnits; opacity?: number };\n\n/**\n * Which coordinate space a gradient's geometry (`from`/`to`, `center`,\n * `radius`) is expressed in. SVG's `gradientUnits`, plus an option for\n * paints that are themselves viewport furniture.\n *\n * - `'bounds'`: fractions of the painted node's bounding box, `0..1` on each\n *   axis — SVG `objectBoundingBox`. Resolved by the node painter, before the\n *   renderer sees it, so the paint follows the node through moves, resizes\n *   and rotation. What a gradient on a scene node wants.\n * - `'local'`: the coordinate space the geometry was handed to the renderer\n *   in — the enclosing group's frame. For draw commands a consumer builds\n *   itself, where \"the coordinates I just wrote\" is the useful frame.\n * - `'world'`: scene coordinates. The paint stays put under pan and zoom\n *   while the geometry moves through it. SVG `userSpaceOnUse`. Requires the\n *   renderer to have been handed a view matrix; falls back to `'screen'`\n *   when it has not.\n * - `'screen'`: CSS pixels of the drawing surface. For overlays and\n *   viewport-fixed washes that should not move with the content at all.\n *\n * Defaults to `'screen'`, which is the behavior every gradient had before\n * this field existed.\n */\nexport type GradientUnits = 'bounds' | 'local' | 'world' | 'screen';\n\n/**\n * A built-in tile, described as plain data. The serializable half of the\n * pattern paint: `resolvePatternSpec()` turns one into a `TextureHandle`\n * at paint time, memoized so identical specs share a texture.\n *\n * `size` is the tile's edge length, and doubles as its extent in paint\n * space — a bigger `size` rasterizes a bigger tile rather than magnifying\n * a small one, which is why there is no separate scale field.\n */\nexport interface TilePatternSpec {\n  tile: 'hatch' | 'crosshatch' | 'dots' | 'chunks';\n  color: string;\n  /** `chunks` only — omit for a transparent tile background. */\n  bg?: string;\n  size?: number;\n  /** `hatch` / `crosshatch`. */\n  lineWidth?: number;\n  /** `dots`. */\n  radius?: number;\n  /** `chunks`. */\n  density?: number;\n  chunkSize?: number;\n  seed?: number;\n}\n\n/** A single color stop within a gradient. `offset` is in 0..1. */\nexport interface GradStop {\n  offset: number;\n  color: string;\n}\n\n/** The gradient members of `FillStyle`, as one type. What a gradient editor\n *  edits, and what the gradient-specific helpers accept. */\nexport type GradientFill = Extract<\n  FillStyle,\n  { fill: 'linear-gradient' | 'radial-gradient' | 'conic-gradient' }\n>;\n\n/** `GradientFill['fill']` — the three gradient discriminants on their own. */\nexport type GradientKind = GradientFill['fill'];\n\n/**\n * Where a stroke sits relative to the geometric edge it strokes.\n *\n * - `'center'` (default): canvas-native — half the stroke width sits inside\n *   the geometry, half outside.\n * - `'inner'`: the entire stroke lies inside the geometry. The outer edge of\n *   the stroke coincides with the geometric edge.\n * - `'outer'`: the entire stroke lies outside the geometry. The inner edge\n *   of the stroke coincides with the geometric edge.\n *\n * Mirrors the (proposed) SVG `stroke-alignment` property. Honoring `inner`\n * or `outer` is the renderer's responsibility — for axis-aligned rects, the\n * kit shifts coordinates by `width / 2`. For arbitrary paths, renderers\n * typically use a stencil mask of the stroked path against the geometry.\n */\nexport type StrokeAlign = 'center' | 'inner' | 'outer';\n\n/** Stroke style: a FillStyle plus structural line parameters. */\nexport interface Stroke {\n  paint: FillStyle;\n  /** World units, or `{ px }` for screen pixels — resolved against the\n   *  accumulated transform scale at draw time, so it holds its on-screen\n   *  thickness as the view zooms. */\n  width?: number | { px: number };\n  /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */\n  dash?: number[];\n  cap?: 'butt' | 'round' | 'square';\n  join?: 'miter' | 'round' | 'bevel';\n  /**\n   * Miter join fallback threshold. When the miter length exceeds\n   * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,\n   * matching SVG — which is also what the kit's own serializer implies when\n   * it omits the attribute for an unset field. Canvas2D's 10 lets an acute\n   * corner throw a spike four times the half-width.\n   */\n  miterLimit?: number;\n  /** Where the stroke sits relative to the geometric edge. Default `'center'`. */\n  align?: StrokeAlign;\n  /**\n   * Per-anchor RGBA, flat (length = 4 × countPathAnchors(path)). Each\n   * value in 0..1. Arc-length interpolated across the tessellated ribbon\n   * between consecutive anchors. When set, `paint` is still required —\n   * its `opacity` (and color, as a placeholder) flow through the shader.\n   */\n  vertexColors?: number[];\n  /**\n   * Per-anchor stroke width (length = `countPathAnchors(path)`). When set,\n   * the tessellator interpolates half-widths along each segment to produce\n   * a tapered ribbon. `width` is used as the fallback for any anchor whose\n   * entry is missing or non-finite. Pressure-driven pencil strokes use\n   * this; pair with `pressureToWidth` to derive widths from stylus input.\n   *\n   * Joins between adjacent segments whose widths differ by more than\n   * `varyingWidthJoinThreshold` (default 1.5×) are forced to bevel\n   * regardless of the `join` setting — miter math is unstable when widths\n   * vary across the corner; smooth round joins with mismatched widths\n   * are a future enhancement.\n   */\n  vertexWidths?: number[];\n  /**\n   * Max width ratio (greater / lesser) at which a non-bevel join is\n   * preserved when `vertexWidths` causes adjacent segments to differ.\n   * Beyond this ratio the join falls back to bevel. Default 1.5. Ignored\n   * when `vertexWidths` is absent.\n   */\n  varyingWidthJoinThreshold?: number;\n}\n\n/**\n * Inflate (positive) or deflate (negative) a rect to honor `align` when\n * stroking it. Returns the rect to pass to a stroked-rect renderer. `width`\n * is the stroke width (defaults to 1 to match canvas).\n *\n * Pure geometry helper — no rendering side effects. Used by path\n * tessellation and the selection overlay to produce a rect whose\n * center-aligned stroke visually coincides with the requested\n * inner/outer-aligned stroke of the original rect.\n */\nexport function alignedStrokeRect(\n  rect: { x: number; y: number; width: number; height: number },\n  align: StrokeAlign,\n  width = 1,\n): { x: number; y: number; width: number; height: number } {\n  if (align === 'center') return rect;\n  // For 'inner', shift inward by width/2 so the stroke's outer edge coincides\n  // with the geometric edge. For 'outer', shift outward.\n  const sign = align === 'inner' ? -1 : 1;\n  const d = (sign * width) / 2;\n  return {\n    x: rect.x - d,\n    y: rect.y - d,\n    width: rect.width + 2 * d,\n    height: rect.height + 2 * d,\n  };\n}\n\n/**\n * The named line styles a `Stroke.dash` array reads as.\n *\n * `custom` is what an imported array that matches no preset reads as — it is\n * reportable, not authorable: there is no array it maps back to.\n */\nexport type StrokeDashStyle = 'solid' | 'dashed' | 'dotted' | 'custom';\n\n/**\n * Dash and gap lengths of the presets, **as multiples of the stroke width**.\n *\n * SVG dash lengths are absolute, so a fixed pattern is a different style at\n * every width: `[6, 3]` is dots on a hairline and a railroad on a 20px\n * stroke. Scaling by the width is what makes \"dashed\" one style.\n */\nexport const STROKE_DASH_RATIOS = {\n  dashed: [3, 2],\n  dotted: [1, 2],\n} as const satisfies Record<'dashed' | 'dotted', readonly [number, number]>;\n\n/** `width` as a plain number — a `{ px }` width is read at scale 1, matching\n *  what an unresolved stroke reaching the tessellator gets. */\nfunction dashWidth(width: number | { px: number } | undefined): number {\n  const w = typeof width === 'object' ? width.px : (width ?? 1);\n  return Number.isFinite(w) && w > 0 ? w : 1;\n}\n\n/**\n * The `Stroke.dash` array for a named style at `width`, or `undefined` for\n * `solid` — which is stored as no dash at all, not as an empty pattern.\n *\n * `custom` has no array of its own and returns `undefined`; a caller that\n * offers it as a choice should refuse the choice rather than call this.\n */\nexport function dashForStrokeStyle(\n  style: StrokeDashStyle,\n  width: number | { px: number } | undefined,\n): number[] | undefined {\n  if (style !== 'dashed' && style !== 'dotted') return undefined;\n  const w = dashWidth(width);\n  return STROKE_DASH_RATIOS[style].map((r) => r * w);\n}\n\n/**\n * The style a stored `dash` reads as at `width`. Absent or empty is `solid`;\n * an array matching neither preset is `custom`.\n */\nexport function strokeDashStyleOf(\n  dash: readonly number[] | undefined,\n  width: number | { px: number } | undefined,\n): StrokeDashStyle {\n  if (dash === undefined || dash.length === 0 || dash.every((v) => v === 0)) return 'solid';\n  const w = dashWidth(width);\n  for (const style of ['dashed', 'dotted'] as const) {\n    const preset = STROKE_DASH_RATIOS[style];\n    // Tolerance is relative to the width: the presets are multiples of it, and\n    // a round-tripped array carries the serializer's decimal trimming.\n    if (dash.length === preset.length && preset.every((r, i) => Math.abs(dash[i] - r * w) <= w * 1e-3)) {\n      return style;\n    }\n  }\n  return 'custom';\n}\n\n/** Region a fill is clipped to. */\nexport interface Region {\n  x: number;\n  y: number;\n  w: number;\n  h: number;\n  shape: 'rectangle' | 'circle';\n}\n"]}
+{"version":3,"sources":["../src/paint.ts"],"names":[],"mappings":";AAyNO,SAAS,iBAAA,CACd,IAAA,EACA,KAAA,EACA,KAAA,GAAQ,CAAA,EACiD;AACzD,EAAA,IAAI,KAAA,KAAU,UAAU,OAAO,IAAA;AAG/B,EAAA,MAAM,IAAA,GAAO,KAAA,KAAU,OAAA,GAAU,EAAA,GAAK,CAAA;AACtC,EAAA,MAAM,CAAA,GAAK,OAAO,KAAA,GAAS,CAAA;AAC3B,EAAA,OAAO;AAAA,IACL,CAAA,EAAG,KAAK,CAAA,GAAI,CAAA;AAAA,IACZ,CAAA,EAAG,KAAK,CAAA,GAAI,CAAA;AAAA,IACZ,KAAA,EAAO,IAAA,CAAK,KAAA,GAAQ,CAAA,GAAI,CAAA;AAAA,IACxB,MAAA,EAAQ,IAAA,CAAK,MAAA,GAAS,CAAA,GAAI;AAAA,GAC5B;AACF;AAiBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,MAAA,EAAQ,CAAC,CAAA,EAAG,CAAC,CAAA;AAAA,EACb,MAAA,EAAQ,CAAC,CAAA,EAAG,CAAC;AACf;AAIA,SAAS,UAAU,KAAA,EAAoD;AACrE,EAAA,MAAM,IAAI,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,CAAM,KAAM,KAAA,IAAS,CAAA;AAC3D,EAAA,OAAO,OAAO,QAAA,CAAS,CAAC,CAAA,IAAK,CAAA,GAAI,IAAI,CAAA,GAAI,CAAA;AAC3C;AASO,SAAS,kBAAA,CACd,OACA,KAAA,EACsB;AACtB,EAAA,IAAI,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,QAAA,EAAU,OAAO,MAAA;AACrD,EAAA,MAAM,CAAA,GAAI,UAAU,KAAK,CAAA;AACzB,EAAA,OAAO,mBAAmB,KAAK,CAAA,CAAE,IAAI,CAAC,CAAA,KAAM,IAAI,CAAC,CAAA;AACnD;AAMO,SAAS,iBAAA,CACd,MACA,KAAA,EACiB;AACjB,EAAA,IAAI,IAAA,KAAS,MAAA,IAAa,IAAA,CAAK,MAAA,KAAW,CAAA,IAAK,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,KAAM,CAAA,KAAM,CAAC,CAAA,EAAG,OAAO,OAAA;AAClF,EAAA,MAAM,CAAA,GAAI,UAAU,KAAK,CAAA;AACzB,EAAA,KAAA,MAAW,KAAA,IAAS,CAAC,QAAA,EAAU,QAAQ,CAAA,EAAY;AACjD,IAAA,MAAM,MAAA,GAAS,mBAAmB,KAAK,CAAA;AAGvC,IAAA,IAAI,KAAK,MAAA,KAAW,MAAA,CAAO,UAAU,MAAA,CAAO,KAAA,CAAM,CAAC,CAAA,EAAG,CAAA,KAAM,KAAK,GAAA,CAAI,IAAA,CAAK,CAAC,CAAA,GAAI,CAAA,GAAI,CAAC,CAAA,IAAK,CAAA,GAAI,IAAI,CAAA,EAAG;AAClG,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT","file":"index.js","sourcesContent":["/**\n * FillStyle and Stroke types — the unified shape for \"what color or texture\n * paints these pixels,\" modeled on SVG's paint-server concept.\n *\n * - `FillStyle` is a tagged union: solid color, pattern, or gradient. Used\n *   wherever a kit option previously took `fillStyle: string`.\n * - `Stroke` pairs a `FillStyle` with structural stroke parameters (width, dash,\n *   line cap/join, alignment).\n * - These types are consumed by the GL renderer's DrawCommand path fills\n *   and strokes.\n *\n * The 2D `applyPaint` / `applyStroke` / `renderFilledRegion` helpers that\n * formerly lived alongside these types were deleted with the 2D backend in\n * Step 10. `alignedStrokeRect` survives as a pure geometry helper used by\n * path tessellation and the selection overlay.\n */\n\nimport type { TextureHandle } from './texture';\n\n/**\n * Color/texture strategy for fills (and, via `Stroke.paint`, strokes).\n *\n * `fill` is optional and defaults to `'solid'` — `{ color: '#abc' }` is\n * equivalent to `{ fill: 'solid', color: '#abc' }`. Pattern paints must set\n * `fill: 'pattern'` explicitly.\n *\n * The `'pattern'` variant's payload is either a `TilePatternSpec` — plain\n * data naming one of the built-in tiles, which survives serialization — or a\n * `TextureHandle` for a tile the consumer built itself via\n * `createTilePattern()`. A handle is a session-scoped registry key, so a\n * paint carrying one cannot be persisted or exported; prefer the spec.\n *\n * `units` on a pattern names the space the tile's origin and scale live in,\n * not the space of any geometry (a pattern has none). Under `'bounds'` the\n * tile anchors to the painted node's box, so the pattern travels with the\n * node and a resize reveals more tiles rather than stretching them;\n * `fillInPoseFrame` resolves that to a `'local'` paint with an explicit\n * `origin` before the renderer sees it.\n */\nexport type FillStyle =\n  | { fill?: 'solid'; color: string; opacity?: number }\n  | { fill: 'pattern'; pattern: TextureHandle | TilePatternSpec; units?: GradientUnits; origin?: { x: number; y: number }; opacity?: number }\n  | { fill: 'linear-gradient'; from: { x: number; y: number }; to: { x: number; y: number }; stops: GradStop[]; units?: GradientUnits; opacity?: number }\n  | { fill: 'radial-gradient'; center: { x: number; y: number }; radius: number; stops: GradStop[]; units?: GradientUnits; opacity?: number }\n  | { fill: 'conic-gradient'; center: { x: number; y: number }; angle: number; stops: GradStop[]; units?: GradientUnits; opacity?: number };\n\n/**\n * Which coordinate space a gradient's geometry (`from`/`to`, `center`,\n * `radius`) is expressed in. SVG's `gradientUnits`, plus an option for\n * paints that are themselves viewport furniture.\n *\n * - `'bounds'`: fractions of the painted node's bounding box, `0..1` on each\n *   axis — SVG `objectBoundingBox`. Resolved by the node painter, before the\n *   renderer sees it, so the paint follows the node through moves, resizes\n *   and rotation. What a gradient on a scene node wants.\n * - `'local'`: the coordinate space the geometry was handed to the renderer\n *   in — the enclosing group's frame. For draw commands a consumer builds\n *   itself, where \"the coordinates I just wrote\" is the useful frame.\n * - `'world'`: scene coordinates. The paint stays put under pan and zoom\n *   while the geometry moves through it. SVG `userSpaceOnUse`. Requires the\n *   renderer to have been handed a view matrix; falls back to `'screen'`\n *   when it has not.\n * - `'screen'`: CSS pixels of the drawing surface. For overlays and\n *   viewport-fixed washes that should not move with the content at all.\n *\n * Defaults to `'screen'`, which is the behavior every gradient had before\n * this field existed.\n */\nexport type GradientUnits = 'bounds' | 'local' | 'world' | 'screen';\n\n/**\n * A built-in tile, described as plain data. The serializable half of the\n * pattern paint: `resolvePatternSpec()` turns one into a `TextureHandle`\n * at paint time, memoized so identical specs share a texture.\n *\n * `size` is the tile's edge length, and doubles as its extent in paint\n * space — a bigger `size` rasterizes a bigger tile rather than magnifying\n * a small one, which is why there is no separate scale field.\n */\nexport interface TilePatternSpec {\n  tile: 'hatch' | 'crosshatch' | 'dots' | 'chunks';\n  color: string;\n  /** `chunks` only — omit for a transparent tile background. */\n  bg?: string;\n  size?: number;\n  /** `hatch` / `crosshatch`. */\n  lineWidth?: number;\n  /** `dots`. */\n  radius?: number;\n  /** `chunks`. */\n  density?: number;\n  chunkSize?: number;\n  seed?: number;\n}\n\n/** A single color stop within a gradient. `offset` is in 0..1. */\nexport interface GradStop {\n  offset: number;\n  color: string;\n}\n\n/** The gradient members of `FillStyle`, as one type. What a gradient editor\n *  edits, and what the gradient-specific helpers accept. */\nexport type GradientFill = Extract<\n  FillStyle,\n  { fill: 'linear-gradient' | 'radial-gradient' | 'conic-gradient' }\n>;\n\n/** `GradientFill['fill']` — the three gradient discriminants on their own. */\nexport type GradientKind = GradientFill['fill'];\n\n/**\n * Where a stroke sits relative to the geometric edge it strokes.\n *\n * - `'center'` (default): canvas-native — half the stroke width sits inside\n *   the geometry, half outside.\n * - `'inner'`: the entire stroke lies inside the geometry. The outer edge of\n *   the stroke coincides with the geometric edge.\n * - `'outer'`: the entire stroke lies outside the geometry. The inner edge\n *   of the stroke coincides with the geometric edge.\n *\n * Mirrors the (proposed) SVG `stroke-alignment` property. Honoring `inner`\n * or `outer` is the renderer's responsibility — for axis-aligned rects, the\n * kit shifts coordinates by `width / 2`. For arbitrary paths, renderers\n * typically use a stencil mask of the stroked path against the geometry.\n */\nexport type StrokeAlign = 'center' | 'inner' | 'outer';\n\n/**\n * The kit's built-in marker vocabulary, open on the string the way\n * `PaintKind` is so a consumer's registered key typechecks.\n */\nexport type KitMarkerKey =\n  | 'arrow' | 'arrow-open' | 'arrow-concave'\n  | 'diamond' | 'diamond-hollow'\n  | 'circle' | 'square' | 'bar';\nexport type MarkerKey = KitMarkerKey | (string & {});\n\n/**\n * A marker on one end (or every interior vertex) of a stroke.\n *\n * `size` reuses `Stroke.width`'s unit system: a bare number scales with the\n * resolved stroke width, `{ px }` pins screen pixels. That is SVG's\n * `markerUnits` in the idiom this codebase already resolves at draw time.\n * Omitted, the marker is one stroke width per unit.\n */\nexport type MarkerRef = MarkerKey | { key: MarkerKey; size?: number | { px: number } };\n\n/** Stroke style: a FillStyle plus structural line parameters. */\nexport interface Stroke {\n  paint: FillStyle;\n  /** World units, or `{ px }` for screen pixels — resolved against the\n   *  accumulated transform scale at draw time, so it holds its on-screen\n   *  thickness as the view zooms. */\n  width?: number | { px: number };\n  /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */\n  dash?: number[];\n  /** Marker at the first vertex of each open subpath, rotated to point back\n   *  along the line (SVG's `auto-start-reverse`, as the only behavior). */\n  markerStart?: MarkerRef;\n  /** Marker at every interior authored vertex, on the bisector of the\n   *  incoming and outgoing directions. Never insets the stroke. */\n  markerMid?: MarkerRef;\n  /** Marker at the last vertex of each open subpath. */\n  markerEnd?: MarkerRef;\n  cap?: 'butt' | 'round' | 'square';\n  join?: 'miter' | 'round' | 'bevel';\n  /**\n   * Miter join fallback threshold. When the miter length exceeds\n   * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,\n   * matching SVG — which is also what the kit's own serializer implies when\n   * it omits the attribute for an unset field. Canvas2D's 10 lets an acute\n   * corner throw a spike four times the half-width.\n   */\n  miterLimit?: number;\n  /** Where the stroke sits relative to the geometric edge. Default `'center'`. */\n  align?: StrokeAlign;\n  /**\n   * Per-anchor RGBA, flat (length = 4 × countPathAnchors(path)). Each\n   * value in 0..1. Arc-length interpolated across the tessellated ribbon\n   * between consecutive anchors. When set, `paint` is still required —\n   * its `opacity` (and color, as a placeholder) flow through the shader.\n   */\n  vertexColors?: number[];\n  /**\n   * Per-anchor stroke width (length = `countPathAnchors(path)`). When set,\n   * the tessellator interpolates half-widths along each segment to produce\n   * a tapered ribbon. `width` is used as the fallback for any anchor whose\n   * entry is missing or non-finite. Pressure-driven pencil strokes use\n   * this; pair with `pressureToWidth` to derive widths from stylus input.\n   *\n   * Joins between adjacent segments whose widths differ by more than\n   * `varyingWidthJoinThreshold` (default 1.5×) are forced to bevel\n   * regardless of the `join` setting — miter math is unstable when widths\n   * vary across the corner; smooth round joins with mismatched widths\n   * are a future enhancement.\n   */\n  vertexWidths?: number[];\n  /**\n   * Max width ratio (greater / lesser) at which a non-bevel join is\n   * preserved when `vertexWidths` causes adjacent segments to differ.\n   * Beyond this ratio the join falls back to bevel. Default 1.5. Ignored\n   * when `vertexWidths` is absent.\n   */\n  varyingWidthJoinThreshold?: number;\n}\n\n/**\n * Inflate (positive) or deflate (negative) a rect to honor `align` when\n * stroking it. Returns the rect to pass to a stroked-rect renderer. `width`\n * is the stroke width (defaults to 1 to match canvas).\n *\n * Pure geometry helper — no rendering side effects. Used by path\n * tessellation and the selection overlay to produce a rect whose\n * center-aligned stroke visually coincides with the requested\n * inner/outer-aligned stroke of the original rect.\n */\nexport function alignedStrokeRect(\n  rect: { x: number; y: number; width: number; height: number },\n  align: StrokeAlign,\n  width = 1,\n): { x: number; y: number; width: number; height: number } {\n  if (align === 'center') return rect;\n  // For 'inner', shift inward by width/2 so the stroke's outer edge coincides\n  // with the geometric edge. For 'outer', shift outward.\n  const sign = align === 'inner' ? -1 : 1;\n  const d = (sign * width) / 2;\n  return {\n    x: rect.x - d,\n    y: rect.y - d,\n    width: rect.width + 2 * d,\n    height: rect.height + 2 * d,\n  };\n}\n\n/**\n * The named line styles a `Stroke.dash` array reads as.\n *\n * `custom` is what an imported array that matches no preset reads as — it is\n * reportable, not authorable: there is no array it maps back to.\n */\nexport type StrokeDashStyle = 'solid' | 'dashed' | 'dotted' | 'custom';\n\n/**\n * Dash and gap lengths of the presets, **as multiples of the stroke width**.\n *\n * SVG dash lengths are absolute, so a fixed pattern is a different style at\n * every width: `[6, 3]` is dots on a hairline and a railroad on a 20px\n * stroke. Scaling by the width is what makes \"dashed\" one style.\n */\nexport const STROKE_DASH_RATIOS = {\n  dashed: [3, 2],\n  dotted: [1, 2],\n} as const satisfies Record<'dashed' | 'dotted', readonly [number, number]>;\n\n/** `width` as a plain number — a `{ px }` width is read at scale 1, matching\n *  what an unresolved stroke reaching the tessellator gets. */\nfunction dashWidth(width: number | { px: number } | undefined): number {\n  const w = typeof width === 'object' ? width.px : (width ?? 1);\n  return Number.isFinite(w) && w > 0 ? w : 1;\n}\n\n/**\n * The `Stroke.dash` array for a named style at `width`, or `undefined` for\n * `solid` — which is stored as no dash at all, not as an empty pattern.\n *\n * `custom` has no array of its own and returns `undefined`; a caller that\n * offers it as a choice should refuse the choice rather than call this.\n */\nexport function dashForStrokeStyle(\n  style: StrokeDashStyle,\n  width: number | { px: number } | undefined,\n): number[] | undefined {\n  if (style !== 'dashed' && style !== 'dotted') return undefined;\n  const w = dashWidth(width);\n  return STROKE_DASH_RATIOS[style].map((r) => r * w);\n}\n\n/**\n * The style a stored `dash` reads as at `width`. Absent or empty is `solid`;\n * an array matching neither preset is `custom`.\n */\nexport function strokeDashStyleOf(\n  dash: readonly number[] | undefined,\n  width: number | { px: number } | undefined,\n): StrokeDashStyle {\n  if (dash === undefined || dash.length === 0 || dash.every((v) => v === 0)) return 'solid';\n  const w = dashWidth(width);\n  for (const style of ['dashed', 'dotted'] as const) {\n    const preset = STROKE_DASH_RATIOS[style];\n    // Tolerance is relative to the width: the presets are multiples of it, and\n    // a round-tripped array carries the serializer's decimal trimming.\n    if (dash.length === preset.length && preset.every((r, i) => Math.abs(dash[i] - r * w) <= w * 1e-3)) {\n      return style;\n    }\n  }\n  return 'custom';\n}\n\n/** Region a fill is clipped to. */\nexport interface Region {\n  x: number;\n  y: number;\n  w: number;\n  h: number;\n  shape: 'rectangle' | 'circle';\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/paint",
-  "version": "1.2.0",
+  "version": "1.3.0-pre.0",
   "description": "Paint vocabulary for weasel: FillStyle, Stroke, gradients, dashes. Plain data, no renderer.",
   "license": "MIT",
   "type": "module",