@weasel-js/stroke 0.0.0-stage → 1.10.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

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @weasel-js/stroke
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A stroke as geometry: the mesh a renderer draws for it, the marker heads that
+cap it, and the region its ink covers as a path.
+
+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/).
+
+```sh
+npm install @weasel-js/stroke
+```
+
+A path comes from `@weasel-js/geom` and the `Stroke` describing how to draw
+its line from `@weasel-js/paint`. This package turns the pair into triangles or
+into another path. It has no scene graph, no renderer, and no React.
+
+## The ribbon
+
+`tessellateStroke(path, stroke, options)` answers a triangle mesh: width, cap,
+join, miter limit, dash, alignment, and per-vertex widths are all in it.
+`resolveStrokeWidth` turns a `{ px }` width into path units at a given scale.
+
+A stroke that must stay a fixed number of screen pixels wide under a
+non-uniform zoom is built in a *stroke metric*, the linear part of the
+transform it will be drawn through. `strokeSpaceOf` makes one, and the
+`polylineIntoMetric` / `coordsOutOfMetric` family moves points in and out of
+it.
+
+## Markers
+
+A marker is a shape drawn at a stroke's start, end, or interior vertices: an
+arrowhead, a dot, a bar. `registerMarker` adds one under a key, and a `Stroke`
+names it in `markerStart`, `markerMid`, or `markerEnd`. `BUILTIN_MARKERS` lists
+the ones registered from the start.
+
+`markerSites` finds where markers sit along a polyline and at what angle.
+`markerHeads` places each registered shape on its site and answers the
+geometry, unpainted. `markerInset` and `strokeInsets` say how far to pull the
+line back so it ends inside the head, and `markerReach` how far a stroke's
+heads can paint from the vertex they sit on.
+
+## A stroke as a path
+
+`strokeToPath(path, stroke)` answers the outline of everything above as one
+fillable path: the ribbon and its heads, unioned. Curves are flattened, so the
+result holds only straight segments.

package/dist/chunk-FQB7N6YD.js

@@ -0,0 +1,108 @@
+import { PATH_M, PATH_L, PATH_Z } from '@weasel-js/geom';
+import { createReflectable } from '@weasel-js/registry';
+
+// src/strokeMarkerShapes.ts
+function poly(pts, size, close = true) {
+  const n = pts.length / 2;
+  const commands = new Uint8Array(close ? n + 1 : n);
+  commands[0] = PATH_M;
+  for (let i = 1; i < n; i++) commands[i] = PATH_L;
+  if (close) commands[n] = PATH_Z;
+  const coords = new Float32Array(pts.length);
+  for (let i = 0; i < pts.length; i++) coords[i] = pts[i] * size;
+  return { kind: "polygon", commands, coords, fillRule: "nonzero" };
+}
+function circle(cx, r, size, segments = 32) {
+  const pts = [];
+  for (let i = 0; i < segments; i++) {
+    const theta = i / segments * Math.PI * 2;
+    pts.push(cx + r * Math.cos(theta), r * Math.sin(theta));
+  }
+  return poly(pts, size);
+}
+var BUILTIN_MARKERS = [
+  {
+    id: "arrow",
+    reads: [],
+    inset: 3,
+    path: ({ size }) => poly([0, 0, -3, -1.5, -3, 1.5], size)
+  },
+  {
+    id: "arrow-open",
+    reads: [],
+    inset: 0,
+    fill: "none",
+    outline: { width: 1 },
+    // Open at the back, so the ribbon runs to the vertex and the arms meet it.
+    // Arms 3.5 long at ±35°: the back opening is 4 units against 2 units of
+    // arm, so the V still reads open. Shorter or narrower and the two arms
+    // close the gap themselves and it paints as a solid triangle.
+    path: ({ size }) => poly([-2.867, -2.007, 0, 0, -2.867, 2.007], size, false)
+  },
+  {
+    id: "arrow-concave",
+    reads: [],
+    inset: 3,
+    path: ({ size }) => poly([0, 0, -3, -1.5, -2, 0, -3, 1.5], size)
+  },
+  {
+    id: "diamond",
+    reads: [],
+    inset: 4,
+    path: ({ size }) => poly([0, 0, -2, -1.2, -4, 0, -2, 1.2], size)
+  },
+  {
+    id: "diamond-hollow",
+    reads: [],
+    inset: 4,
+    fill: "none",
+    outline: { width: 0.5 },
+    path: ({ size }) => poly([0, 0, -2, -1.2, -4, 0, -2, 1.2], size)
+  },
+  {
+    id: "circle",
+    reads: [],
+    inset: 2,
+    path: ({ size }) => circle(-1, 1, size)
+  },
+  {
+    id: "square",
+    reads: [],
+    inset: 2,
+    path: ({ size }) => poly([0, -1, 0, 1, -2, 1, -2, -1], size)
+  },
+  {
+    id: "bar",
+    reads: [],
+    inset: 0,
+    fill: "none",
+    outline: { width: 1 },
+    path: ({ size }) => poly([0, -1.5, 0, 1.5], size, false)
+  }
+];
+var MARKERS = createReflectable();
+function seedBuiltins() {
+  for (const entry of BUILTIN_MARKERS) MARKERS.push(entry.id, entry, { source: "kit" });
+}
+seedBuiltins();
+var markerRegistry = MARKERS.reflection;
+function markerGeneration() {
+  return MARKERS.getVersion();
+}
+function registerMarker(entry) {
+  return MARKERS.push(entry.id, entry);
+}
+function getMarker(key) {
+  return key === void 0 ? void 0 : MARKERS.get(key);
+}
+function listMarkers() {
+  return MARKERS.entries().map((e) => e.value);
+}
+function _resetMarkersForTests() {
+  MARKERS.clear();
+  seedBuiltins();
+}
+
+export { BUILTIN_MARKERS, _resetMarkersForTests, getMarker, listMarkers, markerGeneration, markerRegistry, registerMarker };
+//# sourceMappingURL=chunk-FQB7N6YD.js.map
+//# sourceMappingURL=chunk-FQB7N6YD.js.map

package/dist/chunk-FQB7N6YD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/strokeMarkerShapes.ts","../src/strokeMarkers.ts"],"names":[],"mappings":"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","file":"chunk-FQB7N6YD.js","sourcesContent":["/**\n * The kit's built-in stroke-marker vocabulary.\n *\n * Every entry is authored with its anchor at the origin and pointing +X, so\n * the line arrives from -X and no geometry sits at positive X. Coordinates are\n * in units of `MarkerCtx.size`, which defaults to the resolved stroke width —\n * one definition is therefore correct at any line weight.\n *\n * Not to be confused with `features/paths/markers.ts`, which builds\n * decorative chrome shapes and is unrelated.\n */\n\nimport { PATH_M, PATH_L, PATH_Z, type PolygonPath } from '@weasel-js/geom';\nimport type { MarkerCtx, MarkerEntry } from './strokeMarkers';\n\nfunction poly(pts: readonly number[], size: number, close = true): PolygonPath {\n  const n = pts.length / 2;\n  const commands = new Uint8Array(close ? n + 1 : n);\n  commands[0] = PATH_M;\n  for (let i = 1; i < n; i++) commands[i] = PATH_L;\n  if (close) commands[n] = PATH_Z;\n  const coords = new Float32Array(pts.length);\n  for (let i = 0; i < pts.length; i++) coords[i] = pts[i] * size;\n  return { kind: 'polygon', commands, coords, fillRule: 'nonzero' };\n}\n\n/** Circle of radius `r` centred at `cx`, in marker units. */\nfunction circle(cx: number, r: number, size: number, segments = 32): PolygonPath {\n  const pts: number[] = [];\n  for (let i = 0; i < segments; i++) {\n    const theta = (i / segments) * Math.PI * 2;\n    pts.push(cx + r * Math.cos(theta), r * Math.sin(theta));\n  }\n  return poly(pts, size);\n}\n\n/** The markers the registry is seeded with: `arrow`, `arrow-open`,\n *  `arrow-concave`, `diamond`, `diamond-hollow`, `circle`, `square` and `bar`. */\nexport const BUILTIN_MARKERS: readonly MarkerEntry[] = [\n  {\n    id: 'arrow',\n    reads: [],\n    inset: 3,\n    path: ({ size }: MarkerCtx) => poly([0, 0, -3, -1.5, -3, 1.5], size),\n  },\n  {\n    id: 'arrow-open',\n    reads: [],\n    inset: 0,\n    fill: 'none',\n    outline: { width: 1 },\n    // Open at the back, so the ribbon runs to the vertex and the arms meet it.\n    // Arms 3.5 long at ±35°: the back opening is 4 units against 2 units of\n    // arm, so the V still reads open. Shorter or narrower and the two arms\n    // close the gap themselves and it paints as a solid triangle.\n    path: ({ size }: MarkerCtx) =>\n      poly([-2.867, -2.007, 0, 0, -2.867, 2.007], size, false),\n  },\n  {\n    id: 'arrow-concave',\n    reads: [],\n    inset: 3,\n    path: ({ size }: MarkerCtx) => poly([0, 0, -3, -1.5, -2, 0, -3, 1.5], size),\n  },\n  {\n    id: 'diamond',\n    reads: [],\n    inset: 4,\n    path: ({ size }: MarkerCtx) => poly([0, 0, -2, -1.2, -4, 0, -2, 1.2], size),\n  },\n  {\n    id: 'diamond-hollow',\n    reads: [],\n    inset: 4,\n    fill: 'none',\n    outline: { width: 0.5 },\n    path: ({ size }: MarkerCtx) => poly([0, 0, -2, -1.2, -4, 0, -2, 1.2], size),\n  },\n  {\n    id: 'circle',\n    reads: [],\n    inset: 2,\n    path: ({ size }: MarkerCtx) => circle(-1, 1, size),\n  },\n  {\n    id: 'square',\n    reads: [],\n    inset: 2,\n    path: ({ size }: MarkerCtx) => poly([0, -1, 0, 1, -2, 1, -2, -1], size),\n  },\n  {\n    id: 'bar',\n    reads: [],\n    inset: 0,\n    fill: 'none',\n    outline: { width: 1 },\n    path: ({ size }: MarkerCtx) => poly([0, -1.5, 0, 1.5], size, false),\n  },\n];\n","/**\n * The stroke-marker registry — arrowheads and other line terminators.\n *\n * Keyed by string, because a key is what sits in `stroke.markerEnd`. That is\n * the difference from `registerNodeShape`, which resolves by first-matching\n * predicate and whose `id` is only a label.\n *\n * A built-in's SVG slot lives in `@weasel-js/svg` and cannot be imported here\n * without inverting a package dependency, so an entry carries `toSvg` for that\n * package to consume — the same split `PaintKindEntry` uses.\n */\n\nimport type { Paint, MarkerKey, Stroke } from '@weasel-js/paint';\nimport type { Path } from '@weasel-js/geom';\nimport { createReflectable, type Reflection } from '@weasel-js/registry';\nimport { BUILTIN_MARKERS } from './strokeMarkerShapes';\n\n/** What an entry's `path` is given. Entries that ignore it may return a\n *  constant path. */\nexport interface MarkerCtx {\n  /** One geometry unit, in the same world units the ribbon is tessellated in.\n   *  Defaults to the resolved stroke width. */\n  readonly size: number;\n  /** The stroke this marker belongs to, already width-resolved. */\n  readonly stroke: Stroke;\n}\n\n/** `'line'` means the stroke's own paint — SVG 2's `context-stroke`, as the\n *  default rather than an opt-in. */\nexport type MarkerPaint = Paint | 'line' | 'none';\n\n/** A stroke-marker registry entry: a terminator's geometry, paint and inset. */\nexport interface MarkerEntry {\n  /** `'kit:'`-free for built-ins so the key matches the SVG attribute value;\n   *  consumers should prefix (`'app-my-head'`). A key becomes the `id` of the\n   *  emitted `<marker>` def, so it must be a valid XML name — no colons. */\n  id: MarkerKey;\n  /** Geometry with its anchor at the origin, pointing +X, in units of\n   *  `ctx.size`. An arbitrary anchor is expressed by where the geometry is\n   *  drawn, which is why there is no `refX`/`refY`. */\n  path(ctx: MarkerCtx): Path;\n  /** Default `'line'`. */\n  fill?: MarkerPaint;\n  /** Outline width is in the same units as `path`. `false` (the default)\n   *  means no outline. */\n  outline?: { width: number; paint?: MarkerPaint } | false;\n  /** How far back along the line the stroke stops, in units of `ctx.size`.\n   *  Default 0. A property of the shape, not a setting on the stroke: an open\n   *  V needs 0 or its arms stop meeting the line. */\n  inset?: number;\n  /** `'auto'` (default) follows the line; a number is a fixed angle in\n   *  radians, ignoring the line — SVG's `orient=\"<angle>\"`. */\n  orient?: 'auto' | number;\n  /** The stroke fields `path` reads besides `ctx.size` — `[]` for a shape\n   *  drawn from size alone. Declared, a head is reused across stroke objects\n   *  whose listed fields are equal; omitted, only across frames that pass the\n   *  same stroke object, since `path` might read any of it. */\n  reads?: readonly (keyof Stroke)[];\n  /** Emits the `<marker>` def. Consumed by `@weasel-js/svg`. */\n  toSvg?(id: string, entry: MarkerEntry): string;\n}\n\nconst MARKERS = createReflectable<MarkerEntry>();\n\nfunction seedBuiltins(): void {\n  for (const entry of BUILTIN_MARKERS) MARKERS.push(entry.id, entry, { source: 'kit' });\n}\nseedBuiltins();\n\n/** Every registered marker, with the overrides each displaced. */\nexport const markerRegistry: Reflection<MarkerEntry> = MARKERS.reflection;\n\n/** Bumped whenever the registered set changes, for caches of marker geometry. */\nexport function markerGeneration(): number {\n  return MARKERS.getVersion();\n}\n\n/** Register a marker. Returns a disposer. Re-registering an existing id is an\n *  override; disposing it uncovers whatever it displaced rather than deleting the key. */\nexport function registerMarker(entry: MarkerEntry): () => void {\n  return MARKERS.push(entry.id, entry);\n}\n\n/** The entry for `key`, or `undefined`. */\nexport function getMarker(key: string | undefined): MarkerEntry | undefined {\n  return key === undefined ? undefined : MARKERS.get(key);\n}\n\n/** Every registered marker, built-ins first, in registration order. */\nexport function listMarkers(): readonly MarkerEntry[] {\n  return MARKERS.entries().map((e) => e.value);\n}\n\n/** Test helper. Do not call from product code. */\nexport function _resetMarkersForTests(): void {\n  MARKERS.clear();\n  seedBuiltins();\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,331 @@
+import { Path, PolygonPath, Mat3 } from '@weasel-js/geom';
+import { ScreenLength, Stroke, MarkerRef } from '@weasel-js/paint';
+import { Polyline, Mesh } from '@weasel-js/geom/tessellate';
+import { M as MarkerEntry } from './test-seams-D-zMT-bn.js';
+export { a as MarkerCtx, b as MarkerPaint, g as getMarker, l as listMarkers, m as markerGeneration, c as markerRegistry, r as registerMarker } from './test-seams-D-zMT-bn.js';
+import '@weasel-js/registry';
+
+/**
+ * The space a screen-pixel stroke is built in.
+ *
+ * A `{ px }` stroke is exact on screen only when its ribbon is offset in a
+ * space that measures lengths the way the screen does. The transform's linear
+ * part is `scale · R · P`: a uniform scale, a rotation (or reflection) that
+ * moves no lengths, and `P`, the symmetric unit-determinant stretch left over.
+ * Offsetting the ribbon after `P` and mapping it back through `P⁻¹` gives a
+ * world-space mesh that the full transform turns into a ribbon of exactly
+ * `width · scale` pixels in every direction — and keeps the mesh drawable by
+ * every path that draws a world-space ribbon.
+ *
+ * `P` depends only on the lengths the transform induces (`LᵀL`), not on any
+ * rotation applied after it, so a view that only pans or zooms uniformly keeps
+ * the same metric and the ribbon cache keeps hitting.
+ */
+
+/** `P` = [[p, q], [q, r]], with `pr − q² = 1`. */
+interface StrokeMetric {
+    readonly p: number;
+    readonly q: number;
+    readonly r: number;
+}
+/** A space a screen-sized part of a stroke is built in: the metric, and how
+ *  many screen pixels one of its units is. */
+interface ScreenSpace {
+    readonly metric: StrokeMetric;
+    readonly pxPerUnit: number;
+}
+/**
+ * Where each part of a stroke is built. An absent part is built in world:
+ * everything is under a similarity, and otherwise a part whose size is a world
+ * length. The ribbon is screen-sized for a `{ px }` width; a head for a
+ * `{ px }` size, or for no size on a screen-sized ribbon, since it then takes
+ * the stroke width.
+ */
+interface StrokeSpaces {
+    readonly ribbon?: ScreenSpace;
+    readonly start?: ScreenSpace;
+    readonly mid?: ScreenSpace;
+    readonly end?: ScreenSpace;
+}
+/** A cache-key fragment naming `space`; empty for world. */
+declare function screenSpaceKey(space: ScreenSpace | undefined): string;
+/**
+ * Split the linear map `x' = a·x + c·y, y' = b·x + d·y` — a GL `mat3`'s
+ * `m[0], m[1], m[3], m[4]` — into its geometric-mean scale and its stroke
+ * metric. `metric` is `null` when the map is a similarity, where world space
+ * already measures like the screen; `scale` is `0` for a singular map.
+ */
+declare function strokeSpaceOf(a: number, b: number, c: number, d: number): {
+    scale: number;
+    metric: StrokeMetric | null;
+};
+/** A cache-key fragment naming `metric`; empty for none. */
+declare function metricKey(metric: StrokeMetric | undefined): string;
+/** Map `pl`'s points through `P`, in place. */
+declare function polylineIntoMetric(pl: Polyline, m: StrokeMetric): void;
+/** Map `pl`'s points back out through `P⁻¹`, in place. */
+declare function polylineOutOfMetric(pl: Polyline, m: StrokeMetric): void;
+/** Whether two spaces are the same — world being `null`. */
+declare function sameMetric(a: StrokeMetric | null, b: StrokeMetric | null): boolean;
+/**
+ * What one world unit of width, across a line running along the unit
+ * direction `(tx, ty)` of the metric's own space, measures in that space.
+ * `P` keeps areas, so a strip keeps its area while its length stretches by
+ * `|P u|` (`u` the line's world direction): its width shrinks by the same,
+ * and `1 / |P u|` is `|P⁻¹ t|`.
+ */
+declare function worldWidthInMetric(m: StrokeMetric, tx: number, ty: number): number;
+/** The same, for a line running along the unit world direction `(ux, uy)`. */
+declare function worldWidthInMetricAlongWorld(m: StrokeMetric, ux: number, uy: number): number;
+/** Map interleaved x,y pairs back out through `P⁻¹` = [[r, −q], [−q, p]], in
+ *  place. */
+declare function coordsOutOfMetric(coords: Float32Array, m: StrokeMetric): void;
+/** Whether `P` takes an axis-aligned rect to another one. */
+declare function metricKeepsRects(m: StrokeMetric): boolean;
+/** `rect` in the metric's space, while `P` keeps it axis-aligned; otherwise
+ *  `null`, and the rect has to be carried as a polygon. */
+declare function rectIntoMetric(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, m: StrokeMetric): {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Trimming a stroke's ends where each inset is measured.
+ *
+ * A head stops the line by a length in the head's own space, which need not be
+ * the ribbon's: a world-sized head on a `{ px }` stroke stops it a world
+ * distance short, a `{ px }` head on a world-width stroke a screen distance.
+ * Under a stretching view one length means different distances in the two
+ * spaces depending on which way the line runs, so each end is trimmed in its
+ * own space rather than converted.
+ */
+
+/** A length along the line measured in `metric`'s space, or in world where
+ *  `metric` is `null`. */
+interface MeasuredLength {
+    readonly length: number;
+    readonly metric: StrokeMetric | null;
+}
+/** A plain number is a length in the ribbon's own space. */
+type InsetLength = number | MeasuredLength;
+/**
+ * `pl`, whose points are in `from`'s space, trimmed by `start` and `end` and
+ * carried into `ribbon`'s — `null` for world in both. `pl` may be mapped in
+ * place. Returns `null` when the insets consume the whole run.
+ */
+declare function trimInSpace(pl: Polyline, from: StrokeMetric | null, ribbon: StrokeMetric | null, start: InsetLength | undefined, end: InsetLength | undefined): Polyline | null;
+
+/** Options for stroke tessellation. */
+interface StrokeOptions {
+    flattenTolerance?: number;
+    /**
+     * Shorten each open subpath by this much at its start / end: a length in
+     * the ribbon's space, or one measured in a space of its own. Stroke markers
+     * use this so a filled head is not speared by its own line; the caller
+     * resolves the distance, because this layer knows nothing about the marker
+     * registry.
+     */
+    startInset?: InsetLength;
+    endInset?: InsetLength;
+    /**
+     * Build the ribbon in this metric's space and map it back out, so the
+     * transform it was derived from draws it at an exact screen width — see
+     * `./metric`. Width and dash are then lengths in that space; `vertexWidths`
+     * stay world widths. The path is flattened in world first, so the ribbon
+     * follows the same vertices its fill does.
+     */
+    metric?: StrokeMetric;
+}
+/** Resolve a stroke width to world units. A number is already world units;
+ *  `{ px }` is screen pixels divided by the accumulated scale, so it holds its
+ *  on-screen thickness as the view zooms. */
+declare function resolveStrokeWidth(width: ScreenLength, scale: number): number;
+/**
+ * Build a triangle-mesh ribbon from a stroked Path.
+ *
+ * Supports:
+ *   - cap: 'butt' | 'round' | 'square'
+ *   - join: 'miter' | 'round' | 'bevel'
+ *   - center alignment directly; RectPath inner/outer alignment via a
+ *     pre-shifted rect; PolygonPath inner/outer alignment via stencil at the
+ *     renderer level
+ *   - dash splitting
+ */
+declare function tessellateStroke(path: Path, stroke: Stroke, opts?: StrokeOptions): Mesh;
+
+/**
+ * Split a polyline into open sub-polylines for the "on" portions of a dash
+ * pattern. Each output sub-polyline gets caps from the stroke's `cap` setting.
+ * The "off" portions become invisible gaps. Anchor params are carried through:
+ * sub-polyline endpoints inherit their source polyline-point's anchor params;
+ * dash boundaries that land mid-segment (between two polyline points) snap
+ * their anchor params to whichever endpoint they're closer to when the
+ * segment crosses a path-anchor boundary, otherwise interpolate `t` linearly.
+ */
+declare function splitForDash(pl: Polyline, dash: number[]): Polyline[];
+
+/** What one unit of a `vertexWidths` entry measures across the line at a
+ *  point whose unit tangent, in the polyline's own space, is `(tx, ty)`. */
+type WidthScale = (tx: number, ty: number) => number;
+/** Fill `pl.widths` by interpolating `vertexWidths` across each point's
+ *  (anchorA, anchorB, anchorT). Anchor-aligned points (A === B) read the
+ *  anchor's value directly. Out-of-range / non-finite anchor entries fall
+ *  back to `fallbackWidth`. Given `scale`, each entry is scaled at the point
+ *  that reads it, and the fallback is not. */
+declare function populatePolylineWidths(pl: Polyline, vertexWidths: number[], fallbackWidth: number, scale?: WidthScale): void;
+
+/**
+ * The kit's built-in stroke-marker vocabulary.
+ *
+ * Every entry is authored with its anchor at the origin and pointing +X, so
+ * the line arrives from -X and no geometry sits at positive X. Coordinates are
+ * in units of `MarkerCtx.size`, which defaults to the resolved stroke width —
+ * one definition is therefore correct at any line weight.
+ *
+ * Not to be confused with `features/paths/markers.ts`, which builds
+ * decorative chrome shapes and is unrelated.
+ */
+
+/** The markers the registry is seeded with: `arrow`, `arrow-open`,
+ *  `arrow-concave`, `diamond`, `diamond-hollow`, `circle`, `square` and `bar`. */
+declare const BUILTIN_MARKERS: readonly MarkerEntry[];
+
+/**
+ * Resolving a `MarkerRef` to the distance the ribbon must stop short.
+ *
+ * The tessellation layer takes these as plain numbers and knows nothing about
+ * the registry — keeping that layer free of upward dependencies is deliberate.
+ * The ribbon cache, the SVG serializer and `inkReach` all resolve through here,
+ * so the ribbon, the export and the hit region cannot disagree about where the
+ * line ends.
+ */
+
+/** The size of one marker unit, in the same world units as `strokeWidth`.
+ *  `scale` is the view scale a `{ px }` size resolves against, as a `{ px }`
+ *  stroke width does. */
+declare function resolveMarkerSize(ref: MarkerRef, strokeWidth: number, scale?: number): number;
+/** The registry key a `MarkerRef` names, whether given bare or with a size. */
+declare function markerKeyOf(ref: MarkerRef): string;
+/**
+ * How far back the ribbon stops for `ref`, in world units. Zero for an absent
+ * marker, an unregistered key, or an open head — never throws, because an
+ * unknown key is a data problem and dropping the head is the graceful answer.
+ */
+declare function markerInset(ref: MarkerRef | undefined, strokeWidth: number, scale?: number): number;
+/** The start and end insets a stroke asks for. `markerMid` never insets —
+ *  trimming at an interior vertex would cut the line in two. */
+declare function strokeInsets(stroke: Stroke, strokeWidth: number): {
+    start: number;
+    end: number;
+};
+
+/**
+ * Where a stroke's markers sit and which way they point.
+ *
+ * Computed from the *untrimmed* polyline: trimming moves the endpoint, and a
+ * marker anchors to where the line was authored to end, not to where the
+ * ribbon was cut.
+ */
+
+/** One marker placement, in the polyline's own coordinates. */
+interface MarkerSite {
+    x: number;
+    y: number;
+    /** Radians. The direction the marker's +X axis should point — outward at a
+     *  start or end, along the bisector at an interior vertex. */
+    angle: number;
+    role: 'start' | 'mid' | 'end';
+}
+/** Which marker roles to place. `start` and `end` are ignored on a closed polyline. */
+interface MarkerSiteRequest {
+    start: boolean;
+    mid: boolean;
+    end: boolean;
+}
+/**
+ * Where each requested marker sits on `pl` and the angle it points at.
+ * Mid sites fall only on authored vertices, never on flattened curve samples,
+ * and need the polyline to carry anchor data; without it no mid sites are returned.
+ */
+declare function markerSites(pl: Polyline, want: MarkerSiteRequest): MarkerSite[];
+
+/**
+ * A stroke's marker heads as placed geometry, and how far they reach.
+ */
+
+/** One head's placed geometry, before any paint is applied. */
+interface MarkerHead {
+    readonly entry: MarkerEntry;
+    readonly path: PolygonPath;
+    readonly size: number;
+    /** Where it was built, when not in world — `size` is in this space's units. */
+    readonly space?: ScreenSpace;
+}
+/**
+ * Every marker head for `path` under `stroke`, placed but unpainted.
+ * `strokeWidth` is the already width-resolved stroke width; `flattenTolerance`
+ * matches what the ribbon used, so heads land on the same flattened vertices
+ * the stroke did. A head `spaces` puts in a screen space is placed and sized
+ * there and comes back in world units, so it meets the line it caps.
+ */
+declare function markerHeads(path: Path, stroke: Stroke, strokeWidth: number, flattenTolerance: number | undefined, spaces?: StrokeSpaces): MarkerHead[];
+/**
+ * A key for the stroke fields `entry`'s geometry reads, or `null` when the
+ * entry does not say which it reads and only the stroke's identity can stand
+ * in for them.
+ */
+declare function markerReadsKey(entry: MarkerEntry, stroke: Stroke): string | null;
+/**
+ * How far `stroke`'s markers can paint from the vertex each sits on, split by
+ * where each is built: `world` in world units for a head with a world size,
+ * `px` in screen pixels for one with a `{ px }` size. A head with no size
+ * takes the stroke width, and with it the width's units. Culling and a path
+ * node's grab reach both measure through here.
+ */
+declare function markerReach(stroke: Stroke): {
+    world: number;
+    px: number;
+};
+
+/**
+ * A stroke as geometry: the region its ink covers, as a fillable path.
+ *
+ * The ribbon the renderer draws already has the joins, caps, dashes, and
+ * marker trims; unioning its triangles gives the silhouette with every
+ * self-overlap resolved, so the outline and the drawn stroke cannot disagree.
+ */
+
+/** Options for {@link strokeToPath}. */
+interface StrokeToPathOptions {
+    /** Screen pixels per world unit, for a `{ px }` width or marker size.
+     *  Default 1. */
+    scale?: number;
+    /** Flatness tolerance for curves, in the path's units. */
+    flattenTolerance?: number;
+    /**
+     * The frame the stroke is drawn in, as the matrix taking that frame to the
+     * path's coordinates: a node's `poseFrameOf`. A frame that skews or
+     * stretches does the same to the stroke, as it does on the canvas. For a
+     * `{ px }` width under a view that scales each axis apart, the frame is the
+     * screen: the inverse of the view's scale, with `scale` left at 1.
+     */
+    frame?: Mat3;
+}
+/**
+ * The region `stroke` covers when drawn along `path`, as a path to fill:
+ * width, cap, join, miter limit, dash, alignment, per-vertex widths, and
+ * marker heads all included. Curves are flattened, so the result holds only
+ * M/L/Z. A stroke with no width answers an empty path, and so does one drawn
+ * in a `frame` that flattens it.
+ */
+declare function strokeToPath(path: Path, stroke: Stroke, opts?: StrokeToPathOptions): PolygonPath;
+
+export { BUILTIN_MARKERS, type InsetLength, MarkerEntry, type MarkerHead, type MarkerSite, type MarkerSiteRequest, type MeasuredLength, type ScreenSpace, type StrokeMetric, type StrokeOptions, type StrokeSpaces, type StrokeToPathOptions, type WidthScale, coordsOutOfMetric, markerHeads, markerInset, markerKeyOf, markerReach, markerReadsKey, markerSites, metricKeepsRects, metricKey, polylineIntoMetric, polylineOutOfMetric, populatePolylineWidths, rectIntoMetric, resolveMarkerSize, resolveStrokeWidth, sameMetric, screenSpaceKey, splitForDash, strokeInsets, strokeSpaceOf, strokeToPath, tessellateStroke, trimInSpace, worldWidthInMetric, worldWidthInMetricAlongWorld };