@glissade/scene 0.35.0 → 0.36.0-pre.1

package/dist/component.d.ts

@@ -0,0 +1,66 @@
+import { B as Node, a as Group } from "./nodes.js";
+
+//#region src/component.d.ts
+
+/** One prop in a component's public surface — a manifest type + optionality. */
+interface ComponentPropSpec {
+  /** the §2.2 value-type / shape id this prop accepts (e.g. 'number', 'color', 'string', 'Node[]'). */
+  type: string;
+  /** true when the factory REQUIRES it (default false). */
+  required?: boolean;
+}
+/** The props every component instance carries in addition to its own — a stable
+ *  id (REQUIRED, the collision-safety anchor) plus the base Group passthrough. */
+interface ComponentBaseProps {
+  /** Stable id — REQUIRED; every internal node is namespaced under it. */
+  id: string;
+}
+/** What an instance returns: the subtree + its id + the child-id helpers. */
+interface ComponentInstance {
+  /** the built subtree (a Group whose id === the instance id). */
+  readonly node: Group;
+  /** the instance id (its own namespace root). */
+  readonly id: string;
+  /** namespace a child id: `childId('bar')` → `'<id>/bar'`; no arg → the root id. */
+  childId(sub?: string): string;
+  /** ready-to-bind track targets for a child's prop: `['<id>/<child>/<prop>']`. */
+  targets(child: string, prop: string): string[];
+}
+interface ComponentDef<P extends Record<string, unknown> = Record<string, unknown>> {
+  /** the component's type name — surfaced in describe().components, must be unique. */
+  name: string;
+  /** the public prop surface (names → type/optionality) for describe(). */
+  props: {
+    readonly [prop: string]: ComponentPropSpec;
+  };
+  /**
+   * PURE build: given the instance props (incl. the required `id`) and a
+   * child-id namer, return the subtree. Runs ONCE at construction; must not
+   * read the playhead or any cross-frame state (bind children with tracks/
+   * PropInit closures like any node).
+   */
+  build(props: P & ComponentBaseProps, childId: (sub?: string) => string): Group;
+}
+declare class ComponentError extends Error {
+  constructor(message: string);
+}
+/** Join an instance id + a child sub-id into a namespaced target root. */
+declare function childId(id: string, sub?: string): string;
+interface RegisteredComponent {
+  readonly name: string;
+  readonly props: {
+    readonly [prop: string]: ComponentPropSpec;
+  };
+}
+/** Every component defined so far, in definition order — the seam describe()
+ *  reads to list `components` from the LIVE registry (can't drift). Pure read. */
+declare function listComponents(): RegisteredComponent[];
+/**
+ * Define a reusable component. Returns a factory `(props) → ComponentInstance`.
+ * Registers the component's name + prop surface so `describe().components` lists
+ * it. A duplicate name throws (a component library can't silently shadow).
+ */
+declare function defineComponent<P extends Record<string, unknown> = Record<string, unknown>>(def: ComponentDef<P>): (props: P & ComponentBaseProps) => ComponentInstance;
+/** re-export Node/Group types consumers of this entry name for their `build`. */
+//#endregion
+export { ComponentBaseProps, ComponentDef, ComponentError, ComponentInstance, ComponentPropSpec, Group, type Node, RegisteredComponent, childId, defineComponent, listComponents };

package/dist/component.js

@@ -0,0 +1,82 @@
+import { r as Group } from "./nodes.js";
+//#region src/component.ts
+/**
+* `@glissade/scene/component` — `defineComponent()` (0.36): reusable, typed,
+* describe()-legible animated subscenes. The missing COMPOSITION unit — the
+* user-defined generalization of the built-in `Grid()`/`Chart()`/`splitText()`
+* factories (all already "props → subtree" pure build-time functions).
+*
+*   const LowerThird = defineComponent({
+*     name: 'LowerThird',
+*     props: { name: { type: 'string' }, title: { type: 'string' }, accent: { type: 'color' } },
+*     build: ({ name, title, accent }, cid) => new Group({ id: cid(), children: [
+*       new Rect({ id: cid('bar'), width: 6, height: 40, fill: accent }),
+*       new Text({ id: cid('name'), text: name, ... }),
+*       new Text({ id: cid('title'), text: title, fill: accent, ... }),
+*     ]}),
+*   });
+*
+*   const lt = LowerThird({ id: 'intro', name: 'Ada', title: 'Engineer', accent: '#4ea1ff' });
+*   // scene children: [lt.node]
+*   // animate a child: tl.to(lt.childId('bar') + '/height', 40, { from: 0 })
+*   //   or the ready ids: tl.stagger(lt.targets('bar', 'opacity'), …)
+*
+* PURE build-time fan-out: `build` runs at construction and emits ordinary nodes,
+* so `evaluate()` stays a pure function of time and the goldens hold by
+* construction. Nothing executes at play time.
+*
+* ID-SCOPING is the whole safety story: every instance carries a required stable
+* `id`, and every internal node id is stamped through `cid(sub) = '<id>/<sub>'`,
+* so instancing the SAME component N times (distinct ids) can't collide track
+* targets. Two instances built with the SAME id DO collide — the same footgun
+* `Grid`/`Chart` have; give each instance a unique id.
+*
+* On its OWN tree-shakeable subpath (off the base embed) + re-exported onto the
+* `@glissade/browser` IIFE. `describe().components` lists every component defined
+* so far (side-effect registration on definition — the value-type/examples
+* pattern), so an agent or the studio sees each component's typed prop surface.
+*/
+var ComponentError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ComponentError";
+	}
+};
+/** Join an instance id + a child sub-id into a namespaced target root. */
+function childId(id, sub) {
+	return sub === void 0 || sub === "" ? id : `${id}/${sub}`;
+}
+const registry = /* @__PURE__ */ new Map();
+/** Every component defined so far, in definition order — the seam describe()
+*  reads to list `components` from the LIVE registry (can't drift). Pure read. */
+function listComponents() {
+	return [...registry.values()];
+}
+/**
+* Define a reusable component. Returns a factory `(props) → ComponentInstance`.
+* Registers the component's name + prop surface so `describe().components` lists
+* it. A duplicate name throws (a component library can't silently shadow).
+*/
+function defineComponent(def) {
+	if (registry.has(def.name)) throw new ComponentError(`a component named '${def.name}' is already defined`);
+	for (const [prop, spec] of Object.entries(def.props)) if (spec === null || typeof spec !== "object" || typeof spec.type !== "string") throw new ComponentError(`${def.name}: prop '${prop}' must be { type: string, required? }, got ${JSON.stringify(spec)}`);
+	registry.set(def.name, {
+		name: def.name,
+		props: def.props
+	});
+	return (props) => {
+		if (props.id === void 0 || props.id === "") throw new ComponentError(`${def.name}(...) needs a stable id — every instance namespaces its children under it (so N instances don't collide track targets)`);
+		const id = props.id;
+		const cid = (sub) => childId(id, sub);
+		const node = def.build(props, cid);
+		if (node.id !== id) throw new ComponentError(`${def.name}(...).build must return a Group with id === childId() ('${id}'); got '${node.id ?? "<unset>"}'. Use \`new Group({ id: cid(), … })\`.`);
+		return {
+			node,
+			id,
+			childId: cid,
+			targets: (child, prop) => [`${cid(child)}/${prop}`]
+		};
+	};
+}
+//#endregion
+export { ComponentError, Group, childId, defineComponent, listComponents };

package/dist/describe.d.ts

@@ -72,6 +72,21 @@ interface DescribedNode {
    */
   subpath?: string;
 }
+/**
+ * One user-defined `defineComponent()` in the manifest (0.36) — a reusable
+ * animated subscene's public prop surface, so an agent/studio sees what it
+ * accepts. Generated from the LIVE component registry, so it can't drift.
+ */
+interface DescribedComponent {
+  name: string;
+  /** the component's public props: name → { type, required? } (construction-time). */
+  props: {
+    [prop: string]: {
+      type: string;
+      required?: boolean;
+    };
+  };
+}
 interface DescribedBuilderMethod {
   name: string;
   signature: string;
@@ -117,6 +132,9 @@ interface ApiManifest {
    * `name` is also a `window.glissade.<name>` global on the IIFE.
    */
   helpers: DescribedHelper[];
+  /** user-defined components registered via defineComponent() (0.36); present
+   *  from describe() (possibly empty), absent on manifests captured before 0.36. */
+  components?: DescribedComponent[];
   createScene: string;
   subpaths: {
     [entry: string]: string;
@@ -147,4 +165,4 @@ declare function registerExamples(corpus: {
 }): void;
 declare function describe(opts?: DescribeOptions): ApiManifest;
 //#endregion
-export { ApiManifest, DescribeOptions, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe, registerExamples };
+export { ApiManifest, DescribeOptions, DescribedBuilderMethod, DescribedComponent, DescribedHelper, DescribedNode, DescribedProp, describe, registerExamples };

package/dist/describe.js

@@ -1,4 +1,5 @@
 import { D as NODE_CONSTRUCTION_PROP_NAMES, E as BASE_CONSTRUCTION_PROP_NAMES, a as Path, c as Video, i as ImageNode, o as Rect, r as Group, s as Text, t as Circle } from "./nodes.js";
+import { listComponents } from "./component.js";
 import { easings, listValueTypes } from "@glissade/core";
 //#region src/describe.ts
 /**
@@ -22,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.35.0";
+const RAW_VERSION = "0.36.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) {
@@ -428,6 +429,12 @@ const HELPERS = [
 		import: "@glissade/scene/chart",
 		usage: "Chart({ id, data: Row[], xKey, yKey, width, height, yScale?, bandPadding?, fill?: string | ColorScale }): { node: Group, bars: Rect[], targets(prop): string[] }"
 	},
+	{
+		name: "defineComponent",
+		summary: "Define a reusable, typed, describe()-legible animated subscene — the user-defined generalization of Grid/Chart. Returns a factory (props & { id }) => { node, childId, targets }; each instance namespaces its children under the required id so N instances never collide track targets. Pure build-time. describe().components lists every one defined. On the @glissade/scene/component subpath.",
+		import: "@glissade/scene/component",
+		usage: "defineComponent({ name, props: { <p>: { type, required? } }, build(props, childId): Group }): (props & { id }) => { node: Group, id, childId(sub?), targets(child, prop) }"
+	},
 	{
 		name: "linearScale",
 		summary: "A serializable linear scale (value axis): maps a numeric domain onto a pixel/unit range. Pair with Chart({ yScale }). On the @glissade/scene/chart subpath.",
@@ -493,6 +500,14 @@ let exampleCorpus = {};
 function registerExamples(corpus) {
 	exampleCorpus = corpus;
 }
+function mapComponentProps(props) {
+	const out = {};
+	for (const [k, v] of Object.entries(props)) out[k] = {
+		type: v.type,
+		...v.required ? { required: true } : {}
+	};
+	return out;
+}
 function describe(opts = {}) {
 	const withEx = opts.examples === true && Object.keys(exampleCorpus).length > 0;
 	const ex = (key) => {
@@ -530,6 +545,10 @@ function describe(opts = {}) {
 			...h,
 			...ex(h.name)
 		})) : HELPERS,
+		components: listComponents().map((c) => ({
+			name: c.name,
+			props: mapComponentProps(c.props)
+		})),
 		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.35.0",
+  "version": "0.36.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -31,6 +31,10 @@
       "types": "./dist/chart.d.ts",
       "default": "./dist/chart.js"
     },
+    "./component": {
+      "types": "./dist/component.d.ts",
+      "default": "./dist/component.js"
+    },
     "./path": {
       "types": "./dist/path.d.ts",
       "default": "./dist/path.js"
@@ -69,7 +73,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.35.0"
+    "@glissade/core": "0.36.0-pre.1"
   },
   "repository": {
     "type": "git",