@hyperframes/studio 0.8.19 → 0.8.21

package/src/webmcp/tools/frameTools.ts

@@ -0,0 +1,133 @@
+/**
+ * `studio_frame`: the eyes.
+ *
+ * Without this the tool set is a remote control. With it an agent can author a
+ * change, look at the instant it affects, judge it, and adjust. That loop is the
+ * one thing source alone cannot support, because "what does this look like at
+ * 2.4 seconds" is not a question a file can answer.
+ *
+ * Reuses Studio's existing capture endpoint (`utils/frameCapture`) rather than
+ * inventing a second one. The server renders the composition with Puppeteer, so
+ * the frame reflects the file on disk, not the live preview DOM.
+ */
+
+import { buildFrameCaptureUrl } from "../../utils/frameCapture";
+import { toolFailure, toolOk, type ToolResult } from "../toolResult";
+
+export interface FrameToolDeps {
+  getProjectId: () => string | null;
+  getCompositionPath: () => string | null;
+  readPlayhead: () => { currentTime: number; duration: number; isPlaying: boolean };
+  requestSeek: (time: number) => void;
+  /** Confirms the URL renders. Injected so tests need no network. */
+  probeFrame: (url: string) => Promise<{ ok: boolean; status: number }>;
+  wait: (ms: number) => Promise<void>;
+}
+
+export interface StudioFrameResult {
+  /** Fetch this to see the frame. A PNG of the composition at `time`. */
+  url: string;
+  time: number;
+  compositionPath: string;
+  /** How long the tool waited for a pending write to settle before capturing. */
+  settledMs: number;
+}
+
+export interface StudioFrameInput {
+  /** Seconds. Omit to capture wherever the playhead already is. */
+  time?: number;
+  /**
+   * Milliseconds to wait before capturing, so a just-written edit is visible.
+   * See the staleness note in the description.
+   */
+  settleMs?: number;
+}
+
+/**
+ * Long enough to cover the project watcher's 40ms write-stability threshold
+ * plus filesystem latency, short enough not to be felt. This is the mitigation
+ * for a real, previously-fixed bug: the preview signature is invalidated by a
+ * file watcher, and a capture that beats the watcher renders the PRE-edit
+ * composition. An agent reading that as "my edit failed" would thrash.
+ */
+const DEFAULT_SETTLE_MS = 150;
+const MAX_SETTLE_MS = 5_000;
+
+export async function studioFrame(
+  deps: FrameToolDeps,
+  input: StudioFrameInput = {},
+): Promise<ToolResult<StudioFrameResult>> {
+  const projectId = deps.getProjectId();
+  if (!projectId) {
+    return toolFailure("blocked", "no project is open");
+  }
+
+  if (input.time !== undefined) {
+    if (typeof input.time !== "number" || !Number.isFinite(input.time) || input.time < 0) {
+      return toolFailure("invalid", "time must be a non-negative, finite number of seconds");
+    }
+    deps.requestSeek(input.time);
+  }
+
+  const settledMs = clampSettle(input.settleMs);
+  if (settledMs > 0) await deps.wait(settledMs);
+
+  // Capture whatever the playhead now reads, rather than what was requested:
+  // the player clamps, so those can differ and the frame belongs to the former.
+  const { currentTime } = deps.readPlayhead();
+  const compositionPath = deps.getCompositionPath();
+  const url = buildFrameCaptureUrl({ projectId, compositionPath, currentTime });
+
+  const probe = await deps.probeFrame(url);
+  if (!probe.ok) {
+    return toolFailure(
+      "failed",
+      `the renderer returned ${probe.status} for this frame`,
+      "The composition may not build. Try `hyperframes check`.",
+    );
+  }
+
+  return toolOk<StudioFrameResult>({
+    url,
+    time: currentTime,
+    compositionPath: compositionPath ?? "index.html",
+    settledMs,
+  });
+}
+
+function clampSettle(requested: number | undefined): number {
+  if (requested === undefined) return DEFAULT_SETTLE_MS;
+  if (typeof requested !== "number" || !Number.isFinite(requested) || requested < 0) {
+    return DEFAULT_SETTLE_MS;
+  }
+  return Math.min(requested, MAX_SETTLE_MS);
+}
+
+export const STUDIO_FRAME_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    time: {
+      type: "number",
+      minimum: 0,
+      description: "Seconds. Omit to capture wherever the playhead already is.",
+    },
+    settleMs: {
+      type: "integer",
+      minimum: 0,
+      maximum: MAX_SETTLE_MS,
+      description: `Wait this long before capturing so a just-made edit is included. Default ${DEFAULT_SETTLE_MS}.`,
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_FRAME_DESCRIPTION = [
+  "Render the composition to a PNG at a given time and return its URL, so you can",
+  "SEE the result instead of inferring it from source. Use this to judge a change:",
+  "edit, capture the instant it affects, look, adjust.",
+  "The frame is rendered from the file on disk, not the live preview.",
+  "A capture taken immediately after an edit can therefore predate that edit, because",
+  "the render cache is cleared by a file watcher. The tool waits briefly to cover that;",
+  "raise `settleMs` if a frame still looks stale, rather than concluding the edit failed.",
+  "Returns `ok: true` with `url` and the `time` actually captured, or `ok: false`.",
+].join(" ");

package/src/webmcp/tools/inspectTools.test.ts

@@ -0,0 +1,197 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
+import { studioInspect, type InspectToolDeps, type StudioInspectResult } from "./inspectTools";
+import {
+  expectFailure,
+  expectOk,
+  previewDoc,
+  previewElement,
+  selectionFor,
+} from "../webmcpTestUtils";
+
+function animation(overrides: Partial<GsapAnimation> = {}): GsapAnimation {
+  return {
+    id: "anim-1",
+    targetSelector: "#headline",
+    method: "from",
+    position: 0,
+    properties: { y: -50, opacity: 0 },
+    duration: 1,
+    ease: "power2.out",
+    ...overrides,
+  } as GsapAnimation;
+}
+
+function inspectDeps(overrides: Partial<InspectToolDeps> = {}): InspectToolDeps {
+  return {
+    getPreviewDocument: () => null,
+    buildSelection: async (element) => selectionFor(element),
+    applySelection: () => undefined,
+    requestSeek: () => undefined,
+    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
+    getCurrentSelection: () => null,
+    getGsapDiagnostics: () => ({
+      animations: [],
+      multipleTimelines: false,
+      unsupportedTimelinePattern: false,
+    }),
+    ...overrides,
+  };
+}
+
+describe("studioInspect", () => {
+  it("returns the resolved styles, not the authored ones", async () => {
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+    const selection = selectionFor(element);
+
+    const result = await studioInspect(inspectDeps({ getCurrentSelection: () => selection }));
+
+    const ok = expectOk<StudioInspectResult>(result);
+    // The authored value is a clamp(); the resolved one is what actually renders.
+    expect(ok.styles["font-size"]).toBe("42.7px");
+    expect(ok.inlineStyles.color).toBe("red");
+    expect(ok.box.width).toBe(880);
+  });
+
+  it("reports capabilities and the disabled reason verbatim", async () => {
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+    const locked = selectionFor(element, {
+      capabilities: {
+        canSelect: true,
+        canEditStyles: false,
+        canCrop: false,
+        canMove: false,
+        canResize: false,
+        canApplyManualOffset: false,
+        canApplyManualSize: false,
+        canApplyManualRotation: false,
+        reasonIfDisabled: "Element is inside a locked composition",
+      },
+    });
+
+    const result = await studioInspect(inspectDeps({ getCurrentSelection: () => locked }));
+
+    const ok = expectOk<StudioInspectResult>(result);
+    expect(ok.can.editStyles).toBe(false);
+    expect(ok.can.move).toBe(false);
+    expect(ok.can.reasonIfDisabled).toBe("Element is inside a locked composition");
+  });
+
+  it("lists the animations on the current selection", async () => {
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+
+    const result = await studioInspect(
+      inspectDeps({
+        getCurrentSelection: () => selectionFor(element),
+        getGsapDiagnostics: () => ({
+          animations: [animation()],
+          multipleTimelines: false,
+          unsupportedTimelinePattern: false,
+        }),
+      }),
+    );
+
+    const ok = expectOk<StudioInspectResult>(result);
+    expect(ok.animations).toHaveLength(1);
+    expect(ok.animations[0]?.animationId).toBe("anim-1");
+    expect(ok.animations[0]?.ease).toBe("power2.out");
+    expect(ok.animationEditingBlocked).toBeNull();
+  });
+
+  it("says WHY animation editing is unavailable, so a write is not attempted", async () => {
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+    const base = {
+      getCurrentSelection: () => selectionFor(element),
+    };
+
+    const multiple = await studioInspect(
+      inspectDeps({
+        ...base,
+        getGsapDiagnostics: () => ({
+          animations: [],
+          multipleTimelines: true,
+          unsupportedTimelinePattern: false,
+        }),
+      }),
+    );
+    const unsupported = await studioInspect(
+      inspectDeps({
+        ...base,
+        getGsapDiagnostics: () => ({
+          animations: [],
+          multipleTimelines: false,
+          unsupportedTimelinePattern: true,
+        }),
+      }),
+    );
+
+    expect(expectOk<StudioInspectResult>(multiple).animationEditingBlocked).toMatch(
+      /multiple GSAP timelines/,
+    );
+    expect(expectOk<StudioInspectResult>(unsupported).animationEditingBlocked).toMatch(
+      /not editable/,
+    );
+  });
+
+  it("does not attribute the selection's animations to a different element", async () => {
+    // Studio only parses animations for the CURRENT selection. Reporting them
+    // against another element would report the wrong element's motion.
+    const headline = previewElement('<h1 id="headline">A</h1><p id="body">B</p>', "headline");
+    const doc = headline.ownerDocument;
+
+    const result = await studioInspect(
+      inspectDeps({
+        getPreviewDocument: () => doc,
+        getCurrentSelection: () => selectionFor(headline),
+        getGsapDiagnostics: () => ({
+          animations: [animation()],
+          multipleTimelines: false,
+          unsupportedTimelinePattern: false,
+        }),
+      }),
+      { handle: "dom:body" },
+    );
+
+    const ok = expectOk<StudioInspectResult>(result);
+    expect(ok.isCurrentSelection).toBe(false);
+    expect(ok.animations).toEqual([]);
+    expect(ok.animationEditingBlocked).toMatch(/only readable for the current selection/);
+  });
+
+  it("inspects a handle without changing what is selected", async () => {
+    const doc = previewDoc('<h1 id="headline">A</h1>');
+    const applySelection = vi.fn();
+
+    const result = await studioInspect(
+      inspectDeps({ getPreviewDocument: () => doc, applySelection }),
+      { handle: "dom:headline" },
+    );
+
+    expect(result.ok).toBe(true);
+    // Inspecting is a read. It must not steal the human's selection.
+    expect(applySelection).not.toHaveBeenCalled();
+  });
+
+  it("fails rather than returning an empty result when nothing is selected", async () => {
+    const result = expectFailure(await studioInspect(inspectDeps()));
+
+    // An empty result would assert "this element has nothing", a different and
+    // false claim from "you did not say which element".
+    expect(result.kind).toBe("invalid");
+    expect(result.reason).toMatch(/nothing is selected/);
+    expect(result.hint).toMatch(/studio_select/);
+  });
+
+  it("reports an unknown handle distinctly from an unmounted preview", async () => {
+    const notMounted = expectFailure(await studioInspect(inspectDeps(), { handle: "dom:x" }));
+    expect(notMounted.kind).toBe("blocked");
+
+    const doc = previewDoc('<h1 id="headline">A</h1>');
+    const unknown = expectFailure(
+      await studioInspect(inspectDeps({ getPreviewDocument: () => doc }), { handle: "dom:x" }),
+    );
+    expect(unknown.kind).toBe("invalid");
+    expect(unknown.reason).not.toBe(notMounted.reason);
+  });
+});

package/src/webmcp/tools/inspectTools.ts

@@ -0,0 +1,208 @@
+/**
+ * `studio_inspect`: everything about one element, in one call.
+ *
+ * The point is to prevent a failed write. Every field here either tells the
+ * agent what it can change (`can`, with `reasonIfDisabled` verbatim) or what it
+ * would be changing (the resolved styles, the text fields, the animations).
+ * An agent that reads this first should never attempt an edit the element will
+ * refuse.
+ *
+ * The GSAP diagnostics are here for the same reason: `multipleTimelines` and
+ * `unsupportedTimelinePattern` are states where animation editing is off, and
+ * learning that from a read is cheaper than learning it from a failed write.
+ */
+
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
+import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import { mintElementHandle, patchTargetAddress, resolveElementHandle } from "../handles";
+import { toolFailure, toolOk, type ToolResult } from "../toolResult";
+import type { SelectionToolDeps } from "./selectionTools";
+
+export interface InspectToolDeps extends SelectionToolDeps {
+  /** What the human currently has selected, used when no handle is given. */
+  getCurrentSelection: () => DomEditSelection | null;
+  getGsapDiagnostics: () => {
+    animations: readonly GsapAnimation[];
+    multipleTimelines: boolean;
+    unsupportedTimelinePattern: boolean;
+  };
+}
+
+interface InspectAnimation {
+  animationId: string;
+  method: string;
+  target: string;
+  position: number | string;
+  duration: number | null;
+  ease: string | null;
+  properties: Record<string, number | string>;
+  hasKeyframes: boolean;
+  hasArcPath: boolean;
+}
+
+interface InspectTextField {
+  key: string;
+  label: string;
+  value: string;
+  tagName: string;
+}
+
+export interface StudioInspectResult {
+  handle: string | null;
+  label: string;
+  tagName: string;
+  sourceFile: string;
+  box: { x: number; y: number; width: number; height: number };
+  text: string | null;
+  textFields: InspectTextField[];
+  /** The styles Studio itself surfaces, resolved, not as authored. */
+  styles: Record<string, string>;
+  inlineStyles: Record<string, string>;
+  dataAttributes: Record<string, string>;
+  can: {
+    editStyles: boolean;
+    move: boolean;
+    resize: boolean;
+    rotate: boolean;
+    crop: boolean;
+    editText: boolean;
+    reasonIfDisabled: string | null;
+  };
+  animations: InspectAnimation[];
+  /** Present only when animation editing is unavailable, with the reason. */
+  animationEditingBlocked: string | null;
+  /** True when this element is the one the human currently has selected. */
+  isCurrentSelection: boolean;
+}
+
+export interface StudioInspectInput {
+  /** Omit to inspect the current selection. */
+  handle?: string;
+}
+
+function describeAnimation(animation: GsapAnimation): InspectAnimation {
+  return {
+    animationId: animation.id,
+    method: animation.method,
+    target: animation.targetSelector,
+    position: animation.position,
+    duration: animation.duration ?? null,
+    ease: animation.ease ?? null,
+    properties: animation.properties,
+    hasKeyframes: animation.keyframes !== undefined,
+    hasArcPath: animation.arcPath !== undefined,
+  };
+}
+
+function describe(
+  selection: DomEditSelection,
+  deps: InspectToolDeps,
+  isCurrentSelection: boolean,
+): ToolResult<StudioInspectResult> {
+  const { capabilities } = selection;
+  const gsap = deps.getGsapDiagnostics();
+
+  // Only the CURRENT selection's animations are parsed by Studio. Reporting
+  // them for some other element would be reporting the wrong element's motion,
+  // which is worse than reporting none.
+  const animations = isCurrentSelection ? gsap.animations.map(describeAnimation) : [];
+
+  let animationEditingBlocked: string | null = null;
+  if (!isCurrentSelection) {
+    animationEditingBlocked = "animations are only readable for the current selection";
+  } else if (gsap.multipleTimelines) {
+    animationEditingBlocked = "this composition has multiple GSAP timelines";
+  } else if (gsap.unsupportedTimelinePattern) {
+    animationEditingBlocked = "this composition's timeline pattern is not editable by Studio";
+  }
+
+  return toolOk<StudioInspectResult>({
+    handle: mintElementHandle(patchTargetAddress(selection)),
+    label: selection.label,
+    tagName: selection.tagName,
+    sourceFile: selection.sourceFile,
+    box: selection.boundingBox,
+    text: selection.textContent,
+    textFields: selection.textFields.map((field) => ({
+      key: field.key,
+      label: field.label,
+      value: field.value,
+      tagName: field.tagName,
+    })),
+    styles: selection.computedStyles,
+    inlineStyles: selection.inlineStyles,
+    dataAttributes: selection.dataAttributes,
+    can: {
+      editStyles: capabilities.canEditStyles,
+      move: capabilities.canMove || capabilities.canApplyManualOffset,
+      resize: capabilities.canResize || capabilities.canApplyManualSize,
+      rotate: capabilities.canApplyManualRotation,
+      crop: capabilities.canCrop,
+      editText: selection.textFields.length > 0,
+      reasonIfDisabled: capabilities.reasonIfDisabled ?? null,
+    },
+    animations,
+    animationEditingBlocked,
+    isCurrentSelection,
+  });
+}
+
+export async function studioInspect(
+  deps: InspectToolDeps,
+  input: StudioInspectInput = {},
+): Promise<ToolResult<StudioInspectResult>> {
+  const current = deps.getCurrentSelection();
+
+  if (!input.handle) {
+    // An empty result here would assert "this element has nothing", which is a
+    // different and false claim from "you did not tell me which element".
+    if (!current) {
+      return toolFailure(
+        "invalid",
+        "nothing is selected and no handle was given",
+        "Pass a handle from studio_look, or call studio_select first.",
+      );
+    }
+    return describe(current, deps, true);
+  }
+
+  const doc = deps.getPreviewDocument();
+  if (!doc) return toolFailure("blocked", "the preview is not mounted yet");
+
+  const element = resolveElementHandle(doc, input.handle);
+  if (!element) {
+    return toolFailure(
+      "invalid",
+      `no element matches handle ${input.handle}`,
+      "Call studio_look for current handles.",
+    );
+  }
+
+  const selection = await deps.buildSelection(element);
+  if (!selection) {
+    return toolFailure("blocked", `${input.handle} resolved to an element Studio cannot inspect`);
+  }
+
+  return describe(selection, deps, current?.element === element);
+}
+
+export const STUDIO_INSPECT_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    handle: {
+      type: "string",
+      description: "An element handle from studio_look. Omit to inspect the current selection.",
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_INSPECT_DESCRIPTION = [
+  "Everything about one element: its resolved styles, its text fields, its box,",
+  "its GSAP animations, and crucially what it will and will not accept.",
+  "Read this BEFORE editing. `can` tells you which edits are possible and",
+  "`can.reasonIfDisabled` says why one is not, so you can avoid a write that would be refused.",
+  "Animations are only readable for the CURRENT selection; `animationEditingBlocked` says when",
+  "and why animation editing is unavailable.",
+  "Returns `ok: true`, or `ok: false` with `kind`, `reason` and a `hint`.",
+].join(" ");

package/src/webmcp/tools/selectionTools.test.ts

@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import {
+  studioSeek,
+  studioSelect,
+  type SelectionToolDeps,
+  type StudioSeekResult,
+  type StudioSelectResult,
+} from "./selectionTools";
+import { expectFailure, expectOk, previewDoc, selectionFor } from "../webmcpTestUtils";
+
+function selectionDeps(overrides: Partial<SelectionToolDeps> = {}): SelectionToolDeps {
+  return {
+    getPreviewDocument: () => null,
+    buildSelection: async (element) => selectionFor(element),
+    applySelection: () => undefined,
+    requestSeek: () => undefined,
+    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
+    ...overrides,
+  };
+}
+
+describe("studioSelect", () => {
+  it("applies the selection a click would produce and reports it back", async () => {
+    const doc = previewDoc('<h1 id="headline" data-hf-id="abc">Ship it</h1>');
+    const applySelection = vi.fn();
+
+    const result = await studioSelect(
+      selectionDeps({ getPreviewDocument: () => doc, applySelection }),
+      "hf:abc",
+    );
+
+    const ok = expectOk<StudioSelectResult>(result);
+    expect(ok.handle).toBe("hf:abc");
+    expect(ok.label).toBe("Headline");
+    expect(ok.box.width).toBe(880);
+    // Reveals the inspector, which is what makes the human see what the agent did.
+    expect(applySelection).toHaveBeenCalledTimes(1);
+  });
+
+  it("distinguishes a preview that is not mounted from a handle that does not match", async () => {
+    const notMounted = expectFailure(await studioSelect(selectionDeps(), "dom:headline"));
+    expect(notMounted.kind).toBe("blocked");
+    expect(notMounted.reason).toMatch(/not mounted/);
+
+    const doc = previewDoc('<h1 id="headline">Ship it</h1>');
+    const noMatch = expectFailure(
+      await studioSelect(selectionDeps({ getPreviewDocument: () => doc }), "dom:missing"),
+    );
+    expect(noMatch.kind).toBe("invalid");
+    expect(noMatch.reason).toMatch(/no element matches/);
+    // The two must not be the same message: waiting and re-reading are different fixes.
+    expect(noMatch.reason).not.toBe(notMounted.reason);
+  });
+
+  it("reports an element Studio cannot build a selection for, as a third case", async () => {
+    const doc = previewDoc('<h1 id="headline">Ship it</h1>');
+
+    const result = expectFailure(
+      await studioSelect(
+        selectionDeps({ getPreviewDocument: () => doc, buildSelection: async () => null }),
+        "dom:headline",
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(result.reason).toMatch(/cannot select/);
+  });
+
+  it("rejects a missing handle without touching the preview", async () => {
+    const getPreviewDocument = vi.fn(() => null);
+
+    const result = expectFailure(await studioSelect(selectionDeps({ getPreviewDocument }), "  "));
+
+    expect(result.kind).toBe("invalid");
+    expect(getPreviewDocument).not.toHaveBeenCalled();
+  });
+
+  it("leaves the existing selection alone when it fails", async () => {
+    const doc = previewDoc('<h1 id="headline">Ship it</h1>');
+    const applySelection = vi.fn();
+
+    await studioSelect(
+      selectionDeps({ getPreviewDocument: () => doc, applySelection }),
+      "dom:missing",
+    );
+
+    expect(applySelection).not.toHaveBeenCalled();
+  });
+});
+
+describe("studioSeek", () => {
+  it("reports where the playhead landed, not what was requested", () => {
+    // The player clamps against the ADAPTER's duration, which the wrapper
+    // deliberately does not second-guess.
+    let currentTime = 0;
+    const result = studioSeek(
+      selectionDeps({
+        requestSeek: () => {
+          currentTime = 10;
+        },
+        readPlayhead: () => ({ currentTime, duration: 10, isPlaying: false }),
+      }),
+      999,
+    );
+
+    const ok = expectOk<StudioSeekResult>(result);
+    expect(ok.playhead).toBe(10);
+    expect(ok.moved).toBe(true);
+  });
+
+  it("reports that playback stopped", () => {
+    let isPlaying = true;
+    let currentTime = 0;
+    const result = studioSeek(
+      selectionDeps({
+        requestSeek: () => {
+          currentTime = 2;
+          isPlaying = false;
+        },
+        readPlayhead: () => ({ currentTime, duration: 10, isPlaying }),
+      }),
+      2,
+    );
+
+    expect(expectOk<StudioSeekResult>(result).isPlaying).toBe(false);
+  });
+
+  it("fails rather than claiming a seek the player never received", () => {
+    // `requestSeek` is fire-and-forget: with no adapter mounted it silently does
+    // nothing, and reporting ok would be a lie the agent builds on.
+    const result = expectFailure(
+      studioSeek(
+        selectionDeps({ readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }) }),
+        5,
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(result.reason).toMatch(/did not move/);
+  });
+
+  it("succeeds when asked to seek to where the playhead already is", () => {
+    const result = studioSeek(
+      selectionDeps({ readPlayhead: () => ({ currentTime: 3, duration: 10, isPlaying: false }) }),
+      3,
+    );
+
+    // Nothing moved, but nothing failed either, and `moved` says which.
+    const ok = expectOk<StudioSeekResult>(result);
+    expect(ok.moved).toBe(false);
+    expect(ok.playhead).toBe(3);
+  });
+
+  it("rejects a non-finite time without calling the player", () => {
+    const requestSeek = vi.fn();
+
+    for (const time of [Number.NaN, Number.POSITIVE_INFINITY]) {
+      const result = expectFailure(studioSeek(selectionDeps({ requestSeek }), time));
+      expect(result.kind).toBe("invalid");
+    }
+    expect(requestSeek).not.toHaveBeenCalled();
+  });
+});