@glissade/scene 0.54.0 → 0.55.0-pre.0

package/dist/describe.js

@@ -23,7 +23,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.54.0";
+const RAW_VERSION = "0.55.0-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the
@@ -570,6 +570,24 @@ const HELPERS = [
 		import: "@glissade/scene",
 		usage: "echo(child: Node, opts?: { id?, count?: number, spacing?: number, decay?: number }): Echo"
 	},
+	{
+		name: "camera",
+		summary: "A cinematic camera rig (FACTORY, no `new`): a Group subclass that applies the inverse camera pose as a parent transform over layered content — push-ins, pans, rolls, and pan-only parallax by layer depth. The pose (center/zoom/roll) are keyframeable track targets; the world moves while nodes stay node-local (no double-apply with anchors). Captions belong as SIBLINGS of the camera (outside the rig) so they stay pinned. Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "camera(layers: { content: Node, depth? }[], props?: { id?, center?, zoom?, roll?, shake? }): Camera  —  center is RELATIVE viewport coords ([0.5,0.5]=center, never px); animate 'cam/center(.x/.y)', 'cam/zoom', 'cam/roll'. depth<1 = far (parallax pans less)."
+	},
+	{
+		name: "shake",
+		summary: "A standalone jitter driver (mutate-and-return, like orientToPath): wobbles ANY node’s pose with deterministic value noise, folded in at emit as a parent-space offset so it composes with whatever else drives the node. SEPARATE translate (px) / rotate (deg) / frequency (Hz) amplitudes; pure and byte-identical run-to-run (seeded, no Date/Math.random). Tree-shakeable (@glissade/scene/motion).",
+		import: "@glissade/scene/motion",
+		usage: "shake(node: Node, opts: { seed: number, translate?: number, rotate?: number, frequency?: number }): Node"
+	},
+	{
+		name: "valueNoise",
+		summary: "Closed-form smooth value noise: a PURE function of (seed, t) — lerp(rand(⌊t⌋), rand(⌊t⌋+1), smoothstep(fract t)) with core’s seeded hash. No state, no bake; deterministic by construction (byte-identical run-to-run), fps-independent, O(1), seekable — the closed-form sibling of a spring. Range [0,1); center a signed wobble with *2-1. The primitive behind shake + camera shake.",
+		import: "@glissade/core",
+		usage: "valueNoise(seed: number, t: number): number  //  jitterX = () => 3 * (valueNoise(7, t) * 2 - 1)"
+	},
 	{
 		name: "motionBlur",
 		summary: "Real sampled motion blur: wrap a child so it renders at N sub-frame times across a shutter interval (centered on the frame) and AVERAGES them — tracks every animated prop, not a faked directional blur. A pure multi-time re-eval (playhead re-addressed per sample, running-mean opacity, restored), byte-exact on Skia; browser↔Skia is perceptual-tier for blur.",

package/dist/identity.js

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

package/dist/motion.d.ts

@@ -1,5 +1,6 @@
-import { B as Node, H as NodeProps, U as PropInit, l as Path } from "./nodes.js";
-import { BindableSignal, PathValue, Vec2 } from "@glissade/core";
+import { r as DisplayListBuilder } from "./displayList.js";
+import { B as Node, H as NodeProps, R as EvalContext, U as PropInit, a as Group, l as Path } from "./nodes.js";
+import { BindableSignal, PathValue, Vec2, Vec2Signal } from "@glissade/core";
 
 //#region src/motionPath.d.ts
 
@@ -111,4 +112,99 @@ declare class LookAt extends Node {
 /** `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 };
+//#region src/shake.d.ts
+interface ShakeSpec {
+  /** Seed for the deterministic noise — same seed ⇒ same wobble, every run. */
+  seed: number;
+  /** Peak translation amplitude in px (±); default 0 (no positional jitter). */
+  translate?: number;
+  /** Peak rotation amplitude in degrees (±); default 0 (no rotational jitter). */
+  rotate?: number;
+  /** Noise cycles per second (higher = twitchier); default 8. */
+  frequency?: number;
+}
+/**
+ * The pure per-time shake offset for a spec: `{ dx, dy }` px + `dr` degrees, each
+ * a deterministic function of `(seed, t)`. Both the {@link shake} node driver and
+ * the Camera whole-frame shake fold this in.
+ */
+declare function shakeOffset(spec: ShakeSpec, t: number): {
+  dx: number;
+  dy: number;
+  dr: number;
+};
+/**
+ * A shake transform about the point `p` (parent space): translate by `(dx, dy)`
+ * then rotate `dr` degrees about `p`, so a rotational jitter spins the node around
+ * its own origin rather than the parent's.
+ */
+
+/**
+ * Jitter `node`'s pose with deterministic value noise, then return it (mutate-and-
+ * return, like Grid/orientToPath). SEPARATE `translate` (px) / `rotate` (deg) /
+ * `frequency` (Hz) amplitudes; pass at least one nonzero amplitude. The jitter is
+ * a parent-space offset applied at emit, so it composes with any existing driver.
+ *
+ * `children: [shake(cursor, { seed: 7, translate: 3 })]` — the cursor wobbles ±3px
+ * around wherever else it is (its position track, a followPath, …).
+ */
+declare function shake(node: Node, spec: ShakeSpec): Node;
+//#endregion
+//#region src/camera.d.ts
+/** Thrown for a mis-built or off-safe-area camera (fail loud, never a silent no-op). */
+declare class CameraError extends Error {
+  constructor(message: string);
+}
+/**
+ * One depth layer of a camera rig. `depth` lives on the WRAPPER (not a per-Node
+ * prop, so the base Node/golden contract is untouched): 1 = the focal plane
+ * (default), <1 = farther (parallax: pans less), >1 = nearer (pans more).
+ */
+interface CameraLayer {
+  content: Node;
+  depth?: number;
+}
+interface CameraProps extends NodeProps {
+  /** Focal / pan target in RELATIVE viewport coords ([0.5,0.5]=center); default center. */
+  center?: PropInit<Vec2>;
+  /** Scale about the focal point; default 1. */
+  zoom?: PropInit<number>;
+  /** Camera roll in degrees; default 0. */
+  roll?: PropInit<number>;
+  /** Optional whole-frame shake folded into the pose. */
+  shake?: ShakeSpec;
+}
+/**
+ * The per-layer inverse-camera-pose matrix (pure — the render math, exported for
+ * unit tests). Maps WORLD → SCREEN as
+ *   T(screenCenter) · scale(zoom) · rotate(roll) · T(−effectiveCenter)
+ * where `effectiveCenter = screenCenter + (focalPx − screenCenter)·depth` scales
+ * the PAN by the layer's depth (far layers, depth<1, pan less). `centerRel` is the
+ * RELATIVE focal point ([0.5,0.5]=screen center); `roll` is degrees.
+ */
+
+declare class Camera extends Group {
+  #private;
+  get describeType(): string;
+  /** Focal / pan target, RELATIVE viewport coords. Track `cam/center(.x/.y)`. */
+  readonly center: Vec2Signal;
+  /** Scale about the focal point. Track `cam/zoom`. */
+  readonly zoom: BindableSignal<number>;
+  /** Camera roll, degrees. Track `cam/roll`. */
+  readonly roll: BindableSignal<number>;
+  /** Resolved layers (content + depth), parallel to `children`. */
+  readonly layers: readonly Required<CameraLayer>[];
+  constructor(layers: CameraLayer[], props?: CameraProps);
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/**
+ * Build a {@link Camera} rig (lowercase FACTORY — no `new`): `camera(layers, props?)`.
+ * `layers` are depth planes (`{ content, depth? }`); animate `cam/center(.x/.y)`,
+ * `cam/zoom`, `cam/roll` with tracks for push-ins, pans, and rolls.
+ *
+ * `children: [camera([{ content: bg, depth: 0.3 }, { content: fg }], { id: 'cam' }), caption]`
+ * — `caption` is a SIBLING (outside the rig), so it stays pinned while the camera moves.
+ */
+declare function camera(layers: CameraLayer[], props?: CameraProps): Camera;
+//#endregion
+export { Camera, CameraError, type CameraLayer, type CameraProps, FollowPath, type FollowPathProps, LookAt, type LookAtProps, OrientToPath, type OrientToPathProps, type PathSampler, type ShakeSpec, camera, followPath, lookAt, motionPath, orientToPath, pathLength, pointAtLength, shake, shakeOffset };

package/dist/motion.js

@@ -1,2 +1,268 @@
+import { $ as multiply, C as Node, X as fromTRS, r as Group } from "./nodes.js";
 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 };
+import { signal, valueNoise, vec2Signal } from "@glissade/core";
+//#region src/shake.ts
+/**
+* `shake` (0.55) — a standalone jitter driver that wobbles ANY node's pose with
+* deterministic value noise. It subsumes the hand-rolled per-element jitters
+* (desk-cursor jitterX/Y, glitch shakeAmp, typewriter jitterRate) behind one
+* primitive with SEPARATE translate / rotate / frequency amplitudes.
+*
+* The jitter is realized AT EMIT (the Echo/MotionBlur idiom): `shake` overrides
+* the node's `emit` to wrap it in a save → shake-transform → emit → restore, where
+* the transform is a pure function of `ctx.time` via `valueNoise` — so it composes
+* on top of WHATEVER already drives the node (keyframes, layout, followPath) as a
+* parent-space offset, and stays byte-identical across two `evaluate()` passes (no
+* cross-frame state, no `Date.now`/`Math.random`). The camera whole-frame shake
+* reuses {@link shakeOffset} directly on its pose.
+*
+* Lives on `@glissade/scene/motion` (off the base embed). Note (like Echo/
+* MotionBlur, both emit-time re-eval): the offset is not a Timeline TRACK, so it
+* is a runtime/render effect — it is NOT emitted as animated Lottie keyframes.
+*/
+/** Default temporal frequency (noise cycles per second) when `frequency` is unset. */
+const DEFAULT_FREQUENCY = 8;
+const K_Y = 101;
+const K_ROT = 211;
+/** Signed value noise in [-1, 1) — the bipolar form a shake offset needs. */
+function snoise(seed, t) {
+	return valueNoise(seed, t) * 2 - 1;
+}
+/**
+* The pure per-time shake offset for a spec: `{ dx, dy }` px + `dr` degrees, each
+* a deterministic function of `(seed, t)`. Both the {@link shake} node driver and
+* the Camera whole-frame shake fold this in.
+*/
+function shakeOffset(spec, t) {
+	const tr = spec.translate ?? 0;
+	const rot = spec.rotate ?? 0;
+	const tf = t * (spec.frequency ?? DEFAULT_FREQUENCY);
+	return {
+		dx: tr === 0 ? 0 : tr * snoise(spec.seed, tf),
+		dy: tr === 0 ? 0 : tr * snoise(spec.seed + K_Y, tf),
+		dr: rot === 0 ? 0 : rot * snoise(spec.seed + K_ROT, tf)
+	};
+}
+/**
+* A shake transform about the point `p` (parent space): translate by `(dx, dy)`
+* then rotate `dr` degrees about `p`, so a rotational jitter spins the node around
+* its own origin rather than the parent's.
+*/
+function shakeMatrix(p, dx, dy, dr) {
+	const translate = [
+		1,
+		0,
+		0,
+		1,
+		dx,
+		dy
+	];
+	if (dr === 0) return translate;
+	const toP = [
+		1,
+		0,
+		0,
+		1,
+		p[0],
+		p[1]
+	];
+	const fromP = [
+		1,
+		0,
+		0,
+		1,
+		-p[0],
+		-p[1]
+	];
+	return multiply(translate, multiply(toP, multiply(fromTRS([0, 0], dr, [1, 1]), fromP)));
+}
+/**
+* Jitter `node`'s pose with deterministic value noise, then return it (mutate-and-
+* return, like Grid/orientToPath). SEPARATE `translate` (px) / `rotate` (deg) /
+* `frequency` (Hz) amplitudes; pass at least one nonzero amplitude. The jitter is
+* a parent-space offset applied at emit, so it composes with any existing driver.
+*
+* `children: [shake(cursor, { seed: 7, translate: 3 })]` — the cursor wobbles ±3px
+* around wherever else it is (its position track, a followPath, …).
+*/
+function shake(node, spec) {
+	const tr = spec.translate ?? 0;
+	const rot = spec.rotate ?? 0;
+	if (tr === 0 && rot === 0) throw new Error("shake(): pass a nonzero `translate` (px) or `rotate` (deg) amplitude — both are 0/omitted, so nothing would move.");
+	const origEmit = node.emit.bind(node);
+	node.emit = (out, ctx) => {
+		const { dx, dy, dr } = shakeOffset(spec, ctx.time);
+		if (dx === 0 && dy === 0 && dr === 0) {
+			origEmit(out, ctx);
+			return;
+		}
+		out.push({ op: "save" });
+		out.push({
+			op: "transform",
+			m: shakeMatrix(node.position(), dx, dy, dr)
+		});
+		origEmit(out, ctx);
+		out.push({ op: "restore" });
+	};
+	return node;
+}
+//#endregion
+//#region src/camera.ts
+/**
+* `Camera` (0.55) — a cinematic camera rig for cuts, push-ins, pans, rolls, and
+* parallax over a layered scene. It is a `Group` subclass whose `emit` applies the
+* INVERSE camera pose as a parent transform on its layers, so the WHOLE world moves
+* under a fixed screen while every node stays NODE-LOCAL (its anchor lives in its
+* own localMatrix) — the "camera transforms the world, nodes stay node-local"
+* composition contract, no double-apply with the 0.53 anchor by construction.
+*
+* Pose (all keyframeable track targets — `cam/center(.x/.y)`, `cam/zoom`,
+* `cam/roll`):
+*   - `center` — the focal / pan target in RELATIVE viewport coords ([0.5,0.5] =
+*     screen center), NEVER px (responsive landscape↔portrait). Resolved to world
+*     px at emit against `ctx.size`.
+*   - `zoom`   — scale about the focal point (push-in when animated up).
+*   - `roll`   — camera rotation in degrees.
+*   - `shake`  — an optional whole-frame {@link ShakeSpec} folded into the pose.
+*
+* The per-layer transform is
+*   T(screenCenter) · scale(zoom) · rotate(roll) · T(−effectiveCenter)
+* where a layer's `effectiveCenter` scales the PAN by its `depth` — far layers
+* (depth<1) translate less (v1 parallax is pan-only; DoF-from-depth is deferred).
+*
+* CAPTION-PIN is STRUCTURAL, not a flag: captions belong as SIBLINGS of the Camera
+* (outside the rig), so the camera transform never touches them — a lower-third
+* stays pinned by construction. See golden-camera for the pattern.
+*
+* Lives on `@glissade/scene/motion` (off the base embed).
+*/
+/** Thrown for a mis-built or off-safe-area camera (fail loud, never a silent no-op). */
+var CameraError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CameraError";
+	}
+};
+/**
+* The per-layer inverse-camera-pose matrix (pure — the render math, exported for
+* unit tests). Maps WORLD → SCREEN as
+*   T(screenCenter) · scale(zoom) · rotate(roll) · T(−effectiveCenter)
+* where `effectiveCenter = screenCenter + (focalPx − screenCenter)·depth` scales
+* the PAN by the layer's depth (far layers, depth<1, pan less). `centerRel` is the
+* RELATIVE focal point ([0.5,0.5]=screen center); `roll` is degrees.
+*/
+function cameraLayerMatrix(size, centerRel, zoom, roll, depth) {
+	const pw = size.w / 2;
+	const ph = size.h / 2;
+	const focalX = centerRel[0] * size.w;
+	const focalY = centerRel[1] * size.h;
+	const ecx = pw + (focalX - pw) * depth;
+	const ecy = ph + (focalY - ph) * depth;
+	const scaleRoll = fromTRS([0, 0], roll, [zoom, zoom]);
+	return multiply([
+		1,
+		0,
+		0,
+		1,
+		pw,
+		ph
+	], multiply(scaleRoll, [
+		1,
+		0,
+		0,
+		1,
+		-ecx,
+		-ecy
+	]));
+}
+function initVec2(sig, init) {
+	if (typeof init === "function") sig.bindSource(init);
+	else if (init !== void 0) sig.set(init);
+}
+function initNum(sig, init) {
+	if (typeof init === "function") sig.bindSource(init);
+	else if (init !== void 0) sig.set(init);
+}
+var Camera = class extends Group {
+	get describeType() {
+		return "Camera";
+	}
+	/** Focal / pan target, RELATIVE viewport coords. Track `cam/center(.x/.y)`. */
+	center;
+	/** Scale about the focal point. Track `cam/zoom`. */
+	zoom;
+	/** Camera roll, degrees. Track `cam/roll`. */
+	roll;
+	/** Resolved layers (content + depth), parallel to `children`. */
+	layers;
+	#shake;
+	constructor(layers, props = {}) {
+		if (!Array.isArray(layers) || layers.length === 0) throw new CameraError("camera(layers, props?): needs at least one layer — pass [{ content }] (a node per depth plane).");
+		const resolved = layers.map((l, i) => {
+			if (l == null || !(l.content instanceof Node)) throw new CameraError(`camera(): layer ${i} has no \`content\` Node — each layer is { content: Node, depth?: number }.`);
+			const depth = l.depth ?? 1;
+			if (!Number.isFinite(depth) || depth < 0) throw new CameraError(`camera(): layer ${i} has an invalid depth ${String(l.depth)} — depth must be a finite number >= 0 (1 = focal plane, <1 = far).`);
+			return {
+				content: l.content,
+				depth
+			};
+		});
+		super({
+			...props,
+			children: resolved.map((l) => l.content)
+		});
+		this.layers = resolved;
+		this.center = vec2Signal([.5, .5]);
+		this.zoom = signal(1);
+		this.roll = signal(0);
+		initVec2(this.center, props.center);
+		initNum(this.zoom, props.zoom);
+		initNum(this.roll, props.roll);
+		this.registerTarget("center", this.center, "vec2");
+		this.registerTarget("center.x", this.center.x, "number");
+		this.registerTarget("center.y", this.center.y, "number");
+		this.registerTarget("zoom", this.zoom, "number");
+		this.registerTarget("roll", this.roll, "number");
+		this.#shake = props.shake;
+	}
+	draw(out, ctx) {
+		const size = ctx.size;
+		if (size === void 0) throw new CameraError("Camera needs the scene viewport — evaluate(scene, timeline, t) supplies ctx.size; a bare hand-built ctx must set { size }.");
+		const [cx, cy] = this.center();
+		if (!Number.isFinite(cx) || !Number.isFinite(cy)) throw new CameraError(`Camera center resolved to a non-finite value [${String(cx)}, ${String(cy)}] — center is RELATIVE viewport coords (e.g. [0.5,0.5]); check the bound source/track.`);
+		if (cx < 0 || cx > 1 || cy < 0 || cy > 1) throw new CameraError(`Camera center [${cx}, ${cy}] is outside the safe area [0,1]² — center is RELATIVE viewport coords; keep the pan target on-screen.`);
+		const zoom = this.zoom();
+		const roll = this.roll();
+		const centerRel = [cx, cy];
+		const shake = this.#shake ? shakeOffset(this.#shake, ctx.time) : {
+			dx: 0,
+			dy: 0,
+			dr: 0
+		};
+		const shakeM = shake.dx !== 0 || shake.dy !== 0 || shake.dr !== 0 ? shakeMatrix([size.w / 2, size.h / 2], shake.dx, shake.dy, shake.dr) : void 0;
+		for (const layer of this.layers) {
+			const pose = cameraLayerMatrix(size, centerRel, zoom, roll, layer.depth);
+			const m = shakeM ? multiply(shakeM, pose) : pose;
+			out.push({ op: "save" });
+			out.push({
+				op: "transform",
+				m
+			});
+			layer.content.emit(out, ctx);
+			out.push({ op: "restore" });
+		}
+	}
+};
+/**
+* Build a {@link Camera} rig (lowercase FACTORY — no `new`): `camera(layers, props?)`.
+* `layers` are depth planes (`{ content, depth? }`); animate `cam/center(.x/.y)`,
+* `cam/zoom`, `cam/roll` with tracks for push-ins, pans, and rolls.
+*
+* `children: [camera([{ content: bg, depth: 0.3 }, { content: fg }], { id: 'cam' }), caption]`
+* — `caption` is a SIBLING (outside the rig), so it stays pinned while the camera moves.
+*/
+function camera(layers, props = {}) {
+	return new Camera(layers, props);
+}
+//#endregion
+export { Camera, CameraError, FollowPath, LookAt, OrientToPath, camera, followPath, lookAt, motionPath, orientToPath, pathLength, pointAtLength, shake, shakeOffset };

package/dist/nodes.d.ts

@@ -135,6 +135,18 @@ interface EvalContext {
    * playhead-dependent node degrades gracefully (Echo → a plain group).
    */
   readonly playhead?: Playhead;
+  /**
+   * The scene VIEWPORT size (`scene.size`) this evaluate targets — the only
+   * ambient-frame datum a node may read (a Camera needs the screen center to pan
+   * about / zoom into a RELATIVE focal point). OPTIONAL: `evaluate()`/
+   * `emitWithIds()` supply it; a bare hand-built ctx (a unit test emitting one
+   * node) may omit it, and a size-dependent node fails loud when it's absent.
+   * Reading it is byte-neutral for every existing node — nothing else consults it.
+   */
+  readonly size?: {
+    readonly w: number;
+    readonly h: number;
+  };
 }
 /** A property initializer: a value, or a computed source (§2.1). */
 type PropInit<T> = T | (() => T);

package/dist/scene.js

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

package/package.json

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