@hyperframes/studio 0.8.49 → 0.8.51

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/PromotableControl.tsx

@@ -83,7 +83,7 @@ export function PromotableControl({
         <span
           // Sits above the row (not on top of top-0) so it clears a value that
           // renders flush to the row's right edge, e.g. flat Font/Color rows.
-          className="pointer-events-none absolute -top-2 right-1.5 z-10 inline-flex max-w-[60%] items-center gap-1 truncate rounded bg-studio-accent/20 px-1 py-px font-mono text-[8px] font-medium text-studio-accent"
+          className="pointer-events-none absolute -top-2 right-1.5 z-10 inline-flex max-w-[60%] items-center gap-1 truncate rounded-sm bg-studio-accent/20 px-1 py-px font-mono text-[8px] font-medium text-studio-accent"
           title={`Bound to variable "${promote.boundId}"`}
         >
           ◆ {promote.boundId}
@@ -97,7 +97,7 @@ export function PromotableControl({
             e.stopPropagation();
             promote.promote();
           }}
-          className="absolute -top-2 right-1.5 z-10 inline-flex items-center gap-1 rounded bg-neutral-800/80 px-1 py-px font-mono text-[8px] font-medium text-neutral-400 opacity-70 transition-colors hover:bg-studio-accent/20 hover:text-studio-accent hover:opacity-100"
+          className="absolute -top-2 right-1.5 z-10 inline-flex items-center gap-1 rounded-sm bg-neutral-800/80 px-1 py-px font-mono text-[8px] font-medium text-neutral-400 opacity-70 transition-colors hover:bg-studio-accent/20 hover:text-studio-accent hover:opacity-100"
         >
           ◇ var
         </button>

package/src/components/editor/PropertyPanelEmptyState.tsx

@@ -18,7 +18,7 @@ function FlatEmptyState() {
         </svg>
       </span>
       <div className="text-[13px] font-semibold text-panel-text-0">Nothing selected</div>
-      <div className="max-w-[250px] text-[11px] leading-[1.5] text-panel-text-3">
+      <div className="max-w-[250px] text-[11px] leading-normal text-panel-text-3">
         Click any element on the canvas to edit it, or drag to select several.
       </div>
       <div className="mt-2 flex w-full flex-col gap-1.5">
@@ -27,7 +27,7 @@ function FlatEmptyState() {
             <span className="text-panel-danger">●</span>
             Record a gesture
           </span>
-          <span className="rounded border border-panel-border-input px-[5px] py-px font-mono text-[9px] text-panel-text-5">
+          <span className="rounded-sm border border-panel-border-input px-[5px] py-px font-mono text-[9px] text-panel-text-5">
             R
           </span>
         </span>
@@ -36,7 +36,7 @@ function FlatEmptyState() {
             <span className="text-panel-accent">✦</span>
             Describe a change to the agent
           </span>
-          <span className="rounded border border-panel-border-input px-[5px] py-px font-mono text-[9px] text-panel-text-5">
+          <span className="rounded-sm border border-panel-border-input px-[5px] py-px font-mono text-[9px] text-panel-text-5">
             ⌘K
           </span>
         </span>
@@ -74,7 +74,7 @@ function FlatMultiSelectState({
   return (
     <div className="flex flex-col gap-3 px-4 py-3">
       <div className="flex items-center gap-3 rounded-xl border border-panel-border bg-panel-surface p-3">
-        <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-lg bg-panel-accent/10 text-panel-accent">
+        <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-panel-accent/10 text-panel-accent">
           <Layers size={16} />
         </span>
         <div className="min-w-0 flex-1">
@@ -90,7 +90,7 @@ function FlatMultiSelectState({
           data-flat-multiselect-clear="true"
           aria-label="Clear selection"
           onClick={onClearSelection}
-          className="flex h-[26px] w-[26px] flex-shrink-0 items-center justify-center text-panel-text-3"
+          className="flex h-[26px] w-[26px] shrink-0 items-center justify-center text-panel-text-3"
         >
           <svg
             width="13"
@@ -113,14 +113,14 @@ function FlatMultiSelectState({
               className="flex items-center gap-2 rounded-lg border border-panel-border bg-panel-bg px-2.5 py-[7px]"
             >
               <span
-                className={`flex h-[18px] w-[18px] flex-shrink-0 items-center justify-center rounded text-[9px] font-bold ${className}`}
+                className={`flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-sm text-[9px] font-bold ${className}`}
               >
                 {glyph}
               </span>
               <span className="min-w-0 flex-1 truncate text-[11px] text-panel-text-1">
                 {element.label}
               </span>
-              <span className="flex-shrink-0 font-mono text-[9px] text-panel-text-4">
+              <span className="shrink-0 font-mono text-[9px] text-panel-text-4">
                 {element.id ? `#${element.id}` : element.selector}
               </span>
             </span>

package/src/components/editor/PropertyPanelFlatHeader.tsx

@@ -41,13 +41,13 @@ export function PropertyPanelFlatHeader({
       <Icon
         size={15}
         data-flat-header-icon="true"
-        className={`flex-shrink-0 ${ICON_COLOR_BY_KIND[elementKind]}`}
+        className={`shrink-0 ${ICON_COLOR_BY_KIND[elementKind]}`}
       />
       <div className="flex min-w-0 flex-1 items-baseline gap-2">
         <span className="truncate text-[13px] font-semibold text-panel-text-0">{name}</span>
         <span className="truncate font-mono text-[10px] text-panel-text-4">{meta}</span>
       </div>
-      <div className="flex flex-shrink-0 items-center gap-2.5 text-panel-text-3">
+      <div className="flex shrink-0 items-center gap-2.5 text-panel-text-3">
         {showUngroup && (
           <button
             type="button"

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] ${
@@ -155,7 +179,7 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
         </button>
         <button
           type="button"
-          className="absolute -right-0.5 -bottom-0.5 rounded p-0.5 text-white/50 hover:text-white/90 bg-black/50"
+          className="absolute -right-0.5 -bottom-0.5 rounded-sm p-0.5 text-white/50 hover:text-white/90 bg-black/50"
           onClick={() => setGridPopoverOpen((v) => !v)}
           title="Grid options"
           aria-label="Grid options"
@@ -185,7 +209,7 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
                     updatePrefs({ gridSpacing: val });
                   }
                 }}
-                className="w-16 rounded bg-neutral-900 border border-neutral-600 px-1.5 py-0.5 text-xs text-white text-right tabular-nums outline-none focus:border-studio-accent"
+                className="w-16 rounded-sm bg-neutral-900 border border-neutral-600 px-1.5 py-0.5 text-xs text-white text-right tabular-nums outline-hidden focus:border-studio-accent"
               />
             </label>
             <label className="flex items-center gap-2 text-xs text-white/80 cursor-pointer">

package/src/components/editor/TimelineFxPopover.tsx

@@ -139,7 +139,7 @@ export function TimelineFxPopover({
       ref={rootRef}
       role="dialog"
       aria-label="Effects"
-      className="z-[200] flex flex-col overflow-hidden rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
+      className="z-200 flex flex-col overflow-hidden rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
       style={clampedStyle(anchorRect)}
       onKeyDown={onKeyDown}
       onPointerDown={(event) => event.stopPropagation()}

package/src/components/editor/TopologyLens.tsx

@@ -143,7 +143,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
       ref={overlayRef}
       aria-hidden="true"
       data-topology-lens={visible ? state.phase : "hidden"}
-      className="pointer-events-none absolute inset-0 z-[58] overflow-hidden"
+      className="pointer-events-none absolute inset-0 z-58 overflow-hidden"
     >
       {visible && (
         <>
@@ -171,7 +171,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
                   key={index}
                   data-topology-contour="true"
                   data-topology-node={label}
-                  className="hf-topology-contour pointer-events-none absolute z-[1] rounded"
+                  className="hf-topology-contour pointer-events-none absolute z-1 rounded-sm"
                   style={{
                     ...rectStyle(rect),
                     animationDelay: `${Math.min(index, 5) * 28}ms`,
@@ -181,7 +181,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
               {!reducedMotion && (
                 <div
                   data-topology-scan="true"
-                  className="pointer-events-none absolute z-[2] overflow-hidden rounded"
+                  className="pointer-events-none absolute z-2 overflow-hidden rounded-sm"
                   style={rectStyle(geometry.field.rect)}
                 >
                   <div className="hf-topology-scan absolute inset-y-0 left-0 w-1/4" />
@@ -196,7 +196,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
             data-topology-terminal={
               state.phase === "localizing" ? (state.terminal ?? undefined) : undefined
             }
-            className="hf-topology-target pointer-events-none absolute z-[3] rounded-md"
+            className="hf-topology-target pointer-events-none absolute z-3 rounded-md"
             style={rectStyle(geometry.target.rect)}
           />
         </>

package/src/components/editor/Transform3DCube.tsx

@@ -183,7 +183,7 @@ export function Transform3DCube({
   };
 
   return (
-    <div className="relative overflow-hidden rounded-lg border border-neutral-800 bg-gradient-to-b from-neutral-900 to-neutral-950">
+    <div className="relative overflow-hidden rounded-lg border border-neutral-800 bg-linear-to-b from-neutral-900 to-neutral-950">
       <svg
         ref={svgRef}
         viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
@@ -294,7 +294,7 @@ export function Transform3DCube({
           onClick={onRecenter}
           title="Reset 3D orientation"
           aria-label="Reset 3D orientation"
-          className="absolute right-1.5 top-1.5 rounded p-0.5 text-neutral-500 hover:bg-neutral-800 hover:text-neutral-200"
+          className="absolute right-1.5 top-1.5 rounded-sm p-0.5 text-neutral-500 hover:bg-neutral-800 hover:text-neutral-200"
         >
           <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="12" cy="12" r="9" strokeWidth="2" />

package/src/components/editor/audioFxRevealTarget.ts

@@ -37,6 +37,7 @@ export function audioFxRevealTarget(
   const parsed = parseAutomationTarget(target);
   if (!parsed) return null;
   if (parsed.kind === "volume") return { kind: "volume" };
+  if (parsed.kind === "rate") return null;
   if (parsed.kind === "preset") {
     // A preset-level lane names the preset, not a node inside it: find its run
     // by the first node that belongs to it, which is how `runKey` is built.

package/src/components/editor/domEditing.test.ts

@@ -1103,7 +1103,7 @@ describe("patch builders and prompt builder", () => {
     expect(prompt).toContain("Computed styles (browser-resolved):");
     expect(prompt).toContain("Target HTML:");
     expect(prompt).toContain("Guardrails:");
-    expect(prompt).toContain("Do not modify other elements' data-* attributes or positioning.");
+    expect(prompt).toContain("Do not modify other elements' data-* attributes or positioning");
   });
 
   it("uses an absolute source path in copied agent prompts when provided", () => {

package/src/components/editor/domEditingAgentPrompt.test.ts

@@ -78,9 +78,10 @@ describe("buildElementAgentPrompt", () => {
         "Text: Hello world",
         "",
         "Guardrails:",
-        "- Make a targeted change to this element only.",
-        "- Preserve the rest of the composition and its timing.",
-        "- Do not modify other elements' data-* attributes or positioning.",
+        "- Make a targeted change to this element only, unless the request is a timeline edit.",
+        "- Preserve the rest of the composition and its timing, except what a timeline edit changes.",
+        "- Do not modify other elements' data-* attributes or positioning, except where the requested timeline edit requires it (split, retime, reorder, copy a group, swap media).",
+        "- For timeline edits (trim, split, speed, volume, copy, swap), follow the creator-editing-recipes reference of the hyperframes-core skill and use its exact attribute forms.",
         "- Prefer existing inline styles or existing CSS rules for this element over adding unrelated selectors.",
       ].join("\n"),
     );
@@ -160,9 +161,10 @@ describe("buildPickerAgentPrompt", () => {
     // Both end on the identical guardrails block, byte for byte.
     const guardrails = [
       "Guardrails:",
-      "- Make a targeted change to this element only.",
-      "- Preserve the rest of the composition and its timing.",
-      "- Do not modify other elements' data-* attributes or positioning.",
+      "- Make a targeted change to this element only, unless the request is a timeline edit.",
+      "- Preserve the rest of the composition and its timing, except what a timeline edit changes.",
+      "- Do not modify other elements' data-* attributes or positioning, except where the requested timeline edit requires it (split, retime, reorder, copy a group, swap media).",
+      "- For timeline edits (trim, split, speed, volume, copy, swap), follow the creator-editing-recipes reference of the hyperframes-core skill and use its exact attribute forms.",
       "- Prefer existing inline styles or existing CSS rules for this element over adding unrelated selectors.",
     ].join("\n");
     expect(domPrompt.endsWith(guardrails)).toBe(true);

package/src/components/editor/domEditingAgentPrompt.ts

@@ -28,9 +28,10 @@ export interface AgentPromptElementInfo {
 
 const GUARDRAIL_LINES = [
   "Guardrails:",
-  "- Make a targeted change to this element only.",
-  "- Preserve the rest of the composition and its timing.",
-  "- Do not modify other elements' data-* attributes or positioning.",
+  "- Make a targeted change to this element only, unless the request is a timeline edit.",
+  "- Preserve the rest of the composition and its timing, except what a timeline edit changes.",
+  "- Do not modify other elements' data-* attributes or positioning, except where the requested timeline edit requires it (split, retime, reorder, copy a group, swap media).",
+  "- For timeline edits (trim, split, speed, volume, copy, swap), follow the creator-editing-recipes reference of the hyperframes-core skill and use its exact attribute forms.",
   "- Prefer existing inline styles or existing CSS rules for this element over adding unrelated selectors.",
 ];
 
@@ -96,6 +97,7 @@ export function buildElementAgentPrompt({
   selectionContext,
   userInstruction,
   sourceFilePath,
+  timeline,
 }: {
   selection: DomEditSelection;
   currentTime: number;
@@ -103,6 +105,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 +140,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 });
+    },
+  };
+});