@hyperframes/studio 0.8.24 → 0.8.25

package/src/webmcp/writeCoordinator.ts

@@ -0,0 +1,473 @@
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { parseElementHandle, resolveLiveHandleSelection } from "./handles";
+import { toolFailure, type ToolFailure, type ToolFailureKind } from "./toolResult";
+
+export type StudioWriteOperation =
+  | "set-text"
+  | "set-style"
+  | "transform"
+  | "add-animation"
+  | "update-animation"
+  | "add-keyframe"
+  | "delete-animation";
+
+export const WRITE_RECEIPT_DESCRIPTION =
+  "Read `stage` as the proof level: refused, dispatched, saved, verified, or failed. " +
+  "`changed` is separate, and evidence explains what was actually proven.";
+
+export interface StudioWriteTarget {
+  handle: string;
+  sourceFile: string;
+}
+
+export type StudioWriteEvidence =
+  | { kind: "dispatch"; followUp: "studio_inspect" }
+  | { kind: "content-version"; sourceFile: string; version: string }
+  | {
+      kind: "readback";
+      sourceFile: string;
+      version: string;
+      before: unknown;
+      after: unknown;
+    };
+
+export type StudioWriteAdapterSuccess<T extends object> = T & {
+  ok: true;
+  stage: "dispatched" | "saved" | "verified";
+  changed: boolean;
+  evidence: StudioWriteEvidence;
+};
+
+type StudioWriteAdapterResult<T extends object> = StudioWriteAdapterSuccess<T> | ToolFailure;
+
+export type StudioWriteResult<T extends object> =
+  | (T & {
+      ok: true;
+      stage: "dispatched" | "saved" | "verified";
+      target: StudioWriteTarget;
+      operation: StudioWriteOperation;
+      changed: boolean;
+      evidence: StudioWriteEvidence;
+      cancelRequested?: true;
+    })
+  | (ToolFailure & {
+      stage: "refused" | "failed";
+      target?: StudioWriteTarget;
+      operation: StudioWriteOperation;
+      cancelRequested?: true;
+    });
+
+export interface TargetedWriteDeps {
+  getPreviewDocument: () => Document | null;
+  getProjectId: () => string | null;
+  getWriteBlockedReason: () => string | null;
+  buildSelection: (element: HTMLElement) => Promise<DomEditSelection | null>;
+  applySelection: (selection: DomEditSelection) => void;
+}
+
+export type StudioEditLifecycleState =
+  | { phase: "idle" }
+  | {
+      callId: string;
+      projectId: string;
+      target: StudioWriteTarget;
+      operation: StudioWriteOperation;
+      targetChanged: boolean;
+      phase: "dispatching" | "dispatched" | "saved" | "verified" | "failed";
+      receipt?: StudioWriteResult<object>;
+    };
+
+type LifecycleListener = () => void;
+
+class StudioEditLifecycle {
+  private state: StudioEditLifecycleState = { phase: "idle" };
+  private listeners = new Set<LifecycleListener>();
+  private lastTerminalTarget: { projectId: string; handle: string } | null = null;
+  private activeProjectId: string | null = null;
+  private callSequence = 0;
+
+  getSnapshot = (): StudioEditLifecycleState => this.state;
+
+  subscribe = (listener: LifecycleListener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  begin(projectId: string, target: StudioWriteTarget, operation: StudioWriteOperation): string {
+    this.activateProject(projectId);
+    const callId = `studio-edit-${++this.callSequence}`;
+    const previous = this.lastTerminalTarget;
+    const targetChanged =
+      previous === null || previous.projectId !== projectId || previous.handle !== target.handle;
+    this.publish({
+      callId,
+      projectId,
+      target,
+      operation,
+      targetChanged,
+      phase: "dispatching",
+    });
+    return callId;
+  }
+
+  finish(callId: string, receipt: StudioWriteResult<object>): void {
+    if (this.state.phase === "idle" || this.state.callId !== callId) return;
+    this.lastTerminalTarget = {
+      projectId: this.state.projectId,
+      handle: this.state.target.handle,
+    };
+    this.publish({
+      ...this.state,
+      phase: receipt.ok ? receipt.stage : "failed",
+      receipt,
+    });
+  }
+
+  /** Clear only the invocation that still owns the visual lifecycle. */
+  dismiss(callId: string): void {
+    if (this.state.phase === "idle" || this.state.callId !== callId) return;
+    this.publish({ phase: "idle" });
+  }
+
+  reset(): void {
+    this.activeProjectId = null;
+    this.lastTerminalTarget = null;
+    this.publish({ phase: "idle" });
+  }
+
+  activateProject(projectId: string | null): void {
+    if (this.activeProjectId === projectId) return;
+    this.activeProjectId = projectId;
+    this.lastTerminalTarget = null;
+    this.publish({ phase: "idle" });
+  }
+
+  private publish(state: StudioEditLifecycleState): void {
+    this.state = state;
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/** One state owner shared by the coordinator and Studio's future overlay. */
+export const studioEditLifecycle = new StudioEditLifecycle();
+
+interface TargetedWriteInput<T extends object> {
+  handle: unknown;
+  operation: StudioWriteOperation;
+  signal: AbortSignal;
+  preflight?: (selection: DomEditSelection) => ToolFailure | null | Promise<ToolFailure | null>;
+  write: (selection: DomEditSelection) => Promise<StudioWriteAdapterResult<T>>;
+}
+
+type ResolvedWriteSelection =
+  | { ok: true; selection: DomEditSelection }
+  | { ok: false; failure: ToolFailure };
+
+async function resolveWriteSelection(
+  deps: TargetedWriteDeps,
+  handle: string,
+): Promise<ResolvedWriteSelection> {
+  const resolved = await resolveLiveHandleSelection(
+    deps.getPreviewDocument,
+    handle,
+    deps.buildSelection,
+  );
+  if (resolved.status === "preview-unavailable") {
+    return { ok: false, failure: toolFailure("blocked", "the composition preview is not ready") };
+  }
+  if (resolved.status === "not-found") {
+    return {
+      ok: false,
+      failure: toolFailure("invalid", "the target handle is stale", "Call studio_look and retry."),
+    };
+  }
+  if (resolved.status === "unsupported") {
+    return {
+      ok: false,
+      failure: toolFailure(
+        "blocked",
+        "the target resolved to an element Studio cannot edit",
+        "Try a parent or child element from studio_look.",
+      ),
+    };
+  }
+  if (resolved.status === "changed") {
+    return {
+      ok: false,
+      failure: toolFailure(
+        "invalid",
+        "the target changed while it was resolving",
+        "Call studio_look again.",
+      ),
+    };
+  }
+  return { ok: true, selection: resolved.selection };
+}
+
+function refusedResult<T extends object>(
+  operation: StudioWriteOperation,
+  failure: ToolFailure,
+  cancelRequested = false,
+): StudioWriteResult<T> {
+  return {
+    ...failure,
+    stage: "refused",
+    operation,
+    ...(cancelRequested ? { cancelRequested: true as const } : {}),
+  };
+}
+
+function completedWrite<T extends object>(
+  adapter: StudioWriteAdapterResult<T>,
+  target: StudioWriteTarget,
+  operation: StudioWriteOperation,
+  cancelRequested: boolean,
+): StudioWriteResult<T> {
+  const cancellation = cancelRequested ? { cancelRequested: true as const } : {};
+  return adapter.ok
+    ? { ...adapter, target, operation, ...cancellation }
+    : { ...asFailed(adapter), stage: "failed", target, operation, ...cancellation };
+}
+
+function classifyThrownError(error: unknown): { kind: ToolFailureKind; reason: string } {
+  return {
+    kind: error instanceof TypeError || error instanceof ReferenceError ? "internal" : "failed",
+    reason: error instanceof Error ? error.message : String(error),
+  };
+}
+
+type ValidatedWriteAddress<T extends object> =
+  | { ok: true; handle: string; projectId: string }
+  | { ok: false; result: StudioWriteResult<T> };
+
+function validateProjectScopedHandle<T extends object>(
+  handle: string,
+  projectId: string,
+  operation: StudioWriteOperation,
+): StudioWriteResult<T> | null {
+  const parsedHandle = parseElementHandle(handle);
+  if (!parsedHandle || parsedHandle.version !== 2 || !parsedHandle.projectId) {
+    return refusedResult(
+      operation,
+      toolFailure(
+        "invalid",
+        "writes require a current project-scoped handle from studio_look",
+        "Call studio_look again and pass the returned handle unchanged.",
+      ),
+    );
+  }
+  if (parsedHandle.projectId === projectId) return null;
+  return refusedResult(
+    operation,
+    toolFailure(
+      "invalid",
+      "the handle belongs to a different project",
+      "Call studio_look in the active project.",
+    ),
+  );
+}
+
+function validateWriteAddress<T extends object>(
+  deps: TargetedWriteDeps,
+  input: TargetedWriteInput<T>,
+): ValidatedWriteAddress<T> {
+  if (input.signal.aborted) {
+    return {
+      ok: false,
+      result: refusedResult(
+        input.operation,
+        toolFailure("blocked", "the write was cancelled before dispatch"),
+        true,
+      ),
+    };
+  }
+  if (typeof input.handle !== "string" || !input.handle) {
+    return {
+      ok: false,
+      result: refusedResult(
+        input.operation,
+        toolFailure("invalid", "handle must name an element from studio_look"),
+      ),
+    };
+  }
+  const projectId = deps.getProjectId();
+  if (!projectId) {
+    return {
+      ok: false,
+      result: refusedResult(input.operation, toolFailure("blocked", "there is no active project")),
+    };
+  }
+  const handleFailure = validateProjectScopedHandle<T>(input.handle, projectId, input.operation);
+  if (handleFailure) return { ok: false, result: handleFailure };
+  const blocked = deps.getWriteBlockedReason();
+  if (blocked) {
+    return {
+      ok: false,
+      result: refusedResult(
+        input.operation,
+        toolFailure("blocked", blocked, "Resolve it in Studio, then retry."),
+      ),
+    };
+  }
+  return { ok: true, handle: input.handle, projectId };
+}
+
+type PreparedWriteSelection<T extends object> =
+  | { ok: true; selection: DomEditSelection }
+  | { ok: false; result: StudioWriteResult<T> };
+
+async function prepareWriteSelection<T extends object>(
+  deps: TargetedWriteDeps,
+  input: TargetedWriteInput<T>,
+  handle: string,
+): Promise<PreparedWriteSelection<T>> {
+  const resolved = await resolveWriteSelection(deps, handle);
+  if (!resolved.ok) {
+    return { ok: false, result: refusedResult(input.operation, resolved.failure) };
+  }
+  const { selection } = resolved;
+  if (selection.isInsideLockedComposition) {
+    return {
+      ok: false,
+      result: refusedResult(
+        input.operation,
+        toolFailure("blocked", "the target is inside a locked composition"),
+      ),
+    };
+  }
+  const preflight = await input.preflight?.(selection);
+  if (preflight) return { ok: false, result: refusedResult(input.operation, preflight) };
+  if (input.signal.aborted) {
+    return {
+      ok: false,
+      result: refusedResult(
+        input.operation,
+        toolFailure("blocked", "the write was cancelled before dispatch"),
+        true,
+      ),
+    };
+  }
+  return { ok: true, selection };
+}
+
+export async function runTargetedWrite<T extends object>(
+  deps: TargetedWriteDeps,
+  input: TargetedWriteInput<T>,
+): Promise<StudioWriteResult<T>> {
+  const address = validateWriteAddress(deps, input);
+  if (!address.ok) return address.result;
+  let prepared: PreparedWriteSelection<T>;
+  try {
+    prepared = await prepareWriteSelection(deps, input, address.handle);
+  } catch (error) {
+    const { kind, reason } = classifyThrownError(error);
+    if (kind === "internal") console.error(`[hf-webmcp] ${input.operation} preflight threw`, error);
+    return refusedResult(input.operation, toolFailure(kind, reason));
+  }
+  if (!prepared.ok) return prepared.result;
+  if (deps.getProjectId() !== address.projectId) {
+    return refusedResult(
+      input.operation,
+      toolFailure(
+        "blocked",
+        "the active project changed while the target was resolving",
+        "Call studio_look in the active project and retry.",
+      ),
+    );
+  }
+  const { selection } = prepared;
+  const target = { handle: address.handle, sourceFile: selection.sourceFile };
+  deps.applySelection(selection);
+  const callId = studioEditLifecycle.begin(address.projectId, target, input.operation);
+  let adapter: StudioWriteAdapterResult<T>;
+  try {
+    adapter = await input.write(selection);
+  } catch (error) {
+    const { kind, reason } = classifyThrownError(error);
+    if (kind === "internal") console.error(`[hf-webmcp] ${input.operation} threw`, error);
+    const result: StudioWriteResult<T> = {
+      ok: false,
+      kind,
+      reason,
+      stage: "failed",
+      target,
+      operation: input.operation,
+      ...(input.signal.aborted ? { cancelRequested: true as const } : {}),
+    };
+    studioEditLifecycle.finish(callId, result);
+    return result;
+  }
+  const result = completedWrite(adapter, target, input.operation, input.signal.aborted);
+  studioEditLifecycle.finish(callId, result);
+  return result;
+}
+
+function asFailed(failure: ToolFailure): ToolFailure {
+  const kind: ToolFailureKind =
+    failure.kind === "invalid" || failure.kind === "blocked" ? "failed" : failure.kind;
+  return { ...failure, kind };
+}
+
+export function dispatched<T extends object>(
+  value: T,
+  changed: boolean,
+): StudioWriteAdapterSuccess<T> & {
+  stage: "dispatched";
+  evidence: { kind: "dispatch"; followUp: "studio_inspect" };
+} {
+  return {
+    ok: true,
+    ...value,
+    stage: "dispatched",
+    changed,
+    evidence: { kind: "dispatch", followUp: "studio_inspect" },
+  };
+}
+
+export function saved<T extends object>(
+  value: T,
+  persistence: { sourceFile: string; version: string; changed: boolean },
+): StudioWriteAdapterSuccess<T> & {
+  stage: "saved";
+  evidence: { kind: "content-version"; sourceFile: string; version: string };
+} {
+  return {
+    ok: true,
+    ...value,
+    stage: "saved",
+    changed: persistence.changed,
+    evidence: {
+      kind: "content-version",
+      sourceFile: persistence.sourceFile,
+      version: persistence.version,
+    },
+  };
+}
+
+export function verified<T extends object>(
+  value: T,
+  persistence: { sourceFile: string; version: string; changed: boolean },
+  readback: { before: unknown; after: unknown },
+): StudioWriteAdapterSuccess<T> & {
+  stage: "verified";
+  evidence: {
+    kind: "readback";
+    sourceFile: string;
+    version: string;
+    before: unknown;
+    after: unknown;
+  };
+} {
+  return {
+    ok: true,
+    ...value,
+    stage: "verified",
+    changed: persistence.changed,
+    evidence: {
+      kind: "readback",
+      sourceFile: persistence.sourceFile,
+      version: persistence.version,
+      ...readback,
+    },
+  };
+}