@hyperframes/studio 0.8.49 → 0.8.51

package/src/styles/theme.css

@@ -0,0 +1,213 @@
+/* Studio's design tokens, the one place a design value is decided. Tailwind emits
+ * each as a utility and a CSS custom property; `@theme static` keeps unused
+ * tokens in `:root` so plain CSS and canvas code can still read them. */
+
+@theme static {
+  /* ---------------------------------------------------------------- colour */
+
+  /* Background levels, darkest (app shell) to lightest (inset panel body). */
+  --color-bg-0: #0a0a0a;
+  --color-bg-1: #0c0c0e;
+  --color-bg-2: #121214;
+
+  /* Raised surfaces. */
+  --color-surface: #18181b;
+  --color-surface-alt: #141414;
+  --color-input: #161618;
+  --color-hover: #27272a;
+
+  /* Separators, weakest to strongest. */
+  --color-hairline: #1a1a1c;
+  --color-border: #1e1e1e;
+  --color-border-input: #27272a;
+  --color-border-strong: #262626;
+
+  /* Text, brightest (0) to dimmest (5). */
+  --color-text-0: #fafafa;
+  --color-text-1: #e4e4e7;
+  --color-text-2: #a1a1aa;
+  --color-text-3: #71717a;
+  --color-text-4: #52525b;
+  --color-text-5: #3f3f46;
+  --color-text-body: #e5e5e5;
+  --color-text-muted: #737373;
+
+  /* Roles. Selection and playhead are reserved and differ from the accent so a
+   * selected clip, the playhead and an accented control stay tellable apart. */
+  --color-accent: #3ce6ac;
+  --color-selection: #4ba3d2;
+  --color-playhead: #ffffff;
+  --color-danger: #ef4444;
+  --color-media: #00e3ff;
+  --color-container: #f5a623;
+
+  /* -------------------------------------------------------------- geometry */
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+
+  /* Control heights: 24, 28 and 32 px. `--spacing-*` gives `h-ctl`, `min-h-ctl`
+   * and friends. */
+  --spacing-ctl-sm: 24px;
+  --spacing-ctl: 28px;
+  --spacing-ctl-lg: 32px;
+
+  /* ------------------------------------------------------------------ type */
+
+  /* Dense UI type sizes named by pixel value. `step` avoids a clash with
+   * Tailwind's own `--text-*` scale, whose `xs`, `sm` and `lg` are unchanged. */
+  --text-step-7: 7px;
+  --text-step-8: 8px;
+  --text-step-9: 9px;
+  --text-step-10: 10px;
+  --text-step-11: 11px;
+  --text-step-12: 12px;
+  --text-step-13: 13px;
+  --text-step-14: 14px;
+  --text-step-15: 15px;
+  --text-step-16: 16px;
+  --text-step-17: 17px;
+  --text-step-18: 18px;
+
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-mono: "JetBrains Mono", "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
+
+  /* ---------------------------------------------------------------- shadow */
+
+  /* Floating chrome over a near-black canvas: the hairline ring does the edge
+   * definition that a light-mode drop shadow cannot. */
+  --shadow-menu: 0 8px 24px rgb(0 0 0 / 0.45), 0 0 0 1px rgb(0 0 0 / 0.4);
+  --shadow-popover: 0 16px 40px rgb(0 0 0 / 0.55), 0 0 0 1px rgb(0 0 0 / 0.45);
+
+  /* ---------------------------------------------------------------- motion */
+
+  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
+  --ease-out-expo: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-out-circ: cubic-bezier(0.77, 0, 0.175, 1);
+
+  /* Durations have no Tailwind namespace, so these are plain variables paired
+   * with the `@utility` rules at the bottom of this file. All are at or under
+   * 200 ms. */
+  --duration-focus: 100ms;
+  --duration-press: 120ms;
+  --duration-hover: 150ms;
+  --duration-expand: 160ms;
+  --duration-open: 180ms;
+
+  /* ------------------------------------------------------------------ icon */
+
+  /* Read by `readIconTokens` and handed to Phosphor's `IconContext`. */
+  --icon-size: 16px;
+  --icon-weight: regular;
+
+  /* ------------------------------------------------- deprecated: old names */
+
+  /* The `studio.*` and `panel.*` scales, aliases of the tokens above so existing
+   * markup keeps working during the sweep. U12 removes them from Studio's
+   * source; the published JS preset keeps them one more major. */
+  --color-studio-bg: var(--color-bg-0);
+  --color-studio-surface: var(--color-surface-alt);
+  --color-studio-border: var(--color-border-strong);
+  --color-studio-text: var(--color-text-body);
+  --color-studio-muted: var(--color-text-muted);
+  --color-studio-accent: var(--color-accent);
+  --color-panel-bg: var(--color-bg-1);
+  --color-panel-bg-inset: var(--color-bg-2);
+  --color-panel-input: var(--color-input);
+  --color-panel-surface: var(--color-surface);
+  --color-panel-hover: var(--color-hover);
+  --color-panel-border: var(--color-border);
+  --color-panel-border-input: var(--color-border-input);
+  --color-panel-hairline: var(--color-hairline);
+  --color-panel-text-0: var(--color-text-0);
+  --color-panel-text-1: var(--color-text-1);
+  --color-panel-text-2: var(--color-text-2);
+  --color-panel-text-3: var(--color-text-3);
+  --color-panel-text-4: var(--color-text-4);
+  --color-panel-text-5: var(--color-text-5);
+  --color-panel-accent: var(--color-accent);
+  --color-panel-danger: var(--color-danger);
+  --color-panel-media: var(--color-media);
+  --color-panel-container: var(--color-container);
+
+  /* ------------------------------------------- deprecated: Tailwind palette */
+
+  /* Verbatim Tailwind 4.3.3 defaults for stock colours markup still names, so
+   * `--color-*: initial` does not blank them. U12 deletes this block;
+   * `theme.test.ts` fails if a value drifts from upstream. */
+  --color-amber-50: oklch(98.7% 0.022 95.277);
+  --color-amber-100: oklch(96.2% 0.059 95.617);
+  --color-amber-200: oklch(92.4% 0.12 95.746);
+  --color-amber-300: oklch(87.9% 0.169 91.605);
+  --color-amber-400: oklch(82.8% 0.189 84.429);
+  --color-amber-500: oklch(76.9% 0.188 70.08);
+  --color-amber-900: oklch(41.4% 0.112 45.904);
+  --color-amber-950: oklch(27.9% 0.077 45.635);
+  --color-black: #000;
+  --color-blue-400: oklch(70.7% 0.165 254.624);
+  --color-blue-500: oklch(62.3% 0.214 259.815);
+  --color-cyan-400: oklch(78.9% 0.154 211.53);
+  --color-cyan-500: oklch(71.5% 0.143 215.221);
+  --color-emerald-300: oklch(84.5% 0.143 164.978);
+  --color-emerald-400: oklch(76.5% 0.177 163.223);
+  --color-emerald-500: oklch(69.6% 0.17 162.48);
+  --color-emerald-600: oklch(59.6% 0.145 163.225);
+  --color-emerald-700: oklch(50.8% 0.118 165.612);
+  --color-green-400: oklch(79.2% 0.209 151.711);
+  --color-green-500: oklch(72.3% 0.219 149.579);
+  --color-green-600: oklch(62.7% 0.194 149.214);
+  --color-neutral-50: oklch(98.5% 0 none);
+  --color-neutral-100: oklch(97% 0 none);
+  --color-neutral-200: oklch(92.2% 0 none);
+  --color-neutral-300: oklch(87% 0 none);
+  --color-neutral-400: oklch(70.8% 0 none);
+  --color-neutral-500: oklch(55.6% 0 none);
+  --color-neutral-600: oklch(43.9% 0 none);
+  --color-neutral-700: oklch(37.1% 0 none);
+  --color-neutral-800: oklch(26.9% 0 none);
+  --color-neutral-900: oklch(20.5% 0 none);
+  --color-neutral-950: oklch(14.5% 0 none);
+  --color-orange-300: oklch(83.7% 0.128 66.29);
+  --color-orange-400: oklch(75% 0.183 55.934);
+  --color-pink-400: oklch(71.8% 0.202 349.761);
+  --color-pink-500: oklch(65.6% 0.241 354.308);
+  --color-purple-200: oklch(90.2% 0.063 306.703);
+  --color-purple-300: oklch(82.7% 0.119 306.383);
+  --color-purple-400: oklch(71.4% 0.203 305.504);
+  --color-purple-500: oklch(62.7% 0.265 303.9);
+  --color-purple-900: oklch(38.1% 0.176 304.987);
+  --color-red-100: oklch(93.6% 0.032 17.717);
+  --color-red-200: oklch(88.5% 0.062 18.334);
+  --color-red-300: oklch(80.8% 0.114 19.571);
+  --color-red-400: oklch(70.4% 0.191 22.216);
+  --color-red-500: oklch(63.7% 0.237 25.331);
+  --color-red-600: oklch(57.7% 0.245 27.325);
+  --color-red-700: oklch(50.5% 0.213 27.518);
+  --color-red-800: oklch(44.4% 0.177 26.899);
+  --color-red-900: oklch(39.6% 0.141 25.723);
+  --color-red-950: oklch(25.8% 0.092 26.042);
+  --color-rose-400: oklch(71.2% 0.194 13.428);
+  --color-rose-500: oklch(64.5% 0.246 16.439);
+  --color-sky-200: oklch(90.1% 0.058 230.902);
+  --color-sky-300: oklch(82.8% 0.111 230.318);
+  --color-sky-400: oklch(74.6% 0.16 232.661);
+  --color-sky-500: oklch(68.5% 0.169 237.323);
+  --color-sky-700: oklch(50% 0.134 242.749);
+  --color-sky-900: oklch(39.1% 0.09 240.876);
+  --color-sky-950: oklch(29.3% 0.066 243.157);
+  --color-violet-400: oklch(70.2% 0.183 293.541);
+  --color-violet-500: oklch(60.6% 0.25 292.717);
+  --color-white: #fff;
+}
+
+/* Motion durations as utilities, since Tailwind has no `--duration-*`
+ * namespace. Each one zeroes itself under `prefers-reduced-motion`, so a
+ * caller cannot forget the reduced-motion case. */
+
+@utility duration-* {
+  transition-duration: --value(--duration-*);
+  @media (prefers-reduced-motion: reduce) {
+    transition-duration: 0ms;
+  }
+}

package/src/styles/theme.test.ts

@@ -0,0 +1,196 @@
+// @vitest-environment happy-dom
+
+/** Guards the ways `theme.css` can silently break: a dropped CSS custom
+ * property, a utility that stops compiling, the stock Tailwind palette
+ * leaking back in, or the JS preset / legacy colours drifting from it. */
+
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { Gear, IconContext } from "@phosphor-icons/react";
+import { compile } from "tailwindcss";
+import { afterEach, describe, expect, it } from "vitest";
+import studioPreset from "./tailwind-preset.shared.js";
+import { readIconTokens } from "./iconTokens";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const STYLES_DIR = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const TAILWIND_DIR = path.dirname(require.resolve("tailwindcss/package.json"));
+
+function loadStylesheet(id: string, base: string) {
+  const file = id === "tailwindcss" ? path.join(TAILWIND_DIR, "index.css") : path.resolve(base, id);
+  return { path: file, base: path.dirname(file), content: readFileSync(file, "utf8") };
+}
+
+async function buildSource(source: string, candidates: string[]): Promise<string> {
+  const compiled = await compile(source, {
+    base: STYLES_DIR,
+    loadStylesheet,
+  });
+  return compiled.build(candidates);
+}
+
+const build = (entry: string, candidates: string[]) =>
+  buildSource(readFileSync(path.join(STYLES_DIR, entry), "utf8"), candidates);
+
+function rootVariables(css: string): Map<string, string> {
+  const block = css.match(/:root, :host \{([\s\S]*?)\n {2}\}/);
+  const vars = new Map<string, string>();
+  for (const line of (block?.[1] ?? "").split(";")) {
+    const match = line.match(/(--[a-z0-9-]+):([\s\S]+)/i);
+    if (match) vars.set(match[1], match[2].trim().replace(/\s+/g, " "));
+  }
+  return vars;
+}
+
+const themeSource = readFileSync(path.join(STYLES_DIR, "theme.css"), "utf8");
+
+function declaredValue(name: string): string {
+  const match = themeSource.match(new RegExp(`\\n\\s*${name}:\\s*([^;]+);`));
+  if (!match) throw new Error(`theme.css does not declare ${name}`);
+  return match[1].trim();
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  document.documentElement.removeAttribute("style");
+});
+
+describe("studio theme", () => {
+  it("emits the semantic palette as custom properties and as utilities", async () => {
+    const css = await build("studio.css", ["bg-accent", "text-text-2", "border-border"]);
+
+    expect(rootVariables(css).get("--color-accent")).toBe("#3ce6ac");
+    expect(css).toContain(".bg-accent {");
+    expect(css).toContain("background-color: var(--color-accent)");
+  });
+
+  it("resolves an alpha modifier on a plain hex token through color-mix", async () => {
+    const css = await build("studio.css", ["bg-accent/30"]);
+
+    expect(css).toMatch(/\.bg-accent\\\/30 \{[\s\S]*?color-mix\(/);
+  });
+
+  it("drops every Tailwind default color Studio does not use", async () => {
+    // `palette-reset.css` clears the stock palette. The entries Studio's
+    // markup still references are re-declared as deprecated aliases (U12
+    // removes them); anything outside that set must no longer resolve.
+    const css = await build("studio.css", ["bg-neutral-750", "text-teal-500", "bg-neutral-800"]);
+
+    expect(css).not.toContain("bg-neutral-750");
+    expect(css).not.toContain("text-teal-500");
+    expect(css).toContain(".bg-neutral-800 {");
+  });
+
+  it("leaves a host's stock Tailwind colors alone when only theme.css is imported", async () => {
+    const css = await buildSource('@import "tailwindcss";\n@import "./theme.css";', [
+      "bg-teal-500",
+      "text-accent",
+    ]);
+
+    expect(css).toContain(".bg-teal-500 {");
+    expect(css).toContain(".text-accent {");
+  });
+
+  it("keeps selection, playhead and accent as three distinct colors", () => {
+    const accent = declaredValue("--color-accent");
+    const selection = declaredValue("--color-selection");
+    const playhead = declaredValue("--color-playhead");
+
+    expect(new Set([accent, selection, playhead]).size).toBe(3);
+  });
+
+  it("names every micro type step in use and leaves the Tailwind sizes alone", async () => {
+    const steps = [7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18];
+    const css = await build(
+      "studio.css",
+      steps.map((step) => `text-step-${step}`).concat(["text-xs", "text-sm", "text-lg"]),
+    );
+    const vars = rootVariables(css);
+
+    for (const step of steps) {
+      expect(vars.get(`--text-step-${step}`)).toBe(`${step}px`);
+      expect(css).toContain(`.text-step-${step} {`);
+    }
+    expect(vars.get("--text-xs")).toBe("0.75rem");
+    expect(vars.get("--text-sm")).toBe("0.875rem");
+    expect(vars.get("--text-lg")).toBe("1.125rem");
+  });
+
+  it("compiles a motion-duration utility with a reduced-motion variant", async () => {
+    const css = await build("studio.css", ["duration-press", "duration-open"]);
+
+    expect(css).toMatch(
+      /\.duration-press \{[\s\S]*?transition-duration: var\(--duration-press\)[\s\S]*?prefers-reduced-motion: reduce[\s\S]*?transition-duration: 0ms/,
+    );
+    expect(css).toContain(".duration-open {");
+  });
+
+  it("keeps every legacy Tailwind palette entry at its upstream default value", async () => {
+    // These are copies of Tailwind's own values, kept only so existing markup
+    // renders unchanged. A Tailwind upgrade that moves one of them would
+    // otherwise silently change Studio's colors.
+    const upstream = new Map(
+      [
+        ...readFileSync(path.join(TAILWIND_DIR, "theme.css"), "utf8").matchAll(
+          /\n\s*(--color-[a-z]+-(?:50|\d00|950)):\s*([^;]+);/g,
+        ),
+      ].map(([, name, value]) => [name, value.trim()]),
+    );
+    const legacy = [...themeSource.matchAll(/\n\s*(--color-[a-z]+-(?:50|\d00|950)):\s*([^;]+);/g)];
+
+    expect(legacy.length).toBeGreaterThan(0);
+    for (const [, name, value] of legacy) {
+      expect(upstream.has(name), `${name} is not a Tailwind default`).toBe(true);
+      expect(`${name}: ${value.trim()}`).toBe(`${name}: ${upstream.get(name)}`);
+    }
+  });
+
+  it("keeps the deprecated JS preset in step with the CSS it shadows", () => {
+    const colors = studioPreset.theme.extend.colors;
+
+    expect(colors.studio.accent.toLowerCase()).toBe(declaredValue("--color-accent"));
+    expect(colors.panel.surface.toLowerCase()).toBe(declaredValue("--color-surface"));
+  });
+
+  it("reads the icon defaults off the theme rather than hard-coding them", () => {
+    document.documentElement.style.setProperty("--icon-size", "14px");
+    document.documentElement.style.setProperty("--icon-weight", "bold");
+
+    expect(readIconTokens()).toEqual({ size: "14px", weight: "bold" });
+  });
+
+  it("gives a child icon the token size and weight when it sets neither", () => {
+    document.documentElement.style.setProperty("--icon-size", "14px");
+    document.documentElement.style.setProperty("--icon-weight", "bold");
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        React.createElement(
+          IconContext.Provider,
+          { value: readIconTokens() },
+          React.createElement(Gear, null),
+        ),
+      );
+    });
+    const inherited = host.querySelector("svg");
+    const inheritedShape = inherited?.innerHTML;
+    act(() => {
+      root.render(React.createElement(Gear, { size: 14, weight: "bold" }));
+    });
+    const explicitShape = host.querySelector("svg")?.innerHTML;
+    act(() => root.unmount());
+
+    expect(inherited?.getAttribute("width")).toBe("14px");
+    expect(inherited?.getAttribute("height")).toBe("14px");
+    expect(inheritedShape).toBe(explicitShape);
+  });
+});

package/src/utils/clipboardPayload.test.ts

@@ -33,10 +33,41 @@ describe("deduplicateIds", () => {
 });
 
 describe("serializeClipboardPayload / deserializeClipboardPayload", () => {
-  it("round-trips a timeline clip payload", () => {
+  it("round-trips a single-clip timeline payload", () => {
     const payload: ClipboardPayload = {
       kind: "timeline-clip",
-      html: '<img id="photo" src="a.png" data-start="1" data-duration="3" />',
+      clips: [
+        {
+          html: '<img id="photo" src="a.png" data-start="1" data-duration="3" />',
+          start: 1,
+          duration: 3,
+          track: 0,
+        },
+      ],
+      sourceFile: "index.html",
+    };
+    const json = serializeClipboardPayload(payload);
+    const parsed = deserializeClipboardPayload(json);
+    expect(parsed).toEqual(payload);
+  });
+
+  it("round-trips a group timeline-clip payload", () => {
+    const payload: ClipboardPayload = {
+      kind: "timeline-clip",
+      clips: [
+        {
+          html: '<img id="a" data-start="1" data-duration="0.5" />',
+          start: 1,
+          duration: 0.5,
+          track: 0,
+        },
+        {
+          html: '<img id="b" data-start="2" data-duration="0.5" />',
+          start: 2,
+          duration: 0.5,
+          track: 1,
+        },
+      ],
       sourceFile: "index.html",
     };
     const json = serializeClipboardPayload(payload);
@@ -59,4 +90,13 @@ describe("serializeClipboardPayload / deserializeClipboardPayload", () => {
     expect(deserializeClipboardPayload("not json")).toBeNull();
     expect(deserializeClipboardPayload('{"kind":"unknown"}')).toBeNull();
   });
+
+  it("returns null for a timeline-clip payload with no clips", () => {
+    const json = serializeClipboardPayload({
+      kind: "timeline-clip",
+      clips: [],
+      sourceFile: "index.html",
+    });
+    expect(deserializeClipboardPayload(json)).toBeNull();
+  });
 });

package/src/utils/clipboardPayload.ts

@@ -2,35 +2,35 @@ import { COMPOSITION_ROOT_OPEN_TAG_RE } from "./compositionPatterns";
 
 const CLIPBOARD_MARKER = "hyperframes-clipboard:v1";
 
-export interface ClipboardPayload {
-  kind: "timeline-clip" | "dom-element";
+/** One clip's copied markup plus the original placement needed to preserve
+ *  relative offsets and tracks across a group paste. */
+export interface TimelineClipboardClip {
   html: string;
-  sourceFile: string;
-  originSelector?: string;
-  originSelectorIndex?: number;
+  start: number;
+  duration: number;
+  track: number;
 }
 
-interface SerializedPayload {
-  _marker: string;
-  kind: "timeline-clip" | "dom-element";
-  html: string;
-  sourceFile: string;
-  originSelector?: string;
-  originSelectorIndex?: number;
-}
+export type ClipboardPayload =
+  | { kind: "timeline-clip"; clips: TimelineClipboardClip[]; sourceFile: string }
+  | {
+      kind: "dom-element";
+      html: string;
+      sourceFile: string;
+      originSelector?: string;
+      originSelectorIndex?: number;
+    };
+
+type SerializedPayload = { _marker: string } & ClipboardPayload;
 
 export function serializeClipboardPayload(payload: ClipboardPayload): string {
-  const data: SerializedPayload = {
-    _marker: CLIPBOARD_MARKER,
-    kind: payload.kind,
-    html: payload.html,
-    sourceFile: payload.sourceFile,
-    originSelector: payload.originSelector,
-    originSelectorIndex: payload.originSelectorIndex,
-  };
+  const data: SerializedPayload = { _marker: CLIPBOARD_MARKER, ...payload };
   return JSON.stringify(data);
 }
 
+// Each branch validates one wire shape at the trust boundary; splitting further
+// would fragment one parse into partial validators with no independent reuse.
+// fallow-ignore-next-line complexity
 export function deserializeClipboardPayload(json: string): ClipboardPayload | null {
   let parsed: unknown;
   try {
@@ -41,16 +41,35 @@ export function deserializeClipboardPayload(json: string): ClipboardPayload | nu
   if (!parsed || typeof parsed !== "object") return null;
   const obj = parsed as Record<string, unknown>;
   if (obj._marker !== CLIPBOARD_MARKER) return null;
-  if (obj.kind !== "timeline-clip" && obj.kind !== "dom-element") return null;
-  if (typeof obj.html !== "string" || typeof obj.sourceFile !== "string") return null;
-  return {
-    kind: obj.kind,
-    html: obj.html,
-    sourceFile: obj.sourceFile,
-    originSelector: typeof obj.originSelector === "string" ? obj.originSelector : undefined,
-    originSelectorIndex:
-      typeof obj.originSelectorIndex === "number" ? obj.originSelectorIndex : undefined,
-  };
+  if (typeof obj.sourceFile !== "string") return null;
+  if (obj.kind === "timeline-clip") {
+    if (!Array.isArray(obj.clips)) return null;
+    const clips = obj.clips.filter((c): c is TimelineClipboardClip => {
+      const clip = c as Partial<TimelineClipboardClip> | null;
+      return (
+        !!clip &&
+        typeof clip === "object" &&
+        typeof clip.html === "string" &&
+        typeof clip.start === "number" &&
+        typeof clip.duration === "number" &&
+        typeof clip.track === "number"
+      );
+    });
+    if (clips.length === 0) return null;
+    return { kind: "timeline-clip", clips, sourceFile: obj.sourceFile };
+  }
+  if (obj.kind === "dom-element") {
+    if (typeof obj.html !== "string") return null;
+    return {
+      kind: "dom-element",
+      html: obj.html,
+      sourceFile: obj.sourceFile,
+      originSelector: typeof obj.originSelector === "string" ? obj.originSelector : undefined,
+      originSelectorIndex:
+        typeof obj.originSelectorIndex === "number" ? obj.originSelectorIndex : undefined,
+    };
+  }
+  return null;
 }
 
 /**
@@ -59,6 +78,7 @@ export function deserializeClipboardPayload(json: string): ClipboardPayload | nu
  * the composition root if the selector doesn't match — so paste never silently
  * drops the content.
  */
+// fallow-ignore-next-line complexity
 export function insertAsSibling(
   source: string,
   newHtml: string,
@@ -110,6 +130,7 @@ export function insertAsSibling(
   return source + newHtml;
 }
 
+// fallow-ignore-next-line complexity
 function findClosingTagPosition(html: string, openTagStart: number): number {
   // Find the end of the opening tag
   const openTagEnd = html.indexOf(">", openTagStart);
@@ -156,9 +177,13 @@ function findClosingTagPosition(html: string, openTagStart: number): number {
   return -1;
 }
 
+/** An `id="..."` attribute, not `data-id="..."` or similar — only matches
+ *  when preceded by whitespace, the way every generated attribute is. */
+export const ID_ATTR_RE = /(?<=\s)id="([^"]+)"/;
+
 export function deduplicateIds(html: string, existingIds: string[]): string {
   const existingSet = new Set(existingIds);
-  return html.replace(/(?<=\s)id="([^"]+)"/g, (full, id: string) => {
+  return html.replace(new RegExp(ID_ATTR_RE.source, "g"), (full, id: string) => {
     if (!existingSet.has(id)) return full;
     let counter = 2;
     while (existingSet.has(`${id}-${counter}`)) counter++;

package/src/utils/previewSafeMargins.test.ts

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ACTION_SAFE_PERCENT,
+  SAFE_BOX_PERCENTS,
+  TITLE_SAFE_PERCENT,
+  safeBoxInsetPercent,
+} from "./previewSafeMargins";
+
+const SKILL_PATH = join(import.meta.dirname, "../../../../skills/hyperframes-studio/SKILL.md");
+
+describe("safe boxes", () => {
+  it("are the 90% and 80% boxes, inset 5% and 10% from every edge", () => {
+    expect(SAFE_BOX_PERCENTS).toEqual([90, 80]);
+    expect(SAFE_BOX_PERCENTS.map(safeBoxInsetPercent)).toEqual([5, 10]);
+  });
+});
+
+// Skipped until the hyperframes-studio skill exists on this branch.
+describe.runIf(existsSync(SKILL_PATH))("hyperframes-studio skill matches the constants", () => {
+  it("has a safe-margins line naming both percentages", () => {
+    const skill = readFileSync(SKILL_PATH, "utf8");
+    const line = skill
+      .split("\n")
+      .find(
+        (l) =>
+          /\bsafe margins?\b/i.test(l) &&
+          l.includes(`${ACTION_SAFE_PERCENT}%`) &&
+          l.includes(`${TITLE_SAFE_PERCENT}%`),
+      );
+    expect(line).toBeDefined();
+  });
+});

package/src/utils/previewSafeMargins.ts

@@ -0,0 +1,10 @@
+// Adobe Premiere default: action-safe and title-safe margins are 10% and 20% total (5% and 10% per edge).
+export const ACTION_SAFE_PERCENT = 90;
+export const TITLE_SAFE_PERCENT = 80;
+
+export const SAFE_BOX_PERCENTS = [ACTION_SAFE_PERCENT, TITLE_SAFE_PERCENT] as const;
+
+/** Inset from each frame edge, as a percent of the frame. */
+export function safeBoxInsetPercent(boxPercent: number): number {
+  return (100 - boxPercent) / 2;
+}

package/src/utils/razorSplitTransaction.test.ts

@@ -10,7 +10,6 @@ const element = (over: Partial<TimelineElement> = {}): TimelineElement => ({
   start: 0,
   duration: 4,
   track: 0,
-  timingSource: "authored",
   sourceFile: "index.html",
   ...over,
 });