@underlying/svg 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) underlyi.ng
+
+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,113 @@
+<p align="center">
+  <img alt="underlying" src="https://underlyi.ng/wordmark-sapin.svg" width="280" />
+</p>
+
+<p align="center">
+  <strong>Ride an element along a path, or draw a stroke on - on live physics.</strong>
+</p>
+
+<p align="center">
+  <a href="https://underlyi.ng"><img alt="docs" src="https://img.shields.io/badge/docs-underlyi.ng-1C3426" /></a>
+  <img alt="svg gzip" src="https://img.shields.io/badge/svg-~1.6%20kB%20gzip-1C3426" />
+  <img alt="built on" src="https://img.shields.io/badge/built%20on-%40underlying%2Fcore-1C3426" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-1C3426" />
+</p>
+
+> Beta. The API may still move before 1.0.
+
+SVG path animation for [`@underlying/core`](https://github.com/underlyingjs/underlying/tree/main/packages/core) - MotionPath, DrawSVG, and a resampling morph. The progress of each is a single live value, so where other libraries bake a path tween, here you can flick a marker down a path and let it settle, interrupt a stroke mid-draw, scrub a morph, or hand the same progress to scroll. No new engine: it samples the path with the native `getPointAtLength`/`getTotalLength` and drives core's `animatable`.
+
+```sh
+npm install @underlying/svg @underlying/core
+```
+
+## `motionPath()`
+
+Ride an element along a path. Progress `t` is a live `Animatable`, so spring it, flick it, or retarget it mid-flight - velocity is conserved across the change. `autoRotate` turns the element to face along the path.
+
+```ts
+import { motionPath } from '@underlying/svg'
+
+const ride = motionPath(marker, '#track', { autoRotate: true })
+
+ride.spring(1)               // travel to the end with a real spring
+ride.flick(2.4)              // fling it down the path; it decays to a stop
+ride.spring(0.4)             // retarget mid-flight, momentum kept
+
+ride.t                       // the live 0..1 Animatable - compose it (scroll, timeline)
+ride.revert()                // unbind and restore the element's transform
+```
+
+## `draw()`
+
+Draw a stroke on (0 = hidden, 1 = fully drawn). The fraction is a live `Animatable` too - it can overshoot, and you can interrupt it mid-draw.
+
+```ts
+import { draw } from '@underlying/svg'
+
+const line = draw('#signature')
+line.spring(1)               // draw it on
+line.to(0, { duration: 400 })// erase with a timed tween, still interruptible
+```
+
+## `morph()`
+
+Turn one shape into another. Both outlines are resampled into points along their length and interpolated, so *any* two paths morph - you do not have to match their commands by hand. The fraction is live, so you can scrub it or grab it mid-morph.
+
+```ts
+import { morph } from '@underlying/svg'
+
+const m = morph(blob, starPathData, { closed: true })  // target: a `d` string or an element
+m.spring(1)   // morph to the star
+m.spring(0)   // morph back - interruptible
+m.set(0.5)    // hold it halfway
+```
+
+This is a resampling morph (smooth, handles arbitrary shapes); full command-preserving MorphSVG - sharp-corner fidelity and `shapeIndex` - is future work.
+
+## The familiar one-call form
+
+Both accept a `{ to }` kickoff that reads like `gsap.to(el, { motionPath })` or `{ drawSVG }` - but springs under the hood, and the handle is still there for the live wins.
+
+```ts
+motionPath(marker, '#track', { to: 1, autoRotate: true })
+draw('#signature', { to: 1 })
+```
+
+## Composing - drive the same path from scroll or a timeline
+
+`motionPath` and `draw` own a driver `Animatable` (`.t` / `.fraction`) you can hand to anything that drives a value.
+
+```ts
+import { motionPath } from '@underlying/svg'
+import { createScroll } from '@underlying/scroll'
+
+const ride = motionPath(marker, '#track', { autoRotate: true })
+createScroll({ scroller }).scrub(ride.t)   // marker follows the path as you scroll
+```
+
+## Bring your own driver
+
+The handles are built on thin binders. If you already have an `Animatable` (or want to control the value yourself, GSAP-style), bind it directly:
+
+```ts
+import { bindPath, bindDraw, samplePath } from '@underlying/svg'
+import { animatable } from '@underlying/core'
+
+const t = animatable(0)
+bindPath(marker, '#track', t, { autoRotate: true }) // maps t -> transform
+t.decay({ velocity: 2.4 })
+
+samplePath('#track').at(0.5)  // low-level: { x, y, angle } at progress 0.5
+```
+
+## Notes
+
+- **Reduced motion** is inherited from core: a `spring`/`decay`/`to` on the driver auto-degrades under `prefers-reduced-motion`, so the element jumps to the target with no travel.
+- **Coordinate space.** `motionPath` writes the sampled point straight to the element's `transform`, so the element and the path should share a coordinate space (e.g. both inside the same SVG, or the element absolutely positioned over it).
+- **SSR.** Sampling needs the DOM; pass an element rather than a selector on the server, or call from an effect.
+- **Morph** here resamples both outlines into points and interpolates - it handles any two shapes, but it is not yet the full command-preserving MorphSVG (sharp corners can soften; raise `samples` for fidelity).
+
+## License
+
+MIT (c) underlyi.ng

package/dist/draw.d.ts

@@ -0,0 +1,37 @@
+import { type Animatable, type Scheduler } from '@underlying/core';
+import { type ScalarControls } from './handle';
+/** An element that can be stroke-drawn: reports its length and has a writable style. */
+export interface DrawElement {
+    getTotalLength(): number;
+    style: {
+        strokeDasharray: string;
+        strokeDashoffset: string;
+    };
+}
+/** A draw source: a CSS selector or a stroked geometry element. */
+export type DrawInput = string | DrawElement;
+export interface DrawOptions {
+    /** Scheduler driving the value and the style flush. Defaults to the shared one. */
+    scheduler?: Scheduler;
+    /** Initial draw fraction, 0..1 (0 hidden, 1 drawn). Default 0. */
+    from?: number;
+    /** Spring to this fraction on creation - the GSAP-familiar one-call form. */
+    to?: number;
+}
+/**
+ * Low-level binder: map a driver Animatable (0..1) onto an element's stroke
+ * draw-on (0 = hidden, 1 = fully drawn) via stroke-dasharray/offset. You own the
+ * driver. Returns an unbind fn that restores the original dash properties.
+ */
+export declare function bindDraw(path: DrawInput, source: Animatable, options?: DrawOptions): () => void;
+export interface Draw extends ScalarControls {
+    /** The live 0..1 draw fraction (0 hidden, 1 drawn). Compose it anywhere. */
+    readonly fraction: Animatable;
+}
+/**
+ * Draw a stroke on, physics-first. The fraction is a live Animatable - spring it
+ * in (it can overshoot), interrupt it mid-draw, flick it, or scrub it from
+ * scroll. Restores the original stroke-dash properties on revert().
+ */
+export declare function draw(path: DrawInput, options?: DrawOptions): Draw;
+//# sourceMappingURL=draw.d.ts.map

package/dist/draw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAClG,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9D,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,cAAc,IAAI,MAAM,CAAA;IACxB,KAAK,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7D;AAED,mEAAmE;AACnE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,CAAA;AAE5C,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAcD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,IAAI,CAuCnG;AAED,MAAM,WAAW,IAAK,SAAQ,cAAc;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAA;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,WAAgB,GAAG,IAAI,CAgBrE"}

package/dist/geometry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A subset of SVGGeometryElement: anything that can report its length and sample
+ * a point at a given arc distance. Real `<path>`/`<line>`/`<polyline>` elements
+ * satisfy it natively; tests pass a plain object.
+ */
+export interface PathGeometry {
+    getTotalLength(): number;
+    getPointAtLength(distance: number): {
+        x: number;
+        y: number;
+    };
+}
+/** A path source: a CSS selector or any geometry element/object. */
+export type PathInput = string | PathGeometry;
+/** A sampled point on a path: position plus the tangent direction (degrees). */
+export interface PathPoint {
+    x: number;
+    y: number;
+    /** tangent direction in degrees, fed to autoRotate */
+    angle: number;
+}
+export interface SamplePathOptions {
+    /**
+     * Distance, as a fraction of total length, used to estimate the tangent angle
+     * from two neighbouring samples. Smaller is sharper but noisier. Default 0.001.
+     */
+    tangentEpsilon?: number;
+}
+export interface PathSampler {
+    /** Total path length, in the path's user units. */
+    readonly length: number;
+    /** Point at progress t (clamped to 0..1), with the tangent angle. */
+    at(t: number): PathPoint;
+}
+/** Resolve a {@link PathInput} to a geometry source (querySelector for strings). */
+export declare function resolvePathGeometry(path: PathInput): PathGeometry;
+/**
+ * Wrap a path in a length-normalized sampler: feed it t in 0..1 and read back the
+ * point plus tangent angle. Total length is measured once; each `at()` is two
+ * getPointAtLength() reads (the point, and a neighbour for the tangent).
+ */
+export declare function samplePath(path: PathInput, options?: SamplePathOptions): PathSampler;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../src/geometry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc,IAAI,MAAM,CAAA;IACxB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7D;AAED,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,CAAA;AAE7C,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAID,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAQjE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,GAAG,WAAW,CAgBxF"}

package/dist/handle.d.ts

@@ -0,0 +1,27 @@
+import type { Animatable, AnimationHandle, DecayOptions, SpringOptions, ToOptions } from '@underlying/core';
+/**
+ * The physics verbs every @underlying/svg handle shares. They delegate straight
+ * to the live driver Animatable, so a motionPath or a draw is interruptible and
+ * retargetable at any moment - the same engine as the rest of core.
+ */
+export interface ScalarControls {
+    /** Spring the driver toward a target (0..1), interruptible, velocity conserved. */
+    spring(target: number, options?: SpringOptions): AnimationHandle;
+    /** Glide on inertia from the current velocity, clamped to 0..1. */
+    decay(options?: DecayOptions): AnimationHandle;
+    /** Duration/easing escape hatch - still interruptible. */
+    to(target: number, options?: ToOptions): AnimationHandle;
+    /** Teleport the driver (no animation). */
+    set(value: number): void;
+    /** Flick: seed a velocity (0..1 units/s) and let it decay to a stop on the path. */
+    flick(velocity: number, options?: Omit<DecayOptions, 'velocity'>): AnimationHandle;
+    /** Freeze in place; position and velocity stay readable. */
+    stop(): void;
+    /** Read the driver, 0..1. */
+    progress(): number;
+    /** Stop, unbind, and restore the element to its pre-bind state. */
+    revert(): void;
+}
+/** Build the shared verb surface around a driver value, plus a revert. */
+export declare function scalarControls(value: Animatable, revert: () => void): ScalarControls;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE3G;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,eAAe,CAAA;IAChE,mEAAmE;IACnE,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,eAAe,CAAA;IAC9C,0DAA0D;IAC1D,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,eAAe,CAAA;IACxD,0CAA0C;IAC1C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,oFAAoF;IACpF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,eAAe,CAAA;IAClF,4DAA4D;IAC5D,IAAI,IAAI,IAAI,CAAA;IACZ,6BAA6B;IAC7B,QAAQ,IAAI,MAAM,CAAA;IAClB,mEAAmE;IACnE,MAAM,IAAI,IAAI,CAAA;CACf;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,cAAc,CAWpF"}

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const h=require("@underlying/core"),L=t=>t<0?0:t>1?1:t;function $(t){if(typeof t!="string")return t;if(typeof document>"u")throw new Error("@underlying/svg: a selector needs a DOM; pass an element on the server");const r=document.querySelector(t);if(r===null)throw new Error(`@underlying/svg: no element matches "${t}"`);return r}function M(t,r={}){const e=$(t),n=e.getTotalLength(),s=(r.tangentEpsilon??.001)*n||1e-4;return{length:n,at(l){const a=L(l)*n,d=e.getPointAtLength(a),u=e.getPointAtLength(Math.max(0,a-s)),o=e.getPointAtLength(Math.min(n,a+s)),c=Math.atan2(o.y-u.y,o.x-u.x)*180/Math.PI;return{x:d.x,y:d.y,angle:c}}}}function x(t,r){return{spring:(e,n)=>t.spring(e,n),decay:e=>t.decay(e),to:(e,n)=>t.to(e,n),set:e=>t.set(e),flick:(e,n)=>t.decay({min:0,max:1,...n,velocity:e}),stop:()=>t.stop(),progress:()=>t.get(),revert:r}}function A(t,r,e,n={}){const s=n.scheduler??h.getSharedScheduler(),l=M(r,n),a=n.autoRotate??!1,d=a!==!1,u=typeof a=="number"?a:0;let o=!1,c=null;const i=()=>{const g=l.at(e.get()),m=`translate3d(${g.x}px, ${g.y}px, 0)`;t.style.transform=d?`${m} rotate(${g.angle+u}deg)`:m},f=()=>{c===null&&(c=s.subscribe(()=>{c==null||c(),c=null,o&&(o=!1,i())},"render"))},v=e.on("change",()=>{o=!0,f()});return i(),()=>{v(),c==null||c(),c=null}}function k(t,r,e={}){const n=h.animatable(e.from??0,e.scheduler!==void 0?{scheduler:e.scheduler}:void 0),s=t.style.transform,l=A(t,r,n,e),a=()=>{n.stop(),l(),n.dispose(),t.style.transform=s};return e.to!==void 0&&n.spring(e.to),{t:n,...x(n,a)}}const T=t=>t<0?0:t>1?1:t;function O(t){if(typeof t!="string")return t;if(typeof document>"u")throw new Error("@underlying/svg: a selector needs a DOM; pass an element on the server");const r=document.querySelector(t);if(r===null)throw new Error(`@underlying/svg: no element matches "${t}"`);return r}function E(t,r,e={}){const n=e.scheduler??h.getSharedScheduler(),s=O(t),l=s.getTotalLength(),a=s.style.strokeDasharray,d=s.style.strokeDashoffset;s.style.strokeDasharray=String(l);let u=!1,o=null;const c=()=>{s.style.strokeDashoffset=String(l*(1-T(r.get())))},i=()=>{o===null&&(o=n.subscribe(()=>{o==null||o(),o=null,u&&(u=!1,c())},"render"))},f=r.on("change",()=>{u=!0,i()});return c(),()=>{f(),o==null||o(),o=null,s.style.strokeDasharray=a,s.style.strokeDashoffset=d}}function q(t,r={}){const e=h.animatable(r.from??0,r.scheduler!==void 0?{scheduler:r.scheduler}:void 0),n=E(t,e,r),s=()=>{e.stop(),n(),e.dispose()};return r.to!==void 0&&e.spring(r.to),{fraction:e,...x(e,s)}}const p=t=>Math.round(t*100)/100,S=(t,r)=>{const e=t.getTotalLength(),n=r>1?r-1:1,s=[];for(let l=0;l<r;l+=1){const a=t.getPointAtLength(l/n*e);s.push({x:a.x,y:a.y})}return s},G=(t,r)=>{const e=t[0];if(e===void 0)return"";let n=`M ${p(e.x)} ${p(e.y)}`;for(let s=1;s<t.length;s+=1){const l=t[s];l!==void 0&&(n+=` L ${p(l.x)} ${p(l.y)}`)}return r?`${n} Z`:n},R=t=>{if(typeof t!="string")return t;if(typeof document>"u")throw new Error("@underlying/svg: morph target path data needs a DOM");const r=document.createElementNS("http://www.w3.org/2000/svg","path");return r.setAttribute("d",t),r};function j(t,r,e={}){const n=Math.max(2,e.samples??64),s=e.closed??!1,l=S(t,n),a=S(R(r),n),d=t.getAttribute("d"),u=e.scheduler??h.getSharedScheduler(),o=h.animatable(e.from??0,e.scheduler!==void 0?{scheduler:e.scheduler}:void 0);let c=!1,i=null;const f=()=>{const P=o.get(),D=[];for(let b=0;b<n;b+=1){const y=l[b],w=a[b];y===void 0||w===void 0||D.push({x:y.x+(w.x-y.x)*P,y:y.y+(w.y-y.y)*P})}t.setAttribute("d",G(D,s))},v=()=>{i===null&&(i=u.subscribe(()=>{i==null||i(),i=null,c&&(c=!1,f())},"render"))},g=o.on("change",()=>{c=!0,v()});f();const m=()=>{o.stop(),g(),i==null||i(),i=null,d!==null&&t.setAttribute("d",d),o.dispose()};return e.to!==void 0&&o.spring(e.to),{fraction:o,...x(o,m)}}exports.bindDraw=E;exports.bindPath=A;exports.draw=q;exports.morph=j;exports.motionPath=k;exports.resolvePathGeometry=$;exports.samplePath=M;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/geometry.ts","../src/handle.ts","../src/motion-path.ts","../src/draw.ts","../src/morph.ts"],"sourcesContent":["/**\n * A subset of SVGGeometryElement: anything that can report its length and sample\n * a point at a given arc distance. Real `<path>`/`<line>`/`<polyline>` elements\n * satisfy it natively; tests pass a plain object.\n */\nexport interface PathGeometry {\n  getTotalLength(): number\n  getPointAtLength(distance: number): { x: number; y: number }\n}\n\n/** A path source: a CSS selector or any geometry element/object. */\nexport type PathInput = string | PathGeometry\n\n/** A sampled point on a path: position plus the tangent direction (degrees). */\nexport interface PathPoint {\n  x: number\n  y: number\n  /** tangent direction in degrees, fed to autoRotate */\n  angle: number\n}\n\nexport interface SamplePathOptions {\n  /**\n   * Distance, as a fraction of total length, used to estimate the tangent angle\n   * from two neighbouring samples. Smaller is sharper but noisier. Default 0.001.\n   */\n  tangentEpsilon?: number\n}\n\nexport interface PathSampler {\n  /** Total path length, in the path's user units. */\n  readonly length: number\n  /** Point at progress t (clamped to 0..1), with the tangent angle. */\n  at(t: number): PathPoint\n}\n\nconst clamp01 = (t: number): number => (t < 0 ? 0 : t > 1 ? 1 : t)\n\n/** Resolve a {@link PathInput} to a geometry source (querySelector for strings). */\nexport function resolvePathGeometry(path: PathInput): PathGeometry {\n  if (typeof path !== 'string') return path\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: a selector needs a DOM; pass an element on the server')\n  }\n  const element = document.querySelector(path)\n  if (element === null) throw new Error(`@underlying/svg: no element matches \"${path}\"`)\n  return element as unknown as PathGeometry\n}\n\n/**\n * Wrap a path in a length-normalized sampler: feed it t in 0..1 and read back the\n * point plus tangent angle. Total length is measured once; each `at()` is two\n * getPointAtLength() reads (the point, and a neighbour for the tangent).\n */\nexport function samplePath(path: PathInput, options: SamplePathOptions = {}): PathSampler {\n  const geometry = resolvePathGeometry(path)\n  const length = geometry.getTotalLength()\n  const eps = (options.tangentEpsilon ?? 0.001) * length || 0.0001\n\n  return {\n    length,\n    at(t) {\n      const distance = clamp01(t) * length\n      const point = geometry.getPointAtLength(distance)\n      const behind = geometry.getPointAtLength(Math.max(0, distance - eps))\n      const ahead = geometry.getPointAtLength(Math.min(length, distance + eps))\n      const angle = (Math.atan2(ahead.y - behind.y, ahead.x - behind.x) * 180) / Math.PI\n      return { x: point.x, y: point.y, angle }\n    },\n  }\n}\n","import type { Animatable, AnimationHandle, DecayOptions, SpringOptions, ToOptions } from '@underlying/core'\n\n/**\n * The physics verbs every @underlying/svg handle shares. They delegate straight\n * to the live driver Animatable, so a motionPath or a draw is interruptible and\n * retargetable at any moment - the same engine as the rest of core.\n */\nexport interface ScalarControls {\n  /** Spring the driver toward a target (0..1), interruptible, velocity conserved. */\n  spring(target: number, options?: SpringOptions): AnimationHandle\n  /** Glide on inertia from the current velocity, clamped to 0..1. */\n  decay(options?: DecayOptions): AnimationHandle\n  /** Duration/easing escape hatch - still interruptible. */\n  to(target: number, options?: ToOptions): AnimationHandle\n  /** Teleport the driver (no animation). */\n  set(value: number): void\n  /** Flick: seed a velocity (0..1 units/s) and let it decay to a stop on the path. */\n  flick(velocity: number, options?: Omit<DecayOptions, 'velocity'>): AnimationHandle\n  /** Freeze in place; position and velocity stay readable. */\n  stop(): void\n  /** Read the driver, 0..1. */\n  progress(): number\n  /** Stop, unbind, and restore the element to its pre-bind state. */\n  revert(): void\n}\n\n/** Build the shared verb surface around a driver value, plus a revert. */\nexport function scalarControls(value: Animatable, revert: () => void): ScalarControls {\n  return {\n    spring: (target, options) => value.spring(target, options),\n    decay: (options) => value.decay(options),\n    to: (target, options) => value.to(target, options),\n    set: (next) => value.set(next),\n    flick: (velocity, options) => value.decay({ min: 0, max: 1, ...options, velocity }),\n    stop: () => value.stop(),\n    progress: () => value.get(),\n    revert,\n  }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport { samplePath, type PathInput, type SamplePathOptions } from './geometry'\nimport { scalarControls, type ScalarControls } from './handle'\n\nexport interface PathBindOptions extends SamplePathOptions {\n  /**\n   * Turn the element to face along the path. `true` aligns to the tangent;\n   * a number adds that many degrees of offset (e.g. `90` for a north-up icon).\n   */\n  autoRotate?: boolean | number\n  /** Scheduler driving the value and the style flush. Defaults to the shared one. */\n  scheduler?: Scheduler\n}\n\nexport interface MotionPathOptions extends PathBindOptions {\n  /** Initial progress, 0..1. Default 0. */\n  from?: number\n  /** Spring to this progress on creation - the GSAP-familiar one-call form. */\n  to?: number\n}\n\n/**\n * Low-level binder: map a driver Animatable (0..1) onto an element's transform\n * along a path. You own the driver - spring, decay, or scrub it from scroll or a\n * timeline. Writes the current point synchronously at bind; returns an unbind fn.\n */\nexport function bindPath(\n  element: HTMLElement | SVGElement,\n  path: PathInput,\n  source: Animatable,\n  options: PathBindOptions = {},\n): () => void {\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const sampler = samplePath(path, options)\n  const autoRotate = options.autoRotate ?? false\n  const rotates = autoRotate !== false\n  const offset = typeof autoRotate === 'number' ? autoRotate : 0\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    const point = sampler.at(source.get())\n    const move = `translate3d(${point.x}px, ${point.y}px, 0)`\n    element.style.transform = rotates ? `${move} rotate(${point.angle + offset}deg)` : move\n  }\n\n  // One-shot render subscription per change burst: flush once on the next frame,\n  // then let the scheduler sleep - same pattern as core's bindStyle.\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = source.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  return () => {\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n  }\n}\n\nexport interface MotionPath extends ScalarControls {\n  /** The live 0..1 driver. Compose it: scroll.scrub(mp.t), a timeline, a sequence. */\n  readonly t: Animatable\n}\n\n/**\n * Ride an element along an SVG path, physics-first. Progress `t` is a live\n * Animatable, so you can spring it, flick it down the path and let it settle,\n * retarget it mid-flight (velocity conserved), or hand `t` to scroll/timeline.\n * `autoRotate` turns the element to face along the path.\n */\nexport function motionPath(\n  element: HTMLElement | SVGElement,\n  path: PathInput,\n  options: MotionPathOptions = {},\n): MotionPath {\n  const t = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n  const previousTransform = element.style.transform\n  const unbind = bindPath(element, path, t, options)\n\n  const revert = (): void => {\n    t.stop()\n    unbind()\n    t.dispose()\n    element.style.transform = previousTransform\n  }\n\n  if (options.to !== undefined) t.spring(options.to)\n\n  return { t, ...scalarControls(t, revert) }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport { scalarControls, type ScalarControls } from './handle'\n\n/** An element that can be stroke-drawn: reports its length and has a writable style. */\nexport interface DrawElement {\n  getTotalLength(): number\n  style: { strokeDasharray: string; strokeDashoffset: string }\n}\n\n/** A draw source: a CSS selector or a stroked geometry element. */\nexport type DrawInput = string | DrawElement\n\nexport interface DrawOptions {\n  /** Scheduler driving the value and the style flush. Defaults to the shared one. */\n  scheduler?: Scheduler\n  /** Initial draw fraction, 0..1 (0 hidden, 1 drawn). Default 0. */\n  from?: number\n  /** Spring to this fraction on creation - the GSAP-familiar one-call form. */\n  to?: number\n}\n\nconst clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v)\n\nfunction resolveDrawElement(path: DrawInput): DrawElement {\n  if (typeof path !== 'string') return path\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: a selector needs a DOM; pass an element on the server')\n  }\n  const element = document.querySelector(path)\n  if (element === null) throw new Error(`@underlying/svg: no element matches \"${path}\"`)\n  return element as unknown as DrawElement\n}\n\n/**\n * Low-level binder: map a driver Animatable (0..1) onto an element's stroke\n * draw-on (0 = hidden, 1 = fully drawn) via stroke-dasharray/offset. You own the\n * driver. Returns an unbind fn that restores the original dash properties.\n */\nexport function bindDraw(path: DrawInput, source: Animatable, options: DrawOptions = {}): () => void {\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const element = resolveDrawElement(path)\n  const length = element.getTotalLength()\n  const previousDasharray = element.style.strokeDasharray\n  const previousDashoffset = element.style.strokeDashoffset\n  element.style.strokeDasharray = String(length)\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    element.style.strokeDashoffset = String(length * (1 - clamp01(source.get())))\n  }\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = source.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  return () => {\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n    element.style.strokeDasharray = previousDasharray\n    element.style.strokeDashoffset = previousDashoffset\n  }\n}\n\nexport interface Draw extends ScalarControls {\n  /** The live 0..1 draw fraction (0 hidden, 1 drawn). Compose it anywhere. */\n  readonly fraction: Animatable\n}\n\n/**\n * Draw a stroke on, physics-first. The fraction is a live Animatable - spring it\n * in (it can overshoot), interrupt it mid-draw, flick it, or scrub it from\n * scroll. Restores the original stroke-dash properties on revert().\n */\nexport function draw(path: DrawInput, options: DrawOptions = {}): Draw {\n  const fraction = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n  const unbind = bindDraw(path, fraction, options)\n\n  const revert = (): void => {\n    fraction.stop()\n    unbind()\n    fraction.dispose()\n  }\n\n  if (options.to !== undefined) fraction.spring(options.to)\n\n  return { fraction, ...scalarControls(fraction, revert) }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport type { PathGeometry } from './geometry'\nimport { scalarControls, type ScalarControls } from './handle'\n\n/** A path element whose shape this package rewrites: geometry plus the `d` attribute. */\nexport interface MorphElement extends PathGeometry {\n  getAttribute(name: string): string | null\n  setAttribute(name: string, value: string): void\n}\n\n/** The shape to morph toward: raw path data (`\"M ...\"`) or any geometry/element. */\nexport type MorphTarget = string | PathGeometry\n\nexport interface MorphOptions {\n  scheduler?: Scheduler\n  /** Points sampled along each outline; more is smoother (and heavier). Default 64. */\n  samples?: number\n  /** Close the interpolated outline - for closed shapes (a star, a blob). */\n  closed?: boolean\n  /** Initial morph fraction, 0..1 (0 = original shape, 1 = target). Default 0. */\n  from?: number\n  /** Spring to this fraction on creation. */\n  to?: number\n}\n\ninterface Point {\n  x: number\n  y: number\n}\n\nconst round = (n: number): number => Math.round(n * 100) / 100\n\n// Resample an outline into `count` points evenly spaced by arc length. This is\n// what lets ANY two shapes morph: both become the same-length point list, no\n// matching of bezier commands required.\nconst samplePoints = (geometry: PathGeometry, count: number): Point[] => {\n  const length = geometry.getTotalLength()\n  const divisor = count > 1 ? count - 1 : 1\n  const points: Point[] = []\n  for (let i = 0; i < count; i += 1) {\n    const p = geometry.getPointAtLength((i / divisor) * length)\n    points.push({ x: p.x, y: p.y })\n  }\n  return points\n}\n\nconst toPathData = (points: Point[], closed: boolean): string => {\n  const first = points[0]\n  if (first === undefined) return ''\n  let d = `M ${round(first.x)} ${round(first.y)}`\n  for (let i = 1; i < points.length; i += 1) {\n    const p = points[i]\n    if (p !== undefined) d += ` L ${round(p.x)} ${round(p.y)}`\n  }\n  return closed ? `${d} Z` : d\n}\n\nconst targetGeometry = (target: MorphTarget): PathGeometry => {\n  if (typeof target !== 'string') return target\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: morph target path data needs a DOM')\n  }\n  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')\n  path.setAttribute('d', target)\n  return path as unknown as PathGeometry\n}\n\nexport interface Morph extends ScalarControls {\n  /** The live 0..1 morph fraction (0 original, 1 target). Compose it anywhere. */\n  readonly fraction: Animatable\n}\n\n/**\n * Morph one path into another, physics-first. Both outlines are resampled into\n * `samples` points along their length and interpolated, so any two shapes morph\n * (no matching command structure needed). The fraction is a live Animatable -\n * spring it, scrub it, or grab it mid-morph. `revert()` restores the original `d`.\n */\nexport function morph(element: MorphElement, target: MorphTarget, options: MorphOptions = {}): Morph {\n  const count = Math.max(2, options.samples ?? 64)\n  const closed = options.closed ?? false\n  const fromPoints = samplePoints(element, count)\n  const toPoints = samplePoints(targetGeometry(target), count)\n  const originalD = element.getAttribute('d')\n\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const fraction = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    const f = fraction.get()\n    const blended: Point[] = []\n    for (let i = 0; i < count; i += 1) {\n      const a = fromPoints[i]\n      const b = toPoints[i]\n      if (a === undefined || b === undefined) continue\n      blended.push({ x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f })\n    }\n    element.setAttribute('d', toPathData(blended, closed))\n  }\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = fraction.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  const revert = (): void => {\n    fraction.stop()\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n    if (originalD !== null) element.setAttribute('d', originalD)\n    fraction.dispose()\n  }\n\n  if (options.to !== undefined) fraction.spring(options.to)\n\n  return { fraction, ...scalarControls(fraction, revert) }\n}\n"],"names":["clamp01","resolvePathGeometry","path","element","samplePath","options","geometry","length","eps","t","distance","point","behind","ahead","angle","scalarControls","value","revert","target","next","velocity","bindPath","source","scheduler","getSharedScheduler","sampler","autoRotate","rotates","offset","dirty","cancelFlush","write","move","scheduleFlush","unsubscribe","motionPath","animatable","previousTransform","unbind","v","resolveDrawElement","bindDraw","previousDasharray","previousDashoffset","draw","fraction","round","n","samplePoints","count","divisor","points","i","p","toPathData","closed","first","d","targetGeometry","morph","fromPoints","toPoints","originalD","f","blended","a","b"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { samplePath, resolvePathGeometry } from './geometry';
+export type { PathGeometry, PathInput, PathPoint, PathSampler, SamplePathOptions } from './geometry';
+export { bindPath, motionPath } from './motion-path';
+export type { MotionPath, MotionPathOptions, PathBindOptions } from './motion-path';
+export { bindDraw, draw } from './draw';
+export type { Draw, DrawElement, DrawInput, DrawOptions } from './draw';
+export { morph } from './morph';
+export type { Morph, MorphElement, MorphOptions, MorphTarget } from './morph';
+export type { ScalarControls } from './handle';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACpG,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACvC,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACvE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,152 @@
+import { getSharedScheduler as w, animatable as x } from "@underlying/core";
+const A = (t) => t < 0 ? 0 : t > 1 ? 1 : t;
+function E(t) {
+  if (typeof t != "string") return t;
+  if (typeof document > "u")
+    throw new Error("@underlying/svg: a selector needs a DOM; pass an element on the server");
+  const r = document.querySelector(t);
+  if (r === null) throw new Error(`@underlying/svg: no element matches "${t}"`);
+  return r;
+}
+function L(t, r = {}) {
+  const e = E(t), n = e.getTotalLength(), s = (r.tangentEpsilon ?? 1e-3) * n || 1e-4;
+  return {
+    length: n,
+    at(i) {
+      const l = A(i) * n, a = e.getPointAtLength(l), d = e.getPointAtLength(Math.max(0, l - s)), o = e.getPointAtLength(Math.min(n, l + s)), c = Math.atan2(o.y - d.y, o.x - d.x) * 180 / Math.PI;
+      return { x: a.x, y: a.y, angle: c };
+    }
+  };
+}
+function D(t, r) {
+  return {
+    spring: (e, n) => t.spring(e, n),
+    decay: (e) => t.decay(e),
+    to: (e, n) => t.to(e, n),
+    set: (e) => t.set(e),
+    flick: (e, n) => t.decay({ min: 0, max: 1, ...n, velocity: e }),
+    stop: () => t.stop(),
+    progress: () => t.get(),
+    revert: r
+  };
+}
+function k(t, r, e, n = {}) {
+  const s = n.scheduler ?? w(), i = L(r, n), l = n.autoRotate ?? !1, a = l !== !1, d = typeof l == "number" ? l : 0;
+  let o = !1, c = null;
+  const u = () => {
+    const h = i.at(e.get()), y = `translate3d(${h.x}px, ${h.y}px, 0)`;
+    t.style.transform = a ? `${y} rotate(${h.angle + d}deg)` : y;
+  }, f = () => {
+    c === null && (c = s.subscribe(() => {
+      c == null || c(), c = null, o && (o = !1, u());
+    }, "render"));
+  }, p = e.on("change", () => {
+    o = !0, f();
+  });
+  return u(), () => {
+    p(), c == null || c(), c = null;
+  };
+}
+function C(t, r, e = {}) {
+  const n = x(
+    e.from ?? 0,
+    e.scheduler !== void 0 ? { scheduler: e.scheduler } : void 0
+  ), s = t.style.transform, i = k(t, r, n, e), l = () => {
+    n.stop(), i(), n.dispose(), t.style.transform = s;
+  };
+  return e.to !== void 0 && n.spring(e.to), { t: n, ...D(n, l) };
+}
+const S = (t) => t < 0 ? 0 : t > 1 ? 1 : t;
+function T(t) {
+  if (typeof t != "string") return t;
+  if (typeof document > "u")
+    throw new Error("@underlying/svg: a selector needs a DOM; pass an element on the server");
+  const r = document.querySelector(t);
+  if (r === null) throw new Error(`@underlying/svg: no element matches "${t}"`);
+  return r;
+}
+function O(t, r, e = {}) {
+  const n = e.scheduler ?? w(), s = T(t), i = s.getTotalLength(), l = s.style.strokeDasharray, a = s.style.strokeDashoffset;
+  s.style.strokeDasharray = String(i);
+  let d = !1, o = null;
+  const c = () => {
+    s.style.strokeDashoffset = String(i * (1 - S(r.get())));
+  }, u = () => {
+    o === null && (o = n.subscribe(() => {
+      o == null || o(), o = null, d && (d = !1, c());
+    }, "render"));
+  }, f = r.on("change", () => {
+    d = !0, u();
+  });
+  return c(), () => {
+    f(), o == null || o(), o = null, s.style.strokeDasharray = l, s.style.strokeDashoffset = a;
+  };
+}
+function I(t, r = {}) {
+  const e = x(
+    r.from ?? 0,
+    r.scheduler !== void 0 ? { scheduler: r.scheduler } : void 0
+  ), n = O(t, e, r), s = () => {
+    e.stop(), n(), e.dispose();
+  };
+  return r.to !== void 0 && e.spring(r.to), { fraction: e, ...D(e, s) };
+}
+const b = (t) => Math.round(t * 100) / 100, M = (t, r) => {
+  const e = t.getTotalLength(), n = r > 1 ? r - 1 : 1, s = [];
+  for (let i = 0; i < r; i += 1) {
+    const l = t.getPointAtLength(i / n * e);
+    s.push({ x: l.x, y: l.y });
+  }
+  return s;
+}, q = (t, r) => {
+  const e = t[0];
+  if (e === void 0) return "";
+  let n = `M ${b(e.x)} ${b(e.y)}`;
+  for (let s = 1; s < t.length; s += 1) {
+    const i = t[s];
+    i !== void 0 && (n += ` L ${b(i.x)} ${b(i.y)}`);
+  }
+  return r ? `${n} Z` : n;
+}, G = (t) => {
+  if (typeof t != "string") return t;
+  if (typeof document > "u")
+    throw new Error("@underlying/svg: morph target path data needs a DOM");
+  const r = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  return r.setAttribute("d", t), r;
+};
+function N(t, r, e = {}) {
+  const n = Math.max(2, e.samples ?? 64), s = e.closed ?? !1, i = M(t, n), l = M(G(r), n), a = t.getAttribute("d"), d = e.scheduler ?? w(), o = x(
+    e.from ?? 0,
+    e.scheduler !== void 0 ? { scheduler: e.scheduler } : void 0
+  );
+  let c = !1, u = null;
+  const f = () => {
+    const P = o.get(), $ = [];
+    for (let m = 0; m < n; m += 1) {
+      const g = i[m], v = l[m];
+      g === void 0 || v === void 0 || $.push({ x: g.x + (v.x - g.x) * P, y: g.y + (v.y - g.y) * P });
+    }
+    t.setAttribute("d", q($, s));
+  }, p = () => {
+    u === null && (u = d.subscribe(() => {
+      u == null || u(), u = null, c && (c = !1, f());
+    }, "render"));
+  }, h = o.on("change", () => {
+    c = !0, p();
+  });
+  f();
+  const y = () => {
+    o.stop(), h(), u == null || u(), u = null, a !== null && t.setAttribute("d", a), o.dispose();
+  };
+  return e.to !== void 0 && o.spring(e.to), { fraction: o, ...D(o, y) };
+}
+export {
+  O as bindDraw,
+  k as bindPath,
+  I as draw,
+  N as morph,
+  C as motionPath,
+  E as resolvePathGeometry,
+  L as samplePath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/geometry.ts","../src/handle.ts","../src/motion-path.ts","../src/draw.ts","../src/morph.ts"],"sourcesContent":["/**\n * A subset of SVGGeometryElement: anything that can report its length and sample\n * a point at a given arc distance. Real `<path>`/`<line>`/`<polyline>` elements\n * satisfy it natively; tests pass a plain object.\n */\nexport interface PathGeometry {\n  getTotalLength(): number\n  getPointAtLength(distance: number): { x: number; y: number }\n}\n\n/** A path source: a CSS selector or any geometry element/object. */\nexport type PathInput = string | PathGeometry\n\n/** A sampled point on a path: position plus the tangent direction (degrees). */\nexport interface PathPoint {\n  x: number\n  y: number\n  /** tangent direction in degrees, fed to autoRotate */\n  angle: number\n}\n\nexport interface SamplePathOptions {\n  /**\n   * Distance, as a fraction of total length, used to estimate the tangent angle\n   * from two neighbouring samples. Smaller is sharper but noisier. Default 0.001.\n   */\n  tangentEpsilon?: number\n}\n\nexport interface PathSampler {\n  /** Total path length, in the path's user units. */\n  readonly length: number\n  /** Point at progress t (clamped to 0..1), with the tangent angle. */\n  at(t: number): PathPoint\n}\n\nconst clamp01 = (t: number): number => (t < 0 ? 0 : t > 1 ? 1 : t)\n\n/** Resolve a {@link PathInput} to a geometry source (querySelector for strings). */\nexport function resolvePathGeometry(path: PathInput): PathGeometry {\n  if (typeof path !== 'string') return path\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: a selector needs a DOM; pass an element on the server')\n  }\n  const element = document.querySelector(path)\n  if (element === null) throw new Error(`@underlying/svg: no element matches \"${path}\"`)\n  return element as unknown as PathGeometry\n}\n\n/**\n * Wrap a path in a length-normalized sampler: feed it t in 0..1 and read back the\n * point plus tangent angle. Total length is measured once; each `at()` is two\n * getPointAtLength() reads (the point, and a neighbour for the tangent).\n */\nexport function samplePath(path: PathInput, options: SamplePathOptions = {}): PathSampler {\n  const geometry = resolvePathGeometry(path)\n  const length = geometry.getTotalLength()\n  const eps = (options.tangentEpsilon ?? 0.001) * length || 0.0001\n\n  return {\n    length,\n    at(t) {\n      const distance = clamp01(t) * length\n      const point = geometry.getPointAtLength(distance)\n      const behind = geometry.getPointAtLength(Math.max(0, distance - eps))\n      const ahead = geometry.getPointAtLength(Math.min(length, distance + eps))\n      const angle = (Math.atan2(ahead.y - behind.y, ahead.x - behind.x) * 180) / Math.PI\n      return { x: point.x, y: point.y, angle }\n    },\n  }\n}\n","import type { Animatable, AnimationHandle, DecayOptions, SpringOptions, ToOptions } from '@underlying/core'\n\n/**\n * The physics verbs every @underlying/svg handle shares. They delegate straight\n * to the live driver Animatable, so a motionPath or a draw is interruptible and\n * retargetable at any moment - the same engine as the rest of core.\n */\nexport interface ScalarControls {\n  /** Spring the driver toward a target (0..1), interruptible, velocity conserved. */\n  spring(target: number, options?: SpringOptions): AnimationHandle\n  /** Glide on inertia from the current velocity, clamped to 0..1. */\n  decay(options?: DecayOptions): AnimationHandle\n  /** Duration/easing escape hatch - still interruptible. */\n  to(target: number, options?: ToOptions): AnimationHandle\n  /** Teleport the driver (no animation). */\n  set(value: number): void\n  /** Flick: seed a velocity (0..1 units/s) and let it decay to a stop on the path. */\n  flick(velocity: number, options?: Omit<DecayOptions, 'velocity'>): AnimationHandle\n  /** Freeze in place; position and velocity stay readable. */\n  stop(): void\n  /** Read the driver, 0..1. */\n  progress(): number\n  /** Stop, unbind, and restore the element to its pre-bind state. */\n  revert(): void\n}\n\n/** Build the shared verb surface around a driver value, plus a revert. */\nexport function scalarControls(value: Animatable, revert: () => void): ScalarControls {\n  return {\n    spring: (target, options) => value.spring(target, options),\n    decay: (options) => value.decay(options),\n    to: (target, options) => value.to(target, options),\n    set: (next) => value.set(next),\n    flick: (velocity, options) => value.decay({ min: 0, max: 1, ...options, velocity }),\n    stop: () => value.stop(),\n    progress: () => value.get(),\n    revert,\n  }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport { samplePath, type PathInput, type SamplePathOptions } from './geometry'\nimport { scalarControls, type ScalarControls } from './handle'\n\nexport interface PathBindOptions extends SamplePathOptions {\n  /**\n   * Turn the element to face along the path. `true` aligns to the tangent;\n   * a number adds that many degrees of offset (e.g. `90` for a north-up icon).\n   */\n  autoRotate?: boolean | number\n  /** Scheduler driving the value and the style flush. Defaults to the shared one. */\n  scheduler?: Scheduler\n}\n\nexport interface MotionPathOptions extends PathBindOptions {\n  /** Initial progress, 0..1. Default 0. */\n  from?: number\n  /** Spring to this progress on creation - the GSAP-familiar one-call form. */\n  to?: number\n}\n\n/**\n * Low-level binder: map a driver Animatable (0..1) onto an element's transform\n * along a path. You own the driver - spring, decay, or scrub it from scroll or a\n * timeline. Writes the current point synchronously at bind; returns an unbind fn.\n */\nexport function bindPath(\n  element: HTMLElement | SVGElement,\n  path: PathInput,\n  source: Animatable,\n  options: PathBindOptions = {},\n): () => void {\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const sampler = samplePath(path, options)\n  const autoRotate = options.autoRotate ?? false\n  const rotates = autoRotate !== false\n  const offset = typeof autoRotate === 'number' ? autoRotate : 0\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    const point = sampler.at(source.get())\n    const move = `translate3d(${point.x}px, ${point.y}px, 0)`\n    element.style.transform = rotates ? `${move} rotate(${point.angle + offset}deg)` : move\n  }\n\n  // One-shot render subscription per change burst: flush once on the next frame,\n  // then let the scheduler sleep - same pattern as core's bindStyle.\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = source.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  return () => {\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n  }\n}\n\nexport interface MotionPath extends ScalarControls {\n  /** The live 0..1 driver. Compose it: scroll.scrub(mp.t), a timeline, a sequence. */\n  readonly t: Animatable\n}\n\n/**\n * Ride an element along an SVG path, physics-first. Progress `t` is a live\n * Animatable, so you can spring it, flick it down the path and let it settle,\n * retarget it mid-flight (velocity conserved), or hand `t` to scroll/timeline.\n * `autoRotate` turns the element to face along the path.\n */\nexport function motionPath(\n  element: HTMLElement | SVGElement,\n  path: PathInput,\n  options: MotionPathOptions = {},\n): MotionPath {\n  const t = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n  const previousTransform = element.style.transform\n  const unbind = bindPath(element, path, t, options)\n\n  const revert = (): void => {\n    t.stop()\n    unbind()\n    t.dispose()\n    element.style.transform = previousTransform\n  }\n\n  if (options.to !== undefined) t.spring(options.to)\n\n  return { t, ...scalarControls(t, revert) }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport { scalarControls, type ScalarControls } from './handle'\n\n/** An element that can be stroke-drawn: reports its length and has a writable style. */\nexport interface DrawElement {\n  getTotalLength(): number\n  style: { strokeDasharray: string; strokeDashoffset: string }\n}\n\n/** A draw source: a CSS selector or a stroked geometry element. */\nexport type DrawInput = string | DrawElement\n\nexport interface DrawOptions {\n  /** Scheduler driving the value and the style flush. Defaults to the shared one. */\n  scheduler?: Scheduler\n  /** Initial draw fraction, 0..1 (0 hidden, 1 drawn). Default 0. */\n  from?: number\n  /** Spring to this fraction on creation - the GSAP-familiar one-call form. */\n  to?: number\n}\n\nconst clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v)\n\nfunction resolveDrawElement(path: DrawInput): DrawElement {\n  if (typeof path !== 'string') return path\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: a selector needs a DOM; pass an element on the server')\n  }\n  const element = document.querySelector(path)\n  if (element === null) throw new Error(`@underlying/svg: no element matches \"${path}\"`)\n  return element as unknown as DrawElement\n}\n\n/**\n * Low-level binder: map a driver Animatable (0..1) onto an element's stroke\n * draw-on (0 = hidden, 1 = fully drawn) via stroke-dasharray/offset. You own the\n * driver. Returns an unbind fn that restores the original dash properties.\n */\nexport function bindDraw(path: DrawInput, source: Animatable, options: DrawOptions = {}): () => void {\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const element = resolveDrawElement(path)\n  const length = element.getTotalLength()\n  const previousDasharray = element.style.strokeDasharray\n  const previousDashoffset = element.style.strokeDashoffset\n  element.style.strokeDasharray = String(length)\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    element.style.strokeDashoffset = String(length * (1 - clamp01(source.get())))\n  }\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = source.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  return () => {\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n    element.style.strokeDasharray = previousDasharray\n    element.style.strokeDashoffset = previousDashoffset\n  }\n}\n\nexport interface Draw extends ScalarControls {\n  /** The live 0..1 draw fraction (0 hidden, 1 drawn). Compose it anywhere. */\n  readonly fraction: Animatable\n}\n\n/**\n * Draw a stroke on, physics-first. The fraction is a live Animatable - spring it\n * in (it can overshoot), interrupt it mid-draw, flick it, or scrub it from\n * scroll. Restores the original stroke-dash properties on revert().\n */\nexport function draw(path: DrawInput, options: DrawOptions = {}): Draw {\n  const fraction = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n  const unbind = bindDraw(path, fraction, options)\n\n  const revert = (): void => {\n    fraction.stop()\n    unbind()\n    fraction.dispose()\n  }\n\n  if (options.to !== undefined) fraction.spring(options.to)\n\n  return { fraction, ...scalarControls(fraction, revert) }\n}\n","import { animatable, getSharedScheduler, type Animatable, type Scheduler } from '@underlying/core'\nimport type { PathGeometry } from './geometry'\nimport { scalarControls, type ScalarControls } from './handle'\n\n/** A path element whose shape this package rewrites: geometry plus the `d` attribute. */\nexport interface MorphElement extends PathGeometry {\n  getAttribute(name: string): string | null\n  setAttribute(name: string, value: string): void\n}\n\n/** The shape to morph toward: raw path data (`\"M ...\"`) or any geometry/element. */\nexport type MorphTarget = string | PathGeometry\n\nexport interface MorphOptions {\n  scheduler?: Scheduler\n  /** Points sampled along each outline; more is smoother (and heavier). Default 64. */\n  samples?: number\n  /** Close the interpolated outline - for closed shapes (a star, a blob). */\n  closed?: boolean\n  /** Initial morph fraction, 0..1 (0 = original shape, 1 = target). Default 0. */\n  from?: number\n  /** Spring to this fraction on creation. */\n  to?: number\n}\n\ninterface Point {\n  x: number\n  y: number\n}\n\nconst round = (n: number): number => Math.round(n * 100) / 100\n\n// Resample an outline into `count` points evenly spaced by arc length. This is\n// what lets ANY two shapes morph: both become the same-length point list, no\n// matching of bezier commands required.\nconst samplePoints = (geometry: PathGeometry, count: number): Point[] => {\n  const length = geometry.getTotalLength()\n  const divisor = count > 1 ? count - 1 : 1\n  const points: Point[] = []\n  for (let i = 0; i < count; i += 1) {\n    const p = geometry.getPointAtLength((i / divisor) * length)\n    points.push({ x: p.x, y: p.y })\n  }\n  return points\n}\n\nconst toPathData = (points: Point[], closed: boolean): string => {\n  const first = points[0]\n  if (first === undefined) return ''\n  let d = `M ${round(first.x)} ${round(first.y)}`\n  for (let i = 1; i < points.length; i += 1) {\n    const p = points[i]\n    if (p !== undefined) d += ` L ${round(p.x)} ${round(p.y)}`\n  }\n  return closed ? `${d} Z` : d\n}\n\nconst targetGeometry = (target: MorphTarget): PathGeometry => {\n  if (typeof target !== 'string') return target\n  if (typeof document === 'undefined') {\n    throw new Error('@underlying/svg: morph target path data needs a DOM')\n  }\n  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')\n  path.setAttribute('d', target)\n  return path as unknown as PathGeometry\n}\n\nexport interface Morph extends ScalarControls {\n  /** The live 0..1 morph fraction (0 original, 1 target). Compose it anywhere. */\n  readonly fraction: Animatable\n}\n\n/**\n * Morph one path into another, physics-first. Both outlines are resampled into\n * `samples` points along their length and interpolated, so any two shapes morph\n * (no matching command structure needed). The fraction is a live Animatable -\n * spring it, scrub it, or grab it mid-morph. `revert()` restores the original `d`.\n */\nexport function morph(element: MorphElement, target: MorphTarget, options: MorphOptions = {}): Morph {\n  const count = Math.max(2, options.samples ?? 64)\n  const closed = options.closed ?? false\n  const fromPoints = samplePoints(element, count)\n  const toPoints = samplePoints(targetGeometry(target), count)\n  const originalD = element.getAttribute('d')\n\n  const scheduler = options.scheduler ?? getSharedScheduler()\n  const fraction = animatable(\n    options.from ?? 0,\n    options.scheduler !== undefined ? { scheduler: options.scheduler } : undefined,\n  )\n\n  let dirty = false\n  let cancelFlush: (() => void) | null = null\n\n  const write = (): void => {\n    const f = fraction.get()\n    const blended: Point[] = []\n    for (let i = 0; i < count; i += 1) {\n      const a = fromPoints[i]\n      const b = toPoints[i]\n      if (a === undefined || b === undefined) continue\n      blended.push({ x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f })\n    }\n    element.setAttribute('d', toPathData(blended, closed))\n  }\n  const scheduleFlush = (): void => {\n    if (cancelFlush !== null) return\n    cancelFlush = scheduler.subscribe(() => {\n      cancelFlush?.()\n      cancelFlush = null\n      if (dirty) {\n        dirty = false\n        write()\n      }\n    }, 'render')\n  }\n\n  const unsubscribe = fraction.on('change', () => {\n    dirty = true\n    scheduleFlush()\n  })\n  write()\n\n  const revert = (): void => {\n    fraction.stop()\n    unsubscribe()\n    cancelFlush?.()\n    cancelFlush = null\n    if (originalD !== null) element.setAttribute('d', originalD)\n    fraction.dispose()\n  }\n\n  if (options.to !== undefined) fraction.spring(options.to)\n\n  return { fraction, ...scalarControls(fraction, revert) }\n}\n"],"names":["clamp01","resolvePathGeometry","path","element","samplePath","options","geometry","length","eps","t","distance","point","behind","ahead","angle","scalarControls","value","revert","target","next","velocity","bindPath","source","scheduler","getSharedScheduler","sampler","autoRotate","rotates","offset","dirty","cancelFlush","write","move","scheduleFlush","unsubscribe","motionPath","animatable","previousTransform","unbind","v","resolveDrawElement","bindDraw","previousDasharray","previousDashoffset","draw","fraction","round","n","samplePoints","count","divisor","points","p","toPathData","closed","first","d","i","targetGeometry","morph","fromPoints","toPoints","originalD","f","blended","a","b"],"mappings":"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"}

package/dist/morph.d.ts

@@ -0,0 +1,33 @@
+import { type Animatable, type Scheduler } from '@underlying/core';
+import type { PathGeometry } from './geometry';
+import { type ScalarControls } from './handle';
+/** A path element whose shape this package rewrites: geometry plus the `d` attribute. */
+export interface MorphElement extends PathGeometry {
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+}
+/** The shape to morph toward: raw path data (`"M ..."`) or any geometry/element. */
+export type MorphTarget = string | PathGeometry;
+export interface MorphOptions {
+    scheduler?: Scheduler;
+    /** Points sampled along each outline; more is smoother (and heavier). Default 64. */
+    samples?: number;
+    /** Close the interpolated outline - for closed shapes (a star, a blob). */
+    closed?: boolean;
+    /** Initial morph fraction, 0..1 (0 = original shape, 1 = target). Default 0. */
+    from?: number;
+    /** Spring to this fraction on creation. */
+    to?: number;
+}
+export interface Morph extends ScalarControls {
+    /** The live 0..1 morph fraction (0 original, 1 target). Compose it anywhere. */
+    readonly fraction: Animatable;
+}
+/**
+ * Morph one path into another, physics-first. Both outlines are resampled into
+ * `samples` points along their length and interpolated, so any two shapes morph
+ * (no matching command structure needed). The fraction is a live Animatable -
+ * spring it, scrub it, or grab it mid-morph. `revert()` restores the original `d`.
+ */
+export declare function morph(element: MorphElement, target: MorphTarget, options?: MorphOptions): Morph;
+//# sourceMappingURL=morph.d.ts.map

package/dist/morph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph.d.ts","sourceRoot":"","sources":["../src/morph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAClG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9D,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACzC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD;AAED,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,CAAA;AAE/C,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AA4CD,MAAM,WAAW,KAAM,SAAQ,cAAc;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAA;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,KAAK,CAyDnG"}

package/dist/motion-path.d.ts

@@ -0,0 +1,36 @@
+import { type Animatable, type Scheduler } from '@underlying/core';
+import { type PathInput, type SamplePathOptions } from './geometry';
+import { type ScalarControls } from './handle';
+export interface PathBindOptions extends SamplePathOptions {
+    /**
+     * Turn the element to face along the path. `true` aligns to the tangent;
+     * a number adds that many degrees of offset (e.g. `90` for a north-up icon).
+     */
+    autoRotate?: boolean | number;
+    /** Scheduler driving the value and the style flush. Defaults to the shared one. */
+    scheduler?: Scheduler;
+}
+export interface MotionPathOptions extends PathBindOptions {
+    /** Initial progress, 0..1. Default 0. */
+    from?: number;
+    /** Spring to this progress on creation - the GSAP-familiar one-call form. */
+    to?: number;
+}
+/**
+ * Low-level binder: map a driver Animatable (0..1) onto an element's transform
+ * along a path. You own the driver - spring, decay, or scrub it from scroll or a
+ * timeline. Writes the current point synchronously at bind; returns an unbind fn.
+ */
+export declare function bindPath(element: HTMLElement | SVGElement, path: PathInput, source: Animatable, options?: PathBindOptions): () => void;
+export interface MotionPath extends ScalarControls {
+    /** The live 0..1 driver. Compose it: scroll.scrub(mp.t), a timeline, a sequence. */
+    readonly t: Animatable;
+}
+/**
+ * Ride an element along an SVG path, physics-first. Progress `t` is a live
+ * Animatable, so you can spring it, flick it down the path and let it settle,
+ * retarget it mid-flight (velocity conserved), or hand `t` to scroll/timeline.
+ * `autoRotate` turns the element to face along the path.
+ */
+export declare function motionPath(element: HTMLElement | SVGElement, path: PathInput, options?: MotionPathOptions): MotionPath;
+//# sourceMappingURL=motion-path.d.ts.map

package/dist/motion-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-path.d.ts","sourceRoot":"","sources":["../src/motion-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAClG,OAAO,EAAc,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9D,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC7B,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,WAAW,GAAG,UAAU,EACjC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,eAAoB,GAC5B,MAAM,IAAI,CAyCZ;AAED,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,oFAAoF;IACpF,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,GAAG,UAAU,EACjC,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAkBZ"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@underlying/svg",
+  "version": "0.1.0-beta.0",
+  "description": "SVG path animation for @underlying/core: ride a path, draw a stroke on, or morph one shape into another, physics-first - flick, interrupt, retarget, or scrub. MotionPath, DrawSVG and morph.",
+  "license": "MIT",
+  "author": "underlyi.ng <contact@underlyi.ng>",
+  "keywords": [
+    "animation",
+    "svg",
+    "motionpath",
+    "drawsvg",
+    "morph",
+    "path",
+    "stroke",
+    "physics",
+    "spring"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underlyingjs/underlying.git",
+    "directory": "packages/svg"
+  },
+  "homepage": "https://github.com/underlyingjs/underlying#readme",
+  "bugs": "https://github.com/underlyingjs/underlying/issues",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@underlying/core": "0.1.0-beta.2"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "size": "node scripts/check-size.mjs"
+  }
+}