@glissade/scene 0.26.0-pre.0 → 0.26.0

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.26.0-pre.0";
+const RAW_VERSION = "0.26.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) {
@@ -339,6 +339,12 @@ const HELPERS = [
 		import: "@glissade/scene/motion",
 		usage: "lookAt(target: Node, at: Node, opts?: { id?, offset?: number }): LookAt"
 	},
+	{
+		name: "echo",
+		summary: "Motion trails / onion-skin: wrap a child so it renders at K past playhead offsets (t − i·spacing), each trailing copy fading by decay. A pure multi-time re-eval (the playhead is re-addressed per copy and restored), byte-stable in the golden corpus. Add the returned Echo to the scene.",
+		import: "@glissade/scene",
+		usage: "echo(child: Node, opts?: { id?, count?: number, spacing?: number, decay?: number }): Echo"
+	},
 	{
 		name: "clip",
 		summary: "A reusable, target-agnostic motion captured once as a relative-time key schedule, then applied to a node at a wall-clock start time. Build-time sugar: clip.apply() compiles to ordinary Track[].",

package/dist/echo.js

@@ -0,0 +1,78 @@
+import { r as Group } from "./nodes.js";
+import { batch } from "@glissade/core";
+//#region src/echo.ts
+/**
+* Echo (0.26): motion trails / onion-skin. A wrapper group that renders its
+* children K times — at the playhead and at K−1 earlier offsets (t − i·spacing)
+* — each trailing copy fading by `decay`. The leading copy is the live frame;
+* the ghosts are the subtree "as it was" a few slices ago.
+*
+* It is the pure render form of "re-evaluate at t + k·spacing": within one
+* frame it re-addresses the SCENE PLAYHEAD to each offset time, emits the
+* children (whose bound signals re-derive at that time — tracks, followPath,
+* computeds all follow), then RESTORES the playhead before the walk continues.
+* The whole dance is wrapped in `batch()` so the playhead's subscribers (a
+* player repaint) coalesce to a single, idempotent notification at the restored
+* time — never a mid-emit reentrancy storm. Headless (goldens/export) the
+* playhead has no subscribers, so it is a plain pure multi-sample: evaluate()
+* stays a pure function of time and the DisplayList is byte-stable.
+*
+* Determinism note: the offsets are pure functions of the current playhead, so
+* a cold re-eval reproduces byte-identically (the cache-cold audit passes).
+* Ghost times before the first key clamp to the initial pose (track semantics).
+*/
+var Echo = class extends Group {
+	get describeType() {
+		return "Echo";
+	}
+	count;
+	spacing;
+	decay;
+	constructor(props = {}) {
+		super(props);
+		this.count = Math.max(1, Math.floor(props.count ?? 5));
+		this.spacing = props.spacing ?? .08;
+		this.decay = props.decay ?? .6;
+	}
+	draw(out, ctx) {
+		const playhead = ctx.playhead;
+		if (this.count <= 1 || this.spacing === 0 || playhead === void 0) {
+			super.draw(out, ctx);
+			return;
+		}
+		const now = ctx.time;
+		batch(() => {
+			try {
+				for (let i = this.count - 1; i >= 0; i--) {
+					const alpha = i === 0 ? 1 : this.decay ** i;
+					if (alpha <= 0) continue;
+					const offsetT = now - i * this.spacing;
+					playhead.forceSet(offsetT);
+					out.push({
+						op: "pushGroup",
+						opacity: alpha,
+						blend: "source-over",
+						filters: []
+					});
+					super.draw(out, {
+						...ctx,
+						time: offsetT
+					});
+					out.push({ op: "popGroup" });
+				}
+			} finally {
+				playhead.forceSet(now);
+			}
+		});
+	}
+};
+/** `children: [echo(mover, { count: 6, spacing: 0.05 })]` — mover leaves a fading trail.
+* A convenience wrapper: pass the trailing content as children of the returned Echo. */
+function echo(child, props = {}) {
+	return new Echo({
+		...props,
+		children: [child]
+	});
+}
+//#endregion
+export { echo as n, Echo as t };

package/dist/examples.js

@@ -4,9 +4,10 @@ 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 { i as orientToPath, r as lookAt, s as motionPath } from "./orient.js";
+import { n as echo } from "./echo.js";
 import { pathFromSvg } from "./path.js";
-import { key, timeline, track } from "@glissade/core";
+import { key, retime, timeline, track } from "@glissade/core";
 //#region src/examples.ts
 /**
 * `@glissade/scene/examples` — the runnable example corpus (§0.24 onboarding,
@@ -204,6 +205,58 @@ const EXAMPLES = [
 		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)
+	},
+	{
+		key: "orientToPath",
+		code: "import { Rect } from '@glissade/scene';\nimport { orientToPath } from '@glissade/scene/motion';\nimport { pathFromSvg } from '@glissade/scene/path';\n// rotation-only sibling of followPath: banks the target to the path tangent while its\n// POSITION comes from elsewhere. Drive '<id>/progress' with a track; `offset` if it rests facing up.\nconst sprite = new Rect({ id: 'sprite', width: 12, height: 12 });\norientToPath(sprite, pathFromSvg('M0 0 L100 0 L100 100'), { id: 'bank', progress: 0.5 });",
+		run: () => {
+			orientToPath(new Rect({
+				id: "sprite",
+				width: 12,
+				height: 12
+			}), pathFromSvg("M0 0 L100 0 L100 100"), {
+				id: "bank",
+				progress: .5
+			});
+		}
+	},
+	{
+		key: "lookAt",
+		code: "import { Rect, Circle } from '@glissade/scene';\nimport { lookAt } from '@glissade/scene/motion';\n// aim the target's local +x axis at another node's world origin (a turret tracking a mover)\nconst turret = new Rect({ id: 'turret', width: 12, height: 12, position: [0, 0] });\nconst mover = new Circle({ id: 'mover', radius: 6, position: [40, 20] });\nlookAt(turret, mover);",
+		run: () => {
+			lookAt(new Rect({
+				id: "turret",
+				width: 12,
+				height: 12,
+				position: [0, 0]
+			}), new Circle({
+				id: "mover",
+				radius: 6,
+				position: [40, 20]
+			}));
+		}
+	},
+	{
+		key: "retime",
+		code: "import { retime, track, key } from '@glissade/core';\n// pure key-time transform → ordinary retimed tracks (speed / shift / reverse / pingpong)\nconst move = [track('box/position.x', 'number', [key(0, 0), key(1, 100, 'easeInCubic')])];\nconst slow = retime(move, { speed: 0.5 });    // half speed\nconst back = retime(move, { reverse: true }); // play it backward",
+		run: () => {
+			const move = [track("box/position.x", "number", [key(0, 0), key(1, 100, "easeInCubic")])];
+			retime(move, { speed: .5 });
+			retime(move, { reverse: true });
+		}
+	},
+	{
+		key: "echo",
+		code: "import { Circle, echo } from '@glissade/scene';\n// motion trail / onion-skin: renders the child at K past playhead offsets, each fading by `decay`.\n// Add the returned Echo to the scene; drive the child however you like (its ghosts re-derive at each offset).\nconst dot = new Circle({ id: 'dot', radius: 8, fill: '#39e0ff' });\nconst trail = echo(dot, { count: 6, spacing: 0.05, decay: 0.7 });",
+		run: () => void echo(new Circle({
+			id: "dot",
+			radius: 8,
+			fill: "#39e0ff"
+		}), {
+			count: 6,
+			spacing: .05,
+			decay: .7
+		})
 	}
 ];
 /**

package/dist/index.js

@@ -1,7 +1,8 @@
 import { $ as multiply, A as setDefaultMeasurer, B as validateHachure, C as estimatingMeasurer, D as quantize, E as measureWrappedText, F as hachureLines, G as glow, H as FilterValidationError, I as hashStr, J as IDENTITY, K as validateFilters, L as resolveSketch, M as SketchValidationError, N as arcLength, O as segmentGraphemes, P as flatten, Q as matEquals, R as roughen, S as breakLines, T as isEstimatingMeasurer, U as createDisplayListBuilder, V as validateSketch, W as filtersToCanvasFilter, X as fromTRS, Y as applyToPoint, Z as invert, a as Path, b as __resetEstimateWarnings, c as Video, d as revealSchedule, f as roundedRectSegs, h as resolveAnchor, i as ImageNode, k as segmentWords, l as coercePathData, m as NodeConstructionError, n as Custom, o as Rect, p as Node, q as collapseReplacer, r as Group, s as Text, t as Circle, u as pathFromSegs, x as assertFiniteFontSize, y as MEASURE_QUANTUM_PX, z as sketchStrokes } from "./nodes.js";
 import { a as evaluate, i as createScene, n as ReservedNodeIdError, r as bindScene, t as DuplicateNodeIdError } from "./scene.js";
 import { i as setLayoutEngine, n as getLayoutEngine, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
-import { batch, buildFontRegistry, emitDevWarning, key, lerpColor, oklabToRgba, parseCmap, parseColor, random, rgbaToOklab, signal, stagger, track, validateFonts } from "@glissade/core";
+import { n as echo, t as Echo } from "./echo.js";
+import { buildFontRegistry, emitDevWarning, key, lerpColor, oklabToRgba, parseCmap, parseColor, random, rgbaToOklab, signal, stagger, track, validateFonts } from "@glissade/core";
 //#region src/taxonomy.ts
 /**
 * The CLOSED node taxonomy (DESIGN.md §3.1): exactly nine built-in node TYPES.
@@ -670,81 +671,6 @@ var ShaderEffect = class extends Group {
 		};
 	}
 };
-//#endregion
-//#region src/echo.ts
-/**
-* Echo (0.26): motion trails / onion-skin. A wrapper group that renders its
-* children K times — at the playhead and at K−1 earlier offsets (t − i·spacing)
-* — each trailing copy fading by `decay`. The leading copy is the live frame;
-* the ghosts are the subtree "as it was" a few slices ago.
-*
-* It is the pure render form of "re-evaluate at t + k·spacing": within one
-* frame it re-addresses the SCENE PLAYHEAD to each offset time, emits the
-* children (whose bound signals re-derive at that time — tracks, followPath,
-* computeds all follow), then RESTORES the playhead before the walk continues.
-* The whole dance is wrapped in `batch()` so the playhead's subscribers (a
-* player repaint) coalesce to a single, idempotent notification at the restored
-* time — never a mid-emit reentrancy storm. Headless (goldens/export) the
-* playhead has no subscribers, so it is a plain pure multi-sample: evaluate()
-* stays a pure function of time and the DisplayList is byte-stable.
-*
-* Determinism note: the offsets are pure functions of the current playhead, so
-* a cold re-eval reproduces byte-identically (the cache-cold audit passes).
-* Ghost times before the first key clamp to the initial pose (track semantics).
-*/
-var Echo = class extends Group {
-	get describeType() {
-		return "Echo";
-	}
-	count;
-	spacing;
-	decay;
-	constructor(props = {}) {
-		super(props);
-		this.count = Math.max(1, Math.floor(props.count ?? 5));
-		this.spacing = props.spacing ?? .08;
-		this.decay = props.decay ?? .6;
-	}
-	draw(out, ctx) {
-		const playhead = ctx.playhead;
-		if (this.count <= 1 || this.spacing === 0 || playhead === void 0) {
-			super.draw(out, ctx);
-			return;
-		}
-		const now = ctx.time;
-		batch(() => {
-			try {
-				for (let i = this.count - 1; i >= 0; i--) {
-					const alpha = i === 0 ? 1 : this.decay ** i;
-					if (alpha <= 0) continue;
-					const offsetT = now - i * this.spacing;
-					playhead.forceSet(offsetT);
-					out.push({
-						op: "pushGroup",
-						opacity: alpha,
-						blend: "source-over",
-						filters: []
-					});
-					super.draw(out, {
-						...ctx,
-						time: offsetT
-					});
-					out.push({ op: "popGroup" });
-				}
-			} finally {
-				playhead.forceSet(now);
-			}
-		});
-	}
-};
-/** `children: [echo(mover, { count: 6, spacing: 0.05 })]` — mover leaves a fading trail.
-* A convenience wrapper: pass the trailing content as children of the returned Echo. */
-function echo(child, props = {}) {
-	return new Echo({
-		...props,
-		children: [child]
-	});
-}
 const smoothstep = (u) => u * u * (3 - 2 * u);
 const GAUSS_K = 2.4;
 const GAUSS_NORM = 1 - Math.exp(-5.76 / 2);

package/dist/motion.js

@@ -1,110 +1,2 @@
-import { Y as applyToPoint, a as Path, p as Node } from "./nodes.js";
-import { a as pointAtLength, i as pathLength, n as followPath, r as motionPath, t as FollowPath } from "./motionPath.js";
-import { signal } from "@glissade/core";
-//#region src/orient.ts
-/**
-* Orientation drivers: rotate a node to face where it's *heading* (a path
-* tangent) or to *look at* another node. Both are the rotation-only siblings of
-* `followPath` — companion driver nodes that own only the target's `rotation`
-* via pull-based binding, so position stays whatever else drives it (keyframes,
-* layout, a separate followPath). Nothing executes at play time beyond a pure
-* read of signals already in the graph, so evaluate() stays a pure function of
-* time and the goldens are byte-stable.
-*
-* These live on the tree-shakeable `@glissade/scene/motion` subpath (like
-* followPath) — the base embed doesn't pay for them.
-*/
-const DEG = 180 / Math.PI;
-/**
-* A node's origin in WORLD space, computed WITHOUT reading its own
-* `worldMatrix`/`localMatrix` signals. That matters for the node being oriented:
-* its localMatrix depends on `rotation`, so a rotation source that read
-* `this.worldMatrix()` would form a rotation → worldMatrix → rotation cycle.
-* Projecting `position` through the PARENT's world transform breaks the cycle
-* (a parent's world never depends on its child's rotation). This aims from the
-* node's position origin; an explicit `anchor` offset is not applied (v1).
-*/
-function worldOrigin(n) {
-	return n.parent ? applyToPoint(n.parent.worldMatrix(), n.position()) : n.position();
-}
-/**
-* Owns `target.rotation`, binding it to the path tangent at `progress` — a node
-* banks to face the direction of travel while its POSITION is driven elsewhere
-* (keyframes, layout, or a sibling followPath sharing the same `progress`). The
-* rotation-only half of followPath's `orient`. Add it to the scene; it draws
-* nothing. Animate `<id>/progress`.
-*/
-var OrientToPath = 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;
-		};
-		const offset = props.offset ?? 0;
-		props.target.rotation.bindSource(() => {
-			const t = sampler().tangentAtProgress(this.progress());
-			return Math.atan2(t[1], t[0]) * DEG + offset;
-		});
-	}
-	draw() {}
-};
-/** `children: [node, orientToPath(node, route, { progress: 0.5 })]` — node banks
-* to the route's direction at progress 0.5 while its position comes from elsewhere. */
-function orientToPath(target, path, props = {}) {
-	return new OrientToPath({
-		...props,
-		target,
-		path
-	});
-}
-/**
-* Owns `target.rotation`, aiming target's local +x axis at `at`'s world origin —
-* a turret tracking a mover, an arrow pointing at a label. The angle is computed
-* in WORLD space and applied as `target`'s LOCAL rotation, which is exact when
-* target's parent is unrotated (the common case); a rotated parent would need
-* the parent's world rotation subtracted (v1 does not). Pure: rotation re-derives
-* from both nodes' positions each read, no stored state. Add it to the scene; it
-* draws nothing.
-*/
-var LookAt = class extends Node {
-	target;
-	at;
-	constructor(props) {
-		super(props);
-		this.target = props.target;
-		this.at = props.at;
-		const offset = props.offset ?? 0;
-		props.target.rotation.bindSource(() => {
-			const self = worldOrigin(props.target);
-			const to = worldOrigin(props.at);
-			return Math.atan2(to[1] - self[1], to[0] - self[0]) * DEG + offset;
-		});
-	}
-	draw() {}
-};
-/** `children: [turret, mover, lookAt(turret, mover)]` — turret always faces the mover. */
-function lookAt(target, at, props = {}) {
-	return new LookAt({
-		...props,
-		target,
-		at
-	});
-}
-//#endregion
+import { a as FollowPath, c as pathLength, i as orientToPath, l as pointAtLength, n as OrientToPath, o as followPath, r as lookAt, s as motionPath, t as LookAt } from "./orient.js";
 export { FollowPath, LookAt, OrientToPath, followPath, lookAt, motionPath, orientToPath, pathLength, pointAtLength };

package/dist/{motionPath.js → orient.js}

@@ -1,4 +1,4 @@
-import { a as Path, p as Node } from "./nodes.js";
+import { Y as applyToPoint, a as Path, p as Node } from "./nodes.js";
 import { signal } from "@glissade/core";
 //#region src/motionPath.ts
 /**
@@ -168,4 +168,110 @@ function followPath(target, path, props = {}) {
 	});
 }
 //#endregion
-export { pointAtLength as a, pathLength as i, followPath as n, motionPath as r, FollowPath as t };
+//#region src/orient.ts
+/**
+* Orientation drivers: rotate a node to face where it's *heading* (a path
+* tangent) or to *look at* another node. Both are the rotation-only siblings of
+* `followPath` — companion driver nodes that own only the target's `rotation`
+* via pull-based binding, so position stays whatever else drives it (keyframes,
+* layout, a separate followPath). Nothing executes at play time beyond a pure
+* read of signals already in the graph, so evaluate() stays a pure function of
+* time and the goldens are byte-stable.
+*
+* These live on the tree-shakeable `@glissade/scene/motion` subpath (like
+* followPath) — the base embed doesn't pay for them.
+*/
+const DEG = 180 / Math.PI;
+/**
+* A node's origin in WORLD space, computed WITHOUT reading its own
+* `worldMatrix`/`localMatrix` signals. That matters for the node being oriented:
+* its localMatrix depends on `rotation`, so a rotation source that read
+* `this.worldMatrix()` would form a rotation → worldMatrix → rotation cycle.
+* Projecting `position` through the PARENT's world transform breaks the cycle
+* (a parent's world never depends on its child's rotation). This aims from the
+* node's position origin; an explicit `anchor` offset is not applied (v1).
+*/
+function worldOrigin(n) {
+	return n.parent ? applyToPoint(n.parent.worldMatrix(), n.position()) : n.position();
+}
+/**
+* Owns `target.rotation`, binding it to the path tangent at `progress` — a node
+* banks to face the direction of travel while its POSITION is driven elsewhere
+* (keyframes, layout, or a sibling followPath sharing the same `progress`). The
+* rotation-only half of followPath's `orient`. Add it to the scene; it draws
+* nothing. Animate `<id>/progress`.
+*/
+var OrientToPath = 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;
+		};
+		const offset = props.offset ?? 0;
+		props.target.rotation.bindSource(() => {
+			const t = sampler().tangentAtProgress(this.progress());
+			return Math.atan2(t[1], t[0]) * DEG + offset;
+		});
+	}
+	draw() {}
+};
+/** `children: [node, orientToPath(node, route, { progress: 0.5 })]` — node banks
+* to the route's direction at progress 0.5 while its position comes from elsewhere. */
+function orientToPath(target, path, props = {}) {
+	return new OrientToPath({
+		...props,
+		target,
+		path
+	});
+}
+/**
+* Owns `target.rotation`, aiming target's local +x axis at `at`'s world origin —
+* a turret tracking a mover, an arrow pointing at a label. The angle is computed
+* in WORLD space and applied as `target`'s LOCAL rotation, which is exact when
+* target's parent is unrotated (the common case); a rotated parent would need
+* the parent's world rotation subtracted (v1 does not). Pure: rotation re-derives
+* from both nodes' positions each read, no stored state. Add it to the scene; it
+* draws nothing.
+*/
+var LookAt = class extends Node {
+	target;
+	at;
+	constructor(props) {
+		super(props);
+		this.target = props.target;
+		this.at = props.at;
+		const offset = props.offset ?? 0;
+		props.target.rotation.bindSource(() => {
+			const self = worldOrigin(props.target);
+			const to = worldOrigin(props.at);
+			return Math.atan2(to[1] - self[1], to[0] - self[0]) * DEG + offset;
+		});
+	}
+	draw() {}
+};
+/** `children: [turret, mover, lookAt(turret, mover)]` — turret always faces the mover. */
+function lookAt(target, at, props = {}) {
+	return new LookAt({
+		...props,
+		target,
+		at
+	});
+}
+//#endregion
+export { FollowPath as a, pathLength as c, orientToPath as i, pointAtLength as l, OrientToPath as n, followPath as o, lookAt as r, motionPath as s, LookAt as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.26.0-pre.0",
+  "version": "0.26.0",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -65,7 +65,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.26.0-pre.0"
+    "@glissade/core": "0.26.0"
   },
   "repository": {
     "type": "git",