@glissade/cli 0.46.0 → 0.47.0-pre.0

package/dist/cli.js

@@ -26,7 +26,10 @@ const KNOWN_BOOLEAN_FLAGS = new Set([
 	"write",
 	"keep-voice",
 	"help",
-	"lottie"
+	"lottie",
+	"lint",
+	"global",
+	"iife"
 ]);
 function parseArgs(argv) {
 	const positional = [];
@@ -92,8 +95,8 @@ const USAGE = `usage:
   gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
   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 describe [--out <api.json>] [--examples] [--lint]   snapshot THIS engine's describe() API manifest (stdout, or --out to a file) — the input to gs migrate. --lint reconciles the manifest against the window.glissade runtime surface (every helper/node/surface member resolves, no type surfaced as a value, no arity drift) and exits non-zero on drift
+  gs types [--out <file.ts>] [--from <api.json>] [--check] [--global]   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). --global (alias --iife) instead emits a SELF-CONTAINED ambient window.glissade .d.ts for the no-build <script src> author (typed IIFE surface — a typo'd window.glissade member is a compile error)
   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
@@ -310,6 +313,20 @@ async function main() {
 		const { describe } = await import("@glissade/scene/describe");
 		if (df.has("examples")) await import("@glissade/scene/examples");
 		const manifest = describe(df.has("examples") ? { examples: true } : {});
+		if (df.has("lint")) {
+			const { describeLint, collectRuntimeSurface, exemptFromUnreachable } = await import("./describeLint.js");
+			const { surface, unreachable } = await collectRuntimeSurface(manifest);
+			const exempt = exemptFromUnreachable(manifest, unreachable);
+			const violations = describeLint(manifest, surface, { exempt });
+			if (violations.length > 0) {
+				process.stderr.write(`gs describe --lint: ${violations.length} violation(s) — describe() drifted from the window.glissade surface:\n`);
+				for (const v of violations) process.stderr.write(`  ✗ [${v.kind}] ${v.name}: ${v.detail}\n`);
+				process.exit(1);
+			}
+			const skipped = exempt.size > 0 ? ` (${exempt.size} browser-only helper(s) not verifiable headlessly — the check:describe CI gate covers them against the built @glissade/browser bundle)` : "";
+			process.stderr.write(`gs describe --lint: OK — every described node/helper/surface member resolves on the runtime bundle${skipped}\n`);
+			return;
+		}
 		const json = `${JSON.stringify(manifest, null, 2)}\n`;
 		const outPath = df.get("out");
 		if (outPath) {
@@ -321,7 +338,8 @@ async function main() {
 	}
 	if (command === "types") {
 		const { flags: tf } = parseArgs(rest);
-		const { generateTypedSdk } = await import("./typedSdk.js");
+		const global = tf.has("global") || tf.has("iife");
+		const { generateTypedSdk, generateAmbientDts } = await import("./typedSdk.js");
 		const { readFileSync, writeFileSync, existsSync } = await import("node:fs");
 		const from = tf.get("from");
 		let manifest;
@@ -336,12 +354,12 @@ async function main() {
 			const { describe } = await import("@glissade/scene/describe");
 			manifest = describe();
 		}
-		const src = generateTypedSdk(manifest);
+		const src = global ? generateAmbientDts(manifest) : 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 (!outPath) fail(`gs types ${global ? "--global " : ""}--check needs --out <file> (the committed ${global ? "ambient .d.ts" : "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.stderr.write(`gs types: ${outPath} is STALE — run \`gs types ${global ? "--global " : ""}--out ${outPath}\` to regenerate\n`);
 				process.exit(1);
 			}
 			process.stderr.write(`gs types: ${outPath} is up to date\n`);
@@ -349,7 +367,7 @@ async function main() {
 		}
 		if (outPath) {
 			writeFileSync(outPath, src);
-			process.stderr.write(`gs types: wrote a typed track() SDK (${Object.keys(manifest.nodes).length} node types) → ${outPath}\n`);
+			process.stderr.write(global ? `gs types --global: wrote the self-contained ambient window.glissade .d.ts → ${outPath}\n` : `gs types: wrote a typed track() SDK (${Object.keys(manifest.nodes).length} node types) → ${outPath}\n`);
 		} else process.stdout.write(src);
 		return;
 	}

package/dist/describeLint.js

@@ -0,0 +1,105 @@
+import { usageArity } from "@glissade/scene/describe";
+//#region src/describeLint.ts
+/**
+* Type-only surface names that ARE legitimately a runtime class/value on the
+* bundle (a driver class exported under the same name as its type). Empty today —
+* the current type-only surface (Paint/PathValue/FontAxes) erases entirely — but a
+* seam so a future `FollowPath`-style class-and-type name doesn't false-positive.
+*/
+const RUNTIME_TYPE_ALLOWLIST = /* @__PURE__ */ new Set([]);
+/**
+* Reconcile a describe() manifest against a runtime surface record. Returns every
+* violation (empty = clean); the CLI prints them and exits non-zero.
+*
+* Assertions:
+*  (a) every callable the manifest advertises (node constructor, helper, surface
+*      value function/constructor) resolves to a `function` on the bundle;
+*  (b) every surface `kind:'type'` name is truly type-only (erases at runtime) —
+*      a type surfaced as a runtime value is the drift this catches;
+*  (c) arity: a documented callable must not REQUIRE materially more positional
+*      args than its usage advertises (`Function.length > documented total + 1`;
+*      tolerant by one — a trailing optional like `measurer` legitimately lifts
+*      `Function.length`).
+*/
+function describeLint(manifest, surface, opts = {}) {
+	const exempt = opts.exempt ?? /* @__PURE__ */ new Set();
+	const out = [];
+	const isFn = (n) => typeof surface[n] === "function";
+	const present = (n) => surface[n] !== void 0;
+	const callables = /* @__PURE__ */ new Set();
+	for (const name of Object.keys(manifest.nodes)) callables.add(name);
+	for (const h of manifest.helpers) callables.add(h.name);
+	for (const e of manifest.surface ?? []) if (e.kind === "value" && (e.form === "constructor" || e.form === "function")) callables.add(e.name);
+	for (const name of [...callables].sort()) {
+		if (exempt.has(name) || isFn(name)) continue;
+		out.push(present(name) ? {
+			kind: "not-callable",
+			name,
+			detail: `window.glissade.${name} is a ${typeof surface[name]}, expected a function`
+		} : {
+			kind: "missing",
+			name,
+			detail: `window.glissade.${name} is documented but MISSING from the runtime bundle`
+		});
+	}
+	for (const e of manifest.surface ?? []) if (e.kind === "value" && e.form === "object" && !exempt.has(e.name) && !present(e.name)) out.push({
+		kind: "missing",
+		name: e.name,
+		detail: `window.glissade.${e.name} (value export) is MISSING from the runtime bundle`
+	});
+	for (const e of manifest.surface ?? []) if (e.kind === "type" && !exempt.has(e.name) && present(e.name) && !RUNTIME_TYPE_ALLOWLIST.has(e.name)) out.push({
+		kind: "type-as-value",
+		name: e.name,
+		detail: `'${e.name}' is tagged kind:'type' but resolves to a runtime ${typeof surface[e.name]} — surface it as kind:'value' or remove it`
+	});
+	for (const h of manifest.helpers) {
+		if (exempt.has(h.name)) continue;
+		const fn = surface[h.name];
+		if (typeof fn !== "function") continue;
+		const total = usageArity(h.usage);
+		if (total !== void 0 && fn.length > total + 1) out.push({
+			kind: "arity",
+			name: h.name,
+			detail: `window.glissade.${h.name} takes ${fn.length} params but its usage documents ${total} — update describe()'s usage or the signature`
+		});
+	}
+	return out;
+}
+/**
+* Assemble the runtime surface a HEADLESS `gs describe --lint` can reach: the
+* embed authoring packages the CLI legitimately depends on (core + scene + their
+* tree-shakeable subpaths + player), merged into one record. Browser-only modules
+* (`@glissade/backend-canvas2d/snapshot`, `@glissade/element`) are NOT CLI deps —
+* importing them throws, so those specifiers are collected into `unreachable` and
+* the caller exempts the helpers they'd have provided. (The `check:describe` CI
+* gate injects the built `@glissade/browser` bundle instead, so it verifies those
+* too.)
+*/
+async function collectRuntimeSurface(manifest) {
+	const modules = new Set([
+		"@glissade/core",
+		"@glissade/scene",
+		"@glissade/scene/describe",
+		"@glissade/scene/layout-ctors"
+	]);
+	for (const h of manifest.helpers) modules.add(h.import);
+	const surface = {};
+	const unreachable = /* @__PURE__ */ new Set();
+	for (const spec of modules) try {
+		Object.assign(surface, await import(spec));
+	} catch {
+		unreachable.add(spec);
+	}
+	return {
+		surface,
+		unreachable
+	};
+}
+/** The exempt name-set for a headless lint: helper names whose import module was unreachable. */
+function exemptFromUnreachable(manifest, unreachable) {
+	const exempt = /* @__PURE__ */ new Set();
+	for (const h of manifest.helpers) if (unreachable.has(h.import)) exempt.add(h.name);
+	return exempt;
+}
+//#endregion
+export { collectRuntimeSurface, describeLint, exemptFromUnreachable };

package/dist/mcp.js

@@ -6,12 +6,12 @@ import { join } from "node:path";
 import { validateTrack } from "@glissade/core";
 import { evaluate } from "@glissade/scene";
 import { SkiaBackend } from "@glissade/backend-skia";
+import { describe } from "@glissade/scene/describe";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { emptySidecar, mergeSidecar } from "@glissade/core/sidecar";
 import { applyPatches } from "@glissade/core/studio-host";
-import { describe } from "@glissade/scene/describe";
 //#region src/mcpSession.ts
 /**
 * gs mcp session (0.28): the stateful core behind the AI-native WRITE layer. It

package/dist/typedSdk.js

@@ -100,5 +100,186 @@ function generateTypedSdk(manifest) {
 	L.push("");
 	return L.join("\n");
 }
+/**
+* value-type id → the SELF-CONTAINED TS type used in the ambient d.ts. Opaque core
+* types (`paint`/`fontAxes`/`path`) map to local `Gs*` aliases instead of the real
+* `@glissade/core` names, so the emitted file needs no imports (the no-build author
+* has no node_modules to resolve `Paint` from).
+*/
+const AMBIENT_VALUE_TYPE = {
+	number: "number",
+	vec2: "readonly [number, number]",
+	"vec2-arc": "readonly [number, number]",
+	color: "string",
+	string: "string",
+	boolean: "boolean",
+	paint: "GsPaint",
+	fontAxes: "GsFontAxes",
+	path: "GsPathValue"
+};
+/** The node constructors that get a real per-node props interface (form:'constructor'). */
+const CONSTRUCTOR_NODES = new Set([
+	"Group",
+	"Rect",
+	"Circle",
+	"Path",
+	"Text",
+	"Image",
+	"Video",
+	"Layout"
+]);
+/**
+* Map a manifest prop `type` string to a SELF-CONTAINED TS type for the ambient
+* d.ts. Precise for the known value-type ids (incl. a `|`-union of them, e.g.
+* `color|paint` → `string | GsPaint`); best-effort `unknown` for opaque construction
+* types (`SketchStyle`, `BlendMode`, the `anchor` preset union, …) whose real shapes
+* aren't self-containedly expressible — permissive, so authoring never fights it.
+*/
+function ambientPropType(manifestType) {
+	const members = manifestType.split("|").map((m) => m.trim());
+	if (members.every((m) => m in AMBIENT_VALUE_TYPE)) return [...new Set(members.map((m) => AMBIENT_VALUE_TYPE[m]))].join(" | ");
+	if (manifestType === "Node[]") return "GsNode[]";
+	return "unknown";
+}
+/**
+* Derive a surface taxonomy when the manifest predates 0.47 (no `surface`): node
+* names that are known constructors → constructors, helpers + core callables →
+* functions, `easings` → object, plus the opaque type-only names. Keeps
+* `gs types --global --from <old-api.json>` working (best-effort).
+*/
+function surfaceOf(manifest) {
+	if (manifest.surface && manifest.surface.length > 0) return manifest.surface;
+	const out = [];
+	for (const name of Object.keys(manifest.nodes)) if (CONSTRUCTOR_NODES.has(name)) out.push({
+		name,
+		kind: "value",
+		iife: true,
+		form: "constructor"
+	});
+	else out.push({
+		name,
+		kind: "value",
+		iife: true,
+		form: "function"
+	});
+	for (const h of manifest.helpers) out.push({
+		name: h.name,
+		kind: "value",
+		iife: true,
+		form: "function"
+	});
+	for (const name of [
+		"timeline",
+		"createScene",
+		"track",
+		"evaluate",
+		"stagger",
+		"describe"
+	]) out.push({
+		name,
+		kind: "value",
+		iife: true,
+		form: "function"
+	});
+	out.push({
+		name: "easings",
+		kind: "value",
+		iife: true,
+		form: "object"
+	});
+	for (const name of [
+		"Paint",
+		"PathValue",
+		"FontAxes"
+	]) out.push({
+		name,
+		kind: "type",
+		iife: false,
+		form: "type"
+	});
+	const seen = /* @__PURE__ */ new Set();
+	return out.filter((e) => seen.has(e.name) ? false : (seen.add(e.name), true)).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Generate the SELF-CONTAINED ambient `window.glissade` `.d.ts` from the manifest's
+* `surface` taxonomy. Emits opaque `Gs*` aliases for the complex types, a real
+* per-node construction-props interface for each node constructor (value types
+* reused from the manifest), a best-effort signature per callable, and the global
+* augmentation (`declare global { interface Window { glissade }; const glissade }`).
+* Deterministic (everything sorted) + pure, so it's `--check`-gateable.
+*
+* HONEST about approximation: node instances / Paint / FontAxes / PathValue / the
+* timeline document are OPAQUE brands (the real shapes need the published types);
+* helper signatures beyond the headline authoring calls are `(...args) => any`.
+* The value it delivers is member-name + node-construction-prop type-checking — a
+* typo'd `window.glissade.Reet` or an unknown surface member is a compile error.
+*/
+function generateAmbientDts(manifest) {
+	const surface = surfaceOf(manifest);
+	new Map(manifest.surface ? manifest.surface.map((e) => [e.name, e]) : []);
+	const builderMethods = [...manifest.builder.methods.map((m) => m.name)].sort();
+	const L = [];
+	L.push(`// GENERATED by \`gs types --global\` from the describe() API manifest v${manifest.version} — DO NOT EDIT.`);
+	L.push("// Self-contained ambient types for the NO-BUILD `window.glissade` IIFE (<script src>).");
+	L.push("// Regenerate after a glissade upgrade:  gs types --global --out glissade.d.ts");
+	L.push("// Reference it from your tsconfig `include` (or a /// <reference path> ) — no imports needed.");
+	L.push("//");
+	L.push("// APPROXIMATE: node instances, Paint, FontAxes, PathValue and the Timeline document are");
+	L.push("// OPAQUE brands, and helper signatures beyond the headline authoring calls are `(...args) => any`.");
+	L.push("// What IS checked: every surface member name + each node constructor's construction props.");
+	L.push("");
+	L.push("export {};");
+	L.push("");
+	L.push("/** Opaque best-effort types — the real shapes live in @glissade/core|scene. */");
+	L.push("type GsPaint = string | { readonly [key: string]: unknown };");
+	L.push("type GsFontAxes = { readonly [axis: string]: number };");
+	L.push("type GsPathValue = readonly unknown[];");
+	L.push("type GsNode = { readonly __glissadeNode: 'node' };");
+	L.push("type GsScene = { readonly __glissadeScene: 'scene' };");
+	L.push("type GsTimeline = { readonly __glissadeTimeline: 'timeline' };");
+	L.push("");
+	L.push("/** The `timeline(tl => …)` builder surface (methods from describe().builder). */");
+	L.push("interface GsTimelineBuilder {");
+	for (const name of builderMethods) L.push(`  ${name}(...args: any[]): GsTimelineBuilder;`);
+	L.push("}");
+	L.push("");
+	const ctorNodes = surface.filter((e) => e.form === "constructor" && manifest.nodes[e.name]).map((e) => e.name).sort();
+	const propsInterfaceName = (node) => `Gs${node}Props`;
+	for (const node of ctorNodes) {
+		const props = manifest.nodes[node].props;
+		L.push(`/** Construction props for \`new glissade.${node}({ … })\` (best-effort; opaque prop types → \`unknown\`). */`);
+		L.push(`interface ${propsInterfaceName(node)} {`);
+		for (const prop of Object.keys(props).sort()) L.push(`  ${JSON.stringify(prop)}?: ${ambientPropType(props[prop].type)};`);
+		L.push("}");
+		L.push("");
+	}
+	L.push("/** Every `window.glissade.<name>` export (a typo'd member is a compile error). */");
+	L.push("interface GlissadeGlobal {");
+	for (const e of surface) {
+		if (e.kind !== "value" || !e.iife) continue;
+		L.push(`  ${JSON.stringify(e.name)}: ${ambientMemberType(e, ctorNodes)};`);
+	}
+	L.push("}");
+	L.push("");
+	L.push("declare global {");
+	L.push("  interface Window {");
+	L.push("    glissade: GlissadeGlobal;");
+	L.push("  }");
+	L.push("  const glissade: GlissadeGlobal;");
+	L.push("}");
+	L.push("");
+	return L.join("\n");
+}
+/** The TS type for one window.glissade value member (constructor / function / object). */
+function ambientMemberType(e, ctorNodes) {
+	if (e.form === "object") return "Record<string, unknown>";
+	if (e.form === "constructor") return `new (props?: ${ctorNodes.includes(e.name) ? `Gs${e.name}Props` : "Record<string, unknown>"}) => GsNode`;
+	switch (e.name) {
+		case "timeline": return "(build: (tl: GsTimelineBuilder) => void) => GsTimeline";
+		case "createScene": return "(spec: { size: { w: number; h: number }; children: GsNode[] }) => GsScene";
+		case "track": return "(target: string, type: string, keys: readonly unknown[], opts?: { editable?: boolean }) => unknown";
+		default: return "(...args: any[]) => any";
+	}
+}
 //#endregion
-export { generateTypedSdk };
+export { generateAmbientDts, generateTypedSdk };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.46.0",
+  "version": "0.47.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.46.0",
-    "@glissade/core": "0.46.0",
-    "@glissade/interact": "0.46.0",
-    "@glissade/lottie": "0.46.0",
-    "@glissade/narrate": "0.46.0",
-    "@glissade/player": "0.46.0",
-    "@glissade/scene": "0.46.0",
-    "@glissade/sfx": "0.46.0",
-    "@glissade/svg": "0.46.0"
+    "@glissade/backend-skia": "0.47.0-pre.0",
+    "@glissade/core": "0.47.0-pre.0",
+    "@glissade/interact": "0.47.0-pre.0",
+    "@glissade/lottie": "0.47.0-pre.0",
+    "@glissade/narrate": "0.47.0-pre.0",
+    "@glissade/player": "0.47.0-pre.0",
+    "@glissade/scene": "0.47.0-pre.0",
+    "@glissade/sfx": "0.47.0-pre.0",
+    "@glissade/svg": "0.47.0-pre.0"
   },
   "repository": {
     "type": "git",