@glissade/scene 0.18.0-pre.5 → 0.18.0

package/dist/describe.d.ts

@@ -20,21 +20,43 @@
  * never pulled onto the base embed path — a scene that never calls `describe()`
  * pays zero bytes for it.
  */
-/** One animatable / settable prop in the manifest. */
+/**
+ * One prop in the manifest. The `animatable` flag is the load-bearing
+ * distinction an AI reads to tell "animate this" from "set at construction":
+ *
+ * - An ANIMATABLE prop (`animatable: true`) carries a `target` — a real track
+ *   target you bind via `to`/`fromTo`/`set`. Generated from `listTargets()`,
+ *   so it is a registered target by construction.
+ * - A CONSTRUCTION prop (`animatable: false`) has NO `target` — it is passed to
+ *   the node constructor and NEVER bindable (binding it is rejected by the bind
+ *   guard). `required: true` marks one you can't omit (e.g. Image `assetId`).
+ *
+ * This negative space is the manifest's point: it prevents an AI from
+ * attempting to animate a construction-only prop (an `assetId` track, a
+ * `fontFamily` tween) — those are construction-time decisions, not tracks.
+ */
 interface DescribedProp {
   /** The §2.2 value-type id this prop accepts (e.g. `'vec2'`, `'number'`, `'color'`). */
   type: string;
-  /** Whether a Track can drive it (every registered target is animatable). */
+  /** Whether a Track can drive it. `true` ⇒ a `target` is present; `false` ⇒ construction-only, no `target`. */
   animatable: boolean;
-  /** The track-target template, `'<id>/<path>'` — substitute the node's real id. */
+  /** The track-target template, `'<id>/<path>'` — present ONLY on animatable props; substitute the node's real id. */
   target?: string;
   /** Component count of the value (`vec2` → 2, scalar → 1); omitted for non-numeric reprs. */
   arity?: number;
+  /** Construction-only props: `true` when the constructor REQUIRES it (e.g. Image/Video `assetId`). */
+  required?: boolean;
 }
 interface DescribedNode {
   props: {
     [prop: string]: DescribedProp;
   };
+  /**
+   * The tree-shakeable subpath this node is imported from, when not the base
+   * `@glissade/scene` index (e.g. the Layout family lives on
+   * `@glissade/scene/layout`). Omitted for base-index nodes.
+   */
+  subpath?: string;
 }
 interface DescribedBuilderMethod {
   name: string;

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.18.0-pre.5";
+const RAW_VERSION = "0.18.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) {
@@ -39,9 +39,71 @@ function expectsToType(expects) {
 	if (expects === void 0) return "unknown";
 	return Array.isArray(expects) ? expects.join("|") : expects;
 }
-/** Introspect one freshly-instantiated node into its prop manifest, reading the
-* REAL `registerTarget` calls via `listTargets()` (so it can't drift). */
-function describeNode(node) {
+/**
+* Construction-only props by node type — the difference between a node's Props
+* interface and its `registerTarget` set (its animatable props). These are set
+* once at `new Node({...})` and can never be animated.
+*
+* Base `NodeProps` construction props (`id`, `blend`, `filters`, `anchor`,
+* `cache`) are shared by EVERY node and merged in separately, so this map holds
+* only each node's OWN construction surface.
+*/
+const CONSTRUCTION_PROPS = {
+	Group: { children: { type: "Node[]" } },
+	Rect: {
+		sketch: { type: "SketchStyle" },
+		sketchFill: { type: "HachureSpec" },
+		sketchSeed: { type: "number" }
+	},
+	Circle: {
+		sketch: { type: "SketchStyle" },
+		sketchFill: { type: "HachureSpec" },
+		sketchSeed: { type: "number" }
+	},
+	Path: {
+		sketch: { type: "SketchStyle" },
+		sketchFill: { type: "HachureSpec" },
+		sketchSeed: { type: "number" }
+	},
+	Text: {
+		fontFamily: { type: "string" },
+		fontWeight: { type: "number" },
+		fontStyle: { type: "'normal'|'italic'" },
+		align: { type: "'left'|'center'|'right'" },
+		lineHeight: { type: "number" }
+	},
+	Image: { assetId: {
+		type: "string",
+		required: true
+	} },
+	Video: {
+		assetId: {
+			type: "string",
+			required: true
+		},
+		at: { type: "number" },
+		trimStart: { type: "number" },
+		playbackRate: { type: "number" },
+		clipDuration: { type: "number" },
+		sourceFps: { type: "number" }
+	}
+};
+/**
+* Base-`NodeProps` construction props shared by every node — set at
+* construction, never animatable (none is a registered target).
+*/
+const BASE_CONSTRUCTION_PROPS = {
+	id: { type: "string" },
+	blend: { type: "BlendMode" },
+	filters: { type: "FilterSpec[]" },
+	anchor: { type: "AnchorSpec" },
+	cache: { type: "boolean" }
+};
+/** Introspect one freshly-instantiated node into its prop manifest: the
+* ANIMATABLE props come from the REAL `registerTarget` calls via `listTargets()`
+* (so they can't drift); the CONSTRUCTION-only props are merged from the curated
+* schema (drift-guarded by a constructor test). */
+function describeNode(node, typeName) {
 	const props = {};
 	for (const { path, expects } of node.listTargets()) {
 		const type = expectsToType(expects);
@@ -53,8 +115,71 @@ function describeNode(node) {
 			...arity !== void 0 ? { arity } : {}
 		};
 	}
+	const construction = {
+		...BASE_CONSTRUCTION_PROPS,
+		...CONSTRUCTION_PROPS[typeName] ?? {}
+	};
+	for (const [prop, spec] of Object.entries(construction)) props[prop] = {
+		type: spec.type,
+		animatable: false,
+		...spec.required ? { required: true } : {}
+	};
 	return { props };
 }
+/**
+* The Layout family — `Layout` and its `Stack`/`Row`/`Column` ergonomic
+* factories — lives on the budgeted `@glissade/scene/layout` entry (it ships
+* Yoga wasm), so describe() does NOT import it (that would drag Yoga onto the
+* describe/browser bundle). Instead it carries a CURATED schema, drift-guarded
+* by `describe.test.ts`, which imports the real Layout and asserts these
+* animatable props match its `listTargets()` and these construction props match
+* its constructor.
+*
+* `width`/`height` are animatable number targets; `direction`/`justify`/`align`
+* are construction-only (set once, not tweened). `children` is construction.
+*/
+const LAYOUT_SUBPATH = "@glissade/scene/layout";
+const LAYOUT_ANIMATABLE = {
+	width: { type: "number" },
+	height: { type: "number" },
+	gap: { type: "number" },
+	padding: { type: "number" }
+};
+const LAYOUT_CONSTRUCTION = {
+	direction: { type: "'row'|'column'" },
+	justify: { type: "'start'|'center'|'end'|'space-between'|'space-around'" },
+	align: { type: "'start'|'center'|'end'|'stretch'" },
+	children: { type: "Node[]" }
+};
+/**
+* Build a Layout-family node manifest from the curated schema. Layout is a
+* `Group` subclass, so it inherits every base transform target — reuse a
+* throwaway `Group`'s `listTargets()` for those (no drift on the inherited set),
+* then add the layout-specific animatable + construction props.
+*/
+function describeLayoutNode() {
+	const props = describeNode(new Group(), "Group").props;
+	delete props.children;
+	for (const [prop, spec] of Object.entries(LAYOUT_ANIMATABLE)) {
+		const arity = arityOf(spec.type);
+		props[prop] = {
+			type: spec.type,
+			animatable: true,
+			target: `<id>/${prop}`,
+			...arity !== void 0 ? { arity } : {}
+		};
+	}
+	const construction = LAYOUT_CONSTRUCTION;
+	for (const [prop, spec] of Object.entries(construction)) props[prop] = {
+		type: spec.type,
+		animatable: false,
+		...spec.required ? { required: true } : {}
+	};
+	return {
+		props,
+		subpath: LAYOUT_SUBPATH
+	};
+}
 const NODE_FACTORIES = {
 	Group: () => new Group(),
 	Rect: () => new Rect(),
@@ -80,7 +205,7 @@ const BUILDER_METHODS = [
 	},
 	{
 		name: "stagger",
-		signature: "stagger<T>(targets, { to, from?, duration?, ease? }, { each, anchor?, at? }): TimelineBuilder"
+		signature: "stagger<T>(targets, { to, from?, duration?, ease? }, { each: number | ((rank, count) => number), anchor?, at? }): TimelineBuilder"
 	},
 	{
 		name: "set",
@@ -138,14 +263,21 @@ const SUBPATHS = {
 */
 function describe() {
 	const nodes = {};
-	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = describeNode(factory());
+	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = describeNode(factory(), name);
+	const layout = describeLayoutNode();
+	for (const name of [
+		"Layout",
+		"Stack",
+		"Row",
+		"Column"
+	]) nodes[name] = layout;
 	return {
 		version: PACKAGE_VERSION,
 		nodes,
 		valueTypes: listValueTypes(),
 		easings: Object.keys(easings),
 		builder: { methods: BUILDER_METHODS },
-		createScene: "createScene({ size: { w, h }, children: Node[] }): Scene",
+		createScene: "createScene({ size: { w, h }, children: Node[] }): Scene  —  media assets are declared on the Timeline document: timeline({ assets: { <id>: { kind: 'image'|'video', url } } }); an Image/Video node's `assetId` names an entry here.",
 		subpaths: SUBPATHS
 	};
 }

package/package.json

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