cozyclay 1.10.0 → 2.0.2

package/src/commands/shot.js

@@ -0,0 +1,103 @@
+// One semantic entry point for timeline, camera controls and agent framing.
+import { createCameraBlock, updateCameraBlock, removeCameraRail } from '../camera-block.js';
+import { addShotAtFrame, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { createStableItemId, updateStableItem } from '../stable-items.js';
+import { railFollowForNewGeometry } from '../camera-rail-schedule.js';
+import { studioActionDeclaration } from '../studio-actions.js';
+import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
+import { elementSetSchema, registerElementSet } from './elements.js';
+import './elements/shot.js';
+import { changedIds, fail, shotLabel } from './shared.js';
+
+const id = StudioSchemas.TargetGuard.properties.targetId;
+const number = { type: 'number' };
+const frame = { type: 'integer', minimum: 0 };
+const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const mutation = (id, label, schema) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'shot', input: schema });
+const existing = ['shot.create', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
+const extra = [
+  mutation('shot.set', 'Set shot fields', elementSetSchema('shot')),
+  mutation('shot.rename', 'Rename shot', input({ shotId: id, name: { type: 'string', maxLength: 240 } })),
+  mutation('shot.setCamera', 'Set camera block', input({ shotId: id, patch: { type: 'object', properties: {}, additionalProperties: true } })),
+  mutation('shot.addKey', 'Add camera key', input({ shotId: id, frame })),
+  mutation('shot.moveKey', 'Move camera key', input({ shotId: id, keyId: id, frame })),
+  mutation('shot.removeKey', 'Remove camera key', input({ shotId: id, keyId: id })),
+  mutation('shot.clearKeys', 'Clear camera keys', input({ shotId: id })),
+  mutation('shot.setTimeline', 'Set shot timeline', input({ frameCount: { type: 'integer', minimum: 24, maximum: 28800 } })),
+  mutation('shot.setLens', 'Set camera lens', input({ fovDeg: { ...number, minimum: 14, maximum: 90 } })),
+  mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] }),
+  { ...mutation('shot.replace', 'Replace shot authoring', input({ shots: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } } })), exposure: 'ui-only' },
+  { ...mutation('shot.captureCamera', 'Capture camera framing', input({ shotId: id }, [])), exposure: 'ui-only' },
+  { ...mutation('shot.placeCamera', 'Place camera', input(Object.fromEntries(['x', 'y', 'z', 'lookAtX', 'lookAtY', 'lookAtZ', 'focalMm'].map(key => [key, number])), [])), exposure: 'ui-only' },
+];
+export const declarations = Object.freeze([extra[0], ...existing, ...extra.slice(1).map(entry => entry.id === 'shot.frame' ? entry : { ...entry, exposure: 'ui-only' })]);
+
+export function register(registry, ports) {
+  const owner = () => ports.storeDomain('shot');
+  const mounted = () => Boolean(ports.storeDomain?.('shot')) || 'The shots document owner is not mounted.';
+  const shotOf = shotId => owner().read().find(shot => shot.id === shotId) ?? fail('STALE_TARGET', `Shot ${shotId} is not in this scene.`);
+  const patchShot = (shotId, update) => { shotOf(shotId); owner().write(current => updateStableItem(current, shotId, update, 'shots')); };
+  const methods = {
+    'shot.create': () => owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.split': ({ shotId }) => {
+      const shot = shotOf(shotId), { frame } = ports.state();
+      if (frame <= shot.startFrame || frame > shot.endFrame) fail('TARGET_NOT_READY', `The playhead (frame ${frame}) is not inside ${shot.name} after its first frame.`);
+      owner().write(current => cutAtFrame(current, shotId, frame, owner().capture()));
+    },
+    'shot.duplicate': ({ shotId }) => { shotOf(shotId); owner().write(current => duplicateShot(current, shotId, owner().state().frameCount)); },
+    'shot.remove': ({ shotId }) => { shotOf(shotId); owner().write(current => removeShot(current, shotId)); },
+    'shot.reorder': ({ shotId, startFrame }) => { shotOf(shotId); owner().write(current => reorderShot(current, shotId, startFrame, owner().state().frameCount)); },
+    'shot.setRange': ({ shotId, range }) => {
+      const shot = shotOf(shotId), startFrame = range.startFrame, endFrame = range.endFrameExclusive - 1;
+      const edges = startFrame > shot.endFrame ? [['end', endFrame], ['start', startFrame]] : [['start', startFrame], ['end', endFrame]];
+      owner().write(current => edges.reduce((rows, [edge, frame]) => resizeShot(rows, shotId, edge, frame, owner().state().frameCount), current));
+    },
+    'shot.setCameraRail': ({ shotId, points }) => patchShot(shotId, shot => ({ ...shot, camera: updateCameraBlock(shot.camera, {
+      cameraRail: points, mode: 'rail', railFollow: railFollowForNewGeometry(shot.camera?.railFollow, shot.endFrame - shot.startFrame + 1),
+    }) })),
+    'shot.clearCameraRail': ({ shotId }) => {
+      const shot = shotOf(shotId);
+      if (!createCameraBlock(shot.camera).cameraRail) fail('TARGET_NOT_READY', `${shot.name || shotId} has no camera rail.`);
+      patchShot(shotId, shot => ({ ...shot, camera: removeCameraRail(shot.camera) }));
+    },
+    'shot.rename': ({ shotId, name }) => { shotOf(shotId); owner().write(current => renameShot(current, shotId, name)); },
+    'shot.setCamera': ({ shotId, patch }) => patchShot(shotId, shot => ({ ...shot, camera: updateCameraBlock(shot.camera, patch) })),
+    'shot.addKey': ({ shotId, frame }) => {
+      const shot = shotOf(shotId), target = Math.min(owner().state().frameCount - 1, frame);
+      if (target < shot.startFrame || target > shot.endFrame) return;
+      const framing = owner().capture();
+      patchShot(shotId, shot => ({ ...shot, cameraKeys: [...shot.cameraKeys.filter(key => key.frame !== target),
+        { id: shot.cameraKeys.find(key => key.frame === target)?.id ?? createStableItemId('camera-key'), frame: target, framing }].sort((a, b) => a.frame - b.frame) }));
+    },
+    'shot.moveKey': ({ shotId, keyId, frame }) => patchShot(shotId, shot => ({ ...shot,
+      cameraKeys: moveCameraKey(shot.cameraKeys, keyId, Math.max(shot.startFrame, Math.min(shot.endFrame, frame))) })),
+    'shot.removeKey': ({ shotId, keyId }) => patchShot(shotId, shot => ({ ...shot, cameraKeys: removeCameraKey(shot.cameraKeys, keyId) })),
+    'shot.clearKeys': ({ shotId }) => patchShot(shotId, shot => ({ ...shot, cameraKeys: [] })),
+    'shot.setTimeline': ({ frameCount }) => owner().writeState(before => ({ ...before, frameCount })),
+    'shot.setLens': ({ fovDeg }) => owner().setLens(fovDeg),
+    'shot.replace': ({ shots }) => owner().write(shots),
+    'shot.captureCamera': args => owner().captureCamera(args.shotId),
+    'shot.placeCamera': args => owner().placeCamera(args),
+  };
+  const hasShots = state => state.shots.length > 0 || 'There are no shots yet; add one with shot.create.';
+  const availability = {
+    'shot.create': state => addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
+    'shot.split': state => state.shots.some(shot => state.frame > shot.startFrame && state.frame <= shot.endFrame) || `The playhead (frame ${state.frame}) is not inside a shot after its first frame; move it with operate_studio { frame }.`,
+    'shot.clearCameraRail': state => state.shots.some(shot => createCameraBlock(shot.camera).cameraRail) || 'No shot has a camera rail; lay one with shot.setCameraRail.',
+  };
+  registerElementSet(registry, ports, extra[0]);
+  for (const declaration of declarations.filter(row => row.id !== 'shot.set')) registry.register({ ...declaration,
+    available: state => mounted() === true ? (availability[declaration.id] ?? (existing.includes(declaration) ? hasShots : () => true))(state) : mounted(),
+    run(args) {
+      if (declaration.id === 'shot.frame') {
+        const plan = owner().frame(args);
+        return { affectedIds: plan.affectedIds, summary: 'Framed the shot.' };
+      }
+      const before = owner().read(); methods[declaration.id](args);
+      const after = owner().read(), changed = changedIds(before, after);
+      const affectedIds = changed.length ? changed : [args.shotId ?? ports.state().activeSceneId];
+      return { affectedIds, summary: changed.length ? `${declaration.label}: ${changed.map(id => after.find(row => row.id === id)).filter(Boolean).map(shotLabel).join('; ')}.` : `${declaration.label}.` };
+    },
+  });
+  if (ports.storeDomain?.('shot')) registry.registerToolAlias('frame_shot', 'shot.frame');
+}

package/src/commands/stage.js

@@ -0,0 +1,17 @@
+import { elementSetSchema, registerElementSet } from './elements.js';
+export { STAGE_FIELDS, normalizeStage } from './elements/stage.js';
+
+const input = elementSetSchema('stage');
+const declaration = (id, properties = input.properties) => ({ id, label: 'Set stage', kind: 'mutation', undoDomain: 'stage',
+  description: 'Update authored stage fields, normalized by scene persistence.',
+  input: { ...input, properties } });
+export const declarations = Object.freeze([
+  declaration('stage.set'),
+  declaration('stage.setKeyLight', { keyLight: input.properties.keyLight }),
+  declaration('stage.setEnvironment', Object.fromEntries(['environment', 'environmentImage', 'hasEnvSheet'].map(key => [key, input.properties[key]]))),
+  declaration('stage.setStyle', { style: input.properties.style }),
+  declaration('stage.setFilmback', Object.fromEntries(['shotAspect', 'cameraPresetId', 'sensorId'].filter(key => input.properties[key]).map(key => [key, input.properties[key]]))),
+]);
+export function register(registry, ports) {
+  for (const declaration of declarations) registerElementSet(registry, ports, declaration);
+}

package/src/commands/view.js

@@ -0,0 +1,42 @@
+// Viewer preferences: transient, like the View menu they mirror.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { StudioProtocolError, STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
+import { shotAtFrame } from '../cuts.js';
+
+const fields = STUDIO_TOOL_SCHEMAS.operate_studio.properties;
+const groups = { 'view.select': ['selection', 'shotId'], 'timeline.seek': ['frame'], 'timeline.play': ['playing'], 'view.setMode': ['mode', 'view'] };
+const operations = Object.entries({ ...groups, 'view.update': Object.keys(fields) }).map(([id, keys]) => ({
+	id, label: id, description: 'Change selection, timeline or viewer state without authoring history.', kind: 'transient',
+	input: { type: 'object', properties: Object.fromEntries(keys.map(key => [key, fields[key]])), required: [], additionalProperties: false },
+}));
+export const declarations = Object.freeze([...operations, ...["view.setPartColours", "view.setGuideMode", "view.setInset"].map(studioActionDeclaration)]);
+export const viewCommand = args => Object.entries(groups).find(([, keys]) => Object.keys(args).every(key => keys.includes(key)))?.[0] ?? 'view.update';
+
+export function register(registry, ports) {
+	registry.registerToolAlias('operate_studio', viewCommand);
+	for (const declaration of operations) registry.register({ ...declaration, available: () => true, run(args) {
+		const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+		if (!Object.keys(args).length || (args.view && !Object.keys(args.view).length)) fail('INVALID_ARGUMENT', 'Specify a view operation.');
+		const state = ports.readView();
+		// Pose mode is IK editing: without a rig to solve there is nothing to pose.
+		if (args.mode === 'pose' && args.mode !== state.view.mode && !ports.canPose()) fail('TARGET_NOT_READY', 'Pose mode needs a loaded character rig to edit with IK.');
+		const selection = args.selection === undefined ? state.selection : args.selection;
+		if (selection) {
+			const found = selection.kind === 'scene' ? selection.id === state.host.sceneId : selection.kind === 'camera' ? selection.id === 'camera'
+				: (selection.kind === 'object' ? state.objects : state.characters).some(row => row.id === selection.id);
+			if (!found) fail('STALE_TARGET', 'Selection is not present in this document.');
+		}
+		const shot = args.shotId === undefined ? null : state.shots.find(row => row.id === args.shotId);
+		if (args.shotId !== undefined && !shot) fail('STALE_TARGET', 'Shot is not present in this document.');
+		const frame = args.frame ?? shot?.startFrame ?? state.view.frame;
+		if (frame >= Math.max(1, state.frameCount)) fail('INVALID_RANGE', 'Frame is outside the timeline.');
+		const view = { ...state.view, ...args.view, frame, mode: args.mode ?? state.view.mode, playing: args.playing ?? state.view.playing };
+		ports.publishView({ selection, view, shotId: args.shotId ?? shotAtFrame(state.shots, frame)?.id ?? null });
+		return { affectedIds: [state.host.sceneId], summary: 'Updated editor view.' };
+	} });
+	const viewAction = (id, run) => registry.register({ ...studioActionDeclaration(id), available: () => true,
+		run: args => ({ affectedIds: [], summary: run(args) }) });
+	viewAction("view.setPartColours", ({ mode }) => { ports.choosePartColours(mode); return `Part colours: ${mode}.`; });
+	viewAction("view.setGuideMode", ({ mode }) => { ports.setGuideMode(mode); return `Composition guide: ${mode}.`; });
+	viewAction("view.setInset", ({ collapsed }) => { ports.setInsetCollapsed(collapsed); return `Top-View inset ${collapsed ? "folded" : "unfolded"}.`; });
+}

package/src/document-store.js

@@ -0,0 +1,144 @@
+// Each domain owns immutable authored slices here. The facade composes sessions
+// across stores; neither this store nor its callers restore native snapshots.
+import { createHistory, pushHistory, undoHistory, redoHistory } from './history.js';
+import { StudioProtocolError } from './studio-agent-protocol.js';
+import { copyAuthoredIntent, deepFreeze } from './store/authored-intent.js';
+
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+
+export function createDocumentStore({ owned = {}, dev = import.meta.env?.DEV ?? true, copyIntent = copyAuthoredIntent } = {}) {
+  const freeze = value => dev ? deepFreeze(value) : value;
+  const copy = value => freeze(copyIntent(value));
+  let slices = copy(owned);
+  let snapshot = freeze({ revision: 0, domainRevisions: Object.fromEntries(Object.keys(owned).map(domain => [domain, 0])), slices });
+  let history = createHistory({ historyEntryId: null, snapshot: slices });
+  let active = null, running = 0;
+  const listeners = new Set();
+  const owns = domain => Object.hasOwn(slices, domain);
+  function requireOwner(domain) {
+    if (!owns(domain)) fail('CAPABILITY_MISSING', `No document slice is owned for ${domain}.`);
+  }
+  function publish(next) {
+    const changed = Object.keys(slices).filter(domain => slices[domain] !== next[domain]);
+    if (!changed.length) return;
+    const domainRevisions = { ...snapshot.domainRevisions };
+    for (const domain of changed) domainRevisions[domain]++;
+    slices = freeze(next);
+    snapshot = freeze({ revision: snapshot.revision + 1, domainRevisions, slices });
+    for (const listener of listeners) listener();
+  }
+  function beginAction(domain) {
+    requireOwner(domain);
+    if (active) fail('TARGET_BUSY', 'A document transaction is already open.');
+    const before = slices;
+    const check = () => { if (active !== session) fail('STALE_TARGET', 'Document transaction is no longer current.'); };
+    const session = {
+      // Permission ends at the synchronous publication boundary, not when an
+      // async preparation finishes. Jobs explicitly re-enter through commit.
+      run(fn) { check(); running++; try { return fn(); } finally { running--; } },
+      touch(domain) { check(); requireOwner(domain); },
+      update(domain, update) { return session.run(() => write(domain, update)); },
+      cancel({ restore = true } = {}) {
+        if (active !== session) return false;
+        active = null;
+        if (restore) publish(before);
+        return true;
+      },
+      commit() {
+        check(); active = null;
+        if (!Object.keys(slices).some(key => slices[key] !== before[key])) return { historyEntryId: null };
+        const historyEntryId = crypto.randomUUID();
+        history = pushHistory(history, { historyEntryId, snapshot: slices });
+        return { historyEntryId };
+      },
+    };
+    active = session;
+    return session;
+  }
+  function recordAction(domain, fn, targetId = null, nested = false) {
+    if (nested && active) {
+      active.touch(domain);
+      const result = active.run(fn);
+      return result?.then ? result.then(result => ({ result, historyEntryId: null })) : { result, historyEntryId: null };
+    }
+    const session = beginAction(domain);
+    const done = result => ({ result, ...session.commit() });
+    const failed = error => { session.cancel(); throw error; };
+    try { const result = session.run(fn); return result?.then ? result.then(done, failed) : done(result); }
+    catch (error) { return failed(error); }
+  }
+  function write(domain, update) {
+    requireOwner(domain);
+    if (dev && !running) throw new TypeError(`A store-owned ${domain} write requires a bus run.`);
+    if (!active) return recordAction(domain, () => write(domain, update)).result;
+    if (!running) fail('TARGET_BUSY', 'A document transaction owns this write.');
+    const next = typeof update === 'function' ? update(slices[domain]) : update;
+    if (next !== slices[domain]) publish({ ...slices, [domain]: copy(next) });
+    return slices[domain];
+  }
+  // The oldest snapshot has no retained pre-image. Its id cannot promise Undo.
+  const retainedEntries = () => [...(history.past.length ? [...history.past.slice(1), history.present] : []), ...history.future];
+  function step(redo) {
+    if (active) fail('TARGET_BUSY', 'Finish the document transaction before traversing history.');
+    const entry = redo ? history.future[0] : history.present;
+    const next = (redo ? redoHistory : undoHistory)(history);
+    if (!next) return null;
+    history = next; publish(history.present.snapshot);
+    return entry;
+  }
+  return {
+    owns, read: domain => { requireOwner(domain); return slices[domain]; }, write, beginAction, recordAction,
+    dispose() { active?.cancel(); listeners.clear(); },
+    undo: () => step(false), redo: () => step(true),
+    canUndo: id => !active && history.past.length > 0 && (id === undefined || history.present.historyEntryId === id),
+    canRedo: () => !active && history.future.length > 0,
+    getSnapshot: () => snapshot,
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    isRetained: id => Boolean(id && retainedEntries().some(entry => entry.historyEntryId === id)),
+    history: () => freeze(history),
+    depths: () => ({ past: history.past.length, future: history.future.length }),
+  };
+}
+
+// Compatibility for object producers with token-based drags. There is no
+// separate object history: every preview, cancellation and traversal uses the
+// document store. Immutable producer arrays retain their reference contract.
+export function createSceneHistoryStore(initialObjects, { onObjects, onCommit } = {}) {
+  const store = createDocumentStore({ owned: { objects: initialObjects }, dev: false, copyIntent: value => value });
+  const read = () => store.read('objects');
+  store.subscribe(() => onObjects?.(read()));
+  let active = null, sequence = 0;
+  function close(commit, notify = true) {
+    const current = active; active = null;
+    if (commit) {
+      current.session.commit();
+      if (notify) onCommit?.(current.before, read());
+    } else current.session.cancel();
+  }
+  function settle(notify = true) {
+    if (!active) return;
+    const cancel = active.cancel;
+    close(true, notify); cancel?.();
+  }
+  return {
+    get objects() { return read(); },
+    present: () => store.history().present.snapshot.objects,
+    applyAtomic(fn) {
+      settle();
+      const before = read();
+      store.recordAction('objects', () => store.write('objects', fn));
+      if (before !== read()) onCommit?.(before, read());
+    },
+    begin(owner, cancel) {
+      settle();
+      active = { token: ++sequence, owner, cancel, before: read(), session: store.beginAction('objects') };
+      return active.token;
+    },
+    applyIn(token, fn) { if (active?.token === token) active.session.update('objects', fn); },
+    end(token, { commit }) { if (active?.token !== token) return false; close(commit); return true; },
+    settle,
+    undo() { settle(false); return store.undo() ? read() : null; },
+    redo() { settle(false); return store.redo() ? read() : null; },
+    canUndo: store.canUndo, canRedo: store.canRedo, depths: store.depths,
+  };
+}