@weasel-js/paint 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @weasel-js/paint
+
+Paint vocabulary for weasel: `FillStyle`, `Stroke`, gradients, dashes. Plain
+data — nothing here draws anything.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/api/).
+
+## Install
+
+```sh
+npm install @weasel-js/paint
+```
+
+## Usage
+
+```ts
+import type { FillStyle, Stroke } from '@weasel-js/paint';
+
+const fill: FillStyle = { color: '#c0ffee' };
+const stroke: Stroke = { paint: { color: '#000' }, width: 2, join: 'round' };
+```

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+/**
+ * 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;
+}
+/** The gradient members of `FillStyle`, 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';
+}>;
+/** `GradientFill['fill']` — the three gradient discriminants on their own. */
+type GradientKind = GradientFill['fill'];
+/**
+ * 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;
+    /** 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[];
+    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;
+}
+/**
+ * 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;
+};
+/**
+ * The named line styles a `Stroke.dash` array reads as.
+ *
+ * `custom` is what an imported array that matches no preset reads as — it is
+ * reportable, not authorable: there is no array it maps back to.
+ */
+type StrokeDashStyle = 'solid' | 'dashed' | 'dotted' | 'custom';
+/**
+ * Dash and gap lengths of the presets, **as multiples of the stroke width**.
+ *
+ * SVG dash lengths are absolute, so a fixed pattern is a different style at
+ * every width: `[6, 3]` is dots on a hairline and a railroad on a 20px
+ * stroke. Scaling by the width is what makes "dashed" one style.
+ */
+declare const STROKE_DASH_RATIOS: {
+    readonly dashed: readonly [3, 2];
+    readonly dotted: readonly [1, 2];
+};
+/**
+ * The `Stroke.dash` array for a named style at `width`, or `undefined` for
+ * `solid` — which is stored as no dash at all, not as an empty pattern.
+ *
+ * `custom` has no array of its own and returns `undefined`; a caller that
+ * offers it as a choice should refuse the choice rather than call this.
+ */
+declare function dashForStrokeStyle(style: StrokeDashStyle, width: number | {
+    px: number;
+} | undefined): number[] | undefined;
+/**
+ * The style a stored `dash` reads as at `width`. Absent or empty is `solid`;
+ * an array matching neither preset is `custom`.
+ */
+declare function strokeDashStyleOf(dash: readonly number[] | undefined, width: number | {
+    px: number;
+} | undefined): StrokeDashStyle;
+/** Region a fill is clipped to. */
+interface Region {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    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 };

package/dist/index.js

@@ -0,0 +1,40 @@
+// src/paint.ts
+function alignedStrokeRect(rect, align, width = 1) {
+  if (align === "center") return rect;
+  const sign = align === "inner" ? -1 : 1;
+  const d = sign * width / 2;
+  return {
+    x: rect.x - d,
+    y: rect.y - d,
+    width: rect.width + 2 * d,
+    height: rect.height + 2 * d
+  };
+}
+var STROKE_DASH_RATIOS = {
+  dashed: [3, 2],
+  dotted: [1, 2]
+};
+function dashWidth(width) {
+  const w = typeof width === "object" ? width.px : width ?? 1;
+  return Number.isFinite(w) && w > 0 ? w : 1;
+}
+function dashForStrokeStyle(style, width) {
+  if (style !== "dashed" && style !== "dotted") return void 0;
+  const w = dashWidth(width);
+  return STROKE_DASH_RATIOS[style].map((r) => r * w);
+}
+function strokeDashStyleOf(dash, width) {
+  if (dash === void 0 || dash.length === 0 || dash.every((v) => v === 0)) return "solid";
+  const w = dashWidth(width);
+  for (const style of ["dashed", "dotted"]) {
+    const preset = STROKE_DASH_RATIOS[style];
+    if (dash.length === preset.length && preset.every((r, i) => Math.abs(dash[i] - r * w) <= w * 1e-3)) {
+      return style;
+    }
+  }
+  return "custom";
+}
+
+export { STROKE_DASH_RATIOS, alignedStrokeRect, dashForStrokeStyle, strokeDashStyleOf };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@weasel-js/paint",
+  "version": "1.2.0",
+  "description": "Paint vocabulary for weasel: FillStyle, Stroke, gradients, dashes. Plain data, no renderer.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/paint"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}