cozyclay 1.9.0 → 2.0.0

package/src/command-bus.js

@@ -0,0 +1,349 @@
+// The Studio command runner. The registry owns declarations/implementations;
+// the editor ports own native state/history, and the existing journal owns
+// idempotency. Synchronous UI actions stay synchronous (including user gestures).
+import { HISTORY_LIMIT } from './history.js';
+import { StudioProtocolError, StudioSchemas, validateStudioSchema, validateReceipt, validateStudioIdentity } from './studio-agent-protocol.js';
+
+// A batching/retention adapter over the existing object history owner. The
+// native store still owns every snapshot and transition; this tracks only the
+// retained pre-image identities needed by receipts.
+export function withCommandHistory(store) {
+  let past = [], future = [], group = null;
+  const adapter = Object.create(store);
+  const pushed = before => { if (before !== store.present()) { past.push(before); past = past.slice(-HISTORY_LIMIT); future = []; } };
+  adapter.hasHistoryState = state => state === store.present() || past.includes(state) || future.includes(state);
+  adapter.settle = (...args) => { const before = store.present(); store.settle(...args); pushed(before); };
+  adapter.applyAtomic = fn => {
+    if (group) { if (!group.running) fail('TARGET_BUSY', 'A command transaction owns the object history.'); return store.applyIn(group.token, fn); }
+    adapter.settle(); const before = store.present(); store.applyAtomic(fn); pushed(before);
+  };
+  adapter.begin = (...args) => { adapter.settle(); return store.begin(...args); };
+  adapter.end = (token, options) => { const before = store.present(), ended = store.end(token, options); if (options.commit) pushed(before); return ended; };
+  adapter.undo = () => { adapter.settle(); const before = store.present(), restored = store.undo(); if (restored !== null) { past.pop(); future.unshift(before); } return restored; };
+  adapter.redo = () => { const before = store.present(), restored = store.redo(); if (restored !== null) { past.push(before); future.shift(); } return restored; };
+  adapter.beginCommand = () => {
+    if (group) fail('TARGET_BUSY', 'An object command is already in progress.');
+    adapter.settle(); const before = store.present();
+    const current = { running: 0, token: store.begin('command-bus', () => { current.closed = true; group = null; }) }; group = current;
+    const check = () => { if (current.closed) fail('STALE_TARGET', 'Native object transaction was retired.'); };
+    return {
+      run(fn) { check(); current.running++; try { const result = fn(); if (result?.then) return result.finally(() => { current.running--; }); current.running--; return result; } catch (error) { current.running--; throw error; } },
+      commit() { check(); current.closed = true; group = null; store.end(current.token, { commit: true }); pushed(before); return before !== store.present(); },
+      cancel() { if (current.closed) return false; current.closed = true; group = null; return store.end(current.token, { commit: false }); },
+    };
+  };
+  return adapter;
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+const mapResult = (value, success, failure) => value?.then ? value.then(success, failure) : success(value);
+const toastWarnings = toasts => toasts.slice(-12).map(toast => ({ code: 'STUDIO_TOAST', message: [...toast.message].slice(0, 120).join('') }));
+let activeRunDepth = 0;
+export const isBusRunActive = () => activeRunDepth > 0;
+
+export function createCommandBus({ registry, ports }) {
+  const pending = new Map(), transactions = new Map(), jobs = new Map(), listeners = new Set();
+  const confirmations = new Map(), historyReceipts = new Map();
+  function exposure(entry, args, request) {
+    if (request.origin === 'ui') return;
+    if (entry.exposure === 'ui-only') fail('CAPABILITY_MISSING', 'This command is available only from the Studio UI.');
+    if (entry.id === 'load_scenes') {
+      const ids = scenes => [...new Set(scenes.map(scene => scene.id))].sort();
+      if (same(ids(args.document.scenes), ids(registry.state().scenes))) return;
+    } else if (entry.exposure !== 'confirm' || entry.requiresConfirmation?.(registry.state(), args) === false) return;
+    const token = confirmations.get(request.confirmationToken);
+    if (!token || token.id !== entry.id || !same(token.args, args) || !same(token.host, ports.read().host) || token.expires < (ports.now ?? Date.now)()) fail('CONFIRMATION_REQUIRED', entry.confirmationReason ?? 'This command needs user confirmation.');
+    confirmations.delete(request.confirmationToken);
+  }
+  const emit = event => { for (const listener of listeners) listener(event); ports.emit?.(event); };
+  const identifier = StudioSchemas.TargetGuard.properties.targetId;
+  const object = properties => ({ type: 'object', properties, required: Object.keys(properties), additionalProperties: false });
+  const argsSchema = { type: 'object', properties: {}, required: [], additionalProperties: true };
+  const controls = {
+    'run.begin': object({ id: identifier, args: argsSchema }),
+    'run.update': object({ txId: identifier, args: argsSchema }),
+    'run.commit': object({ txId: identifier }),
+    'run.cancel': object({ txId: identifier }),
+    'job.await': { ...object({ jobId: identifier }), properties: { jobId: identifier, timeoutMs: { type: 'integer', minimum: 1, maximum: 300_000, default: 30_000 } } },
+    'job.cancel': object({ jobId: identifier }),
+    'edit.undo': { ...object({ receiptId: identifier }), required: [] },
+    'edit.redo': { ...object({ receiptId: identifier }), required: [] },
+  };
+  const clear = timer => (ports.clearTimeout ?? clearTimeout)(timer);
+  function cancelTransaction(tx, expired = false, reason = new StudioProtocolError('CANCELLED', 'Transaction was cancelled.')) {
+    transactions.delete(tx.txId); clear(tx.timer); if (tx.workTimer !== undefined) clear(tx.workTimer); tx.controller.abort(reason);
+    tx.session.cancel({ restore: same(tx.before.host, ports.read().host) });
+    emit({ type: 'transaction.cancelled', txId: tx.txId, expired });
+  }
+  function renew(tx) {
+    if (tx.timer !== undefined) clear(tx.timer);
+    tx.timer = (ports.setTimeout ?? setTimeout)(() => cancelTransaction(tx, true), ports.transactionIdleMs ?? 30_000);
+  }
+  function control(id, args, request, before) {
+    if (id === 'edit.undo' || id === 'edit.redo') {
+      const redo = id === 'edit.redo', historyEntryId = ports.history?.(redo);
+      const previous = args.receiptId ? ports.receipt(args.receiptId) : historyReceipts.get(historyEntryId)
+        ?? (historyEntryId ? { receiptId: historyEntryId, host: before.host, affectedIds: [before.host.sceneId],
+          undo: { historyEntryId, entries: 1, canUndoDirect: true } } : null);
+      if (!args.receiptId && !previous) return validateReceipt({ ok: true, status: 'noop', action: id,
+        commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host, authored: false, mutated: false,
+        revision: { before: before.revision, after: before.revision }, affectedIds: [], delta: [],
+        checks: { coverage: 'native-history-restoration' }, undo: null, warnings: [] });
+      if (!previous?.undo || !ports.isRetained(previous)) fail('UNDO_EXPIRED', 'The receipt no longer has a retained history entry.');
+      if (!same(previous.host, before.host)) fail('STALE_SCENE', 'The receipt belongs to another document.');
+      if (redo ? historyEntryId !== previous.undo.historyEntryId : !ports.canUndo(previous)) fail('UNDO_CONFLICT', 'Another edit owns the history boundary.');
+      (redo ? ports.redo : ports.undo)();
+      const after = ports.read(), ids = previous.affectedIds;
+      const restoredTargets = ids.map(targetId => ({ ...before.host, targetId, token: ports.readTarget?.(targetId) ?? `removed-${crypto.randomUUID()}` }));
+      return validateReceipt({ ok: true, status: redo ? 'applied' : 'undone', commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+        authored: true, revision: { before: before.revision, after: after.revision }, affectedIds: ids,
+        delta: ids.slice(0, 8).map(targetId => ({ id: targetId, after: { token: restoredTargets.find(t => t.targetId === targetId).token } })),
+        checks: { coverage: 'native-history-restoration' }, undo: { ...previous.undo, canUndoDirect: redo }, warnings: [],
+        ...(redo ? { action: id, mutated: true } : { undoneReceiptId: previous.receiptId, restoredTargets }),
+        ...(ids.length > 8 ? { detailCursor: request.commandId } : {}) });
+    }
+    if (id.startsWith('job.')) {
+      const job = jobs.get(args.jobId);
+      if (!job || !same(job.host, before.host)) fail('STALE_TARGET', 'Job is not in this document.');
+      if (id === 'job.cancel' && !job.outcome) job.controller.abort(new StudioProtocolError('CANCELLED', 'Job was cancelled.'));
+      let timer;
+      const wait = id === 'job.await' && !job.outcome ? Promise.race([job.completion, new Promise((_, reject) => {
+        timer = (ports.setTimeout ?? setTimeout)(() => reject(new StudioProtocolError('TIMEOUT', 'Job is still running.')), args.timeoutMs);
+      })]) : job.completion;
+      return wait.then(value => validateReceipt({ ...value, commandId: request.commandId, ...(value.ok ? { receiptId: crypto.randomUUID() } : {}), jobId: job.id })).finally(() => { if (timer !== undefined) clear(timer); });
+    }
+    let tx;
+    if (id === 'run.begin') {
+      if (transactions.size) fail('TARGET_BUSY', 'Finish or cancel the open command transaction first.');
+      const prepared = registry.prepare(args.id, args.args);
+      exposure(prepared.entry, prepared.args, request);
+      if (prepared.entry.kind !== 'mutation') fail('INVALID_ARGUMENT', 'Only mutations can open a transaction.');
+      tx = { txId: crypto.randomUUID(), entry: prepared.entry, before, origin: request.origin, targetId: prepared.args.characterId ?? null, controller: new AbortController(),
+        session: ports.beginAction(prepared.entry.undoDomain, prepared.args.characterId ?? null), affectedIds: new Set(), toasts: [] };
+      transactions.set(tx.txId, tx); renew(tx);
+    } else {
+      tx = transactions.get(args.txId);
+      if (!tx || !same(tx.before.host, before.host)) fail('STALE_TARGET', 'Transaction is no longer open in this document.');
+      if (request.origin !== tx.origin) fail('TARGET_BUSY', 'This transaction belongs to another origin.');
+      if (tx.updating && id !== 'run.cancel') fail('TARGET_BUSY', 'A transaction update is still running.');
+      if (id === 'run.update') {
+        const prepared = registry.prepare(tx.entry.id, args.args);
+        if (tx.entry.undoDomain === 'motion' && prepared.args.characterId !== tx.targetId) fail('INVALID_ARGUMENT', 'A motion transaction keeps its original target.');
+        const shown = [], release = ports.captureToasts?.(toast => shown.push(typeof toast === 'string' ? { message: toast } : toast));
+        const context = { origin: request.origin, signal: tx.controller.signal, check() {
+          tx.controller.signal.throwIfAborted();
+          if (!transactions.has(tx.txId) || !same(tx.before.host, ports.read().host)) fail('STALE_TARGET', 'Transaction is no longer current.');
+        } };
+        const finish = result => {
+          release?.(); clear(tx.workTimer); tx.updating = false; context.check();
+          if (shown.length && ports.read().revision === before.revision) fail('TARGET_NOT_READY', shown.at(-1).message);
+          for (const target of result.affectedIds) tx.affectedIds.add(target);
+          tx.toasts.push(...shown);
+          renew(tx); return transactionReceipt(id, tx, request, before);
+        };
+        const rejected = error => {
+          release?.(); clear(tx.workTimer); tx.updating = false;
+          if (!(error instanceof StudioProtocolError) && shown.length && ports.read().revision === before.revision) error = new StudioProtocolError('TARGET_NOT_READY', shown.at(-1).message);
+          if (transactions.has(tx.txId)) cancelTransaction(tx);
+          throw error;
+        };
+        try {
+          tx.updating = true; clear(tx.timer);
+          tx.workTimer = (ports.setTimeout ?? setTimeout)(() => cancelTransaction(tx, true, new StudioProtocolError('TIMEOUT', `${tx.entry.id} exceeded its deadline.`)), tx.entry.timeoutMs ?? 30_000);
+          const updated = tx.session.run(() => registry.invoke(tx.entry, prepared.args, context));
+          if (!updated?.then) return finish(updated);
+          const cancelled = new Promise((_, reject) => tx.controller.signal.addEventListener('abort', () => reject(tx.controller.signal.reason), { once: true }));
+          return Promise.race([updated, cancelled]).then(finish, rejected);
+        } catch (error) { return rejected(error); }
+      }
+      if (id === 'run.cancel') cancelTransaction(tx);
+      if (id === 'run.commit') {
+        transactions.delete(tx.txId); clear(tx.timer);
+        try { tx.historyEntryId = tx.session.commit().historyEntryId; }
+        catch (error) { tx.session.cancel({ restore: false }); throw error; }
+      }
+    }
+    return transactionReceipt(id, tx, request, id === 'run.commit' ? tx.before : before);
+  }
+  function transactionReceipt(id, tx, request, before) {
+    const after = ports.read();
+    return validateReceipt({ ok: true, status: 'completed', kind: 'transaction', commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+      action: id, txId: tx.txId, authored: Boolean(tx.historyEntryId), revision: { before: before.revision, after: after.revision },
+      affectedIds: [...tx.affectedIds], delta: [], checks: { coverage: 'wire-transaction' }, warnings: toastWarnings(tx.toasts),
+      undo: tx.historyEntryId ? { historyEntryId: tx.historyEntryId, entries: 1, canUndoDirect: true } : null });
+  }
+  function refusal(request, before, error, mutated) {
+    const changed = mutated ?? (ports.read().revision !== before.revision);
+    return validateReceipt({ ok: false, commandId: request.commandId, host: before.host,
+      code: error.code ?? 'INVALID_ARGUMENT', phase: changed ? 'commit' : 'admission', affectedIds: [], expectedTargets: [], currentTargets: [],
+      mutated: changed, preserved: { authoredState: changed ? 'changed' : 'unchanged' }, recovery: { action: 'inspect', retryAllowed: false },
+      message: [...String(error.message || error)].slice(0, 500).join('') });
+  }
+  function receipt(entry, request, before, result, historyEntryId, toasts = []) {
+    const after = ports.read(), changed = after.revision !== before.revision;
+    if (entry.kind === 'mutation' && changed && !historyEntryId) fail('UNCERTAIN_APPLY', `${entry.id} changed the scene without one undoable entry.`);
+    const completed = entry.kind === 'job' || entry.kind === 'document' || (entry.kind === 'mutation' && changed && after.revision > before.revision + 1);
+    const ids = completed || changed ? result.affectedIds : entry.kind === 'transient' ? [before.host.sceneId] : [];
+    return validateReceipt({ ok: true, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+      action: entry.id, summary: result.summary, status: completed ? 'completed' : entry.kind === 'transient' ? 'transient' : changed ? 'applied' : 'noop',
+      authored: changed, ...(completed ? { kind: entry.kind, ...(result.output === undefined ? {} : { output: result.output }), ...(same(before.host, after.host) ? {} : { nextHost: after.host }) } : entry.kind === 'transient' ? { view: { before: before.viewRevision ?? 0, after: after.viewRevision ?? 0 } } : { mutated: changed }),
+      revision: { before: before.revision, after: after.revision }, affectedIds: ids,
+      delta: ids.slice(0, 8).map(id => ({ id, after: ports.readback?.(id, after) ?? { removed: true } })),
+      checks: { coverage: `studio-action:${entry.id}` }, warnings: toastWarnings(toasts),
+      undo: historyEntryId ? { historyEntryId, entries: 1, canUndoDirect: true } : null, ...(ids.length > 8 ? { detailCursor: request.commandId } : {}) });
+  }
+  function executeRun(id, args = {}, options = {}) {
+    const request = { origin: 'ui', commandId: crypto.randomUUID(), ...options };
+    if (request.origin === 'ui' && (id === 'edit.undo' || id === 'edit.redo')) ports.finishHistoryGesture?.();
+    const before = ports.read(), journal = ports.journal();
+    let begun = false, releaseToasts, timer, foregroundTimer, job, applied = false, committedHistoryId;
+    const controller = new AbortController();
+    const clearTimer = () => {
+      if (timer !== undefined) clear(timer);
+      if (foregroundTimer !== undefined) clear(foregroundTimer);
+    };
+    const toasts = [];
+    const toastRefusal = () => toasts.length && ports.read().revision === before.revision ? new StudioProtocolError('TARGET_NOT_READY', toasts.at(-1).message) : null;
+    const remember = value => {
+      if (job?.background) {
+        const commandId = job.completionCommandId ??= crypto.randomUUID();
+        journal.begin(commandId);
+        value = validateReceipt({ ...value, commandId, jobId: job.id });
+      }
+      const recorded = journal.record(value);
+      if (recorded.undo?.canUndoDirect && !id.startsWith('edit.')) historyReceipts.set(recorded.undo.historyEntryId, recorded);
+      for (const [key, receipt] of historyReceipts) if (ports.isRetained?.(receipt) === false) historyReceipts.delete(key);
+      ports.remember?.(recorded); return recorded;
+    };
+    const rejected = error => {
+      clearTimer();
+      releaseToasts?.(); releaseToasts = null;
+      if (!(error instanceof StudioProtocolError)) error = toastRefusal() ?? error;
+      if (request.origin === 'ui' && error.uiMessage) ports.showRefusal?.(error.uiMessage);
+      const value = refusal(request, before, error, job ? applied : undefined);
+      const recorded = begun ? remember(value) : value;
+      if (job && !job.completion) { job.outcome = recorded; job.completion = Promise.resolve(recorded); emit({ type: 'job.completed', jobId: job.id, receipt: recorded }); }
+      return recorded;
+    };
+    try {
+      if (request.origin !== 'ui' && !same(validateStudioIdentity(request.host), before.host)) fail('STALE_SCENE', 'The live document changed.');
+      const signature = JSON.stringify({ id, args, ...request });
+      if (!journal.begin(request.commandId, signature)) return journal.get(request.commandId) ?? pending.get(request.commandId) ?? refusal(request, before, new StudioProtocolError('UNCERTAIN_APPLY', 'Command is still executing.'));
+      begun = true;
+      const prepared = controls[id] ? { args: validateStudioSchema(controls[id], args) } : registry.prepare(id, args);
+      const { entry, args: validated } = prepared;
+      if (request.origin !== 'ui') {
+        // Job controls observe/cancel an admitted identity; completion itself
+        // can advance the revision while their wire request is in transit.
+        // Document identity and the job's own publication fence still apply.
+        if (!['job.await', 'job.cancel'].includes(id) && request.expectedRevision !== before.revision) fail('STALE_SCENE', 'Authored state changed; obtain fresh intent.');
+        if (before.busy && !transactions.has(validated.txId) && !id.startsWith('job.')) fail('TARGET_BUSY', 'Finish the current editor gesture first.');
+      }
+      if (controls[id]) return mapResult(control(id, validated, request, before), remember, rejected);
+      if (transactions.size) fail('TARGET_BUSY', 'Finish or cancel the open command transaction first.');
+      exposure(entry, validated, request);
+      releaseToasts = ports.captureToasts?.(toast => toasts.push(typeof toast === 'string' ? { message: toast } : toast));
+      const domain = entry.domain ?? entry.undoDomain;
+      const targetId = entry.target?.(validated, before) ?? validated.characterId ?? validated.shotId ?? validated.objectId;
+      let token = targetId ? ports.readTarget?.(targetId) : null;
+      let domainRevision = domain ? before.domainRevisions?.[domain] : null;
+      const rebase = () => {
+        const current = ports.read();
+        token = targetId ? ports.readTarget?.(targetId) : null;
+        domainRevision = domain ? current.domainRevisions?.[domain] : null;
+      };
+      const nestedIds = new Set();
+      const context = { origin: request.origin, signal: controller.signal,
+        check() {
+          controller.signal.throwIfAborted();
+          const current = ports.read();
+          if (!same(current.host, before.host) || (domain && current.domainRevisions?.[domain] !== domainRevision) || (targetId && ports.readTarget?.(targetId) !== token)) fail('STALE_TARGET', 'The target or its authored domain changed while the job was running.');
+        },
+        commit(apply) {
+          context.check();
+          if (!domain) fail('INVALID_ARGUMENT', 'A committing job must declare its domain.');
+          const recorded = ports.recordAction(domain, apply, targetId ?? null);
+          if (recorded?.then) fail('INVALID_ARGUMENT', 'Job publication must be synchronous; prepare before commit.');
+          committedHistoryId = recorded.historyEntryId; applied ||= Boolean(committedHistoryId);
+          if (job) rebase();
+          return recorded.result;
+        },
+        run(nestedId, nestedArgs = {}) {
+          if (job) context.check(); else controller.signal.throwIfAborted();
+          const nested = registry.prepare(nestedId, nestedArgs); exposure(nested.entry, nested.args, request);
+          const invoke = () => registry.invoke(nested.entry, nested.args, context);
+          const value = nested.entry.kind === 'mutation' ? ports.recordAction(nested.entry.undoDomain, invoke, nested.args.characterId ?? null, true) : { result: invoke() };
+          // Only the synchronous owned step may advance the fence. Never absorb
+          // an external edit while an asynchronous nested step is suspended;
+          // its later publication must itself use context.run/commit.
+          if (job) rebase();
+          return mapResult(value, recorded => mapResult(recorded.result, result => {
+            if (job) { context.check(); rebase(); applied ||= Boolean(recorded.historyEntryId); }
+            for (const target of result.affectedIds) nestedIds.add(target);
+            return result;
+          }));
+        },
+      };
+      if (entry.kind === 'job') { job = { id: crypto.randomUUID(), host: before.host, controller, background: false }; jobs.set(job.id, job); }
+      timer = (ports.setTimeout ?? setTimeout)(() => {
+        const error = new StudioProtocolError('TIMEOUT', `${entry.id} exceeded its deadline.`);
+        controller.abort(error);
+      }, job && entry.background === true ? 300_000 : entry.timeoutMs ?? 30_000);
+      // The race observes expiry even if a backend ignores cancellation.
+      const invoke = () => {
+        const value = registry.invoke(entry, validated, context);
+        if (!value?.then) return value;
+        const deadline = new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true }));
+        return Promise.race([value, deadline]);
+      };
+      const value = entry.kind === 'mutation' ? ports.recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
+      const finish = ({ result, historyEntryId }) => mapResult(result, output => {
+        clearTimer();
+        releaseToasts?.(); releaseToasts = null;
+        const refused = toastRefusal();
+        if (refused) throw refused;
+        return remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts));
+      });
+      const finished = value?.then ? value.then(finish) : finish(value);
+      const answer = finished?.then ? finished.catch(rejected) : finished;
+      if (job) {
+        job.completion = Promise.resolve(answer).then(outcome => { job.outcome = outcome; emit({ type: 'job.completed', jobId: job.id, receipt: outcome }); return outcome; });
+        const detach = () => {
+          job.background = true;
+          const current = ports.read();
+          return journal.record(validateReceipt({ ok: true, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+            action: entry.id, status: 'started', kind: 'job', jobId: job.id, authored: false, revision: { before: current.revision, after: current.revision },
+            affectedIds: [], delta: [], checks: { coverage: `studio-action:${entry.id}` }, warnings: [], undo: null }));
+        };
+        if (answer?.then && request.wait === false) return detach();
+        if (answer?.then && entry.background === true) {
+          const foreground = Promise.race([job.completion, new Promise(resolve => {
+            foregroundTimer = (ports.setTimeout ?? setTimeout)(() => resolve(detach()), entry.timeoutMs ?? 30_000);
+          })]).finally(() => pending.delete(request.commandId));
+          pending.set(request.commandId, foreground);
+          return foreground;
+        }
+      }
+      if (answer?.then) { const settled = (job?.completion ?? answer).finally(() => pending.delete(request.commandId)); pending.set(request.commandId, settled); return settled; }
+      return answer;
+    } catch (error) { return rejected(error); }
+  }
+  function run(...args) {
+    activeRunDepth++;
+    try {
+      const value = executeRun(...args);
+      if (value?.then) return value.finally(() => { activeRunDepth--; });
+      activeRunDepth--;
+      return value;
+    } catch (error) {
+      activeRunDepth--;
+      throw error;
+    }
+  }
+  return { run,
+    // Trusted UI adapter only: wire callers can consume, never mint a token.
+    confirm(id, args = {}) { const prepared = registry.prepare(id, args), token = crypto.randomUUID(); confirmations.set(token, { id, args: prepared.args, host: ports.read().host, expires: (ports.now ?? Date.now)() + 300_000 }); return token; },
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    dispose() { for (const tx of transactions.values()) cancelTransaction(tx); for (const job of jobs.values()) if (!job.outcome) job.controller.abort(new StudioProtocolError('CANCELLED', 'Studio closed.')); listeners.clear(); } };
+}

package/src/commands/ai.js

@@ -0,0 +1,31 @@
+// AI commands: the Send-to-AI package, the editor's own generate(), which
+// reads the mode and image model from the render. A changed choice is set
+// first and generate() runs once React has rendered it; a commit already under
+// way can predate it, so the wait repeats until the render shows the choice.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { fail } from "./shared.js";
+
+export const declarations = Object.freeze(["ai.prepareShot"].map(studioActionDeclaration));
+
+export function register(registry, ports) {
+	registry.register({ ...studioActionDeclaration("ai.prepareShot"), available: () => true,
+		run: async ({ mode, model }, context) => {
+			const current = ports.state().aiShot, wanted = { mode: mode ?? current.mode, imageModel: model ?? current.imageModel };
+			if (model && wanted.mode !== "image") fail("INVALID_ARGUMENT", `model picks an image model, but this would be a ${wanted.mode} prompt; omit model or pass mode "image".`);
+			const rendered = () => { const { aiShot } = ports.state(); return aiShot.mode === wanted.mode && aiShot.imageModel === wanted.imageModel; };
+			if (!rendered()) {
+				ports.setAiShotMode(wanted.mode);
+				ports.setAiImageModel(wanted.imageModel);
+				for (let commits = 0; !rendered(); commits++) {
+					if (commits === 3) fail("TARGET_NOT_READY", "The Studio did not render the new mode and model; run the action again.");
+					await ports.afterRender();
+				}
+			}
+			context?.check();
+			const result = ports.generate();
+			const shot = result.shot && { id: result.shot.id, name: result.shot.name, range: { startFrame: result.shot.startFrame, endFrameExclusive: result.shot.endFrame + 1 } };
+			const referenceFrames = (result.frame ? 1 : 0) + (result.frameB ? 1 : 0);
+			return { affectedIds: [], output: { prompt: result.prompt, mode: result.mode, modelLabel: result.modelLabel ?? null, shot, aspectRatio: result.aspectRatio, cameraMode: result.camera?.mode ?? null, referenceFrames },
+				summary: `Prepared the ${result.mode} prompt${result.modelLabel ? ` for ${result.modelLabel}` : ""} for ${shot ? `${shot.name} [${shot.range.startFrame}, ${shot.range.endFrameExclusive})` : "the current camera"}; the Studio's result panel shows it with ${referenceFrames} reference frame${referenceFrames === 1 ? "" : "s"} for the user to copy and download.` };
+		} });
+}

package/src/commands/cast.js

@@ -0,0 +1,140 @@
+// Cast commands: a named character's root waypoints and IK key layer. They
+// name their character explicitly, so they run the same way whichever
+// character is active and whatever mode the editor is in.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { characterOf, fail, changedIds } from "./shared.js";
+import { elementSetSchema, registerElementSet } from './elements.js';
+import './elements/character.js';
+import { createCharacterEntry } from '../scenes.js';
+import { DEFAULT_POSE } from '../poses.js';
+import { createStableItemId, updateStableItem, removeStableItem } from '../stable-items.js';
+import { movePromptClipFrames } from '../ardy/prompt-clips.js';
+import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
+
+const id = StudioSchemas.TargetGuard.properties.targetId;
+const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const record = { type: 'object', properties: {}, additionalProperties: true };
+const mutation = (id, label, schema, exposure = 'open') => ({ id, label, description: label, kind: 'mutation', undoDomain: 'cast', input: schema, exposure });
+const blocks = elementSetSchema('character').properties.set.properties.layer.properties.promptClips;
+const semantic = [
+	mutation('character.set', 'Set character fields', elementSetSchema('character')),
+	mutation('character.add', 'Add character', input({ character: record })),
+	mutation('character.remove', 'Remove character', input({ characterId: id })),
+	mutation('character.update', 'Update character', input({ characterId: id, patch: record })),
+	mutation('character.setPose', 'Set character pose', input({ characterId: id, pose: { oneOf: [id, record, { type: 'null' }] }, clearMotion: { type: 'boolean' } }, ['characterId', 'pose'])),
+	mutation('character.setPromptBlocks', 'Set prompt blocks', input({ characterId: id, blocks })),
+	mutation('characters.arrange', 'Arrange characters', STUDIO_TOOL_SCHEMAS.arrange_characters),
+	mutation('cast.replace', 'Replace cast', input({ characters: { type: 'array', items: record, minItems: 1 } }), 'ui-only'),
+	mutation('cast.setCustomPoses', 'Set pose library', input({ poses: { type: 'array', items: record } }), 'ui-only'),
+	mutation('cast.savePose', 'Save pose', input({ pose: record, characterId: id, clearMotion: { type: 'boolean' } }, ['pose']), 'ui-only'),
+	mutation('cast.removePose', 'Remove saved pose', input({ id }), 'ui-only'),
+	mutation('cast.showExtras', 'Show extra subjects', input({ show: { type: 'boolean' } }), 'ui-only'),
+	mutation('cast.setLayer', 'Set character layer', input({ characterId: id, layer: record }), 'ui-only'),
+	...['add', 'move', 'resize', 'change', 'remove'].map(verb => mutation(`character.${verb}PromptBlock`, `${verb} prompt block`,
+		input({ characterId: id, id, frame: { type: 'number' }, edge: { type: 'string', enum: ['start', 'end'] }, text: { type: 'string', maxLength: 2000 } },
+			verb === 'add' ? ['characterId', 'frame'] : verb === 'remove' ? ['characterId', 'id'] : verb === 'change' ? ['characterId', 'id', 'text'] : verb === 'resize' ? ['characterId', 'id', 'edge', 'frame'] : ['characterId', 'id', 'frame']), 'ui-only')),
+];
+export const declarations = Object.freeze([...semantic, ...["character.addWaypoint", "character.moveWaypoint", "character.removeWaypoint", "character.clearWaypoints"].map(studioActionDeclaration)]);
+
+export function register(registry, ports) {
+	const owner = () => ports.storeDomain('cast');
+	const mounted = () => Boolean(ports.storeDomain?.('cast')) || 'The cast document owner is not mounted.';
+	const character = characterId => owner().read().find(row => row.id === characterId) ?? fail('STALE_TARGET', `Character ${characterId} is not in this scene.`);
+	const pose = value => typeof value === 'string' ? owner().poses().find(row => row.id === value) ?? fail('STALE_TARGET', `Pose ${value} is not in the library.`) : value;
+	const patch = (characterId, update) => { character(characterId); owner().write(rows => rows.map(row => row.id === characterId ? { ...row, ...update } : row)); };
+	function promptEdit(command, args) {
+		const before = character(args.characterId), clips = before.layer.promptClips;
+		let next;
+		if (command === 'character.addPromptBlock') {
+			const snapped = Math.max(0, Math.round(args.frame / 48) * 48);
+			const blocked = clips.some(clip => snapped < clip.endFrame && snapped + 48 > clip.startFrame);
+			const startFrame = blocked ? Math.max(snapped, ...clips.map(clip => clip.endFrame)) : snapped;
+			next = [...clips, { id: createStableItemId('prompt-clip'), startFrame, endFrame: startFrame + 48, text: '' }];
+		} else if (command === 'character.removePromptBlock') next = removeStableItem(clips, args.id, 'promptClips');
+		else if (command === 'character.changePromptBlock') next = updateStableItem(clips, args.id, clip => ({ ...clip, text: args.text }), 'promptClips');
+		else if (command === 'character.movePromptBlock') next = movePromptClipFrames(clips, args.id, args.frame, 48);
+		else {
+			next = updateStableItem(clips, args.id, clip => {
+				const snapped = Math.max(0, Math.round(args.frame / 48) * 48);
+				return args.edge === 'start' ? { ...clip, startFrame: Math.min(Math.max(snapped, clip.endFrame - 120), clip.endFrame - 48) }
+					: { ...clip, endFrame: Math.min(Math.max(clip.startFrame + 48, snapped), clip.startFrame + 120) };
+			}, 'promptClips');
+			const resized = next.find(clip => clip.id === args.id);
+			if (next.some(clip => clip.id !== args.id && resized.startFrame < clip.endFrame && resized.endFrame > clip.startFrame)) return;
+		}
+		patch(args.characterId, { layer: { ...before.layer, promptClips: next } });
+		owner().extendTimeline(next.reduce((end, clip) => Math.max(end, clip.endFrame), 24));
+	}
+	const methods = {
+		'character.add': ({ character: value }) => {
+			const row = createCharacterEntry({ ...value, id: value.id ?? createStableItemId('character') }, owner().read().length);
+			if (owner().read().some(entry => entry.id === row.id)) fail('INVALID_ARGUMENT', 'Character id already exists.');
+			owner().write(rows => [...rows, row]);
+		},
+		'character.remove': ({ characterId }) => { character(characterId); if (owner().read().length <= 1) fail('INVALID_ARGUMENT', 'Cannot remove the final character.'); owner().write(rows => rows.filter(row => row.id !== characterId)); },
+		'character.update': ({ characterId, patch: value }) => patch(characterId, value),
+		'character.setPose': ({ characterId, pose: value, clearMotion }) => { character(characterId); owner().applyPose(characterId, pose(value), clearMotion); },
+		'character.setPromptBlocks': ({ characterId, blocks }) => {
+			const entry = character(characterId); patch(characterId, { layer: { ...entry.layer, promptClips: blocks } });
+		},
+		'cast.replace': ({ characters }) => owner().write(characters),
+		'cast.setCustomPoses': ({ poses }) => owner().writeState(before => ({ ...before, customPoses: poses })),
+		'cast.savePose': ({ pose, characterId, clearMotion }) => {
+			if (characterId) character(characterId);
+			owner().writeState(before => ({ ...before, customPoses: [...before.customPoses.filter(entry => entry.id !== pose.id), pose] }));
+			if (characterId) owner().applyPose(characterId, pose, clearMotion);
+		},
+		'cast.removePose': ({ id }) => owner().writeState(before => ({
+			characters: before.characters.map(entry => entry.pose?.id === id ? { ...entry, pose: DEFAULT_POSE } : entry),
+			customPoses: before.customPoses.filter(entry => entry.id !== id),
+		})),
+
+		'cast.showExtras': ({ show }) => owner().showExtras(show),
+		'cast.setLayer': ({ characterId, layer }) => patch(characterId, { layer: { ...character(characterId).layer, ...layer } }),
+	};
+	registerElementSet({ register(entry) {
+		registry.register({ ...entry, available: mounted, run(args) {
+			// A pose id selects a complete library entry, not a deep bone patch.
+			const ops = args.ops ?? [args];
+			const poses = ops.filter(op => Object.hasOwn(op.set, 'pose')).map(op => ({ id: op.id, value: pose(op.set.pose) }));
+			const fields = ops.map(({ id, set: { pose: _pose, ...set } }) => ({ id, set }));
+			const result = entry.run(args.ops ? { ops: fields } : fields[0]);
+			for (const selected of poses) owner().applyPose(selected.id, selected.value, false);
+			return result;
+		} });
+	} }, ports, semantic[0]);
+	for (const declaration of semantic.slice(1)) registry.register({ ...declaration, available: mounted, run(args) {
+		if (declaration.id === 'characters.arrange') { const plan = owner().arrange(args); return { affectedIds: plan.affectedIds, summary: 'Arranged characters.' }; }
+		const before = owner().read();
+		if (declaration.id.endsWith('PromptBlock')) promptEdit(declaration.id, args); else methods[declaration.id](args);
+		const changed = changedIds(before, owner().read());
+		return { affectedIds: changed.length ? changed : [args.characterId ?? ports.state().activeSceneId], summary: declaration.label };
+	} });
+	if (ports.storeDomain?.('cast')) registry.registerToolAlias('arrange_characters', 'characters.arrange');
+	const castAction = (id, run) => registry.register({ ...studioActionDeclaration(id),
+		available: state => state.characters.length > 0 || "There are no characters in this scene; add one with arrange_characters.",
+		run: args => {
+			const character = characterOf(ports, args.characterId);
+			return { affectedIds: [character.id], summary: run(args, character.subject || character.id) };
+		} });
+	const pin = waypoint => `frame ${waypoint.frame} (x ${waypoint.x}, z ${waypoint.z})`;
+	const warned = warnings => warnings.length ? `; warning: ${warnings[0]}` : "";
+	castAction("character.addWaypoint", ({ characterId, position, frame }, name) => {
+		const { waypoint, index, warnings } = ports.addCharacterWaypoint(characterId, position, frame ?? null);
+		ports.setWaypointMode(true);
+		return `Added ${name}'s root waypoint ${index + 1} at ${pin(waypoint)}${warned(warnings)}.`;
+	});
+	castAction("character.moveWaypoint", ({ characterId, frame, position }, name) => {
+		const { waypoint, warnings } = ports.moveCharacterWaypoint(characterId, frame, position);
+		ports.setWaypointMode(true);
+		return `Moved ${name}'s root waypoint to ${pin(waypoint)}${warned(warnings)}.`;
+	});
+	castAction("character.removeWaypoint", ({ characterId, frame }, name) => {
+		ports.removeCharacterWaypoint(characterId, frame);
+		return `Removed ${name}'s root waypoint at frame ${frame}.`;
+	});
+	castAction("character.clearWaypoints", ({ characterId }, name) => {
+		const count = ports.clearCharacterWaypoints(characterId);
+		return count ? `Cleared ${name}'s root path (${count} waypoint${count === 1 ? "" : "s"}).` : `${name} has no root waypoints; nothing changed.`;
+	});
+}

package/src/commands/elements/character.js

@@ -0,0 +1,13 @@
+import { createCharacterEntry } from '../../scenes.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('character.')).map(row => {
+  const { min, max, gizmo, ...element } = row;
+  if (row.path === 'character.position') return { ...element, documentPath: { x: 'x', y: 'y', z: 'z' } };
+  if (row.path === 'character.promptBlocks') return { ...element, documentPath: 'layer.promptClips' };
+  if (row.path === 'character.pose') return { ...element, readback: item => ({ text: item?.pose?.id ?? null }) };
+  return element;
+});
+registerElementKind('character', { collection: true, documentKey: 'characters', elements, normalize: createCharacterEntry });
+registerElementKind('poseLibrary', { collection: true, documentKey: 'customPoses', elements: [], normalize: value => value });

package/src/commands/elements/motion.js

@@ -0,0 +1,14 @@
+import { registerElementKind } from '../elements.js';
+import { wrapAngle } from '../../scene-objects.js';
+
+const elements = [
+  ...['anchorX', 'anchorZ', 'rotationDeg'].map(field => ({ path: `motion.take.${field}`, type: 'number' })),
+  { path: 'motion.take.prompt', type: 'string' },
+  { path: 'motion.ikKeys', type: 'array', readOnly: true },
+  { path: 'motion.takeRecipe', type: 'object', readOnly: true },
+  { path: 'motion.takeVersions', type: 'array', readOnly: true },
+];
+registerElementKind('motion', { collection: true, elements, normalize: row => ({ ...row, take: row.take && { ...row.take,
+  anchorX: Math.max(-240, Math.min(240, row.take.anchorX ?? 0)), anchorZ: Math.max(-240, Math.min(240, row.take.anchorZ ?? 0)),
+  rotationDeg: wrapAngle(row.take.rotationDeg ?? 0),
+} }) });

package/src/commands/elements/object.js

@@ -0,0 +1,22 @@
+import { normalizeSceneObject } from '../../scene-objects.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const components = {
+  position: { x: 'x', y: 'y', z: 'z' },
+  rotation: { x: 'rotX', y: 'rot', z: 'rotZ' },
+  scale: { x: 'scaleX', y: 'scaleY', z: 'scaleZ' },
+};
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('object.')).map(row => {
+  // Wire validation checks finite numbers; persistence owns the transform clamps.
+  const { min, max, ...element } = row;
+  const field = row.path.slice(7);
+  return { ...element, ...(components[field] ? { documentPath: components[field] } : {}),
+    ...(field === 'remove' ? { readback: item => ({ flag: item === undefined }) } : {}) };
+});
+export function normalizeObjectSet(record) {
+  const item = normalizeSceneObject(record);
+  // The owning collection consumes this lifecycle intent before persistence.
+  return record.remove === true ? { ...item, remove: true } : item;
+}
+registerElementKind('object', { collection: true, documentKey: 'objects', elements, normalize: normalizeObjectSet });

package/src/commands/elements/scene.js

@@ -0,0 +1,16 @@
+import { registerElementKind } from '../elements.js';
+
+// Array position is the authoritative order. The owner refreshes this persisted
+// field after every move, so generic set/read and the project file agree.
+registerElementKind('scene', {
+  collection: true, documentKey: 'scenes',
+  elements: [
+    { path: 'scene.name', type: 'string' },
+    { path: 'scene.order', type: 'number' },
+  ],
+  normalize: scene => ({ ...scene, name: scene.name.trim(), order: Math.max(0, Math.round(scene.order)) }),
+});
+registerElementKind('project', {
+  elements: [{ path: 'project.name', type: 'string' }],
+  normalize: project => project,
+});

package/src/commands/elements/shot.js

@@ -0,0 +1,9 @@
+import { createShotAuthoringDocument } from '../../shot-authoring.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+export function normalizeShot(record) {
+  return createShotAuthoringDocument({ shots: [record], frameCount: Math.max(24, record.endFrame + 1) }).shots[0];
+}
+registerElementKind('shot', { collection: true, documentKey: 'shots',
+  elements: STUDIO_ELEMENTS.filter(row => row.path.startsWith('shot.')), normalize: normalizeShot });

package/src/commands/elements/stage.js

@@ -0,0 +1,11 @@
+import { createSceneStage } from '../../scenes.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('stage.'));
+export const STAGE_FIELDS = [...new Set(elements.map(element => (element.documentPath ?? element.path.slice(6)).split('.')[0]))];
+export function normalizeStage(source) {
+  const normalized = createSceneStage(source);
+  return Object.fromEntries(STAGE_FIELDS.map(key => [key, normalized[key]]));
+}
+registerElementKind('stage', { elements, normalize: normalizeStage });