@glissade/core 0.8.1 → 0.9.0-pre.1

package/dist/studioHost.d.ts

@@ -0,0 +1,126 @@
+import { H as Key, N as Timeline, S as isEditableNodeId, St as ValueTypeId, a as SidecarOrphan, lt as EaseSpec, r as SidecarDoc, w as targetNodeId } from "./sidecar.js";
+
+//#region src/timelinePatch.d.ts
+
+/** A new key's data (no id — one is assigned on apply). */
+interface NewKey {
+  t: number;
+  value: unknown;
+  ease?: EaseSpec;
+  interp?: 'default' | 'hold';
+}
+type TimelinePatch = {
+  op: 'setTrackKeys';
+  timelineId: string;
+  target: string;
+  type: ValueTypeId;
+  keys: Key[];
+  baseHash?: string | null;
+  verbatim?: boolean;
+} | {
+  op: 'removeTrack';
+  timelineId: string;
+  target: string;
+  prune?: boolean;
+} | {
+  op: 'addKey';
+  timelineId: string;
+  target: string;
+  key: NewKey;
+} | {
+  op: 'removeKey';
+  timelineId: string;
+  target: string;
+  id: string;
+} | {
+  op: 'moveKey';
+  timelineId: string;
+  target: string;
+  id: string;
+  t: number;
+} | {
+  op: 'setKeyValue';
+  timelineId: string;
+  target: string;
+  id: string;
+  value: unknown;
+} | {
+  op: 'setKeyEase';
+  timelineId: string;
+  target: string;
+  id: string;
+  ease?: EaseSpec;
+  interp?: 'default' | 'hold';
+} | {
+  op: 'setLabel';
+  timelineId: string;
+  name: string;
+  t: number;
+} | {
+  op: 'removeLabel';
+  timelineId: string;
+  name: string;
+};
+interface PatchOk {
+  ok: true;
+  doc: SidecarDoc;
+  /** inverse transaction — apply to undo (restores each touched track/label). */
+  inverse: TimelinePatch[];
+}
+interface PatchErr {
+  ok: false;
+  error: string;
+}
+type PatchResult = PatchOk | PatchErr;
+/** The code-baseline track for a target, so a first edit on a code-only track seeds + records its baseHash. */
+interface TrackBaseline {
+  type: ValueTypeId;
+  keys: readonly Key[];
+}
+type BaselineLookup = (timelineId: string, target: string) => TrackBaseline | null;
+/**
+ * Apply a batch of patches **atomically**: validate-and-build against a working
+ * copy; on the FIRST invalid patch, return `{ ok: false }` with the original
+ * doc untouched (immutable updates never mutate the input). On success, return
+ * the new doc plus the inverse transaction (one snapshot-restore per touched
+ * track/label). `baseline` seeds a first edit on a code-only track.
+ */
+declare function applyPatches(doc: SidecarDoc, patches: readonly TimelinePatch[], baseline?: BaselineLookup): PatchResult;
+/** Apply a single patch (convenience over `applyPatches`). */
+declare function applyPatch(doc: SidecarDoc, patch: TimelinePatch, baseline?: BaselineLookup): PatchResult;
+//#endregion
+//#region src/studioHost.d.ts
+/** The merged code+sidecar view plus the tracks parked off the merge (§6.2 rule 3). */
+type MergedTimeline = Timeline & {
+  orphans: Record<string, SidecarOrphan>;
+};
+/** `${nodeId}/${propPath}` — the §2.2 canonical track grammar. */
+type SignalPath = string;
+type Unsubscribe = () => void;
+interface PropDescriptor {
+  name: string;
+  type: ValueTypeId;
+  /** editable IFF the node has an explicit id AND a merged/editor-created track exists (§6.4 sub-decision). */
+  editable: boolean;
+}
+interface NodeDescriptor {
+  id: string;
+  /** the node kind (Group/Rect/Text/…). */
+  type: string;
+  props: PropDescriptor[];
+}
+type StudioEvent = 'tree-changed' | 'doc-patched' | 'playhead-moved';
+interface StudioHost {
+  /** ids, types, prop schemas + editability — deep plain data, clone-safe. */
+  getSceneTree(): NodeDescriptor[];
+  /** merged code+sidecar timeline + orphans (§6.2). */
+  getTimeline(): MergedTimeline;
+  /** bridge a node/prop signal to a callback; returns an unsubscribe. */
+  subscribeSignal(path: SignalPath, cb: (v: unknown) => void): Unsubscribe;
+  /** apply an edit transaction — validated + atomic; returns the inverse for undo. */
+  applyPatch(patches: TimelinePatch[]): PatchResult;
+  setPlayhead(t: number): void;
+  on(ev: StudioEvent, cb: (...args: unknown[]) => void): Unsubscribe;
+}
+//#endregion
+export { type BaselineLookup, MergedTimeline, type NewKey, NodeDescriptor, type PatchErr, type PatchOk, type PatchResult, PropDescriptor, SignalPath, StudioEvent, StudioHost, type TimelinePatch, type TrackBaseline, Unsubscribe, applyPatch, applyPatches, isEditableNodeId, targetNodeId };

package/dist/studioHost.js

@@ -0,0 +1,262 @@
+import { a as hashKeys, h as targetNodeId, l as normalizeEditedKeys, n as assignKeyIds, p as isEditableNodeId } from "./sidecar.js";
+//#region src/timelinePatch.ts
+/** Unambiguous composite map key (no control-char separators). */
+function refKey(timelineId, name) {
+	return JSON.stringify([timelineId, name]);
+}
+function parseRefKey(k) {
+	return JSON.parse(k);
+}
+function getTimeline(doc, id) {
+	return doc.timelines[id] ?? { tracks: {} };
+}
+/** The current sidecar entry for a target, seeding from the code baseline (with ids) if absent. */
+function resolveEntry(doc, p, baseline) {
+	const existing = doc.timelines[p.timelineId]?.tracks[p.target];
+	if (existing) return existing;
+	const base = baseline?.(p.timelineId, p.target) ?? null;
+	if (!base) return null;
+	return {
+		type: base.type,
+		baseHash: hashKeys(base.keys),
+		keys: assignKeyIds(base.keys.map((k) => ({ ...k })))
+	};
+}
+function putEntry(doc, timelineId, target, entry) {
+	const tl = getTimeline(doc, timelineId);
+	return {
+		...doc,
+		timelines: {
+			...doc.timelines,
+			[timelineId]: {
+				...tl,
+				tracks: {
+					...tl.tracks,
+					[target]: entry
+				}
+			}
+		}
+	};
+}
+function removeEntry(doc, timelineId, target, prune = false) {
+	const tl = doc.timelines[timelineId];
+	if (!tl?.tracks[target]) return doc;
+	const tracks = { ...tl.tracks };
+	delete tracks[target];
+	const labels = tl.labels;
+	if (prune && Object.keys(tracks).length === 0 && (!labels || Object.keys(labels).length === 0)) {
+		const timelines = { ...doc.timelines };
+		delete timelines[timelineId];
+		return {
+			...doc,
+			timelines
+		};
+	}
+	return {
+		...doc,
+		timelines: {
+			...doc.timelines,
+			[timelineId]: {
+				...tl,
+				tracks
+			}
+		}
+	};
+}
+/**
+* Apply a key-list edit. `verbatim` restores keys EXACTLY as given (the inverse
+* path — it is replaying a prior valid state, so re-normalizing would re-pin
+* springs / re-nudge collisions and break byte-exact undo). The forward editor
+* path normalizes (§2.7 spring re-pin + collision nudge) and (re)assigns ids.
+*/
+function withKeys(entry, keys, verbatim = false) {
+	return {
+		...entry,
+		keys: verbatim ? keys.map((k) => ({ ...k })) : assignKeyIds(normalizeEditedKeys(keys))
+	};
+}
+/**
+* Apply a batch of patches **atomically**: validate-and-build against a working
+* copy; on the FIRST invalid patch, return `{ ok: false }` with the original
+* doc untouched (immutable updates never mutate the input). On success, return
+* the new doc plus the inverse transaction (one snapshot-restore per touched
+* track/label). `baseline` seeds a first edit on a code-only track.
+*/
+function applyPatches(doc, patches, baseline) {
+	let work = doc;
+	const trackSnap = /* @__PURE__ */ new Map();
+	const labelSnap = /* @__PURE__ */ new Map();
+	const tlExisted = /* @__PURE__ */ new Map();
+	const snapTrack = (timelineId, target) => {
+		if (!tlExisted.has(timelineId)) tlExisted.set(timelineId, work.timelines[timelineId] !== void 0);
+		const k = refKey(timelineId, target);
+		if (!trackSnap.has(k)) trackSnap.set(k, work.timelines[timelineId]?.tracks[target] ?? null);
+	};
+	const snapLabel = (timelineId, name) => {
+		const k = refKey(timelineId, name);
+		if (!labelSnap.has(k)) labelSnap.set(k, work.timelines[timelineId]?.labels?.[name]);
+	};
+	for (const p of patches) switch (p.op) {
+		case "setTrackKeys": {
+			if (!p.verbatim && !isEditableNodeId(targetNodeId(p.target))) return {
+				ok: false,
+				error: `setTrackKeys: '${p.target}' is not an editable host (structural/un-id'd nodes cannot host tracks, §6.5)`
+			};
+			snapTrack(p.timelineId, p.target);
+			const prev = work.timelines[p.timelineId]?.tracks[p.target];
+			const entry = withKeys({
+				type: p.type,
+				baseHash: p.baseHash !== void 0 ? p.baseHash : prev?.baseHash ?? null,
+				keys: []
+			}, p.keys.map((k) => ({ ...k })), p.verbatim);
+			work = putEntry(work, p.timelineId, p.target, entry);
+			break;
+		}
+		case "removeTrack":
+			if (!work.timelines[p.timelineId]?.tracks[p.target]) return {
+				ok: false,
+				error: `removeTrack: no sidecar track '${p.target}'`
+			};
+			snapTrack(p.timelineId, p.target);
+			work = removeEntry(work, p.timelineId, p.target, p.prune);
+			break;
+		case "addKey": {
+			if (!isEditableNodeId(targetNodeId(p.target))) return {
+				ok: false,
+				error: `addKey: '${p.target}' is not an editable host (structural/un-id'd nodes cannot host tracks, §6.5)`
+			};
+			const entry = resolveEntry(work, p, baseline);
+			if (!entry) return {
+				ok: false,
+				error: `addKey: unknown track '${p.target}' (no sidecar entry and no code baseline)`
+			};
+			snapTrack(p.timelineId, p.target);
+			const k = {
+				t: p.key.t,
+				value: p.key.value,
+				...p.key.ease !== void 0 ? { ease: p.key.ease } : {},
+				...p.key.interp !== void 0 ? { interp: p.key.interp } : {}
+			};
+			work = putEntry(work, p.timelineId, p.target, withKeys(entry, [...entry.keys, k]));
+			break;
+		}
+		case "removeKey":
+		case "moveKey":
+		case "setKeyValue":
+		case "setKeyEase": {
+			const entry = resolveEntry(work, p, baseline);
+			if (!entry) return {
+				ok: false,
+				error: `${p.op}: unknown track '${p.target}'`
+			};
+			if (!entry.keys.some((k) => k.id === p.id)) return {
+				ok: false,
+				error: `${p.op}: no key '${p.id}' in '${p.target}'`
+			};
+			snapTrack(p.timelineId, p.target);
+			const next = p.op === "removeKey" ? entry.keys.filter((k) => k.id !== p.id) : entry.keys.map((k) => {
+				if (k.id !== p.id) return k;
+				if (p.op === "moveKey") return {
+					...k,
+					t: Math.max(0, p.t)
+				};
+				if (p.op === "setKeyValue") return {
+					...k,
+					value: p.value
+				};
+				const u = { ...k };
+				if (p.ease !== void 0) u.ease = p.ease;
+				else delete u.ease;
+				if (p.interp !== void 0) u.interp = p.interp;
+				else delete u.interp;
+				return u;
+			});
+			work = putEntry(work, p.timelineId, p.target, withKeys(entry, next));
+			break;
+		}
+		case "setLabel": {
+			snapLabel(p.timelineId, p.name);
+			const tl = getTimeline(work, p.timelineId);
+			work = {
+				...work,
+				timelines: {
+					...work.timelines,
+					[p.timelineId]: {
+						...tl,
+						labels: {
+							...tl.labels ?? {},
+							[p.name]: p.t
+						}
+					}
+				}
+			};
+			break;
+		}
+		case "removeLabel": {
+			snapLabel(p.timelineId, p.name);
+			const tl = work.timelines[p.timelineId];
+			if (tl?.labels && p.name in tl.labels) {
+				const labels = { ...tl.labels };
+				delete labels[p.name];
+				work = {
+					...work,
+					timelines: {
+						...work.timelines,
+						[p.timelineId]: {
+							...tl,
+							labels
+						}
+					}
+				};
+			}
+			break;
+		}
+	}
+	const inverse = [];
+	for (const [k, snap] of trackSnap) {
+		const [timelineId, target] = parseRefKey(k);
+		if (snap === null) inverse.push(tlExisted.get(timelineId) === false ? {
+			op: "removeTrack",
+			timelineId,
+			target,
+			prune: true
+		} : {
+			op: "removeTrack",
+			timelineId,
+			target
+		});
+		else inverse.push({
+			op: "setTrackKeys",
+			timelineId,
+			target,
+			type: snap.type,
+			keys: snap.keys.map((x) => ({ ...x })),
+			baseHash: snap.baseHash,
+			verbatim: true
+		});
+	}
+	for (const [k, value] of labelSnap) {
+		const [timelineId, name] = parseRefKey(k);
+		inverse.push(value === void 0 ? {
+			op: "removeLabel",
+			timelineId,
+			name
+		} : {
+			op: "setLabel",
+			timelineId,
+			name,
+			t: value
+		});
+	}
+	return {
+		ok: true,
+		doc: work,
+		inverse
+	};
+}
+/** Apply a single patch (convenience over `applyPatches`). */
+function applyPatch(doc, patch, baseline) {
+	return applyPatches(doc, [patch], baseline);
+}
+//#endregion
+export { applyPatch, applyPatches, isEditableNodeId, targetNodeId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.8.1",
+  "version": "0.9.0-pre.1",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./studio-host": {
+      "types": "./dist/studioHost.d.ts",
+      "default": "./dist/studioHost.js"
     }
   },
   "files": [