@glissade/cli 0.43.1-pre.0 → 0.44.0-pre.0

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,96 @@
+//#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 (+ the
+* component surface is construction-only, so excluded). Deduped by path; the FIRST
+* value type wins and a differing later one is reported in `conflicts` (base targets
+* are uniform — a conflict is a taxonomy smell worth surfacing, not silently picking).
+*/
+function collectTargets(manifest) {
+	const byPath = /* @__PURE__ */ new Map();
+	const conflicts = [];
+	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 existing = byPath.get(path);
+		if (existing === void 0) byPath.set(path, prop.type);
+		else if (existing !== prop.type) conflicts.push(`${path}: ${existing} vs ${prop.type}`);
+	}
+	return {
+		targets: [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([path, valueType]) => ({
+			path,
+			valueType
+		})),
+		conflicts
+	};
+}
+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, conflicts } = collectTargets(manifest);
+	const usedCoreTypes = [...new Set(targets.map((t) => CORE_TYPE_IMPORTS[t.valueType]).filter((n) => n !== void 0))].sort();
+	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 (conflicts.length) L.push(`// NOTE: ${conflicts.length} path(s) carry >1 value type across nodes: ${conflicts.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("type TypeIdOf<P extends TrackTarget> =");
+	for (const t of targets) L.push(`  P extends \`\${string}/${t.path}\` ? '${t.valueType}' :`);
+	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}\` ? ${tsValueOf(t.valueType)} :`);
+	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-pre.0",
+  "version": "0.44.0-pre.0",
   "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-pre.0",
-    "@glissade/core": "0.43.1-pre.0",
-    "@glissade/interact": "0.43.1-pre.0",
-    "@glissade/lottie": "0.43.1-pre.0",
-    "@glissade/narrate": "0.43.1-pre.0",
-    "@glissade/player": "0.43.1-pre.0",
-    "@glissade/scene": "0.43.1-pre.0",
-    "@glissade/sfx": "0.43.1-pre.0",
-    "@glissade/svg": "0.43.1-pre.0"
+    "@glissade/backend-skia": "0.44.0-pre.0",
+    "@glissade/core": "0.44.0-pre.0",
+    "@glissade/interact": "0.44.0-pre.0",
+    "@glissade/lottie": "0.44.0-pre.0",
+    "@glissade/narrate": "0.44.0-pre.0",
+    "@glissade/player": "0.44.0-pre.0",
+    "@glissade/scene": "0.44.0-pre.0",
+    "@glissade/sfx": "0.44.0-pre.0",
+    "@glissade/svg": "0.44.0-pre.0"
   },
   "repository": {
     "type": "git",