@hyperframes/studio 0.8.49 → 0.8.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.49",
+  "version": "0.8.50",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.49",
-    "@hyperframes/studio-server": "0.8.49",
-    "@hyperframes/player": "0.8.49",
-    "@hyperframes/sdk": "0.8.49",
-    "@hyperframes/core": "0.8.49"
+    "@hyperframes/player": "0.8.50",
+    "@hyperframes/core": "0.8.50",
+    "@hyperframes/studio-server": "0.8.50",
+    "@hyperframes/sdk": "0.8.50",
+    "@hyperframes/parsers": "0.8.50"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.49"
+    "@hyperframes/producer": "0.8.50"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -211,7 +211,7 @@ export function StudioApp() {
   const domEditDeleteBridge: DomEditDelete = (s, o) => handleDomEditElementDeleteRef.current(s, o);
   const resetKeyframesRef = useRef<() => boolean>(() => false);
   const deleteSelectedKeyframesRef = useRef<() => void>(() => {});
-  const { handleCopy, handlePaste, handleCut } = useClipboard({
+  const { handleCopy, handlePaste, handleCut, handleDuplicate, canPaste } = useClipboard({
     projectId,
     activeCompPath,
     domEditSelectionRef: domEditSelectionBridgeRef,
@@ -219,7 +219,7 @@ export function StudioApp() {
     writeProjectFile: fileManager.writeProjectFile,
     recordEdit: editHistory.recordEdit,
     reloadPreview,
-    handleTimelineElementDelete: timelineEditing.handleTimelineElementDelete,
+    handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
     handleDomEditElementDelete: domEditDeleteBridge,
     previewIframeRef,
   });
@@ -240,6 +240,7 @@ export function StudioApp() {
     handleCopy,
     handlePaste,
     handleCut,
+    handleDuplicate,
     onResetKeyframes: () => resetKeyframesRef.current(),
     onDeleteSelectedKeyframes: () => deleteSelectedKeyframesRef.current(),
     onAfterUndoRedo: () => invalidateGsapCacheRef.current(),
@@ -341,7 +342,7 @@ export function StudioApp() {
     setConsoleErrors,
     resetErrors: resetConsoleErrors,
   } = useConsoleErrorCapture(previewIframe);
-  const dragOverlay = useGlobalFileDrop(timelineEditing.handleTimelineFileDrop);
+  const fileDrop = useGlobalFileDrop(timelineEditing.handleTimelineFileDrop);
   const handleToggleRecordingRef = useRef<() => void>(() => {});
   const domEditSessionRef = useRef(domEditSession);
   domEditSessionRef.current = domEditSession;
@@ -446,10 +447,8 @@ export function StudioApp() {
               <DomEditProvider value={domEditSession}>
                 <div
                   className="flex flex-col h-full w-full bg-neutral-950 relative"
-                  onDragOver={dragOverlay.onDragOver}
-                  onDragEnter={dragOverlay.onDragEnter}
-                  onDragLeave={dragOverlay.onDragLeave}
-                  onDrop={dragOverlay.onDrop}
+                  onDragOver={fileDrop.onDragOver}
+                  onDrop={fileDrop.onDrop}
                 >
                   <StudioHeader
                     captureFrameHref={frameCapture.captureFrameHref}
@@ -538,6 +537,10 @@ export function StudioApp() {
                     handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
                     handleRazorSplit={timelineEditing.handleRazorSplit}
                     handleRazorSplitAll={timelineEditing.handleRazorSplitAll}
+                    onCopyClip={handleCopy}
+                    onPasteClip={handlePaste}
+                    onDuplicateClip={handleDuplicate}
+                    canPasteClip={canPaste}
                     setCompIdToSrc={setCompIdToSrc}
                     setCompositionLoading={setCompositionLoading}
                     shouldShowMotionPath={shouldShowMotionPath}
@@ -568,7 +571,6 @@ export function StudioApp() {
                     clearConsoleErrors={() => setConsoleErrors(null)}
                     domEditSession={domEditSession}
                     activeCompPath={activeCompPath}
-                    dragOverlayActive={dragOverlay.active}
                     toasts={toasts}
                     dismissToast={dismissToast}
                   />

package/src/components/EditorShell.selectionSync.test.tsx

@@ -86,6 +86,10 @@ describe("EditorShell timeline selection sync", () => {
           handleTimelineElementSplit={vi.fn()}
           handleRazorSplit={vi.fn()}
           handleRazorSplitAll={vi.fn()}
+          onCopyClip={vi.fn(() => false)}
+          onPasteClip={vi.fn(async () => {})}
+          onDuplicateClip={vi.fn(async () => false)}
+          canPasteClip={vi.fn(() => false)}
           setCompIdToSrc={vi.fn()}
           setCompositionLoading={vi.fn()}
           shouldShowMotionPath={false}

package/src/components/EditorShell.tsx

@@ -55,6 +55,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
     files: File[],
     placement?: TimelineDropPlacement,
   ) => Promise<void> | void;
+  onCopyClip: () => boolean;
+  onPasteClip: () => Promise<void>;
+  onDuplicateClip: () => Promise<boolean>;
+  canPasteClip: () => boolean;
   setCompIdToSrc: (map: Map<string, string>) => void;
   setCompositionLoading: (loading: boolean) => void;
   shouldShowMotionPath: boolean;
@@ -93,6 +97,10 @@ export function EditorShell({
   handleTimelineElementSplit,
   handleRazorSplit,
   handleRazorSplitAll,
+  onCopyClip,
+  onPasteClip,
+  onDuplicateClip,
+  canPasteClip,
   setCompIdToSrc,
   setCompositionLoading,
   shouldShowMotionPath,
@@ -181,6 +189,10 @@ export function EditorShell({
             onBlockDrop={handleTimelineBlockDrop}
             onCompositionDrop={handleTimelineCompositionDrop}
             onDeleteElement={handleTimelineElementDelete}
+            onCopyClip={onCopyClip}
+            onPasteClip={onPasteClip}
+            onDuplicateClip={onDuplicateClip}
+            canPasteClip={canPasteClip}
             previewOverlay={
               <PreviewOverlays
                 shouldShowMotionPath={shouldShowMotionPath}
@@ -219,6 +231,10 @@ interface EditorShellBodyProps {
     placement: TimelineDropPlacement,
   ) => Promise<void> | void;
   onDeleteElement: (element: TimelineElement) => Promise<void> | void;
+  onCopyClip: () => boolean;
+  onPasteClip: () => Promise<void>;
+  onDuplicateClip: () => Promise<boolean>;
+  canPasteClip: () => boolean;
 }
 
 function EditorShellBody({
@@ -235,6 +251,10 @@ function EditorShellBody({
   onBlockDrop,
   onCompositionDrop,
   onDeleteElement,
+  onCopyClip,
+  onPasteClip,
+  onDuplicateClip,
+  canPasteClip,
 }: EditorShellBodyProps) {
   const { compositionStack, updateCompositionStack, containerRef } = useNLEContext();
 
@@ -289,6 +309,10 @@ function EditorShellBody({
         onBlockDrop={onBlockDrop}
         onCompositionDrop={onCompositionDrop}
         onDeleteElement={onDeleteElement}
+        onCopyClip={onCopyClip}
+        onPasteClip={onPasteClip}
+        onDuplicateClip={onDuplicateClip}
+        canPasteClip={canPasteClip}
         onSelectTimelineElement={onSelectTimelineElement}
         timelineFooter={
           captionEditMode ? (

package/src/components/StudioOverlays.tsx

@@ -1,7 +1,6 @@
 import type { ComponentProps } from "react";
 import { LintModal } from "./LintModal";
 import { AskAgentModal } from "./AskAgentModal";
-import { StudioGlobalDragOverlay } from "./StudioGlobalDragOverlay";
 import { StudioToast } from "./StudioToast";
 import { StudioFeedbackCard } from "./feedback/StudioFeedbackCard";
 import { buildAgentContextPreview } from "./editor/domEditingAgentPrompt";
@@ -19,14 +18,13 @@ export interface StudioOverlaysProps {
   clearConsoleErrors: () => void;
   domEditSession: ReturnType<typeof useDomEditSession>;
   activeCompPath: string | null;
-  dragOverlayActive: boolean;
   toasts: ReturnType<typeof useToast>["toasts"];
   dismissToast: (id: number) => void;
 }
 
 /**
  * Floating overlays for the studio shell: lint / console-error modals, the
- * ask-agent modal, the global drag overlay, and the toast. Extracted from
+ * ask-agent modal, and the toast. Extracted from
  * `App.tsx` to keep the shell within the studio's 600-line decomposition budget.
  */
 // fallow-ignore-next-line complexity
@@ -39,7 +37,6 @@ export function StudioOverlays({
   clearConsoleErrors,
   domEditSession,
   activeCompPath,
-  dragOverlayActive,
   toasts,
   dismissToast,
 }: StudioOverlaysProps) {
@@ -78,7 +75,6 @@ export function StudioOverlays({
           }}
         />
       )}
-      {dragOverlayActive && <StudioGlobalDragOverlay />}
       {/* One bottom-right stack so the feedback card and toasts queue instead
           of covering each other. Empty when nothing is showing. */}
       <div className="absolute bottom-6 right-6 z-[91] flex flex-col items-end gap-2">

package/src/components/editor/PreviewGuides.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PreviewGuides } from "./PreviewGuides";
+import { usePreviewGuidesStore } from "./previewGuidesStore";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const compRect = vi.hoisted(() => ({
+  current: { left: 20, top: 20, width: 400, height: 225, scaleX: 1, scaleY: 1 },
+}));
+vi.mock("./useDomEditCompositionRect", () => ({
+  useDomEditCompositionRect: () => compRect.current,
+}));
+
+afterEach(() => {
+  compRect.current = { left: 20, top: 20, width: 400, height: 225, scaleX: 1, scaleY: 1 };
+  document.body.innerHTML = "";
+  window.localStorage.clear();
+});
+
+function render(rulerVisible: boolean, safeMarginsVisible: boolean) {
+  usePreviewGuidesStore.setState({ rulerVisible, safeMarginsVisible });
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => {
+    createRoot(host).render(<PreviewGuides iframeRef={{ current: null }} />);
+  });
+  return host;
+}
+
+describe("PreviewGuides", () => {
+  it("draws nothing when both toggles are off", () => {
+    const host = render(false, false);
+    expect(host.querySelector("[data-testid]")).toBeNull();
+  });
+
+  it("draws the ruler with ticks 0 to 100 every 10 on both edges", () => {
+    const host = render(true, false);
+    const top = host.querySelector('[data-testid="preview-ruler-top"]');
+    expect(Array.from(top?.children ?? []).map((t) => t.textContent)).toEqual(
+      Array.from({ length: 11 }, (_, i) => String(i * 10)),
+    );
+    expect(host.querySelector('[data-testid="preview-ruler-left"]')).not.toBeNull();
+    expect(host.querySelector('[data-testid="preview-safe-90"]')).toBeNull();
+    expect(host.querySelector('[data-testid="preview-safe-80"]')).toBeNull();
+  });
+
+  it("draws the 90% and 80% boxes with edge-midpoint ticks and no labels or caption band", () => {
+    const host = render(false, true);
+    const box = (pct: number) =>
+      host.querySelector<HTMLElement>(`[data-testid="preview-safe-${pct}"]`);
+    expect([box(90)?.style.left, box(90)?.style.bottom]).toEqual(["5%", "5%"]);
+    expect([box(80)?.style.top, box(80)?.style.right]).toEqual(["10%", "10%"]);
+    expect(box(90)?.children.length).toBe(4);
+    expect(box(80)?.children.length).toBe(4);
+    expect(host.textContent).toBe("");
+    expect(host.querySelector('[data-testid="preview-ruler-top"]')).toBeNull();
+  });
+
+  it("places the ruler in the gutter outside the frame", () => {
+    const host = render(true, false);
+    const top = host.querySelector<HTMLElement>('[data-testid="preview-ruler-top"]');
+    const left = host.querySelector<HTMLElement>('[data-testid="preview-ruler-left"]');
+    expect([top?.style.left, top?.style.top, top?.style.width]).toEqual(["20px", "4px", "400px"]);
+    expect([left?.style.left, left?.style.top, left?.style.height]).toEqual([
+      "4px",
+      "20px",
+      "225px",
+    ]);
+  });
+
+  it("draws nothing until the composition has a size", () => {
+    compRect.current = { left: 0, top: 0, width: 0, height: 0, scaleX: 1, scaleY: 1 };
+    const host = render(true, true);
+    expect(host.querySelector("[data-testid]")).toBeNull();
+  });
+
+  it("draws the same boxes on a portrait composition", () => {
+    compRect.current = { left: 20, top: 20, width: 225, height: 400, scaleX: 1, scaleY: 1 };
+    const host = render(false, true);
+    const box = host.querySelector<HTMLElement>('[data-testid="preview-safe-90"]');
+    expect([box?.style.left, box?.style.top]).toEqual(["5%", "5%"]);
+    expect(host.querySelector('[data-testid="preview-safe-80"]')).not.toBeNull();
+  });
+});

package/src/components/editor/PreviewGuides.tsx

@@ -0,0 +1,125 @@
+import { memo, useRef, type RefObject } from "react";
+import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
+import { RULER_GUTTER_PX, usePreviewGuidesStore } from "./previewGuidesStore";
+import { SAFE_BOX_PERCENTS, safeBoxInsetPercent } from "../../utils/previewSafeMargins";
+
+interface PreviewGuidesProps {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+}
+
+const TICKS = Array.from({ length: 11 }, (_, i) => i * 10);
+const INK = "rgba(255,255,255,0.7)";
+
+/** Ruler and safe-margin boxes drawn over the preview pane, never inside the composition. */
+export const PreviewGuides = memo(function PreviewGuides({ iframeRef }: PreviewGuidesProps) {
+  const rulerVisible = usePreviewGuidesStore((s) => s.rulerVisible);
+  const safeMarginsVisible = usePreviewGuidesStore((s) => s.safeMarginsVisible);
+  if (!rulerVisible && !safeMarginsVisible) return null;
+  return (
+    <ActiveGuides
+      iframeRef={iframeRef}
+      rulerVisible={rulerVisible}
+      safeMarginsVisible={safeMarginsVisible}
+    />
+  );
+});
+
+interface ActiveGuidesProps extends PreviewGuidesProps {
+  rulerVisible: boolean;
+  safeMarginsVisible: boolean;
+}
+
+/** Owns the composition-rect subscription, so it only runs while a guide is on. */
+function ActiveGuides({ iframeRef, rulerVisible, safeMarginsVisible }: ActiveGuidesProps) {
+  const paneRef = useRef<HTMLDivElement>(null);
+  const rect = useDomEditCompositionRect({ iframeRef, overlayRef: paneRef });
+  const ready = rect.width > 0 && rect.height > 0;
+
+  return (
+    <div ref={paneRef} aria-hidden="true" className="pointer-events-none absolute inset-0 z-20">
+      {ready && rulerVisible && (
+        <>
+          <div
+            data-testid="preview-ruler-top"
+            className="absolute bg-black/70"
+            style={{
+              left: rect.left,
+              top: rect.top - RULER_GUTTER_PX,
+              width: rect.width,
+              height: RULER_GUTTER_PX,
+            }}
+          >
+            {TICKS.map((pct) => (
+              <span
+                key={pct}
+                className="absolute bottom-0 border-l text-[9px] leading-none tabular-nums pl-0.5 h-2.5"
+                style={{ left: `${pct}%`, borderColor: INK, color: INK }}
+              >
+                {pct}
+              </span>
+            ))}
+          </div>
+          <div
+            data-testid="preview-ruler-left"
+            className="absolute bg-black/70"
+            style={{
+              left: rect.left - RULER_GUTTER_PX,
+              top: rect.top,
+              width: RULER_GUTTER_PX,
+              height: rect.height,
+            }}
+          >
+            {TICKS.map((pct) => (
+              <span
+                key={pct}
+                className="absolute right-0 border-t text-[9px] leading-none tabular-nums pt-0.5 w-2.5"
+                style={{ top: `${pct}%`, borderColor: INK, color: INK }}
+              >
+                {pct}
+              </span>
+            ))}
+          </div>
+        </>
+      )}
+      {ready && safeMarginsVisible && (
+        <div
+          className="absolute"
+          style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+        >
+          {SAFE_BOX_PERCENTS.map((boxPercent) => (
+            <SafeBox key={boxPercent} boxPercent={boxPercent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+const TICK_PX = 7;
+const EDGE_MIDPOINTS = [
+  { edge: "top", style: { left: "50%", top: -(TICK_PX + 1) / 2, width: 1, height: TICK_PX } },
+  { edge: "bottom", style: { left: "50%", bottom: -(TICK_PX + 1) / 2, width: 1, height: TICK_PX } },
+  { edge: "left", style: { top: "50%", left: -(TICK_PX + 1) / 2, width: TICK_PX, height: 1 } },
+  { edge: "right", style: { top: "50%", right: -(TICK_PX + 1) / 2, width: TICK_PX, height: 1 } },
+] as const;
+
+/** One thin white box inset from every edge, with a tick at the midpoint of each edge. */
+function SafeBox({ boxPercent }: { boxPercent: number }) {
+  const inset = `${safeBoxInsetPercent(boxPercent)}%`;
+  return (
+    <div
+      data-testid={`preview-safe-${boxPercent}`}
+      className="absolute border border-white/90"
+      style={{
+        left: inset,
+        top: inset,
+        right: inset,
+        bottom: inset,
+      }}
+    >
+      {EDGE_MIDPOINTS.map(({ edge, style }) => (
+        <span key={edge} className="absolute bg-white/90" style={style} />
+      ))}
+    </div>
+  );
+}

package/src/components/editor/SnapToolbar.test.tsx

@@ -8,6 +8,7 @@ import { usePlayerStore } from "../../player/store/playerStore";
 import type { LeftSidebarHandle } from "../sidebar/LeftSidebar";
 import type { DomEditSelection } from "./domEditing";
 import { SnapToolbar } from "./SnapToolbar";
+import { usePreviewGuidesStore } from "./previewGuidesStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -53,6 +54,7 @@ function AppHotkeyHarness() {
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(async () => undefined),
     handleCut: vi.fn(async () => false),
+    handleDuplicate: vi.fn(async () => false),
     onResetKeyframes: vi.fn(() => false),
     onDeleteSelectedKeyframes: vi.fn(),
   });
@@ -119,3 +121,22 @@ describe("SnapToolbar keyboard shortcuts", () => {
     act(() => root.unmount());
   });
 });
+
+describe("SnapToolbar ruler and safe-margin toggles", () => {
+  it.each([
+    ["Toggle ruler", "rulerVisible"],
+    ["Toggle safe margins", "safeMarginsVisible"],
+  ])("%s flips %s and remembers it", (label, key) => {
+    usePreviewGuidesStore.setState({ rulerVisible: false, safeMarginsVisible: false });
+    const { root } = renderToolbar();
+    const button = () => document.querySelector<HTMLButtonElement>(`[aria-label="${label}"]`);
+    expect(button()?.getAttribute("aria-pressed")).toBe("false");
+
+    act(() => button()?.click());
+
+    expect(button()?.getAttribute("aria-pressed")).toBe("true");
+    const stored = window.localStorage.getItem("hf-studio-ui-preferences") ?? "{}";
+    expect(JSON.parse(stored)[key]).toBe(true);
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/SnapToolbar.tsx

@@ -1,7 +1,8 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
-import { MagnetStraight, GridFour, Path } from "@phosphor-icons/react";
+import { MagnetStraight, GridFour, Path, Ruler, FrameCorners } from "@phosphor-icons/react";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { usePlayerStore } from "../../player/store/playerStore";
+import { usePreviewGuidesStore } from "./previewGuidesStore";
 
 const SNAP_DEFAULTS = {
   snapEnabled: true,
@@ -39,6 +40,7 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
   const motionPathCreateAvailable = usePlayerStore((s) => s.motionPathCreateAvailable);
   const motionPathArmed = usePlayerStore((s) => s.motionPathArmed);
   const setMotionPathArmed = usePlayerStore((s) => s.setMotionPathArmed);
+  const guides = usePreviewGuidesStore();
   const popoverRef = useRef<HTMLDivElement>(null);
   const gridButtonRef = useRef<HTMLButtonElement>(null);
 
@@ -116,6 +118,28 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
           <Path size={16} weight={motionPathArmed ? "fill" : "regular"} />
         </button>
       )}
+      {(
+        [
+          ["rulerVisible", "Ruler", Ruler],
+          ["safeMarginsVisible", "Safe margins", FrameCorners],
+        ] as const
+      ).map(([key, label, Icon]) => (
+        <button
+          key={key}
+          type="button"
+          className={`rounded-md p-1.5 transition-colors active:scale-[0.95] ${
+            guides[key]
+              ? "bg-studio-accent/20 text-studio-accent"
+              : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
+          }`}
+          onClick={() => guides.toggle(key)}
+          title={`${label} ${guides[key] ? "on" : "off"}`}
+          aria-label={`Toggle ${label.toLowerCase()}`}
+          aria-pressed={guides[key]}
+        >
+          <Icon size={16} weight={guides[key] ? "fill" : "regular"} />
+        </button>
+      ))}
       <button
         type="button"
         className={`rounded-md p-1.5 transition-colors active:scale-[0.95] ${

package/src/components/editor/domEditingAgentPrompt.ts

@@ -96,6 +96,7 @@ export function buildElementAgentPrompt({
   selectionContext,
   userInstruction,
   sourceFilePath,
+  timeline,
 }: {
   selection: DomEditSelection;
   currentTime: number;
@@ -103,6 +104,8 @@ export function buildElementAgentPrompt({
   selectionContext?: string;
   userInstruction?: string;
   sourceFilePath?: string;
+  /** The `formatTimelineBlock` text; omitted or empty when the timeline has no clips. */
+  timeline?: string;
 }): string {
   const displayedSourceFile = sourceFilePath?.trim() || selection.sourceFile;
   const info: AgentPromptElementInfo = {
@@ -136,6 +139,8 @@ export function buildElementAgentPrompt({
 
   lines.push(...buildElementDetailLines(info));
 
+  if (timeline) lines.push("", timeline);
+
   if (tagSnippet) {
     lines.push("", "Target HTML:", tagSnippet);
   }

package/src/components/editor/previewGuidesStore.ts

@@ -0,0 +1,26 @@
+import { create } from "zustand";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+
+/** Space the preview fit reserves above and left of the frame while the ruler is on. */
+export const RULER_GUTTER_PX = 16;
+
+type GuideKey = "rulerVisible" | "safeMarginsVisible";
+
+interface PreviewGuidesState {
+  rulerVisible: boolean;
+  safeMarginsVisible: boolean;
+  toggle: (key: GuideKey) => void;
+}
+
+export const usePreviewGuidesStore = create<PreviewGuidesState>((set, get) => {
+  const stored = readStudioUiPreferences();
+  return {
+    rulerVisible: stored.rulerVisible ?? false,
+    safeMarginsVisible: stored.safeMarginsVisible ?? false,
+    toggle: (key) => {
+      const next = !get()[key];
+      writeStudioUiPreferences({ [key]: next });
+      set({ [key]: next });
+    },
+  };
+});

package/src/components/nle/NLEPreview.test.ts

@@ -134,6 +134,19 @@ describe("getPreviewPlayerKey", () => {
 });
 
 describe("resolvePreviewStageSize", () => {
+  it("reserves the ruler gutter on both sides of both axes", () => {
+    const wide = { width: 1920, height: 1080 };
+    const tall = { width: 1080, height: 1920 };
+    expect(resolvePreviewStageSize(512, 402, wide, undefined, 16)).toEqual({
+      width: 464,
+      height: 261,
+    });
+    expect(resolvePreviewStageSize(512, 402, tall, undefined, 16)).toEqual({
+      width: 199.125,
+      height: 354,
+    });
+  });
+
   it("fits portrait composition dimensions by height in a narrow viewport", () => {
     expect(resolvePreviewStageSize(512, 402, { width: 1080, height: 1920 }, undefined)).toEqual({
       width: 217.125,

package/src/components/nle/NLEPreview.tsx

@@ -11,6 +11,7 @@ import {
   toDomPrecision,
   type PreviewZoomState,
 } from "./previewZoom";
+import { RULER_GUTTER_PX, usePreviewGuidesStore } from "../editor/previewGuidesStore";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 interface NLEPreviewProps {
   projectId: string;
@@ -89,9 +90,10 @@ export function resolvePreviewStageSize(
   viewportHeight: number,
   compositionSize: PreviewCompositionSize | null,
   portrait: boolean | undefined,
+  gutterPx = 0,
 ): { width: number; height: number } {
-  const availableWidth = Math.max(0, viewportWidth - PREVIEW_STAGE_INSET_PX);
-  const availableHeight = Math.max(0, viewportHeight - PREVIEW_STAGE_INSET_PX);
+  const availableWidth = Math.max(0, viewportWidth - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
+  const availableHeight = Math.max(0, viewportHeight - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
   const aspectRatio =
     compositionSize && compositionSize.width > 0 && compositionSize.height > 0
       ? compositionSize.width / compositionSize.height
@@ -135,6 +137,7 @@ export const NLEPreview = memo(function NLEPreview({
     onStageRef?.(stageRef);
   }, [onStageRef]);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
+  const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
 
   const zoomRef = useRef<PreviewZoomState>(loadInitialZoom());
@@ -164,14 +167,16 @@ export const NLEPreview = memo(function NLEPreview({
 
     const updateStageSize = () => {
       const rect = viewport.getBoundingClientRect();
-      setStageSize(resolvePreviewStageSize(rect.width, rect.height, compositionSize, portrait));
+      setStageSize(
+        resolvePreviewStageSize(rect.width, rect.height, compositionSize, portrait, gutterPx),
+      );
     };
 
     updateStageSize();
     const observer = new ResizeObserver(updateStageSize);
     observer.observe(viewport);
     return () => observer.disconnect();
-  }, [compositionSize, portrait]);
+  }, [compositionSize, portrait, gutterPx]);
 
   const onCompositionSizeChangeRef = useRef(onCompositionSizeChange);
   onCompositionSizeChangeRef.current = onCompositionSizeChange;