@weasel-js/stroke 1.10.1 → 1.11.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Path, PolygonPath, Affine } from '@weasel-js/geom';
-import { ScreenLength, Stroke, MarkerRef } from '@weasel-js/paint';
+import { ScreenLength, Stroke, VertexWidth, StrokeNib, 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';
@@ -164,11 +164,9 @@ declare function tessellateStroke(path: Path, stroke: Stroke, opts?: StrokeOptio
 /**
  * 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.
+ * The "off" portions become invisible gaps. Anchor params and per-point
+ * widths and offsets are carried through: a dash boundary landing mid-segment takes
+ * {@link anchorParamsBetween}'s params and the width interpolated there.
  */
 declare function splitForDash(pl: Polyline, dash: number[]): Polyline[];
 
@@ -176,11 +174,23 @@ declare function splitForDash(pl: Polyline, dash: number[]): Polyline[];
  *  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;
+ *  (anchorA, anchorB, anchorT), each side of the path on its own, and
+ *  `pl.offsets` where the two sides differ. Anchor-aligned points (A === B)
+ *  read the anchor's value directly. Entries resolve through
+ *  `vertexHalfWidths`, so a missing one takes `fallbackWidth`. Given `scale`,
+ *  each entry is scaled at the point that reads it, and the fallback is not. */
+declare function populatePolylineWidths(pl: Polyline, vertexWidths: readonly VertexWidth[], fallbackWidth: number, scale?: WidthScale): void;
+/** The widest a stroke of `width` draws: twice the farthest any edge sits
+ *  from the path. A nib only ever narrows it. */
+declare function widestStrokeWidth(width: number, vertexWidths: readonly VertexWidth[] | undefined): number;
+
+/**
+ * What a nib does to a stroke's width moving along the unit direction
+ * `(tx, ty)`: an elliptical pen whose long axis is the nib's edge, `1` moving
+ * across it and `nib.ratio` moving along it. `angle` is counterclockwise on a
+ * y-down screen, so the edge points along `(cos, -sin)`.
+ */
+declare function nibWidthScale(nib: StrokeNib): WidthScale;
 
 /**
  * The kit's built-in stroke-marker vocabulary.
@@ -295,6 +305,51 @@ declare function markerReach(stroke: Stroke): {
     px: number;
 };
 
+/**
+ * Where a stroke's outline edge runs near a point: what an editor that drags a
+ * stroke's edge hit-tests and measures against.
+ */
+
+/** One side of a stroke's ribbon, as `VertexWidth` names them. */
+type StrokeSide = 'left' | 'right';
+/** A stroke's edge nearest a point, as {@link strokeEdgeNear} finds it. */
+interface StrokeEdgeHit {
+    /** The point on the path's flattening the edge is measured from. */
+    x: number;
+    y: number;
+    /** The unit normal there, pointing from the path toward the edge. */
+    nx: number;
+    ny: number;
+    /** Which edge this is. */
+    side: StrokeSide;
+    /** How far each edge sits from the path there, as drawn: per-vertex widths,
+     *  the nib, and alignment applied. An inner or outer stroke draws one side
+     *  only, the other being the path itself, at 0. */
+    left: number;
+    right: number;
+    /** How far the query point lies outside the edge; negative inside the ink. */
+    gap: number;
+    /** What a stored half-width is multiplied by to give the edge's distance
+     *  there: the nib's factor, doubled for an inner or outer stroke. */
+    factor: number;
+}
+/** Options for {@link strokeEdgeNear}. */
+interface StrokeEdgeOptions {
+    /** Screen pixels per world unit, for a `{ px }` width. Default 1. */
+    scale?: number;
+    flattenTolerance?: number;
+}
+/**
+ * The edge of `stroke`, drawn along `path`, that passes nearest `(x, y)`,
+ * measured along the path's normal: either side of a centered stroke, with
+ * per-vertex widths (each side of a pair on its own) and the nib applied. An
+ * inner or outer stroke is a centered one twice as wide cut to one side of the
+ * path's fill, so its edge is the one on that side, at twice the distance, and
+ * a point on the far side is measured to it across the ink. Caps, joins, and
+ * markers are not considered. `null` when the path has no segment of any length.
+ */
+declare function strokeEdgeNear(path: Path, stroke: Stroke, x: number, y: number, opts?: StrokeEdgeOptions): StrokeEdgeHit | null;
+
 /**
  * A stroke as geometry: the region its ink covers, as a fillable path.
  *
@@ -351,4 +406,4 @@ interface OffsetPathOptions {
  */
 declare function offsetPath(path: Path, distance: number, opts?: OffsetPathOptions): PolygonPath;
 
-export { BUILTIN_MARKERS, type InsetLength, MarkerEntry, type MarkerHead, type MarkerSite, type MarkerSiteRequest, type MeasuredLength, type OffsetPathOptions, type ScreenSpace, type StrokeMetric, type StrokeOptions, type StrokeSpaces, type StrokeToPathOptions, type WidthScale, coordsOutOfMetric, markerHeads, markerInset, markerKeyOf, markerReach, markerReadsKey, markerSites, metricKeepsRects, metricKey, offsetPath, polylineIntoMetric, polylineOutOfMetric, populatePolylineWidths, rectIntoMetric, resolveMarkerSize, resolveStrokeWidth, sameMetric, screenSpaceKey, splitForDash, strokeInsets, strokeSpaceOf, strokeToPath, tessellateStroke, trimInSpace, worldWidthInMetric, worldWidthInMetricAlongWorld };
+export { BUILTIN_MARKERS, type InsetLength, MarkerEntry, type MarkerHead, type MarkerSite, type MarkerSiteRequest, type MeasuredLength, type OffsetPathOptions, type ScreenSpace, type StrokeEdgeHit, type StrokeEdgeOptions, type StrokeMetric, type StrokeOptions, type StrokeSide, type StrokeSpaces, type StrokeToPathOptions, type WidthScale, coordsOutOfMetric, markerHeads, markerInset, markerKeyOf, markerReach, markerReadsKey, markerSites, metricKeepsRects, metricKey, nibWidthScale, offsetPath, polylineIntoMetric, polylineOutOfMetric, populatePolylineWidths, rectIntoMetric, resolveMarkerSize, resolveStrokeWidth, sameMetric, screenSpaceKey, splitForDash, strokeEdgeNear, strokeInsets, strokeSpaceOf, strokeToPath, tessellateStroke, trimInSpace, widestStrokeWidth, worldWidthInMetric, worldWidthInMetricAlongWorld };