@hyperframes/studio 0.8.49 → 0.8.51

package/src/utils/sdkCanvasComposition.test.ts

@@ -0,0 +1,77 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { openComposition } from "@hyperframes/sdk";
+
+/**
+ * linkedom's HTMLCanvasElement constructor calls `createCanvas(300, 150)` from
+ * the Node-only `canvas` package. linkedom guards that import in a try/catch —
+ * try the native package, fall back to its own bundled shim — but a bundler
+ * resolves the require statically, so the catch never fires in the browser
+ * build and `createCanvas` lands undefined. Parsing any `<canvas>` tag then
+ * throws, `openComposition` rejects, and Studio silently loses its SDK session
+ * for the whole composition (no cutover, and the resolver shadow does not run
+ * either).
+ *
+ * Production telemetry, 72h after the v0.8.47 flip: 1065 of 1544
+ * `studio:sdk_session_unavailable` events were this crash, spread across a
+ * large share of 197 users. Canvas is common in compositions — Three.js,
+ * shaders, particle effects, charts.
+ *
+ * The fix is a `resolve.alias` in the studio's vite config pointing `canvas` at
+ * linkedom's own shim. This test pins the behaviour the alias has to preserve.
+ */
+const CANVAS_COMPOSITION = `<!doctype html>
+<html>
+  <body data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="3">
+      <canvas id="scene" width="800" height="600"></canvas>
+    </div>
+  </body>
+</html>`;
+
+describe("openComposition with a <canvas> element", () => {
+  it("opens a session instead of throwing on createCanvas", async () => {
+    const session = await openComposition(CANVAS_COMPOSITION, { history: false });
+    expect(session).toBeTruthy();
+    session.dispose();
+  });
+
+  it("models the canvas element so edits can target it", async () => {
+    const session = await openComposition(CANVAS_COMPOSITION, { history: false });
+    // A composition whose elements cannot be modelled is a session the cutover
+    // path declines wholesale (sessionEmpty), which is the same silent bypass by
+    // a different route.
+    expect(session.getElements().length).toBeGreaterThan(0);
+    session.dispose();
+  });
+});
+
+describe("canvas browser-stub alias", () => {
+  // The two tests above pass with OR without the fix: vitest resolves
+  // `require('canvas')` at runtime, so linkedom's own try/catch fallback works
+  // here. Only the bundled build breaks. Nothing else in this suite can observe
+  // the bundler, so the alias itself is what has to be pinned — without this,
+  // deleting the alias reintroduces a crash that is invisible until it reaches
+  // production telemetry.
+  it("is configured, so the browser build never resolves the Node canvas package", () => {
+    const config = readFileSync(resolve(import.meta.dirname, "../../vite.config.ts"), "utf8");
+    expect(config).toMatch(
+      /\bcanvas:\s*resolve\(__dirname,\s*"src\/shims\/canvasBrowserStub\.js"\)/,
+    );
+  });
+
+  it("exports the createCanvas shape linkedom destructures", async () => {
+    const stub = await import("../shims/canvasBrowserStub.js");
+    // linkedom takes the DEFAULT import and destructures createCanvas off it
+    // (`import Canvas from '...'; const {createCanvas} = Canvas`), so the
+    // default export is the one that actually has to carry the function.
+    expect(typeof stub.default.createCanvas).toBe("function");
+    expect(typeof stub.createCanvas).toBe("function");
+    const canvas = stub.default.createCanvas(300, 150);
+    expect(canvas.width).toBe(300);
+    expect(canvas.height).toBe(150);
+    expect(canvas.getContext()).toBeNull();
+  });
+});

package/src/utils/studioUiPreferences.test.ts

@@ -37,6 +37,21 @@ describe("studio UI preferences", () => {
     });
   });
 
+  it("remembers the ruler and safe-margin toggles and drops non-boolean values", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ rulerVisible: true, safeMarginsVisible: false }, storage);
+    expect(readStudioUiPreferences(storage)).toEqual({
+      rulerVisible: true,
+      safeMarginsVisible: false,
+    });
+
+    storage.setItem(
+      "hf-studio-ui-preferences",
+      JSON.stringify({ rulerVisible: "yes", safeMarginsVisible: 1 }),
+    );
+    expect(readStudioUiPreferences(storage)).toEqual({});
+  });
+
   it("ignores malformed stored values", () => {
     const storage = createStorage();
     storage.setItem(
@@ -101,6 +116,34 @@ describe("thumbnailMode preference", () => {
   });
 });
 
+describe("per-project scoping", () => {
+  it("keeps two projects' preferences independent", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ leftWidth: 300 }, storage, "alpha");
+    writeStudioUiPreferences({ leftWidth: 500 }, storage, "beta");
+
+    expect(readStudioUiPreferences(storage, "alpha").leftWidth).toBe(300);
+    expect(readStudioUiPreferences(storage, "beta").leftWidth).toBe(500);
+  });
+
+  it("a project with nothing saved yet inherits the pre-scoping global entry once", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ leftWidth: 600 }));
+
+    expect(readStudioUiPreferences(storage, "gamma").leftWidth).toBe(600);
+  });
+
+  it("stops inheriting the global entry once the project has its own write", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ leftWidth: 600 }));
+
+    writeStudioUiPreferences({ leftWidth: 250 }, storage, "gamma");
+
+    expect(readStudioUiPreferences(storage, "gamma").leftWidth).toBe(250);
+    expect(readStudioUiPreferences(storage, null).leftWidth).toBe(600);
+  });
+});
+
 describe("timeline zoom pin persistence", () => {
   it("round-trips a pinned manual zoom (survives the post-edit reload)", () => {
     const storage = createStorage();

package/src/utils/studioUiPreferences.ts

@@ -1,3 +1,6 @@
+import type { SerializedDockview } from "dockview-react";
+import { parseDockLayout } from "../components/dock/dockLayoutSchema";
+
 export interface StoredPreviewZoomState {
   zoomPercent: number;
   panX: number;
@@ -20,6 +23,8 @@ export interface StudioUiPreferences {
   recentBlocks?: string[];
   snapEnabled?: boolean;
   gridVisible?: boolean;
+  rulerVisible?: boolean;
+  safeMarginsVisible?: boolean;
   gridSpacing?: number;
   snapToGrid?: boolean;
   /** Timeline magnet: snap clip drags/trims/drops to playhead, clip edges, and beats. */
@@ -45,6 +50,8 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
+  /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
+  dockLayout?: SerializedDockview;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -62,11 +69,15 @@ function getBrowserStorage(): Storage | null {
   }
 }
 
+function storageKeyFor(projectId: string | null): string {
+  return projectId ? `${STUDIO_UI_PREFERENCES_KEY}:${projectId}` : STUDIO_UI_PREFERENCES_KEY;
+}
+
 // fallow-ignore-next-line complexity
-function readStorage(storage: Storage | null): StudioUiPreferences {
+function readStorage(storage: Storage | null, key: string): StudioUiPreferences {
   if (!storage) return {};
   try {
-    const raw = storage.getItem(STUDIO_UI_PREFERENCES_KEY);
+    const raw = storage.getItem(key);
     if (!raw) return {};
     const parsed: unknown = JSON.parse(raw);
     if (!isRecord(parsed)) return {};
@@ -130,6 +141,12 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.gridVisible === "boolean") {
       preferences.gridVisible = parsed.gridVisible;
     }
+    if (typeof parsed.rulerVisible === "boolean") {
+      preferences.rulerVisible = parsed.rulerVisible;
+    }
+    if (typeof parsed.safeMarginsVisible === "boolean") {
+      preferences.safeMarginsVisible = parsed.safeMarginsVisible;
+    }
     if (typeof parsed.gridSpacing === "number" && Number.isFinite(parsed.gridSpacing)) {
       preferences.gridSpacing = parsed.gridSpacing;
     }
@@ -157,27 +174,38 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.agentToolsEnabled === "boolean") {
       preferences.agentToolsEnabled = parsed.agentToolsEnabled;
     }
+    const dockLayout = parseDockLayout(parsed.dockLayout);
+    if (dockLayout) preferences.dockLayout = dockLayout;
     return preferences;
   } catch {
     return {};
   }
 }
 
-export function readStudioUiPreferences(storage: Storage | null = getBrowserStorage()) {
-  return readStorage(storage);
+/** `projectId` opts a caller into a per-project entry (falls back once to the
+ *  shared entry so a project's first read isn't blank). Defaults to `null`:
+ *  most callers read once at mount, never on a live project switch. */
+export function readStudioUiPreferences(
+  storage: Storage | null = getBrowserStorage(),
+  projectId: string | null = null,
+): StudioUiPreferences {
+  const scoped = readStorage(storage, storageKeyFor(projectId));
+  if (!projectId || Object.keys(scoped).length > 0) return scoped;
+  return readStorage(storage, STUDIO_UI_PREFERENCES_KEY);
 }
 
 export function writeStudioUiPreferences(
   patch: StudioUiPreferences,
   storage: Storage | null = getBrowserStorage(),
+  projectId: string | null = null,
 ) {
   if (!storage) return;
   try {
     const next = {
-      ...readStorage(storage),
+      ...readStudioUiPreferences(storage, projectId),
       ...patch,
     };
-    storage.setItem(STUDIO_UI_PREFERENCES_KEY, JSON.stringify(next));
+    storage.setItem(storageKeyFor(projectId), JSON.stringify(next));
   } catch {
     /* localStorage may be unavailable or full */
   }

package/src/utils/timelineDropTrackInsert.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../player";
+import {
+  applyTrackRenumbers,
+  planDropTrackInsert,
+  resolveDropTrack,
+} from "./timelineDropTrackInsert";
+
+function clip(id: string, track: number, start: number): TimelineElement {
+  return {
+    id,
+    key: id,
+    tag: "div",
+    start,
+    duration: 2,
+    track,
+    authoredTrack: track,
+    hfId: `hf-${id}`,
+    domId: id,
+    // Main-document elements carry no sourceFile, as in production.
+  };
+}
+
+const trackOrder = [0, 1, 2];
+const dropped = { id: "new", tag: "img", start: 5, duration: 3 };
+const elements = [clip("a", 0, 0), clip("b", 1, 0), clip("c", 2, 0)];
+const source = elements
+  .map(
+    (e) =>
+      `<div data-hf-id="${e.hfId}" id="${e.id}" data-start="0" data-track-index="${e.track}"></div>`,
+  )
+  .join("\n");
+
+describe("planDropTrackInsert", () => {
+  it("opens a lane between two rows and pushes the lanes below down", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("opens a lane above the first row", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 0, dropped });
+    expect(plan?.track).toBe(0);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("still renumbers when the peers' own sourceFile is a real path, not undefined", () => {
+    const subComp = elements.map((e) => ({ ...e, sourceFile: "sub.html" }));
+    const plan = planDropTrackInsert({ elements: subComp, trackOrder, insertRow: 1, dropped });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+});
+
+describe("planDropTrackInsert against the display row order", () => {
+  it("counts an audio-group anchor row the way a clip drag does", () => {
+    // Rows shown: group anchor (-0.5), track 0, track 1. Row boundary 2 is between 0 and 1.
+    const grouped = elements.slice(0, 2).map((e) => (e.id === "a" ? { ...e, audioGroup: "g" } : e));
+    const plan = planDropTrackInsert({
+      elements: grouped,
+      trackOrder: [-0.5, 0, 1],
+      insertRow: 2,
+      dropped,
+    });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([["b", 2]]);
+  });
+});
+
+describe("applyTrackRenumbers", () => {
+  it("rewrites only the renumbered clips' data-track-index", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    const out = applyTrackRenumbers(source, plan!);
+    const tracks = [...out.matchAll(/id="(\w)"[^>]*data-track-index="(\d+)"/g)].map((m) => [
+      m[1],
+      +m[2],
+    ]);
+    expect(tracks).toEqual([
+      ["a", 0],
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("throws when a clip's opening tag is missing", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    expect(() => applyTrackRenumbers("<div></div>", plan!)).toThrow(/Cannot renumber/);
+  });
+});
+
+describe("resolveDropTrack", () => {
+  it("keeps the aimed lane and the source when no insert is asked for", () => {
+    const out = resolveDropTrack({
+      source,
+      elements,
+      placement: { track: 2 },
+      dropped,
+    });
+    expect(out).toEqual({ source, track: 2 });
+  });
+
+  it("returns the new lane and the source with the lanes below pushed down", () => {
+    const out = resolveDropTrack({
+      source,
+      elements,
+      placement: { track: 1, insertRow: 1, trackOrder },
+      dropped,
+    });
+    expect(out.track).toBe(1);
+    expect(out.source).toContain('id="b" data-start="0" data-track-index="2"');
+  });
+
+  it("refuses to insert when a locked clip would have to move", () => {
+    const locked = elements.map((e) => (e.id === "b" ? { ...e, timelineLocked: true } : e));
+    expect(() =>
+      resolveDropTrack({
+        source,
+        elements: locked,
+        placement: { track: 1, insertRow: 1, trackOrder },
+        dropped,
+      }),
+    ).toThrow(/locked/);
+  });
+});

package/src/utils/timelineDropTrackInsert.ts

@@ -0,0 +1,83 @@
+import type { TimelineElement } from "../player";
+import { layoutAfterTrackInsert } from "../player/components/timelineDragLanding";
+import { canMoveTimelineElement } from "../player/components/timelineAuthoredMoveTarget";
+import type { TimelineDropPlacement } from "../player/components/timelineCallbacks";
+import { applyPatchByTarget, readAttributeByTarget } from "./sourcePatcher";
+import { buildPatchTarget } from "../hooks/timelineEditingHelpers";
+import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
+
+export interface DropTrackInsertPlan {
+  /** Lane the dropped clip is written on. */
+  track: number;
+  /** Existing clips whose lane changes to make room. */
+  renumbers: Array<{ element: TimelineElement; track: number }>;
+}
+
+/** Plan a new lane at boundary `insertRow` with the renumber a clip drag into a gutter uses.
+ *  Null when a locked clip would have to move. */
+export function planDropTrackInsert(input: {
+  elements: TimelineElement[];
+  /** The row order the timeline shows (anchor rows included), which `insertRow` indexes. */
+  trackOrder: readonly number[];
+  insertRow: number;
+  dropped: Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
+}): DropTrackInsertPlan | null {
+  const { elements, trackOrder, insertRow, dropped } = input;
+  const newElement: TimelineElement = {
+    ...dropped,
+    key: dropped.id,
+    // Parked on an existing lane so it adds no lane of its own to the topology.
+    track: elements[0]?.track ?? 0,
+    // sameSourceFile compares this raw field: borrow the peers' value, not the resolved path.
+    sourceFile: elements[0]?.sourceFile,
+  };
+  const layout = layoutAfterTrackInsert(newElement, dropped.start, insertRow, null, {
+    elements: [...elements, newElement],
+    trackOrder: [...trackOrder],
+  });
+  if (!layout) return null;
+  const byKey = new Map(elements.map((e) => [e.key ?? e.id, e]));
+  const renumbers: DropTrackInsertPlan["renumbers"] = [];
+  for (const norm of layout.normalized) {
+    const key = norm.key ?? norm.id;
+    if (key === dropped.id) continue;
+    const src = byKey.get(key);
+    if (!src || norm.track === (src.authoredTrack ?? src.track)) continue;
+    if (!canMoveTimelineElement(src)) return null;
+    renumbers.push({ element: src, track: norm.track });
+  }
+  const track = layout.normalized.find((n) => (n.key ?? n.id) === dropped.id)?.track;
+  return track == null ? null : { track, renumbers };
+}
+
+/** Rewrite `data-track-index` on each renumbered clip's opening tag, via the shared source patcher. */
+export function applyTrackRenumbers(source: string, plan: DropTrackInsertPlan): string {
+  let out = source;
+  for (const { element, track } of plan.renumbers) {
+    const target = buildPatchTarget(element);
+    if (!target || readAttributeByTarget(out, target, "track-index") === undefined) {
+      throw new Error(`Cannot renumber the track of "${element.id}" in the source`);
+    }
+    out = applyPatchByTarget(out, target, {
+      type: "attribute",
+      property: "track-index",
+      value: formatTimelineAttributeNumber(track),
+    });
+  }
+  return out;
+}
+
+/** The lane a dropped clip is written on and the source with any lanes pushed down to make room. */
+export function resolveDropTrack(input: {
+  source: string;
+  elements: TimelineElement[];
+  placement: TimelineDropPlacement;
+  dropped: Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
+}): { source: string; track: number } {
+  const { source, elements, placement, dropped } = input;
+  if (placement.insertRow == null) return { source, track: placement.track };
+  const { insertRow, trackOrder } = placement;
+  const plan = planDropTrackInsert({ elements, trackOrder, insertRow, dropped });
+  if (!plan) throw new Error("Cannot open a new track here: a locked clip would have to move.");
+  return { source: applyTrackRenumbers(source, plan), track: plan.track };
+}

package/src/utils/timelineElementSplit.test.ts

@@ -78,9 +78,8 @@ describe("canSplitElementAt", () => {
     ).toBe(false);
   });
 
-  it("rejects locked and implicit elements while allowing identified compositions", () => {
+  it("rejects locked elements while allowing identified compositions", () => {
     expect(canSplitElementAt(element({ timelineLocked: true }), 3)).toBe(false);
-    expect(canSplitElementAt(element({ timingSource: "implicit" }), 3)).toBe(false);
     expect(
       canSplitElementAt(
         element({ kind: "composition", compositionSrc: "child.html", playbackRate: 2 }),

package/src/utils/timelineElementSplit.ts

@@ -27,7 +27,6 @@ export function canSplitElement(el: TimelineElement): boolean {
     el.playbackRate == null || (Number.isFinite(el.playbackRate) && el.playbackRate > 0);
   return (
     !el.timelineLocked &&
-    el.timingSource !== "implicit" &&
     hasStableIdentity &&
     hasValidRate &&
     !!el.duration &&

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

@@ -370,3 +370,43 @@ function sceneDoc(): Document {
   </main>`;
   return doc;
 }
+
+describe("buildStudioLook clips", () => {
+  const clip = (overrides: Partial<TimelineElement>) =>
+    element({ tag: "audio", kind: "audio", domId: "sfx", start: 2, duration: 0.5, ...overrides });
+
+  it("returns timeline clips that are not scene layers, audio included", () => {
+    const result = buildStudioLook(
+      snapshot({
+        elements: [clip({ domId: "late", start: 9 }), clip({ domId: "early", volume: 0.85 })],
+      }),
+    );
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.clipCount).toBe(2);
+    expect(result.clips.map((c) => c.id)).toEqual(["early", "late"]);
+    expect(result.clips[0]).toMatchObject({ kind: "audio", start: 2, volume: 0.85 });
+    expect(result.elements).toEqual([]);
+  });
+
+  it("filters clips by id, kind or src", () => {
+    const result = buildStudioLook(
+      snapshot({
+        elements: [
+          clip({ domId: "click", src: "click.mp3" }),
+          clip({ domId: "vo", src: "voice.mp3" }),
+        ],
+      }),
+      { filter: "voice" },
+    );
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.clips.map((c) => c.id)).toEqual(["vo"]);
+  });
+
+  it("caps clips at the limit and reports the full count and truncation", () => {
+    const elements = Array.from({ length: 5 }, (_, i) => clip({ domId: `c${i}`, start: i }));
+    const result = buildStudioLook(snapshot({ elements }), { limit: 2 });
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.clips.map((c) => c.id)).toEqual(["c0", "c1"]);
+    expect([result.clipCount, result.clipsTruncated]).toEqual([5, true]);
+  });
+});

package/src/webmcp/tools/lookTools.ts

@@ -11,6 +11,7 @@
 import { collectDomEditLayerItems } from "../../components/editor/domEditingLayers";
 import type { DomEditLayerItem, DomEditSelection } from "../../components/editor/domEditingTypes";
 import type { TimelineElement } from "../../player/store/timelineElement";
+import { byStart, describeClip, type ClipFact } from "../../player/lib/describeClips";
 import { mintElementHandle, patchTargetAddress, timelineElementAddress } from "../handles";
 import { toolOk, type ToolResult } from "../toolResult";
 
@@ -107,8 +108,15 @@ export interface StudioLook {
   elementCount: number;
   truncated: boolean;
   elements: LookElement[];
+  /** Every timeline clip, audio included, whether or not it is a visual layer. */
+  clipCount: number;
+  clipsTruncated: boolean;
+  clips: LookClip[];
 }
 
+/** A timeline clip; `handle` is null when the clip has no addressable source element. */
+type LookClip = ClipFact & { handle: string | null };
+
 export interface StudioLookInput {
   /** Case-insensitive substring match against label, tag, and handle. */
   filter?: string;
@@ -154,6 +162,22 @@ function describeSelection(
   };
 }
 
+function matchesClipFilter(clip: LookClip, needle: string): boolean {
+  return [clip.id, clip.label, clip.kind, clip.src].some((field) =>
+    field?.toLowerCase().includes(needle),
+  );
+}
+
+function describeClipsWithHandles(snapshot: StudioLookSnapshot): LookClip[] {
+  const activeCompositionPath = snapshot.compositionPath ?? "index.html";
+  return snapshot.elements.map((element) => ({
+    ...describeClip(element),
+    handle: mintElementHandle(
+      timelineElementAddress(element, activeCompositionPath, snapshot.projectId),
+    ),
+  }));
+}
+
 function matchesFilter(element: LookElement, needle: string): boolean {
   return (
     element.label.toLowerCase().includes(needle) ||
@@ -258,6 +282,8 @@ export function buildStudioLook(
   const requested =
     Number.isInteger(input.limit) && input.limit! > 0 ? input.limit! : DEFAULT_LIMIT;
   const limit = Math.min(requested, DEFAULT_LIMIT);
+  const clips = describeClipsWithHandles(snapshot).sort(byStart);
+  const matchedClips = needle ? clips.filter((clip) => matchesClipFilter(clip, needle)) : clips;
 
   return toolOk<StudioLook>({
     projectId: snapshot.projectId,
@@ -281,6 +307,9 @@ export function buildStudioLook(
     elementCount: matched.length,
     truncated: matched.length > limit,
     elements: matched.slice(0, limit),
+    clipCount: matchedClips.length,
+    clipsTruncated: matchedClips.length > limit,
+    clips: matchedClips.slice(0, limit),
   });
 }
 
@@ -296,7 +325,7 @@ export const STUDIO_LOOK_INPUT_SCHEMA = {
       type: "integer",
       minimum: 1,
       maximum: DEFAULT_LIMIT,
-      description: `Cap the returned elements (default and max ${DEFAULT_LIMIT}). elementCount always reports the full match count.`,
+      description: `Cap the returned elements and clips (default and max ${DEFAULT_LIMIT} each). elementCount and clipCount always report the full match count.`,
     },
   },
   additionalProperties: false,
@@ -307,6 +336,8 @@ export const STUDIO_LOOK_DESCRIPTION = [
   "the playhead and duration, what the human currently has selected (including what that",
   "element will and will not accept), and the live nested scene in DOM preorder.",
   "Each scene element includes source ownership, hierarchy, and optional timeline timing.",
+  "`clips` lists every timeline clip, audio included: kind, start, duration, track, volume,",
+  "volume/effect automation points, playback rate, audio group and role.",
   "Pass a handle back to any tool that edits an element.",
   "Returns an object with `ok: true`, or `ok: false` with `kind`, `reason` and often a `hint`.",
   "`history.undoLabel` is worth checkpointing before a batch: if it later names something",