@glissade/scene 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -139,6 +139,92 @@ interface DrawOnEachOptions extends DrawOnOptions {
  * whiteboard sequence. Returns one reveal track per id, staggered by `delay`. */
 declare function drawOnEach(targets: readonly string[], opts?: DrawOnEachOptions): Track<number>[];
 //#endregion
+//#region src/guards.d.ts
+/**
+ * Render-mode determinism guards (DESIGN.md §5.5). During export the banned
+ * globals are patched — for the synchronous scope of a single evaluate() call —
+ * to throw (CLI/CI) or warn-once-then-delegate (browser/dev), then restored.
+ * Scoped to evaluate() re-entry, never installed globally, so timers and clocks
+ * outside the read phase are untouched. This backstops the static eslint rules
+ * (`@glissade/eslint-plugin`) for the cases lint can't see (closures, indirect
+ * calls, third-party code reachable from a node's emit()).
+ */
+declare class DeterminismViolationError extends Error {
+  constructor(api: string);
+}
+type GuardMode = 'throw' | 'warn' | 'off';
+/**
+ * Run `fn` (a single synchronous evaluate()) with the banned globals guarded.
+ * `throw` rejects any call (CLI/CI); `warn` warns once per API then delegates
+ * to the real implementation (browser/dev); `off` is a no-op. Globals are
+ * always restored, even if `fn` throws. `fn` MUST be synchronous — patching is
+ * only valid for the sync read phase, never across an await.
+ */
+declare function withDeterminismGuards<T>(mode: GuardMode, fn: () => T): T;
+//#endregion
+//#region src/scene.d.ts
+interface Scene {
+  readonly root: Group;
+  readonly nodes: ReadonlyMap<string, Node>;
+  readonly size: {
+    w: number;
+    h: number;
+  };
+  /** Per-scene playhead; players and evaluate() write it. */
+  readonly playhead: Playhead;
+  resolveTarget(target: string): BindablePropTarget | undefined;
+  /**
+   * Inject the active backend's TextMeasurer (§3.2) so line breaking always
+   * measures with the rasterizer that will draw. Defaults to an estimator.
+   */
+  setTextMeasurer(measurer: TextMeasurer): void;
+  readonly textMeasurer: TextMeasurer;
+}
+declare class DuplicateNodeIdError extends Error {
+  constructor(id: string);
+}
+interface SceneInit {
+  size: {
+    w: number;
+    h: number;
+  };
+  children: Node[];
+}
+/**
+ * The scene-module convention: what `gs render`, the golden harness, and the
+ * studio load. createScene is a factory — every consumer gets a fresh graph.
+ */
+interface SceneModule {
+  createScene(): Scene;
+  timeline: Timeline;
+}
+declare function createScene(init: SceneInit): Scene;
+interface BindingCacheEntry {
+  compiled: CompiledTimeline;
+  bound: BoundTimeline;
+}
+declare function bindScene(scene: Scene, doc: Timeline): BindingCacheEntry;
+/**
+ * The non-negotiable contract (§2.5): same (scene, timeline, t) → identical
+ * DisplayList, in any call order. Never awaits; asset readiness is the
+ * caller's precondition.
+ */
+declare function evaluate(scene: Scene, doc: Timeline, t: number): DisplayList;
+//#endregion
+//#region src/cacheColdAudit.d.ts
+interface CacheColdResult {
+  ok: boolean;
+  /** id of the first node whose isolated emit() diverged (set only when !ok). */
+  node?: string;
+}
+/**
+ * Evaluate two fresh scenes from `createScene` at `t` and confirm the
+ * DisplayLists are byte-identical. Returns `{ ok: true }` for a pure scene, or
+ * `{ ok: false, node }` naming the first divergent node. DEV-only — never on
+ * the render hot path.
+ */
+declare function auditCacheCold(createScene: () => Scene, doc: Timeline, t: number): CacheColdResult;
+//#endregion
 //#region src/motionPath.d.ts
 /** An arc-length-parameterized sampler over a path. */
 interface PathSampler {
@@ -388,53 +474,4 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   render(target: TCanvas, list: DisplayList): void;
 }
 //#endregion
-//#region src/scene.d.ts
-interface Scene {
-  readonly root: Group;
-  readonly nodes: ReadonlyMap<string, Node>;
-  readonly size: {
-    w: number;
-    h: number;
-  };
-  /** Per-scene playhead; players and evaluate() write it. */
-  readonly playhead: Playhead;
-  resolveTarget(target: string): BindablePropTarget | undefined;
-  /**
-   * Inject the active backend's TextMeasurer (§3.2) so line breaking always
-   * measures with the rasterizer that will draw. Defaults to an estimator.
-   */
-  setTextMeasurer(measurer: TextMeasurer): void;
-  readonly textMeasurer: TextMeasurer;
-}
-declare class DuplicateNodeIdError extends Error {
-  constructor(id: string);
-}
-interface SceneInit {
-  size: {
-    w: number;
-    h: number;
-  };
-  children: Node[];
-}
-/**
- * The scene-module convention: what `gs render`, the golden harness, and the
- * studio load. createScene is a factory — every consumer gets a fresh graph.
- */
-interface SceneModule {
-  createScene(): Scene;
-  timeline: Timeline;
-}
-declare function createScene(init: SceneInit): Scene;
-interface BindingCacheEntry {
-  compiled: CompiledTimeline;
-  bound: BoundTimeline;
-}
-declare function bindScene(scene: Scene, doc: Timeline): BindingCacheEntry;
-/**
- * The non-negotiable contract (§2.5): same (scene, timeline, t) → identical
- * DisplayList, in any call order. Never awaits; asset readiness is the
- * caller's precondition.
- */
-declare function evaluate(scene: Scene, doc: Timeline, t: number): DisplayList;
-//#endregion
-export { type AnchorSpec, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EditMark, type EvalContext, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontSpec, Group, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, 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, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch };
+export { type AnchorSpec, type BindablePropTarget, type BlendMode, type CacheColdResult, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EditMark, type EvalContext, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontSpec, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, 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, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -254,6 +254,234 @@ function drawOnEach(targets, opts = {}) {
 	return stagger(targets.map((t) => drawOn(t, opts)), delay);
 }
 //#endregion
+//#region src/guards.ts
+/**
+* Render-mode determinism guards (DESIGN.md §5.5). During export the banned
+* globals are patched — for the synchronous scope of a single evaluate() call —
+* to throw (CLI/CI) or warn-once-then-delegate (browser/dev), then restored.
+* Scoped to evaluate() re-entry, never installed globally, so timers and clocks
+* outside the read phase are untouched. This backstops the static eslint rules
+* (`@glissade/eslint-plugin`) for the cases lint can't see (closures, indirect
+* calls, third-party code reachable from a node's emit()).
+*/
+var DeterminismViolationError = class extends Error {
+	constructor(api) {
+		super(`'${api}' was called inside evaluate() — scene code must be a pure function of time (§5.5). Read ctx.time/frame, use the seeded random(seed) from @glissade/core, and resolve assets before rendering.`);
+		this.name = "DeterminismViolationError";
+	}
+};
+function bannedSlots() {
+	const g = globalThis;
+	const slots = [
+		{
+			target: Math,
+			key: "random",
+			label: "Math.random"
+		},
+		{
+			target: Date,
+			key: "now",
+			label: "Date.now"
+		},
+		{
+			target: g,
+			key: "setTimeout",
+			label: "setTimeout"
+		},
+		{
+			target: g,
+			key: "setInterval",
+			label: "setInterval"
+		}
+	];
+	if (typeof performance !== "undefined") slots.push({
+		target: performance,
+		key: "now",
+		label: "performance.now"
+	});
+	if (typeof g["requestAnimationFrame"] === "function") slots.push({
+		target: g,
+		key: "requestAnimationFrame",
+		label: "requestAnimationFrame"
+	});
+	return slots;
+}
+/**
+* Run `fn` (a single synchronous evaluate()) with the banned globals guarded.
+* `throw` rejects any call (CLI/CI); `warn` warns once per API then delegates
+* to the real implementation (browser/dev); `off` is a no-op. Globals are
+* always restored, even if `fn` throws. `fn` MUST be synchronous — patching is
+* only valid for the sync read phase, never across an await.
+*/
+function withDeterminismGuards(mode, fn) {
+	if (mode === "off") return fn();
+	const slots = bannedSlots();
+	const saved = slots.map((s) => s.target[s.key]);
+	const warned = /* @__PURE__ */ new Set();
+	slots.forEach((s, i) => {
+		s.target[s.key] = (...args) => {
+			if (mode === "throw") throw new DeterminismViolationError(s.label);
+			if (!warned.has(s.label)) {
+				warned.add(s.label);
+				emitDevWarning(`${s.label} called inside evaluate() — nondeterministic, not reproducible on export (§5.5)`);
+			}
+			return saved[i].apply(s.target, args);
+		};
+	});
+	try {
+		return fn();
+	} finally {
+		slots.forEach((s, i) => {
+			s.target[s.key] = saved[i];
+		});
+	}
+}
+//#endregion
+//#region src/scene.ts
+/**
+* Scene assembly + the canonical evaluate(scene, timeline, t) (DESIGN.md §2.5,
+* §3.1): pure, total, deterministic — driver writes the playhead (sanctioned
+* entry write), then a pull-only read phase collects the DisplayList.
+*/
+var DuplicateNodeIdError = class extends Error {
+	constructor(id) {
+		super(`duplicate node id '${id}' — explicit ids must be unique (§3.1/§6.5)`);
+		this.name = "DuplicateNodeIdError";
+	}
+};
+function indexNodes(root, into, measurerSource) {
+	root.measurerSource = measurerSource;
+	if (root.id !== void 0) {
+		if (into.has(root.id)) throw new DuplicateNodeIdError(root.id);
+		into.set(root.id, root);
+	}
+	if (root instanceof Group) for (const child of root.children) indexNodes(child, into, measurerSource);
+}
+function createScene(init) {
+	const root = new Group({
+		id: "__root",
+		children: init.children
+	});
+	const nodes = /* @__PURE__ */ new Map();
+	const playhead = createPlayhead();
+	let measurer = null;
+	indexNodes(root, nodes, () => measurer ?? fallbackMeasurer());
+	return {
+		root,
+		nodes,
+		size: init.size,
+		playhead,
+		resolveTarget: (target) => {
+			const slash = target.indexOf("/");
+			if (slash < 0) return void 0;
+			return nodes.get(target.slice(0, slash))?.resolveTarget(target.slice(slash + 1));
+		},
+		setTextMeasurer: (m) => {
+			measurer = m;
+		},
+		get textMeasurer() {
+			return measurer ?? fallbackMeasurer();
+		}
+	};
+}
+const bindings = /* @__PURE__ */ new WeakMap();
+function bindScene(scene, doc) {
+	let perScene = bindings.get(scene);
+	if (!perScene) {
+		perScene = /* @__PURE__ */ new WeakMap();
+		bindings.set(scene, perScene);
+	}
+	let entry = perScene.get(doc);
+	if (!entry) {
+		const compiled = compileTimeline(doc);
+		entry = {
+			compiled,
+			bound: bindTimeline(compiled, scene.resolveTarget, scene.playhead)
+		};
+		perScene.set(doc, entry);
+	}
+	return entry;
+}
+/**
+* The non-negotiable contract (§2.5): same (scene, timeline, t) → identical
+* DisplayList, in any call order. Never awaits; asset readiness is the
+* caller's precondition.
+*/
+function evaluate(scene, doc, t) {
+	bindScene(scene, doc);
+	const fps = doc.fps;
+	const ctx = {
+		time: t,
+		frame: fps !== void 0 ? Math.round(t * fps) : -1,
+		measurer: scene.textMeasurer
+	};
+	return evaluateAt(scene.playhead, t, () => {
+		const out = createDisplayListBuilder(scene.size);
+		scene.root.emit(out, ctx);
+		return out.finish();
+	});
+}
+//#endregion
+//#region src/cacheColdAudit.ts
+/** Stable string of a DisplayList for comparison (opaque resources collapse to a marker). */
+function hashDisplayList(dl) {
+	return JSON.stringify(dl, (_key, value) => {
+		if (value instanceof ArrayBuffer) return `ab:${value.byteLength}`;
+		if (ArrayBuffer.isView(value)) return `view:${value.byteLength}`;
+		if (typeof value === "function") return void 0;
+		return value;
+	});
+}
+/**
+* Evaluate two fresh scenes from `createScene` at `t` and confirm the
+* DisplayLists are byte-identical. Returns `{ ok: true }` for a pure scene, or
+* `{ ok: false, node }` naming the first divergent node. DEV-only — never on
+* the render hot path.
+*/
+function auditCacheCold(createScene, doc, t) {
+	const warm = createScene();
+	const cold = createScene();
+	const a = evaluate(warm, doc, t);
+	const b = evaluate(cold, doc, t);
+	if (hashDisplayList(a) === hashDisplayList(b)) return { ok: true };
+	const frame = doc.fps !== void 0 ? Math.round(t * doc.fps) : -1;
+	const ctxA = {
+		time: t,
+		frame,
+		measurer: warm.textMeasurer
+	};
+	const ctxB = {
+		time: t,
+		frame,
+		measurer: cold.textMeasurer
+	};
+	let groupFallback;
+	for (const [id, nodeA] of warm.nodes) {
+		const nodeB = cold.nodes.get(id);
+		if (!nodeB) return {
+			ok: false,
+			node: id
+		};
+		const ea = createDisplayListBuilder(warm.size);
+		nodeA.emit(ea, ctxA);
+		const eb = createDisplayListBuilder(cold.size);
+		nodeB.emit(eb, ctxB);
+		if (hashDisplayList(ea.finish()) === hashDisplayList(eb.finish())) continue;
+		if (nodeA instanceof Group) {
+			groupFallback ??= id;
+			continue;
+		}
+		return {
+			ok: false,
+			node: id
+		};
+	}
+	return {
+		ok: false,
+		...groupFallback !== void 0 ? { node: groupFallback } : {}
+	};
+}
+//#endregion
 //#region src/motionPath.ts
 /**
 * Motion along a path: sample a point (and tangent) at an arc-length position on
@@ -1016,89 +1244,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-//#region src/scene.ts
-/**
-* Scene assembly + the canonical evaluate(scene, timeline, t) (DESIGN.md §2.5,
-* §3.1): pure, total, deterministic — driver writes the playhead (sanctioned
-* entry write), then a pull-only read phase collects the DisplayList.
-*/
-var DuplicateNodeIdError = class extends Error {
-	constructor(id) {
-		super(`duplicate node id '${id}' — explicit ids must be unique (§3.1/§6.5)`);
-		this.name = "DuplicateNodeIdError";
-	}
-};
-function indexNodes(root, into, measurerSource) {
-	root.measurerSource = measurerSource;
-	if (root.id !== void 0) {
-		if (into.has(root.id)) throw new DuplicateNodeIdError(root.id);
-		into.set(root.id, root);
-	}
-	if (root instanceof Group) for (const child of root.children) indexNodes(child, into, measurerSource);
-}
-function createScene(init) {
-	const root = new Group({
-		id: "__root",
-		children: init.children
-	});
-	const nodes = /* @__PURE__ */ new Map();
-	const playhead = createPlayhead();
-	let measurer = null;
-	indexNodes(root, nodes, () => measurer ?? fallbackMeasurer());
-	return {
-		root,
-		nodes,
-		size: init.size,
-		playhead,
-		resolveTarget: (target) => {
-			const slash = target.indexOf("/");
-			if (slash < 0) return void 0;
-			return nodes.get(target.slice(0, slash))?.resolveTarget(target.slice(slash + 1));
-		},
-		setTextMeasurer: (m) => {
-			measurer = m;
-		},
-		get textMeasurer() {
-			return measurer ?? fallbackMeasurer();
-		}
-	};
-}
-const bindings = /* @__PURE__ */ new WeakMap();
-function bindScene(scene, doc) {
-	let perScene = bindings.get(scene);
-	if (!perScene) {
-		perScene = /* @__PURE__ */ new WeakMap();
-		bindings.set(scene, perScene);
-	}
-	let entry = perScene.get(doc);
-	if (!entry) {
-		const compiled = compileTimeline(doc);
-		entry = {
-			compiled,
-			bound: bindTimeline(compiled, scene.resolveTarget, scene.playhead)
-		};
-		perScene.set(doc, entry);
-	}
-	return entry;
-}
-/**
-* The non-negotiable contract (§2.5): same (scene, timeline, t) → identical
-* DisplayList, in any call order. Never awaits; asset readiness is the
-* caller's precondition.
-*/
-function evaluate(scene, doc, t) {
-	bindScene(scene, doc);
-	const fps = doc.fps;
-	const ctx = {
-		time: t,
-		frame: fps !== void 0 ? Math.round(t * fps) : -1,
-		measurer: scene.textMeasurer
-	};
-	return evaluateAt(scene.playhead, t, () => {
-		const out = createDisplayListBuilder(scene.size);
-		scene.root.emit(out, ctx);
-		return out.finish();
-	});
-}
-//#endregion
-export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch };
+export { Circle, ColdAssetError, DeterminismViolationError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch, withDeterminismGuards };

package/package.json

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