@glissade/scene 0.25.0 → 0.26.0-pre.1

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.25.0";
+const RAW_VERSION = "0.26.0-pre.1";
 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) {
@@ -327,6 +327,24 @@ const HELPERS = [
 		import: "@glissade/scene/motion",
 		usage: "followPath(target: Node, path: Node, opts?: { id?, orient?: boolean }): FollowPath  —  drive '<id>/progress' with a track"
 	},
+	{
+		name: "orientToPath",
+		summary: "The rotation-only sibling of followPath: owns a target's rotation, banking it to the path tangent at progress, while POSITION is left to whatever drives it (keyframes, layout, a sibling followPath). Pure, tree-shakeable.",
+		import: "@glissade/scene/motion",
+		usage: "orientToPath(target: Node, path: PathValue | Path, opts?: { id?, progress?, offset?: number }): OrientToPath  —  drive '<id>/progress' with a track"
+	},
+	{
+		name: "lookAt",
+		summary: "A driver node that owns a target's rotation, aiming its local +x axis at another node's world origin — a turret tracking a mover, an arrow pointing at a label. Re-derives from both positions each frame; no stored state.",
+		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[].",
@@ -339,6 +357,12 @@ const HELPERS = [
 		import: "@glissade/core/clips",
 		usage: "clipList(clip: Clip, targets: string[], startT: number, opts?: { stagger?: number }): { tracks }"
 	},
+	{
+		name: "retime",
+		summary: "Retime a set of tracks by remapping their key TIMES — speed (slow-mo/fast), shift (delay/advance), reverse, or pingpong — as a pure build-time transform to ordinary retimed Track[]. Reverse/pingpong time-mirror each ease exactly (built-ins + cubicBezier); springs/holds fail loud.",
+		import: "@glissade/core",
+		usage: "retime(tracks: Track[], { speed?, shift?, reverse?, pingpong? }): Track[]"
+	},
 	{
 		name: "renderToDataURL",
 		summary: "Capture a single frame as a PNG/WebP data URL — evaluate → render → data-URL, the no-build screenshot DX helper. Browser-only.",

package/dist/diagnostics.js

@@ -153,12 +153,14 @@ function auditCacheCold(createScene, doc, t) {
 	const ctxA = {
 		time: t,
 		frame,
-		measurer: warm.textMeasurer
+		measurer: warm.textMeasurer,
+		playhead: warm.playhead
 	};
 	const ctxB = {
 		time: t,
 		frame,
-		measurer: cold.textMeasurer
+		measurer: cold.textMeasurer,
+		playhead: cold.playhead
 	};
 	let groupFallback;
 	for (const [id, nodeA] of warm.nodes) {

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/identity.js

@@ -52,7 +52,8 @@ function emitWithIds(scene, doc, t) {
 	const ctx = {
 		time: t,
 		frame: fps !== void 0 ? Math.round(t * fps) : -1,
-		measurer: scene.textMeasurer
+		measurer: scene.textMeasurer,
+		playhead: scene.playhead
 	};
 	return evaluateAt(scene.playhead, t, () => {
 		const builder = instrument(createDisplayListBuilder(scene.size));

package/dist/index.d.ts

@@ -423,6 +423,28 @@ declare class ShaderEffect extends Group {
   protected groupShader(): ShaderRef;
 }
 //#endregion
+//#region src/echo.d.ts
+interface EchoProps extends NodeProps {
+  children?: Node[];
+  /** total copies including the live one (≥ 1); default 5. */
+  count?: number;
+  /** seconds between successive copies (the trail's time spread); default 0.08. */
+  spacing?: number;
+  /** opacity multiplier per trailing step — copy i has opacity decay^i (0..1); default 0.6. */
+  decay?: number;
+}
+declare class Echo extends Group {
+  get describeType(): string;
+  readonly count: number;
+  readonly spacing: number;
+  readonly decay: number;
+  constructor(props?: EchoProps);
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/** `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. */
+declare function echo(child: Node, props?: Omit<EchoProps, 'children'>): Echo;
+//#endregion
 //#region src/raster2d.d.ts
 /** A backend gradient handle (DOM CanvasGradient and @napi-rs CanvasGradient both satisfy it). */
 interface CanvasGradientLike {
@@ -619,4 +641,4 @@ declare function meshRasterSize(bw: number, bh: number): {
   h: number;
 };
 //#endregion
-export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, Custom, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EachBox, type EachContext, type EachDistribute, EachError, type EachLayout, type EachMotion, type EachOpts, type EachResult, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, type FontByteLoader, type FontSpec, type GraphemeBox, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, NodeConstructionError, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSeg, type Place, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, type WrappedTextMetrics, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, Custom, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EachBox, type EachContext, type EachDistribute, EachError, type EachLayout, type EachMotion, type EachOpts, type EachResult, Echo, type EchoProps, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, type FontByteLoader, type FontSpec, type GraphemeBox, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, NodeConstructionError, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSeg, type Place, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, type WrappedTextMetrics, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, echo, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -1,6 +1,7 @@
 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 { 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
 /**
@@ -1356,4 +1357,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DeterminismViolationError, DuplicateNodeIdError, EachError, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, NodeConstructionError, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, Video, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DeterminismViolationError, DuplicateNodeIdError, EachError, Echo, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, NodeConstructionError, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, Video, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, echo, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/motion.d.ts

@@ -57,4 +57,58 @@ declare class FollowPath extends Node {
  * Pass the Path *node* to follow it as it morphs; pass a PathValue for a fixed route. */
 declare function followPath(target: Node, path: PathValue | Path, props?: Omit<FollowPathProps, 'target' | 'path'>): FollowPath;
 //#endregion
-export { FollowPath, type FollowPathProps, type PathSampler, followPath, motionPath, pathLength, pointAtLength };
+//#region src/orient.d.ts
+interface OrientToPathProps extends NodeProps {
+  /** the node whose `rotation` this owns (position is left to whatever drives it) */
+  target: Node;
+  /** a static PathValue, or a Path node followed LIVE (re-sampled as its `data` morphs) */
+  path: PathValue | Path;
+  /** 0→1 arc-length position whose TANGENT sets the angle; default 1. Track `<id>/progress`. */
+  progress?: PropInit<number>;
+  /** degrees added to the tangent angle (e.g. if the sprite points up at rest) */
+  offset?: number;
+  samplesPerSegment?: number;
+}
+/**
+ * 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`.
+ */
+declare class OrientToPath extends Node {
+  readonly target: Node;
+  readonly progress: BindableSignal<number>;
+  constructor(props: OrientToPathProps);
+  protected draw(): void;
+}
+/** `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. */
+declare function orientToPath(target: Node, path: PathValue | Path, props?: Omit<OrientToPathProps, 'target' | 'path'>): OrientToPath;
+interface LookAtProps extends NodeProps {
+  /** the node whose `rotation` this owns */
+  target: Node;
+  /** the node to face — `target` rotates so its +x axis points at `at`'s origin */
+  at: Node;
+  /** degrees added to the facing angle (e.g. if the sprite points up at rest, pass -90) */
+  offset?: number;
+}
+/**
+ * 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.
+ */
+declare class LookAt extends Node {
+  readonly target: Node;
+  readonly at: Node;
+  constructor(props: LookAtProps);
+  protected draw(): void;
+}
+/** `children: [turret, mover, lookAt(turret, mover)]` — turret always faces the mover. */
+declare function lookAt(target: Node, at: Node, props?: Omit<LookAtProps, 'target' | 'at'>): LookAt;
+//#endregion
+export { FollowPath, type FollowPathProps, LookAt, type LookAtProps, OrientToPath, type OrientToPathProps, type PathSampler, followPath, lookAt, motionPath, orientToPath, pathLength, pointAtLength };

package/dist/motion.js

@@ -1,2 +1,2 @@
-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 };
+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/nodes.d.ts

@@ -1,5 +1,5 @@
 import { C as Mat2x3, a as FilterSpec, d as Paint, f as PathSeg, g as ShaderRef, r as DisplayListBuilder, s as FontSpec, t as BlendMode } from "./displayList.js";
-import { BindableSignal, FontAxes, PathValue, ReadonlySignal, Rng, Track, ValueTypeId, Vec2, Vec2Signal } from "@glissade/core";
+import { BindableSignal, FontAxes, PathValue, Playhead, ReadonlySignal, Rng, Track, ValueTypeId, Vec2, Vec2Signal } from "@glissade/core";
 
 //#region src/text.d.ts
 
@@ -125,6 +125,16 @@ interface EvalContext {
   readonly frame: number;
   /** Injected by mount()/CLI/exporters (§3.2): the active backend's measurer. */
   readonly measurer: TextMeasurer;
+  /**
+   * The scene playhead being driven this evaluate. The one channel a node may
+   * re-address WITHIN a frame to sample its subtree at an OFFSET time (Echo's
+   * trails / onion-skin) — always restored before the walk continues, so it is
+   * a pure, re-entrant read. Everything else reads it only through bound signals.
+   * Optional: the real evaluate()/emitWithIds()/cache-cold audit always supply
+   * it; a bare hand-built ctx (a unit test emitting one node) may omit it, and a
+   * playhead-dependent node degrades gracefully (Echo → a plain group).
+   */
+  readonly playhead?: Playhead;
 }
 /** A property initializer: a value, or a computed source (§2.1). */
 type PropInit<T> = T | (() => T);

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/dist/scene.js

@@ -109,7 +109,8 @@ function evaluate(scene, doc, t = 0) {
 	const ctx = {
 		time: t,
 		frame: fps !== void 0 ? Math.round(t * fps) : -1,
-		measurer: scene.textMeasurer
+		measurer: scene.textMeasurer,
+		playhead: scene.playhead
 	};
 	return evaluateAt(scene.playhead, t, () => {
 		const out = createDisplayListBuilder(scene.size);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.25.0",
+  "version": "0.26.0-pre.1",
   "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.25.0"
+    "@glissade/core": "0.26.0-pre.1"
   },
   "repository": {
     "type": "git",