@hyperframes/studio 0.8.48 → 0.8.50

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

@@ -20,6 +20,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. */
@@ -62,11 +64,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 +136,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;
     }
@@ -163,21 +175,30 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
   }
 }
 
-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/timelineCompositionInsert.ts

@@ -3,6 +3,7 @@ import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import type { RecordEditInput } from "./studioFileHistory";
 import { buildProjectApiPath } from "./projectRouting";
 import { studioWriteHeaders } from "./studioFileVersion";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
 interface TimelineCompositionInsertionResult {
   path: string;
@@ -76,7 +77,7 @@ export async function commitTimelineCompositionInsertion(input: {
       await input.writeFile(input.targetPath, result.before, result.after);
       throw error;
     }
-    input.selectHost(`${input.targetPath}#${result.hostId}`);
+    input.selectHost(deriveTimelineStoreKeyForDomId(result.hostId, input.targetPath));
     try {
       input.resync?.();
     } catch (error) {

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",