@glissade/scene 0.19.1 → 0.20.0-pre.3

package/dist/scene.d.ts

@@ -0,0 +1,71 @@
+import { n as DisplayList } from "./displayList.js";
+import { I as BindablePropTarget, W as TextMeasurer, i as Group, z as Node } from "./nodes.js";
+import { BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
+
+//#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);
+}
+declare class ReservedNodeIdError 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;
+/**
+ * Controlled / imperative drive (0.19): `evaluate(scene)` with NO timeline —
+ * the host owns the clock. It evaluates against an EMPTY timeline at the
+ * scene's current playhead value (`peek()`, 0 by default), so values set
+ * imperatively via `node.set(...)` between frames survive into the DisplayList
+ * (no track clobbers them). See docs/controlled-drive.md for the loop and the
+ * `.set()`-vs-timeline precedence contract.
+ *
+ * PRECEDENCE: a timeline track ALWAYS overrides `.set()` on the prop it
+ * targets while that track is live — pass the timeline through the 3-arg form
+ * for animated props; reserve this overload for host-owned props.
+ */
+declare function evaluate(scene: Scene): DisplayList;
+//#endregion
+export { SceneModule as a, evaluate as c, SceneInit as i, ReservedNodeIdError as n, bindScene as o, Scene as r, createScene as s, DuplicateNodeIdError as t };

package/dist/scene.js

@@ -0,0 +1,120 @@
+import { L as createDisplayListBuilder, r as Group, y as fallbackMeasurer } from "./nodes.js";
+import { r as isConstructionProp } from "./constructionProps.js";
+import { bindTimeline, compileTimeline, createPlayhead, evaluateAt, signal } from "@glissade/core";
+//#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";
+	}
+};
+var ReservedNodeIdError = class extends Error {
+	constructor(id) {
+		super(`node id '${id}' uses the reserved '~' prefix — that namespace is for structural fallback ids (§6.5), which are inspection-only and never track targets; choose another id`);
+		this.name = "ReservedNodeIdError";
+	}
+};
+function indexNodes(root, into, measurerSource) {
+	root.measurerSource = measurerSource;
+	if (root.id !== void 0) {
+		if (root.id.startsWith("~")) throw new ReservedNodeIdError(root.id);
+		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();
+	const measurer = signal(null);
+	indexNodes(root, nodes, () => measurer() ?? fallbackMeasurer());
+	return {
+		root,
+		nodes,
+		size: init.size,
+		playhead,
+		resolveTarget: (target) => {
+			for (let slash = target.lastIndexOf("/"); slash > 0; slash = target.lastIndexOf("/", slash - 1)) {
+				const node = nodes.get(target.slice(0, slash));
+				if (node) return node.resolveTarget(target.slice(slash + 1));
+			}
+		},
+		setTextMeasurer: (m) => {
+			measurer.set(m);
+		},
+		get textMeasurer() {
+			return measurer.peek() ?? fallbackMeasurer();
+		}
+	};
+}
+const bindings = /* @__PURE__ */ new WeakMap();
+/**
+* When a target fails to resolve, return a friendlier reason IF it names a
+* known CONSTRUCTION prop (animatable: false — e.g. `assetId`, `fontFamily`):
+* the target IS correctly rejected, but "no signal resolves to it" hides WHY.
+* Resolves the node by the same longest-registered-id-prefix walk as
+* `resolveTarget`, then checks the node's construction-prop schema. Returns
+* undefined (⇒ the generic message) for a genuinely-unknown prop or unknown id.
+*/
+function constructionPropMessage(nodes, target) {
+	for (let slash = target.lastIndexOf("/"); slash > 0; slash = target.lastIndexOf("/", slash - 1)) {
+		const node = nodes.get(target.slice(0, slash));
+		if (!node) continue;
+		const prop = target.slice(slash + 1);
+		if (isConstructionProp(node.describeType, prop)) return `'${target}' is a construction prop (animatable:false) — set it at construction (new ${node.describeType}({ ${prop} })); it is not an animatable target.`;
+		return;
+	}
+}
+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, { unboundMessage: (target) => constructionPropMessage(scene.nodes, target) })
+		};
+		perScene.set(doc, entry);
+	}
+	return entry;
+}
+/**
+* Empty timeline — zero tracks, so binding installs ZERO computed sources and
+* any imperative `node.set(...)` value survives evaluate untouched. Shared and
+* frozen so the WeakMap binding cache keys on a single stable document across
+* the whole controlled-drive loop (one bind, reused every frame).
+*/
+const EMPTY_TIMELINE = Object.freeze({
+	version: 1,
+	tracks: []
+});
+function evaluate(scene, doc, t = 0) {
+	if (doc === void 0) return evaluate(scene, EMPTY_TIMELINE, scene.playhead.peek());
+	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 { evaluate as a, createScene as i, ReservedNodeIdError as n, bindScene as r, DuplicateNodeIdError as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.19.1",
+  "version": "0.20.0-pre.3",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -17,6 +17,14 @@
       "types": "./dist/layout.d.ts",
       "default": "./dist/layout.js"
     },
+    "./layout-ctors": {
+      "types": "./dist/layoutCtors.d.ts",
+      "default": "./dist/layoutCtors.js"
+    },
+    "./grid": {
+      "types": "./dist/grid.d.ts",
+      "default": "./dist/grid.js"
+    },
     "./path": {
       "types": "./dist/path.d.ts",
       "default": "./dist/path.js"
@@ -28,6 +36,18 @@
     "./type": {
       "types": "./dist/type.d.ts",
       "default": "./dist/type.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.ts",
+      "default": "./dist/diagnostics.js"
+    },
+    "./motion": {
+      "types": "./dist/motion.d.ts",
+      "default": "./dist/motion.js"
+    },
+    "./identity": {
+      "types": "./dist/identity.d.ts",
+      "default": "./dist/identity.js"
     }
   },
   "files": [
@@ -35,7 +55,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.19.1"
+    "@glissade/core": "0.20.0-pre.3"
   },
   "repository": {
     "type": "git",
@@ -44,6 +64,6 @@
   },
   "scripts": {
     "build": "tsdown",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p spike/tsconfig.json"
   }
 }