@glissade/cli 0.43.1 → 0.44.0-pre.1

package/dist/cli.js

@@ -91,6 +91,7 @@ const USAGE = `usage:
   gs mcp <scene-module>   start an MCP stdio server for this scene: describe / list_targets / apply_patch / undo / render_frame (the AI-native write layer)
   gs build [filter...] [--config <glissade.config.ts>] [--affected <git-ref>] [--explain]   content-graph DAG runner: narrate→sfx→loudness→render per scene, runs ONLY the stale subtree. --affected <ref> pre-filters to scenes a git diff since <ref> touched (rebuild only what a change set touched; composed with the per-step content-hash staleness)
   gs describe [--out <api.json>] [--examples]   snapshot THIS engine's describe() API manifest (stdout, or --out to a file) — the input to gs migrate
+  gs types [--out <file.ts>] [--from <api.json>] [--check]   codegen a type-checked track() SDK from the describe() manifest: only registered animatable paths + their value types compile, so a typo'd path or wrong value-type id is a COMPILE error (import track from the generated file). --check fails if --out is stale. Zero-runtime (types + a re-typed re-export of the real track)
   gs migrate <baseline-api.json> [--json] [--check]   diff a saved API manifest against the current engine: moved imports / removed / added / changed, with a suggested fix per breaking item (advisory; --check exits non-zero on any breaking change for CI gating)
   gs repin <scene-module> --golden <dir> [--name <p>] [--frames a,b,..] [--fps <n>] [--since <ref>] [--write] [--only a,b] [--heatmap <dir>] [--floor <ssim>] [--force]   narration-aware golden reviewer: render current vs committed goldens, report perceptual delta + the re-narration cause, re-pin only frames you allow (default dry-run; --floor refuses a bigger-than-expected drop)
   gs localize <scene-module> --to <locale> [--from <locale>] [--write] [--strict] [--keep-voice] [--json]   fork a narration into a new locale (clone segment/pause structure, PRESERVING beat ids so .start() anchors survive) + stub messages.<locale>.json from the scene's t() ids, running the render path's parity + localize checks BEFORE any TTS. Default dry-run (exits non-zero on drift); --write emits <base>.<locale>.narration.json + messages.<locale>.json (re-localize CARRIES existing translations over — never clobbers); --strict refuses to write on a preflight failure
@@ -195,7 +196,7 @@ async function main() {
 		process.stdout.write(`${describe().version}\n`);
 		return;
 	}
-	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin" && command !== "master" && command !== "localize") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin" && command !== "master" && command !== "localize" && command !== "types") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -307,6 +308,40 @@ async function main() {
 		} else process.stdout.write(json);
 		return;
 	}
+	if (command === "types") {
+		const { flags: tf } = parseArgs(rest);
+		const { generateTypedSdk } = await import("./typedSdk.js");
+		const { readFileSync, writeFileSync, existsSync } = await import("node:fs");
+		const from = tf.get("from");
+		let manifest;
+		if (from) {
+			try {
+				manifest = JSON.parse(readFileSync(from, "utf8"));
+			} catch (err) {
+				fail(`gs types: could not read manifest '${from}': ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (typeof manifest.version !== "string" || manifest.nodes === void 0) fail(`'${from}' is not a describe() API manifest (missing version/nodes)`);
+		} else {
+			const { describe } = await import("@glissade/scene/describe");
+			manifest = describe();
+		}
+		const src = generateTypedSdk(manifest);
+		const outPath = tf.get("out");
+		if (tf.has("check")) {
+			if (!outPath) fail("gs types --check needs --out <file> (the committed typed-SDK file to verify)");
+			if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : "") !== src) {
+				process.stderr.write(`gs types: ${outPath} is STALE — run \`gs types --out ${outPath}\` to regenerate\n`);
+				process.exit(1);
+			}
+			process.stderr.write(`gs types: ${outPath} is up to date\n`);
+			return;
+		}
+		if (outPath) {
+			writeFileSync(outPath, src);
+			process.stderr.write(`gs types: wrote a typed track() SDK (${Object.keys(manifest.nodes).length} node types) → ${outPath}\n`);
+		} else process.stdout.write(src);
+		return;
+	}
 	if (command === "migrate") {
 		const { positional: mp, flags: mf } = parseArgs(rest);
 		const baselinePath = mp[0];

package/dist/typedSdk.js

@@ -0,0 +1,104 @@
+//#region src/typedSdk.ts
+/** value-type id → the TS type its keyframes carry. Unmapped ids fall back to `unknown`. */
+const TS_VALUE_TYPE = {
+	number: "number",
+	vec2: "readonly [number, number]",
+	"vec2-arc": "readonly [number, number]",
+	color: "string",
+	string: "string",
+	boolean: "boolean",
+	paint: "Paint",
+	fontAxes: "FontAxes",
+	path: "PathValue"
+};
+/** core types the generated file must import when a mapped value type references them. */
+const CORE_TYPE_IMPORTS = {
+	paint: "Paint",
+	fontAxes: "FontAxes",
+	path: "PathValue"
+};
+/**
+* Collect every animatable prop path across the manifest's node taxonomy (component
+* props are construction-only → excluded). Value types are UNIONED per path — the
+* manifest encodes a polymorphic prop as a pipe-joined id (`'color|paint'`), and a
+* path can carry different types on different node types; both cases become the union
+* of members, so passing ANY valid member type-checks (a wrong-type-for-a-specific-node
+* still fails loud at bind — the honest best an instance-free SDK can do). `polymorphic`
+* lists the >1-member paths for the header note.
+*/
+function collectTargets(manifest) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const node of Object.values(manifest.nodes)) for (const [path, prop] of Object.entries(node.props)) {
+		if (!prop.animatable || prop.target === void 0) continue;
+		const set = byPath.get(path) ?? /* @__PURE__ */ new Set();
+		for (const member of prop.type.split("|")) set.add(member.trim());
+		byPath.set(path, set);
+	}
+	const targets = [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([path, set]) => ({
+		path,
+		valueTypes: [...set].sort()
+	}));
+	return {
+		targets,
+		polymorphic: targets.filter((t) => t.valueTypes.length > 1).map((t) => `${t.path}: ${t.valueTypes.join(" | ")}`)
+	};
+}
+const tsValueOf = (valueType) => TS_VALUE_TYPE[valueType] ?? "unknown";
+/**
+* Generate the typed-SDK source (a `.ts` module). Emits a `KnownTrackPath` union, a
+* `TrackTarget` template (`` `${string}/${KnownTrackPath}` ``), per-path `TypeIdOf` /
+* `ValueOf` conditional maps, and a re-typed `track` re-export whose runtime IS
+* `@glissade/core`'s `track` (only the types are narrowed). Deterministic: paths are
+* sorted, so the same manifest → byte-identical output (drift-guardable with `--check`).
+*/
+function generateTypedSdk(manifest) {
+	const { targets, polymorphic } = collectTargets(manifest);
+	const usedCoreTypes = [...new Set(targets.flatMap((t) => t.valueTypes.map((v) => CORE_TYPE_IMPORTS[v])).filter((n) => n !== void 0))].sort();
+	/** union of value-type id literals for a target, e.g. `'color' | 'paint'`. */
+	const typeIdUnion = (t) => t.valueTypes.map((v) => `'${v}'`).join(" | ");
+	/** union of TS value types for a target, e.g. `string | Paint`. */
+	const valueUnion = (t) => [...new Set(t.valueTypes.map(tsValueOf))].join(" | ");
+	const L = [];
+	L.push(`// GENERATED by \`gs types\` from the describe() API manifest v${manifest.version} — DO NOT EDIT.`);
+	L.push("// Regenerate after a glissade upgrade (or when you add a defineComponent target):");
+	L.push("//   gs types --out glissade-targets.ts");
+	L.push("// Then import `track` from here instead of @glissade/core to type-check your targets.");
+	if (polymorphic.length) L.push(`// Polymorphic paths (accept a value-type UNION): ${polymorphic.join(", ")}`);
+	L.push("");
+	L.push(`import { track as _track, type Track, type Key } from '@glissade/core';`);
+	if (usedCoreTypes.length) L.push(`import type { ${usedCoreTypes.join(", ")} } from '@glissade/core';`);
+	L.push("");
+	L.push("/** Every animatable prop path in the describe() taxonomy — a typo'd path is a type error. */");
+	L.push(`export type KnownTrackPath =`);
+	for (const t of targets) L.push(`  | '${t.path}'`);
+	L.push(`  ;`);
+	L.push("");
+	L.push("/** A track target: any node id + a KNOWN animatable path. */");
+	L.push("export type TrackTarget = `${string}/${KnownTrackPath}`;");
+	L.push("");
+	L.push("/** The value-type id each path expects (a wrong `type` arg is a type error;");
+	L.push(" *  a polymorphic prop like `fill: color|paint` accepts either member). */");
+	L.push("type TypeIdOf<P extends TrackTarget> =");
+	for (const t of targets) L.push(`  P extends \`\${string}/${t.path}\` ? ${typeIdUnion(t)} :`);
+	L.push("  never;");
+	L.push("");
+	L.push("/** The value each path animates (the keyframe value type). */");
+	L.push("type ValueOf<P extends TrackTarget> =");
+	for (const t of targets) L.push(`  P extends \`\${string}/${t.path}\` ? ${valueUnion(t)} :`);
+	L.push("  never;");
+	L.push("");
+	L.push("/**");
+	L.push(" * Type-checked `track` — only a KNOWN path + its correct value type compile.");
+	L.push(" * Runtime is `@glissade/core`'s `track` verbatim (only the types are narrowed).");
+	L.push(" */");
+	L.push("export const track = _track as <P extends TrackTarget>(");
+	L.push("  target: P,");
+	L.push("  type: TypeIdOf<P>,");
+	L.push("  keys: Key<ValueOf<P>>[],");
+	L.push("  opts?: { editable?: boolean },");
+	L.push(") => Track<ValueOf<P>>;");
+	L.push("");
+	return L.join("\n");
+}
+//#endregion
+export { generateTypedSdk };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.43.1",
+  "version": "0.44.0-pre.1",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -28,15 +28,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.43.1",
-    "@glissade/core": "0.43.1",
-    "@glissade/interact": "0.43.1",
-    "@glissade/lottie": "0.43.1",
-    "@glissade/narrate": "0.43.1",
-    "@glissade/player": "0.43.1",
-    "@glissade/scene": "0.43.1",
-    "@glissade/sfx": "0.43.1",
-    "@glissade/svg": "0.43.1"
+    "@glissade/backend-skia": "0.44.0-pre.1",
+    "@glissade/core": "0.44.0-pre.1",
+    "@glissade/interact": "0.44.0-pre.1",
+    "@glissade/lottie": "0.44.0-pre.1",
+    "@glissade/narrate": "0.44.0-pre.1",
+    "@glissade/player": "0.44.0-pre.1",
+    "@glissade/scene": "0.44.0-pre.1",
+    "@glissade/sfx": "0.44.0-pre.1",
+    "@glissade/svg": "0.44.0-pre.1"
   },
   "repository": {
     "type": "git",