@glissade/scene 0.23.0-pre.5 → 0.24.0-pre.0

package/dist/describe.d.ts

@@ -51,6 +51,13 @@ interface DescribedNode {
   props: {
     [prop: string]: DescribedProp;
   };
+  /**
+   * Runnable, drift-guarded code snippets for this node — present ONLY when
+   * `describe({ examples: true })` is called AND `@glissade/scene/examples` has
+   * been imported (it registers the corpus). Each string is an executable example
+   * the doctest harness runs, so it can't go stale (§0.24 onboarding).
+   */
+  examples?: readonly string[];
   /**
    * What this node's `position` points at WITHOUT an explicit `anchor` (its
    * legacy origin): 'center' for shapes, 'baseline-left' for Text, etc. Override
@@ -68,6 +75,8 @@ interface DescribedNode {
 interface DescribedBuilderMethod {
   name: string;
   signature: string;
+  /** Runnable example snippets — see {@link DescribedNode.examples}. */
+  examples?: readonly string[];
 }
 /**
  * One helper/factory in the manifest — the broader builder API beyond the node
@@ -87,6 +96,8 @@ interface DescribedHelper {
   import: string;
   /** A minimal signature/usage string showing the call shape. */
   usage: string;
+  /** Runnable example snippets — see {@link DescribedNode.examples}. */
+  examples?: readonly string[];
 }
 /** The full machine-readable manifest `describe()` returns. */
 interface ApiManifest {
@@ -117,6 +128,23 @@ interface ApiManifest {
  * targets, enumerate the ValueType + easing registries, and curate the builder /
  * subpath surface. JSON-serializable; safe to call any number of times.
  */
-declare function describe(): ApiManifest;
+interface DescribeOptions {
+  /**
+   * Attach runnable example snippets (per node / builder method / helper) from
+   * the registered corpus (§0.24 onboarding). The corpus is registered by
+   * importing `@glissade/scene/examples`, kept OFF the base index so it costs
+   * nothing when unused. With no corpus registered, `examples: true` is a no-op
+   * (the manifest is byte-identical to `describe()`).
+   */
+  examples?: boolean;
+}
+/**
+ * Register the runnable-example corpus — called by `@glissade/scene/examples` on
+ * import. A registration hook (not a static import) so `describe()` stays lean.
+ */
+declare function registerExamples(corpus: {
+  readonly [key: string]: readonly string[];
+}): void;
+declare function describe(opts?: DescribeOptions): ApiManifest;
 //#endregion
-export { ApiManifest, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe };
+export { ApiManifest, DescribeOptions, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe, registerExamples };

package/dist/describe.js

@@ -22,7 +22,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.23.0-pre.5";
+const RAW_VERSION = "0.24.0-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /** Arity of a value type's numeric repr: vec2/vec2-arc → 2, number → 1; others (color/paint/path/string/boolean) carry no scalar arity. */
 function arityOf(type) {
@@ -390,31 +390,60 @@ const SUBPATHS = {
 	"@glissade/scene/path": "SVG geometry: pathFromSvg / parseSvgPathData — parse an SVG `d` string into a PathValue for Path.data."
 };
 /**
-* Build the machine-readable API manifest from the live registries (§4.4). Pure
-* introspection: instantiate each built-in node once to read its registered track
-* targets, enumerate the ValueType + easing registries, and curate the builder /
-* subpath surface. JSON-serializable; safe to call any number of times.
+* The registered runnable-example corpus, keyed by describe-key (node type name /
+* builder method name / helper name). Populated by `@glissade/scene/examples` at
+* import time via {@link registerExamples} — describe NEVER statically imports the
+* corpus, so the base index and the IIFE never pay for it (the value-type-registry
+* pattern). Empty until that subpath is loaded.
 */
-function describe() {
+let exampleCorpus = {};
+/**
+* Register the runnable-example corpus — called by `@glissade/scene/examples` on
+* import. A registration hook (not a static import) so `describe()` stays lean.
+*/
+function registerExamples(corpus) {
+	exampleCorpus = corpus;
+}
+function describe(opts = {}) {
+	const withEx = opts.examples === true && Object.keys(exampleCorpus).length > 0;
+	const ex = (key) => {
+		const e = withEx ? exampleCorpus[key] : void 0;
+		return e && e.length > 0 ? { examples: e } : void 0;
+	};
 	const nodes = {};
-	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = describeNode(factory(), name);
+	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = {
+		...describeNode(factory(), name),
+		...ex(name)
+	};
 	const layout = describeLayoutNode();
 	for (const name of [
 		"Layout",
 		"Stack",
 		"Row",
 		"Column"
-	]) nodes[name] = layout;
+	]) {
+		const e = ex(name);
+		nodes[name] = e ? {
+			...layout,
+			...e
+		} : layout;
+	}
 	return {
 		version: PACKAGE_VERSION,
 		nodes,
 		valueTypes: listValueTypes(),
 		easings: Object.keys(easings),
-		builder: { methods: BUILDER_METHODS },
-		helpers: HELPERS,
+		builder: { methods: withEx ? BUILDER_METHODS.map((m) => ({
+			...m,
+			...ex(m.name)
+		})) : BUILDER_METHODS },
+		helpers: withEx ? HELPERS.map((h) => ({
+			...h,
+			...ex(h.name)
+		})) : HELPERS,
 		createScene: "createScene({ size: { w, h }, children: Node[] }): Scene  —  media assets are declared on the Timeline document: timeline({ assets: { <id>: { kind: 'image'|'video', url } } }); an Image/Video node's `assetId` names an entry here.",
 		subpaths: SUBPATHS
 	};
 }
 //#endregion
-export { describe };
+export { describe, registerExamples };

package/dist/examples.d.ts

@@ -0,0 +1,38 @@
+//#region src/examples.d.ts
+/**
+ * `@glissade/scene/examples` — the runnable example corpus (§0.24 onboarding,
+ * card `8jQ9rNqStGDL`). The single highest agent-onboarding cost is STALE
+ * examples: prose that drifts from the runtime, which a cold agent can't
+ * glance-test. The fix is to make canonical examples EXECUTABLE and surfaced from
+ * the same place the doctest harness runs them, so they can't go stale.
+ *
+ * Each {@link ApiExample} carries a copy-pasteable `code` string (what
+ * `describe({ examples: true })` surfaces) AND an executable `run` thunk against
+ * the REAL API (what `examples.test.ts` asserts never throws). The two sit
+ * adjacent and are kept in lockstep; the `run` guard is what fails CI the moment
+ * an example's API drifts (a renamed export, a changed shape).
+ *
+ * Tree-shaking: this module is OFF the base scene index (its own subpath entry),
+ * so a scene that never imports it pays zero bytes. Importing it REGISTERS the
+ * corpus with `describe()` via {@link registerExamples} (the value-type-registry
+ * pattern) — describe never imports examples, so the base embed + IIFE stay lean.
+ */
+/** One runnable example, attached to its describe-key (node type / builder method
+ *  / helper name). `code` is surfaced; `run` is the executed drift guard. */
+interface ApiExample {
+  /** The describe-key this attaches to: a node type ('Rect'), builder method
+   *  ('to'), or helper name ('splitText'). */
+  key: string;
+  /** The copy-pasteable snippet `describe({ examples: true })` surfaces. */
+  code: string;
+  /** Executes the SAME call against the real API — the doctest harness asserts it
+   *  never throws, so the surfaced `code` can't reference a drifted API. */
+  run: () => void;
+}
+declare const EXAMPLES: readonly ApiExample[];
+/** Group the corpus by describe-key → the surfaced code snippets. */
+declare function examplesByKey(): {
+  readonly [key: string]: readonly string[];
+};
+//#endregion
+export { ApiExample, EXAMPLES, examplesByKey };

package/dist/examples.js

@@ -0,0 +1,217 @@
+import { a as Path, i as ImageNode, o as Rect, r as Group, s as Text, t as Circle } from "./nodes.js";
+import { registerExamples } from "./describe.js";
+import { a as evaluate, i as createScene } from "./scene.js";
+import { Grid } from "./grid.js";
+import { Stack } from "./layoutCtors.js";
+import { splitText } from "./type.js";
+import { r as motionPath } from "./motionPath.js";
+import { pathFromSvg } from "./path.js";
+import { key, timeline, track } from "@glissade/core";
+//#region src/examples.ts
+/**
+* `@glissade/scene/examples` — the runnable example corpus (§0.24 onboarding,
+* card `8jQ9rNqStGDL`). The single highest agent-onboarding cost is STALE
+* examples: prose that drifts from the runtime, which a cold agent can't
+* glance-test. The fix is to make canonical examples EXECUTABLE and surfaced from
+* the same place the doctest harness runs them, so they can't go stale.
+*
+* Each {@link ApiExample} carries a copy-pasteable `code` string (what
+* `describe({ examples: true })` surfaces) AND an executable `run` thunk against
+* the REAL API (what `examples.test.ts` asserts never throws). The two sit
+* adjacent and are kept in lockstep; the `run` guard is what fails CI the moment
+* an example's API drifts (a renamed export, a changed shape).
+*
+* Tree-shaking: this module is OFF the base scene index (its own subpath entry),
+* so a scene that never imports it pays zero bytes. Importing it REGISTERS the
+* corpus with `describe()` via {@link registerExamples} (the value-type-registry
+* pattern) — describe never imports examples, so the base embed + IIFE stay lean.
+*/
+/** A throwaway scene+evaluate so a node example proves it renders end-to-end, not
+*  just constructs (the estimating measurer suffices — no backend needed). */
+function renders(...children) {
+	evaluate(createScene({
+		size: {
+			w: 320,
+			h: 200
+		},
+		children
+	}), timeline(() => {}), 0);
+}
+const EXAMPLES = [
+	{
+		key: "Rect",
+		code: "import { Rect } from '@glissade/scene';\nnew Rect({ position: [160, 100], width: 200, height: 100, fill: '#3b82f6', cornerRadius: 12 });",
+		run: () => renders(new Rect({
+			position: [160, 100],
+			width: 200,
+			height: 100,
+			fill: "#3b82f6",
+			cornerRadius: 12
+		}))
+	},
+	{
+		key: "Circle",
+		code: "import { Circle } from '@glissade/scene';\nnew Circle({ position: [160, 100], radius: 48, fill: '#ef4444' });",
+		run: () => renders(new Circle({
+			position: [160, 100],
+			radius: 48,
+			fill: "#ef4444"
+		}))
+	},
+	{
+		key: "Text",
+		code: "import { Text } from '@glissade/scene';\n// position anchors at the baseline-left by default; set `anchor` to share a corner with a shape\nnew Text({ position: [40, 60], text: 'Hello', fontSize: 32, fill: '#111827' });",
+		run: () => renders(new Text({
+			position: [40, 60],
+			text: "Hello",
+			fontSize: 32,
+			fill: "#111827"
+		}))
+	},
+	{
+		key: "Path",
+		code: "import { Path } from '@glissade/scene';\nimport { pathFromSvg } from '@glissade/scene/path';\n// Path.data wants a PathValue — parse an SVG `d` string with pathFromSvg (NOT a raw string)\nnew Path({ data: pathFromSvg('M0 0 L100 0 L50 80 Z'), fill: '#10b981' });",
+		run: () => renders(new Path({
+			data: pathFromSvg("M0 0 L100 0 L50 80 Z"),
+			fill: "#10b981"
+		}))
+	},
+	{
+		key: "Group",
+		code: "import { Group, Rect, Text } from '@glissade/scene';\n// a Group nests its children as one unit (and renders as a wrapper <div> on the DOM tier)\nnew Group({ id: 'card', children: [\n  new Rect({ anchor: 'top-left', position: [0, 0], width: 240, height: 96, fill: '#0f172a', cornerRadius: 16 }),\n  new Text({ anchor: 'top-left', position: [16, 16], text: 'Title', fontSize: 24, fill: '#f8fafc' }),\n] });",
+		run: () => renders(new Group({
+			id: "card",
+			children: [new Rect({
+				anchor: "top-left",
+				position: [0, 0],
+				width: 240,
+				height: 96,
+				fill: "#0f172a",
+				cornerRadius: 16
+			}), new Text({
+				anchor: "top-left",
+				position: [16, 16],
+				text: "Title",
+				fontSize: 24,
+				fill: "#f8fafc"
+			})]
+		}))
+	},
+	{
+		key: "Image",
+		code: "import { Image } from '@glissade/scene';\n// `assetId` names a media entry declared on the Timeline: timeline({ assets: { hero: { kind: 'image', url } } })\nnew Image({ assetId: 'hero', position: [160, 100], width: 200, height: 120 });",
+		run: () => renders(new ImageNode({
+			assetId: "hero",
+			position: [160, 100],
+			width: 200,
+			height: 120
+		}))
+	},
+	{
+		key: "to",
+		code: "import { timeline } from '@glissade/core';\n// `from` anchors the start; the per-target cursor advances by `duration`\ntimeline((tl) => tl.to('card/position', [200, 100], { duration: 1, from: [0, 0] }));",
+		run: () => void timeline((tl) => tl.to("card/position", [200, 100], {
+			duration: 1,
+			from: [0, 0]
+		}))
+	},
+	{
+		key: "fromTo",
+		code: "import { timeline } from '@glissade/core';\ntimeline((tl) => tl.fromTo('card/opacity', 0, 1, { duration: 0.5 }));",
+		run: () => void timeline((tl) => tl.fromTo("card/opacity", 0, 1, { duration: .5 }))
+	},
+	{
+		key: "stagger",
+		code: "import { timeline } from '@glissade/core';\n// one tween per target, cascaded by `each`; `anchor` picks where the cascade ranks from\ntimeline((tl) => tl.stagger(['a/opacity', 'b/opacity', 'c/opacity'], { to: 1, from: 0, duration: 0.4 }, { each: 0.1 }));",
+		run: () => void timeline((tl) => tl.stagger([
+			"a/opacity",
+			"b/opacity",
+			"c/opacity"
+		], {
+			to: 1,
+			from: 0,
+			duration: .4
+		}, { each: .1 }))
+	},
+	{
+		key: "set",
+		code: "import { timeline } from '@glissade/core';\n// a hold key — the value snaps at the resolved position\ntimeline((tl) => tl.set('card/fill', '#ef4444', { at: 0.5 }));",
+		run: () => void timeline((tl) => tl.set("card/fill", "#ef4444", { at: .5 }))
+	},
+	{
+		key: "tracks",
+		code: "import { timeline, track, key } from '@glissade/core';\n// attach raw keyframe tracks (the value type is the 2nd arg)\ntimeline((tl) => tl.tracks([track('card/x', 'number', [key(0, 0), key(1, 100)])]));",
+		run: () => void timeline((tl) => tl.tracks([track("card/x", "number", [key(0, 0), key(1, 100)])]))
+	},
+	{
+		key: "splitText",
+		code: "import { splitText } from '@glissade/scene/type';\n// the source needs an `id` — parts bind tracks against `<id>/<i>`. sp.targets('opacity') gives the reveal-recipe targets\nconst sp = splitText({ id: 'title', text: 'Hello', fontSize: 40 }, { by: 'grapheme' });",
+		run: () => void splitText({
+			id: "title",
+			text: "Hello",
+			fontSize: 40
+		}, { by: "grapheme" })
+	},
+	{
+		key: "measureWrappedText",
+		code: "import { createScene } from '@glissade/scene';\n// size a bubble/card to wrapped text WITHOUT a Text node (the FontSpec field is `size`, not `fontSize`)\nconst scene = createScene({ size: { w: 400, h: 200 }, children: [] });\nconst { width, lines, height } = scene.measureWrappedText('a long string that wraps across the box', { family: 'sans-serif', size: 24 }, 280);",
+		run: () => {
+			createScene({
+				size: {
+					w: 400,
+					h: 200
+				},
+				children: []
+			}).measureWrappedText("a long string that wraps across the box", {
+				family: "sans-serif",
+				size: 24
+			}, 280);
+		}
+	},
+	{
+		key: "Grid",
+		code: "import { Grid } from '@glissade/scene/grid';\n// build-time fan-out into a column grid (no Yoga) — children move to cell centers.\n// fr columns (`columns: 3`) need a `width` to resolve against; `cellHeight` is the row pitch\nGrid({ columns: 3, width: 360, gap: 16, cellHeight: 80, children: [new Rect({ width: 80, height: 60 }), new Rect({ width: 80, height: 60 })] });",
+		run: () => void Grid({
+			columns: 3,
+			width: 360,
+			gap: 16,
+			cellHeight: 80,
+			children: [new Rect({
+				width: 80,
+				height: 60
+			}), new Rect({
+				width: 80,
+				height: 60
+			})]
+		})
+	},
+	{
+		key: "Stack",
+		code: "import { Stack } from '@glissade/scene/layout';\nimport { loadYogaLayoutEngine } from '@glissade/scene/layout';\n// flexbox via Yoga — load the engine ONCE before evaluating any layout scene:\n// await loadYogaLayoutEngine();\nStack({ direction: 'row', gap: 16, children: [new Rect({ width: 80, height: 80 }), new Rect({ width: 80, height: 80 })] });",
+		run: () => void Stack({
+			direction: "row",
+			gap: 16,
+			children: [new Rect({
+				width: 80,
+				height: 80
+			}), new Rect({
+				width: 80,
+				height: 80
+			})]
+		})
+	},
+	{
+		key: "motionPath",
+		code: "import { motionPath } from '@glissade/scene/motion';\nimport { pathFromSvg } from '@glissade/scene/path';\nconst mp = motionPath(pathFromSvg('M0 0 C50 0 50 100 100 100'));\nconst pointHalfway = mp.atProgress(0.5); // { x, y }",
+		run: () => void motionPath(pathFromSvg("M0 0 C50 0 50 100 100 100")).atProgress(.5)
+	}
+];
+/** Group the corpus by describe-key → the surfaced code snippets. */
+function examplesByKey() {
+	const byKey = {};
+	for (const ex of EXAMPLES) (byKey[ex.key] ??= []).push(ex.code);
+	return byKey;
+}
+registerExamples(examplesByKey());
+//#endregion
+export { EXAMPLES, examplesByKey };

package/dist/motion.js

@@ -1,171 +1,2 @@
-import { a as Path, p as Node } from "./nodes.js";
-import { signal } from "@glissade/core";
-//#region src/motionPath.ts
-/**
-* Motion along a path: sample a point (and tangent) at an arc-length position on
-* a PathValue, and drive a node along it over time. The Path node draws/morphs
-* geometry; this is the companion that makes another node — a cursor, a dot, an
-* arrow — *travel* that geometry.
-*
-* Sampling is arc-length parameterized (constant speed), so progress 0→1 moves
-* evenly instead of bunching at the control points. Pure and deterministic: the
-* table is built once from a static PathValue and `atProgress` is a pure
-* function of progress, so evaluate() stays pure and goldens are byte-stable.
-*/
-const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
-function cubicPoint(p0, p1, p2, p3, t) {
-	const mt = 1 - t;
-	const a = mt * mt * mt;
-	const b = 3 * mt * mt * t;
-	const c = 3 * mt * t * t;
-	const d = t * t * t;
-	return [a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]];
-}
-/** PathValue contours → cubic segments, same v/in/out math as Path.pathSegs. */
-function toCubics(path) {
-	const out = [];
-	for (const ct of path) {
-		const n = ct.v.length;
-		for (let i = 0; i < n - 1; i++) out.push([
-			ct.v[i],
-			[ct.v[i][0] + ct.out[i][0], ct.v[i][1] + ct.out[i][1]],
-			[ct.v[i + 1][0] + ct.in[i + 1][0], ct.v[i + 1][1] + ct.in[i + 1][1]],
-			ct.v[i + 1]
-		]);
-		if (ct.closed && n > 1) out.push([
-			ct.v[n - 1],
-			[ct.v[n - 1][0] + ct.out[n - 1][0], ct.v[n - 1][1] + ct.out[n - 1][1]],
-			[ct.v[0][0] + ct.in[0][0], ct.v[0][1] + ct.in[0][1]],
-			ct.v[0]
-		]);
-	}
-	return out;
-}
-/**
-* Build a reusable arc-length sampler. Densely samples each cubic into a
-* cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
-* are simple span lerps — smooth enough for motion, no per-call bezier solve.
-*/
-function motionPath(path, opts = {}) {
-	const steps = Math.max(1, Math.floor(opts.samplesPerSegment ?? 32));
-	const cubics = toCubics(path);
-	const pts = [];
-	const cum = [];
-	if (cubics.length > 0) {
-		let prev = cubicPoint(...cubics[0], 0);
-		pts.push(prev);
-		cum.push(0);
-		let acc = 0;
-		for (const cub of cubics) for (let k = 1; k <= steps; k++) {
-			const p = cubicPoint(...cub, k / steps);
-			acc += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
-			pts.push(p);
-			cum.push(acc);
-			prev = p;
-		}
-	} else {
-		const first = path[0]?.v[0];
-		pts.push(first ? [first[0], first[1]] : [0, 0]);
-		cum.push(0);
-	}
-	const total = cum[cum.length - 1];
-	const locate = (s) => {
-		if (total <= 0 || s <= 0) return {
-			i: 0,
-			f: 0
-		};
-		if (s >= total) return {
-			i: pts.length - 2,
-			f: 1
-		};
-		let i = 0;
-		while (i < cum.length - 1 && cum[i + 1] < s) i++;
-		const span = cum[i + 1] - cum[i];
-		return {
-			i,
-			f: span > 0 ? (s - cum[i]) / span : 0
-		};
-	};
-	const at = (s) => {
-		if (pts.length === 1) return [pts[0][0], pts[0][1]];
-		const { i, f } = locate(s);
-		const a = pts[i];
-		const b = pts[i + 1];
-		return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
-	};
-	const tangentAt = (s) => {
-		if (pts.length === 1) return [1, 0];
-		const { i } = locate(s);
-		const a = pts[i];
-		const b = pts[i + 1];
-		const dx = b[0] - a[0];
-		const dy = b[1] - a[1];
-		const len = Math.hypot(dx, dy);
-		return len > 0 ? [dx / len, dy / len] : [1, 0];
-	};
-	return {
-		length: total,
-		at,
-		tangentAt,
-		atProgress: (u) => at(clamp01(u) * total),
-		tangentAtProgress: (u) => tangentAt(clamp01(u) * total)
-	};
-}
-/** Total arc length of a path. */
-function pathLength(path) {
-	return motionPath(path).length;
-}
-/** Point at arc-length s along a path (clamped to [0, length]). */
-function pointAtLength(path, s) {
-	return motionPath(path).at(s);
-}
-/**
-* A companion node that drives `target` along `path` as `progress` animates.
-* Owns the target's `position` (and `rotation` when `orient`) via pull-based
-* binding, so there's no eval-order side effect. Add it to the scene (its
-* `progress` is the animatable target); it draws nothing itself.
-*/
-var FollowPath = class extends Node {
-	target;
-	progress;
-	constructor(props) {
-		super(props);
-		this.target = props.target;
-		this.progress = signal(1);
-		if (typeof props.progress === "function") this.progress.bindSource(props.progress);
-		else if (props.progress !== void 0) this.progress.set(props.progress);
-		this.registerTarget("progress", this.progress, "number");
-		const sOpts = props.samplesPerSegment !== void 0 ? { samplesPerSegment: props.samplesPerSegment } : {};
-		const getPath = props.path instanceof Path ? () => props.path.data() : () => props.path;
-		let cachedPath = getPath();
-		let cachedSampler = motionPath(cachedPath, sOpts);
-		const sampler = () => {
-			const pv = getPath();
-			if (pv !== cachedPath) {
-				cachedPath = pv;
-				cachedSampler = motionPath(pv, sOpts);
-			}
-			return cachedSampler;
-		};
-		props.target.position.bindSource(() => sampler().atProgress(this.progress()));
-		if (props.orient) {
-			const offset = props.orientOffset ?? 0;
-			props.target.rotation.bindSource(() => {
-				const t = sampler().tangentAtProgress(this.progress());
-				return Math.atan2(t[1], t[0]) * 180 / Math.PI + offset;
-			});
-		}
-	}
-	draw() {}
-};
-/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route.
-* Pass the Path *node* to follow it as it morphs; pass a PathValue for a fixed route. */
-function followPath(target, path, props = {}) {
-	return new FollowPath({
-		...props,
-		target,
-		path
-	});
-}
-//#endregion
+import { a as pointAtLength, i as pathLength, n as followPath, r as motionPath, t as FollowPath } from "./motionPath.js";
 export { FollowPath, followPath, motionPath, pathLength, pointAtLength };

package/dist/motionPath.js

@@ -0,0 +1,171 @@
+import { a as Path, p as Node } from "./nodes.js";
+import { signal } from "@glissade/core";
+//#region src/motionPath.ts
+/**
+* Motion along a path: sample a point (and tangent) at an arc-length position on
+* a PathValue, and drive a node along it over time. The Path node draws/morphs
+* geometry; this is the companion that makes another node — a cursor, a dot, an
+* arrow — *travel* that geometry.
+*
+* Sampling is arc-length parameterized (constant speed), so progress 0→1 moves
+* evenly instead of bunching at the control points. Pure and deterministic: the
+* table is built once from a static PathValue and `atProgress` is a pure
+* function of progress, so evaluate() stays pure and goldens are byte-stable.
+*/
+const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+function cubicPoint(p0, p1, p2, p3, t) {
+	const mt = 1 - t;
+	const a = mt * mt * mt;
+	const b = 3 * mt * mt * t;
+	const c = 3 * mt * t * t;
+	const d = t * t * t;
+	return [a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]];
+}
+/** PathValue contours → cubic segments, same v/in/out math as Path.pathSegs. */
+function toCubics(path) {
+	const out = [];
+	for (const ct of path) {
+		const n = ct.v.length;
+		for (let i = 0; i < n - 1; i++) out.push([
+			ct.v[i],
+			[ct.v[i][0] + ct.out[i][0], ct.v[i][1] + ct.out[i][1]],
+			[ct.v[i + 1][0] + ct.in[i + 1][0], ct.v[i + 1][1] + ct.in[i + 1][1]],
+			ct.v[i + 1]
+		]);
+		if (ct.closed && n > 1) out.push([
+			ct.v[n - 1],
+			[ct.v[n - 1][0] + ct.out[n - 1][0], ct.v[n - 1][1] + ct.out[n - 1][1]],
+			[ct.v[0][0] + ct.in[0][0], ct.v[0][1] + ct.in[0][1]],
+			ct.v[0]
+		]);
+	}
+	return out;
+}
+/**
+* Build a reusable arc-length sampler. Densely samples each cubic into a
+* cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
+* are simple span lerps — smooth enough for motion, no per-call bezier solve.
+*/
+function motionPath(path, opts = {}) {
+	const steps = Math.max(1, Math.floor(opts.samplesPerSegment ?? 32));
+	const cubics = toCubics(path);
+	const pts = [];
+	const cum = [];
+	if (cubics.length > 0) {
+		let prev = cubicPoint(...cubics[0], 0);
+		pts.push(prev);
+		cum.push(0);
+		let acc = 0;
+		for (const cub of cubics) for (let k = 1; k <= steps; k++) {
+			const p = cubicPoint(...cub, k / steps);
+			acc += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
+			pts.push(p);
+			cum.push(acc);
+			prev = p;
+		}
+	} else {
+		const first = path[0]?.v[0];
+		pts.push(first ? [first[0], first[1]] : [0, 0]);
+		cum.push(0);
+	}
+	const total = cum[cum.length - 1];
+	const locate = (s) => {
+		if (total <= 0 || s <= 0) return {
+			i: 0,
+			f: 0
+		};
+		if (s >= total) return {
+			i: pts.length - 2,
+			f: 1
+		};
+		let i = 0;
+		while (i < cum.length - 1 && cum[i + 1] < s) i++;
+		const span = cum[i + 1] - cum[i];
+		return {
+			i,
+			f: span > 0 ? (s - cum[i]) / span : 0
+		};
+	};
+	const at = (s) => {
+		if (pts.length === 1) return [pts[0][0], pts[0][1]];
+		const { i, f } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
+	};
+	const tangentAt = (s) => {
+		if (pts.length === 1) return [1, 0];
+		const { i } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		const dx = b[0] - a[0];
+		const dy = b[1] - a[1];
+		const len = Math.hypot(dx, dy);
+		return len > 0 ? [dx / len, dy / len] : [1, 0];
+	};
+	return {
+		length: total,
+		at,
+		tangentAt,
+		atProgress: (u) => at(clamp01(u) * total),
+		tangentAtProgress: (u) => tangentAt(clamp01(u) * total)
+	};
+}
+/** Total arc length of a path. */
+function pathLength(path) {
+	return motionPath(path).length;
+}
+/** Point at arc-length s along a path (clamped to [0, length]). */
+function pointAtLength(path, s) {
+	return motionPath(path).at(s);
+}
+/**
+* A companion node that drives `target` along `path` as `progress` animates.
+* Owns the target's `position` (and `rotation` when `orient`) via pull-based
+* binding, so there's no eval-order side effect. Add it to the scene (its
+* `progress` is the animatable target); it draws nothing itself.
+*/
+var FollowPath = class extends Node {
+	target;
+	progress;
+	constructor(props) {
+		super(props);
+		this.target = props.target;
+		this.progress = signal(1);
+		if (typeof props.progress === "function") this.progress.bindSource(props.progress);
+		else if (props.progress !== void 0) this.progress.set(props.progress);
+		this.registerTarget("progress", this.progress, "number");
+		const sOpts = props.samplesPerSegment !== void 0 ? { samplesPerSegment: props.samplesPerSegment } : {};
+		const getPath = props.path instanceof Path ? () => props.path.data() : () => props.path;
+		let cachedPath = getPath();
+		let cachedSampler = motionPath(cachedPath, sOpts);
+		const sampler = () => {
+			const pv = getPath();
+			if (pv !== cachedPath) {
+				cachedPath = pv;
+				cachedSampler = motionPath(pv, sOpts);
+			}
+			return cachedSampler;
+		};
+		props.target.position.bindSource(() => sampler().atProgress(this.progress()));
+		if (props.orient) {
+			const offset = props.orientOffset ?? 0;
+			props.target.rotation.bindSource(() => {
+				const t = sampler().tangentAtProgress(this.progress());
+				return Math.atan2(t[1], t[0]) * 180 / Math.PI + offset;
+			});
+		}
+	}
+	draw() {}
+};
+/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route.
+* Pass the Path *node* to follow it as it morphs; pass a PathValue for a fixed route. */
+function followPath(target, path, props = {}) {
+	return new FollowPath({
+		...props,
+		target,
+		path
+	});
+}
+//#endregion
+export { pointAtLength as a, pathLength as i, followPath as n, motionPath as r, FollowPath as t };

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@glissade/scene",
-  "version": "0.23.0-pre.5",
+  "version": "0.24.0-pre.0",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20.19"
   },
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/examples.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -52,6 +54,10 @@
     "./identity": {
       "types": "./dist/identity.d.ts",
       "default": "./dist/identity.js"
+    },
+    "./examples": {
+      "types": "./dist/examples.d.ts",
+      "default": "./dist/examples.js"
     }
   },
   "files": [
@@ -59,7 +65,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.23.0-pre.5"
+    "@glissade/core": "0.24.0-pre.0"
   },
   "repository": {
     "type": "git",