@hyperframes/studio 0.7.54 → 0.7.56

package/src/player/lib/time.test.ts

@@ -3,26 +3,26 @@ import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatT
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
-    expect(formatTime(0)).toBe("0:00");
+    expect(formatTime(0)).toBe("00:00");
   });
 
   // fallow-ignore-next-line code-duplication
   it("formats seconds less than a minute", () => {
-    expect(formatTime(5)).toBe("0:05");
-    expect(formatTime(30)).toBe("0:30");
-    expect(formatTime(59)).toBe("0:59");
+    expect(formatTime(5)).toBe("00:05");
+    expect(formatTime(30)).toBe("00:30");
+    expect(formatTime(59)).toBe("00:59");
   });
 
   it("formats exact minutes", () => {
-    expect(formatTime(60)).toBe("1:00");
-    expect(formatTime(120)).toBe("2:00");
+    expect(formatTime(60)).toBe("01:00");
+    expect(formatTime(120)).toBe("02:00");
     expect(formatTime(600)).toBe("10:00");
   });
 
   it("formats minutes and seconds", () => {
-    expect(formatTime(65)).toBe("1:05");
-    expect(formatTime(90)).toBe("1:30");
-    expect(formatTime(125)).toBe("2:05");
+    expect(formatTime(65)).toBe("01:05");
+    expect(formatTime(90)).toBe("01:30");
+    expect(formatTime(125)).toBe("02:05");
   });
 
   it("formats large values (over an hour)", () => {
@@ -32,28 +32,28 @@ describe("formatTime", () => {
   });
 
   it("floors fractional seconds", () => {
-    expect(formatTime(0.9)).toBe("0:00");
-    expect(formatTime(1.5)).toBe("0:01");
-    expect(formatTime(59.99)).toBe("0:59");
-    expect(formatTime(60.5)).toBe("1:00");
+    expect(formatTime(0.9)).toBe("00:00");
+    expect(formatTime(1.5)).toBe("00:01");
+    expect(formatTime(59.99)).toBe("00:59");
+    expect(formatTime(60.5)).toBe("01:00");
   });
 
-  it("pads single-digit seconds with leading zero", () => {
-    expect(formatTime(1)).toBe("0:01");
-    expect(formatTime(61)).toBe("1:01");
+  it("pads single-digit minutes and seconds with leading zeros", () => {
+    expect(formatTime(1)).toBe("00:01");
+    expect(formatTime(61)).toBe("01:01");
     expect(formatTime(609)).toBe("10:09");
   });
 
   it("guards against negative values", () => {
-    expect(formatTime(-1)).toBe("0:00");
+    expect(formatTime(-1)).toBe("00:00");
   });
 
   it("guards against NaN", () => {
-    expect(formatTime(NaN)).toBe("0:00");
+    expect(formatTime(NaN)).toBe("00:00");
   });
 
   it("guards against Infinity", () => {
-    expect(formatTime(Infinity)).toBe("0:00");
+    expect(formatTime(Infinity)).toBe("00:00");
   });
 });
 

package/src/player/lib/time.ts

@@ -1,10 +1,14 @@
 export const STUDIO_PREVIEW_FPS = 30;
 
 export function formatTime(time: number): string {
-  if (!Number.isFinite(time) || time < 0) return "0:00";
+  if (!Number.isFinite(time) || time < 0) return "00:00";
   const mins = Math.floor(time / 60);
   const secs = Math.floor(time % 60);
-  return `${mins}:${secs.toString().padStart(2, "0")}`;
+  // Zero-pad minutes as well as seconds so every readout is a stable-width
+  // MM:SS (e.g. "00:44", not "0:44"). Minutes past 99 keep their extra digits
+  // ("120:00"); an hours-style H:MM:SS grouping is applied by callers that need
+  // it (see formatTimelineTickLabel), never here.
+  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
 }
 
 export function secondsToFrame(time: number, fps = STUDIO_PREVIEW_FPS): number {

package/src/player/lib/timelineDOM.test.ts

@@ -4,8 +4,13 @@ import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
   createImplicitTimelineLayersFromDOM,
-  buildStandaloneRootTimelineElement,
+  mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
+import type { TimelineElement } from "../store/playerStore";
+
+function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
+  return { id, tag: "img", start: 0, duration: 5, track: 0, ...extra };
+}
 
 function makeDoc(html: string): Document {
   const d = document.implementation.createHTMLDocument();
@@ -13,29 +18,6 @@ function makeDoc(html: string): Document {
   return d;
 }
 
-function makeLiveDoc(html: string): Document {
-  document.head.innerHTML = "";
-  document.body.innerHTML = html;
-  return document;
-}
-
-function mockComputedZIndex(doc: Document, zIndexById: ReadonlyMap<string, string>): void {
-  const win = doc.defaultView;
-  if (!win) throw new Error("Expected document window");
-  const original = win.getComputedStyle.bind(win);
-  Object.defineProperty(win, "getComputedStyle", {
-    configurable: true,
-    value: (element: Element, pseudoElt?: string | null) => {
-      const style = original(element, pseudoElt);
-      const zIndex = zIndexById.get(element.id);
-      if (zIndex != null) {
-        Object.defineProperty(style, "zIndex", { configurable: true, value: zIndex });
-      }
-      return style;
-    },
-  });
-}
-
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   it("harvests hfId from a data-start element that has data-hf-id", () => {
     const doc = makeDoc(`
@@ -126,58 +108,6 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
 
     expect(element.hidden).toBe(true);
   });
-
-  it("captures the effective z-index from the live element, not the runtime inline-only value", () => {
-    // The runtime reports inline-only z-index (0 for CSS-rule authored z-index),
-    // which must NOT override the live element's effective z-index — otherwise
-    // the timeline collapses every CSS-styled clip to a z=0 tie and mis-orders.
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="hero" class="clip" data-start="0" data-duration="5" style="z-index: 30"></div>
-      </div>
-    `);
-    const hostEl = doc.getElementById("hero");
-
-    const element = createTimelineElementFromManifestClip({
-      clip: {
-        id: "hero",
-        label: "Hero",
-        kind: "element",
-        tagName: "div",
-        start: 0,
-        duration: 5,
-        track: 0,
-        zIndex: 0,
-        compositionId: null,
-        parentCompositionId: null,
-        compositionSrc: null,
-        assetUrl: null,
-      },
-      fallbackIndex: 0,
-      doc,
-      hostEl,
-    });
-
-    expect(element.zIndex).toBe(30);
-    expect(element.hasExplicitZIndex).toBe(true);
-  });
-
-  it("marks parsed inline, CSS-rule, and auto z-index authorship accurately", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="inline" class="clip" data-start="0" data-duration="2" style="z-index: 3"></div>
-        <div id="rule" class="clip" data-start="0" data-duration="2"></div>
-        <div id="auto" class="clip" data-start="0" data-duration="2"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["rule", "12"]]));
-
-    const elements = parseTimelineFromDOM(doc, 10);
-
-    expect(elements.find((el) => el.id === "inline")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "rule")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "auto")?.hasExplicitZIndex).toBe(false);
-  });
 });
 
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
@@ -211,31 +141,28 @@ describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
 
     expect(layers).toEqual([]);
   });
+});
 
-  it("marks implicit layer CSS z-index authorship from computed style", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="layer" class="clip"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["layer", "8"]]));
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
-
-    expect(layers[0]?.zIndex).toBe(8);
-    expect(layers[0]?.hasExplicitZIndex).toBe(true);
+describe("mergeTimelineElementsPreservingDowngrades — genuine removal vs transient downgrade", () => {
+  it("drops a removed TOP-LEVEL element (undo of a split) instead of ghosting it", () => {
+    const current = [el("a"), el("a-split")]; // post-split store: original + clone
+    const next = [el("a")]; // fresh scan of the reverted file: clone gone
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id)).toEqual(["a"]);
   });
-});
 
-describe("buildStandaloneRootTimelineElement", () => {
-  it("marks the standalone root as auto z-index", () => {
-    const root = buildStandaloneRootTimelineElement({
-      compositionId: "root",
-      tagName: "div",
-      rootDuration: 10,
-      iframeSrc: "/preview/comp/index.html",
-    });
+  it("still preserves an enriched sub-composition child a bare re-scan drops", () => {
+    const current = [el("a"), el("sub-child", { compositionSrc: "sub.html" })];
+    const next = [el("a")]; // bare DOM scan misses the enriched sub-comp child
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id).sort()).toEqual(["a", "sub-child"]);
+  });
 
-    expect(root?.hasExplicitZIndex).toBe(false);
+  it("trusts the fresh scan fully when it is not shorter", () => {
+    const current = [el("a"), el("b", { compositionSrc: "sub.html" })];
+    const next = [el("a"), el("c")];
+    expect(
+      mergeTimelineElementsPreservingDowngrades(current, next, 30, 30).map((e) => e.id),
+    ).toEqual(["a", "c"]);
   });
 });

package/src/player/lib/timelineDOM.ts

@@ -10,7 +10,6 @@
 
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
-import { getElementZIndex, hasExplicitZIndex } from "./layerOrdering";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -24,6 +23,7 @@ import {
   buildTimelineElementIdentity,
   getTimelineElementIdentity,
   isTimelineIgnoredElement,
+  readTimelineElementZIndex,
 } from "./timelineElementHelpers";
 
 // Re-export helpers that were previously public from this module so that
@@ -66,49 +66,6 @@ function resolveClipTag(clip: ClipManifestClip): string {
   return clip.tagName || clip.kind || "div";
 }
 
-function resolveDomCompositionContext(
-  element: Element,
-  root: Element | null,
-): {
-  parentCompositionId: string | null;
-  compositionAncestors: string[];
-  stackingContextId: string | null;
-} {
-  const ancestors: string[] = [];
-  let parentCompositionId: string | null = null;
-  let cursor = element.parentElement;
-  while (cursor) {
-    const compositionId = cursor.getAttribute("data-composition-id");
-    if (compositionId) {
-      ancestors.push(compositionId);
-      if (!parentCompositionId && cursor !== root) {
-        parentCompositionId = compositionId;
-      }
-    }
-    cursor = cursor.parentElement;
-  }
-  const compositionAncestors = ancestors.reverse();
-  return {
-    parentCompositionId,
-    compositionAncestors,
-    stackingContextId: parentCompositionId ?? compositionAncestors[0] ?? null,
-  };
-}
-
-function isHTMLElement(element: Element | null): element is HTMLElement {
-  if (!element) return false;
-  const HtmlElementCtor = element.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return typeof HtmlElementCtor !== "undefined" && element instanceof HtmlElementCtor;
-}
-
-function getTimelineElementZIndex(element: Element | null): number | undefined {
-  return isHTMLElement(element) ? getElementZIndex(element) : undefined;
-}
-
-function getTimelineElementHasExplicitZIndex(element: Element | null): boolean {
-  return isHTMLElement(element) ? hasExplicitZIndex(element) : false;
-}
-
 // fallow-ignore-next-line complexity
 export function createTimelineElementFromManifestClip(params: {
   clip: ClipManifestClip;
@@ -130,14 +87,6 @@ export function createTimelineElementFromManifestClip(params: {
   let sourceFile: string | undefined;
 
   let hfId: string | undefined;
-  const domContext = hostEl
-    ? resolveDomCompositionContext(hostEl, doc?.querySelector("[data-composition-id]") ?? null)
-    : null;
-  const compositionAncestors = clip.compositionAncestors ?? domContext?.compositionAncestors;
-  const parentCompositionId = clip.parentCompositionId ?? domContext?.parentCompositionId;
-  const stackingContextId =
-    clip.stackingContextId ?? parentCompositionId ?? compositionAncestors?.[0] ?? null;
-
   if (hostEl) {
     domId = hostEl.id || undefined;
     hfId = hostEl.getAttribute("data-hf-id") || undefined;
@@ -164,15 +113,6 @@ export function createTimelineElementFromManifestClip(params: {
     start: clip.start,
     duration: clip.duration,
     track: clip.track,
-    // Prefer the effective (computed) z-index read from the live element — the
-    // same read the reorder commit uses — so CSS-rule z-index (not just inline)
-    // is captured. clip.zIndex from the runtime is inline-only (0 for CSS rules),
-    // so it can only serve as a fallback when the element isn't live.
-    zIndex: getTimelineElementZIndex(hostEl) ?? clip.zIndex ?? 0,
-    hasExplicitZIndex: getTimelineElementHasExplicitZIndex(hostEl),
-    stackingContextId,
-    parentCompositionId,
-    compositionAncestors,
     domId,
     hfId,
     selector,
@@ -185,6 +125,7 @@ export function createTimelineElementFromManifestClip(params: {
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    entry.zIndex = readTimelineElementZIndex(hostEl);
   }
   if (clip.assetUrl) entry.src = clip.assetUrl;
   if (clip.kind === "composition" && clip.compositionId) {
@@ -207,8 +148,6 @@ export function createTimelineElementFromManifestClip(params: {
       }
     }
     if (hostEl) {
-      entry.zIndex = getTimelineElementZIndex(hostEl) ?? entry.zIndex;
-      entry.hasExplicitZIndex = getTimelineElementHasExplicitZIndex(hostEl);
       entry.domId = hostEl.id || undefined;
       entry.hfId = hostEl.getAttribute("data-hf-id") || undefined;
       entry.selector = getTimelineElementSelector(hostEl);
@@ -269,10 +208,10 @@ export function createImplicitTimelineLayersFromDOM(
     });
     if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
 
-    const compositionContext = resolveDomCompositionContext(child, rootComp);
     layers.push({
       domId: child.id || undefined,
       hfId: child.getAttribute("data-hf-id") || undefined,
+      zIndex: readTimelineElementZIndex(child),
       duration: rootDuration,
       id: identity.id,
       key: identity.key,
@@ -281,11 +220,6 @@ export function createImplicitTimelineLayersFromDOM(
       selectorIndex,
       sourceFile,
       start: 0,
-      zIndex: getTimelineElementZIndex(child),
-      hasExplicitZIndex: getTimelineElementHasExplicitZIndex(child),
-      stackingContextId: compositionContext.stackingContextId,
-      parentCompositionId: compositionContext.parentCompositionId,
-      compositionAncestors: compositionContext.compositionAncestors,
       tag: child.tagName.toLowerCase(),
       timingSource: "implicit",
       track: maxTrack + 1 + layers.length,
@@ -347,7 +281,6 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selectorIndex,
       sourceFile,
     });
-    const compositionContext = resolveDomCompositionContext(el, rootComp);
     const entry: TimelineElement = {
       id: identity.id,
       label,
@@ -356,17 +289,13 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       start,
       duration: dur,
       track: isNaN(track) ? 0 : track,
-      zIndex: getTimelineElementZIndex(el),
-      hasExplicitZIndex: getTimelineElementHasExplicitZIndex(el),
-      stackingContextId: compositionContext.stackingContextId,
-      parentCompositionId: compositionContext.parentCompositionId,
-      compositionAncestors: compositionContext.compositionAncestors,
       domId: el.id || undefined,
       hfId: el.getAttribute("data-hf-id") || undefined,
       selector,
       selectorIndex,
       sourceFile,
       timingSource: "authored",
+      zIndex: readTimelineElementZIndex(el),
     };
 
     const mediaEl = resolveMediaElement(el);
@@ -437,7 +366,14 @@ export function mergeTimelineElementsPreservingDowngrades(
 
   const nextIdentities = new Set(nextElements.map(getTimelineElementIdentity));
   const preserved = currentElements.filter(
-    (element) => !nextIdentities.has(getTimelineElementIdentity(element)),
+    (element) =>
+      !nextIdentities.has(getTimelineElementIdentity(element)) &&
+      // Only preserve enriched sub-composition children (compositionSrc set),
+      // which a bare DOM re-scan legitimately drops and enrichMissingCompositions
+      // re-adds. A TOP-LEVEL element missing from the fresh scan was genuinely
+      // removed (undo of a split, a delete), so let it go — otherwise undoing a
+      // split leaves a ghost clip in the timeline even though the file is reverted.
+      element.compositionSrc != null,
   );
   if (preserved.length === 0) return nextElements;
   return [...nextElements, ...preserved];
@@ -481,11 +417,6 @@ export function buildStandaloneRootTimelineElement(params: {
     start: 0,
     duration: params.rootDuration,
     track: 0,
-    zIndex: 0,
-    hasExplicitZIndex: false,
-    stackingContextId: params.compositionId,
-    parentCompositionId: null,
-    compositionAncestors: [params.compositionId],
     compositionSrc,
     selector: params.selector,
     selectorIndex: params.selectorIndex,

package/src/player/lib/timelineElementHelpers.ts

@@ -15,6 +15,31 @@ import { isFinitePositive } from "./playbackAdapter";
 // Duration attribute helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Read a host element's effective CSS stacking order for the timeline's reverse
+ * z→lane mapping. Prefers the inline `style.zIndex` (what the canvas context
+ * menu and LayersPanel z-edits write via handleDomZIndexReorderCommit), falls
+ * back to computed style; "auto" / empty / unparseable ⇒ 0. Works with a
+ * detached parse Document (no defaultView) as well as a live iframe. Mirrors
+ * canvasContextMenuZOrder.parseZIndex semantics so the two directions agree.
+ */
+export function readTimelineElementZIndex(el: Element): number {
+  const html = el as HTMLElement;
+  const parseZ = (value: string | null | undefined): number | null => {
+    if (value == null || value === "" || value === "auto") return null;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : null;
+  };
+  const fromInline = parseZ(html.style?.zIndex);
+  if (fromInline != null) return fromInline;
+  const view = el.ownerDocument?.defaultView;
+  if (view?.getComputedStyle) {
+    const fromComputed = parseZ(view.getComputedStyle(html).zIndex);
+    if (fromComputed != null) return fromComputed;
+  }
+  return 0;
+}
+
 function readDurationAttribute(el: Element | null | undefined): number {
   if (!el) return 0;
   const duration =
@@ -36,14 +61,20 @@ export function isTimelineIgnoredElement(el: Element): boolean {
   );
 }
 
-export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
+/**
+ * Furthest clip end (start + RAW `data-duration`) over every non-root clip in the
+ * document. Reads the authored attribute, NOT any runtime-computed value — so it
+ * is immune to the runtime's clamp that truncates a clip's live duration to the
+ * composition length. This is the source of truth for content-driven duration:
+ * computing it from the store instead would feed the truncated value back in and
+ * make the composition length ratchet down (research HANDOFF-3 §6.1 feedback loop).
+ */
+export function furthestClipEndFromDocument(doc: Document | null | undefined): number {
   if (!doc) return 0;
-  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
-  if (rootDuration > 0) return rootDuration;
-
+  const root = doc.querySelector("[data-composition-id]");
   let maxEnd = 0;
   for (const node of Array.from(doc.querySelectorAll("[data-start]"))) {
-    if (isTimelineIgnoredElement(node)) continue;
+    if (node === root || isTimelineIgnoredElement(node)) continue;
     const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
     const duration = readDurationAttribute(node);
     if (!Number.isFinite(start) || start < 0 || duration <= 0) continue;
@@ -52,6 +83,24 @@ export function readTimelineDurationFromDocument(doc: Document | null | undefine
   return maxEnd;
 }
 
+export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
+  if (!doc) return 0;
+  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
+  if (rootDuration > 0) return rootDuration;
+  return furthestClipEndFromDocument(doc);
+}
+
+/**
+ * Furthest clip end parsed straight from a composition SOURCE STRING (the HTML
+ * being saved). Uses raw `data-duration`, so it is the correct input for syncing
+ * the root duration after an edit — reading the store instead would use the
+ * runtime-truncated durations and shrink the composition (the feedback loop).
+ */
+export function furthestClipEndFromSource(source: string): number {
+  if (!source) return 0;
+  return furthestClipEndFromDocument(new DOMParser().parseFromString(source, "text/html"));
+}
+
 // ---------------------------------------------------------------------------
 // DOM element type guards
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineIframeHelpers.ts

@@ -18,6 +18,7 @@ import {
   getTimelineElementSelectorIndex,
   getTimelineElementDisplayLabel,
   buildTimelineElementIdentity,
+  readTimelineElementZIndex,
 } from "./timelineElementHelpers";
 
 // ---------------------------------------------------------------------------
@@ -377,6 +378,7 @@ export function buildMissingCompositionElements(
       selector,
       selectorIndex,
       sourceFile,
+      zIndex: readTimelineElementZIndex(el),
     };
     if (compSrc) {
       entry.compositionSrc = compSrc;

package/src/player/store/playerStore.ts

@@ -3,6 +3,7 @@ import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import type { BeatEditState } from "../../utils/beatEditing";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { computePinnedZoomPercent } from "../components/timelineZoom";
 
 /** Minimal keyframe cache types — mirrors GsapKeyframesData without pulling in Node-only gsap-parser. */
 export interface KeyframeCacheEntry {
@@ -75,6 +76,10 @@ export interface TimelineElement {
 export type ZoomMode = "fit" | "manual";
 type TimelineTool = "select" | "razor";
 
+export interface SelectElementOptions {
+  preserveSet?: boolean;
+}
+
 function resolveElementSelection(
   ids: Iterable<string>,
   anchor?: string | null,
@@ -142,6 +147,25 @@ interface PlayerState {
 
   /** Multi-select: additional selected elements beyond selectedElementId. */
   selectedElementIds: Set<string>;
+  clearSelectedElementIds: () => void;
+  /** Replace the whole multi-selection at once (marquee live updates). */
+  setSelectedElementIds: (ids: Set<string>) => void;
+  /** Timeline magnet toggle — when false, clip drags/trims/drops never snap. */
+  timelineSnapEnabled: boolean;
+  setTimelineSnapEnabled: (enabled: boolean) => void;
+  /**
+   * Pin the timeline zoom to its current visual scale before a duration-changing
+   * edit, so a subsequent duration change (which recomputes fit-pps) stops
+   * rescaling every clip. No-op once already pinned (mode is "manual").
+   */
+  pinTimelineZoom: (currentPixelsPerSecond: number, fitPixelsPerSecond: number) => void;
+  /**
+   * The timeline's live pixels-per-second + fit basis, published by <Timeline> on
+   * every render. Non-reactive scratch state (never read as a render input).
+   */
+  timelinePps: number;
+  timelineFitPps: number;
+  setTimelineScale: (pps: number, fitPps: number) => void;
   setSelection: (ids: Iterable<string>, anchor?: string | null) => void;
   addSelectedElementId: (id: string) => void;
   toggleSelectedElementId: (id: string) => void;
@@ -160,7 +184,7 @@ interface PlayerState {
   setTimelineReady: (ready: boolean) => void;
   setBeatDragging: (dragging: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
-  setSelectedElementId: (id: string | null) => void;
+  setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;
   /** Move the selection anchor within an active multi-selection without collapsing it. */
   setSelectionAnchor: (id: string | null) => void;
   updateElement: (
@@ -260,6 +284,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
+  timelinePps: 100,
+  timelineFitPps: 100,
   inPoint: null,
   outPoint: null,
 
@@ -383,6 +409,32 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   },
   setLoopEnabled: (enabled) => set({ loopEnabled: enabled }),
   setZoomMode: (mode) => set({ zoomMode: mode }),
+  clearSelectedElementIds: () => set({ selectedElementIds: new Set() }),
+  setSelectedElementIds: (ids: Set<string>) => set({ selectedElementIds: new Set(ids) }),
+  timelineSnapEnabled: readStudioUiPreferences().timelineSnapEnabled ?? true,
+  setTimelineSnapEnabled: (enabled) => {
+    writeStudioUiPreferences({ timelineSnapEnabled: enabled });
+    set({ timelineSnapEnabled: enabled });
+  },
+  pinTimelineZoom: (currentPixelsPerSecond, fitPixelsPerSecond) =>
+    set((s) => {
+      // Already pinned (or the user manually zoomed) — never clobber that.
+      if (s.zoomMode === "manual") return {};
+      const percent = computePinnedZoomPercent(currentPixelsPerSecond, fitPixelsPerSecond);
+      writeStudioUiPreferences({
+        timelineZoomMode: "manual",
+        timelineManualZoomPercent: percent,
+      });
+      return { zoomMode: "manual", manualZoomPercent: percent };
+    }),
+  setTimelineScale: (pps, fitPps) => {
+    // Non-reactive publish: mutate in place + reuse the same object identity so no
+    // subscriber re-renders (these fields are never a render input, only read
+    // imperatively before pinning).
+    const state = get();
+    state.timelinePps = pps;
+    state.timelineFitPps = fitPps;
+  },
   setInPoint: (time) =>
     set((state) => {
       const t = time !== null && Number.isFinite(time) ? time : null;
@@ -414,9 +466,16 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   // A genuine single selection: always collapse the set to just this element. User
   // intent (timeline click, preview click via applyDomSelection) flows here; DOM sync
   // echoes that must preserve a group go through setSelectionAnchor instead.
-  setSelectedElementId: (id) =>
+  setSelectedElementId: (id, options) =>
     set((s) => {
-      const selectedElementIds = id ? new Set([id]) : new Set<string>();
+      const preserveSet = Boolean(options?.preserveSet && id && s.selectedElementIds.has(id));
+      const selectedElementIds = preserveSet
+        ? new Set(s.selectedElementIds)
+        : options?.preserveSet
+          ? new Set<string>()
+          : id
+            ? new Set([id])
+            : new Set<string>();
       // Selecting a different element drops any active keyframe selection — otherwise
       // a stale activeKeyframePct from a prior diamond click would force the next drag
       // to "modify" a keyframe on the new element. A diamond click sets the pct AFTER