@hyperframes/studio 0.8.50 → 0.8.52

package/src/styles/tokenGate.test.ts

@@ -0,0 +1,109 @@
+// The token gate (R11, AE1). Tailwind silently drops a class it cannot compile, so `rounded-button`
+// renders as no radius and nothing goes red. This compiles Studio's real entry stylesheet with every
+// class the source claims and reports any candidate producing no selector as `file: class`.
+// Tailwind is the only judge, so there is no allowlist; a failing class is fixed, never excused.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { compile } from "tailwindcss";
+import { describe, expect, it } from "vitest";
+import { extractClassCandidates } from "./classCandidates";
+import { listSourceFiles, loadStylesheet, STYLES_DIR } from "./styleSources";
+
+// A class selector in the emitted CSS, escapes removed: `.hover\:bg-surface\/50` reads back as its candidate.
+const CLASS_SELECTOR = /\.((?:\\.|[^\s.,{}()>+~:[\]#'"*/\\])+)/g;
+
+// Tailwind's `group`/`peer` variant markers (`group/card`) produce no rule of their own, so no
+// compiled selector can vouch for them. Nothing else is exempt.
+const MARKERS = new Set(["group", "peer"]);
+
+// `hf-` is HyperFrames' reserved prefix for semantic hooks, not utilities, so Tailwind is the
+// wrong judge of them.
+const HOOK_PREFIX = /^hf-/;
+
+/** Compile Studio's stylesheet and return every class it can produce. */
+async function resolvable(candidates: string[]): Promise<Set<string>> {
+  const compiled = await compile(readFileSync(path.join(STYLES_DIR, "studio.css"), "utf8"), {
+    base: STYLES_DIR,
+    loadStylesheet,
+  });
+  const css = compiled.build(candidates);
+  const selectors = new Set<string>();
+  for (const [, selector] of css.matchAll(CLASS_SELECTOR)) {
+    selectors.add(selector.replace(/\\(.)/g, "$1"));
+  }
+  return selectors;
+}
+
+// `file: class` for every class the sources claim that Tailwind cannot make. Sources are passed
+// in so the fixtures exercise the same code path as the tree.
+async function unresolved(sources: ReadonlyMap<string, string>): Promise<string[]> {
+  const claims = new Map<string, string[]>();
+  for (const [file, source] of sources) {
+    for (const candidate of extractClassCandidates(source)) {
+      const seen = claims.get(candidate.base);
+      if (seen) seen.push(file);
+      else claims.set(candidate.base, [file]);
+    }
+  }
+  const produced = await resolvable([...claims.keys()]);
+  const failures: string[] = [];
+  for (const [candidate, files] of claims) {
+    if (produced.has(candidate) || MARKERS.has(candidate.split("/")[0])) continue;
+    if (HOOK_PREFIX.test(candidate)) continue;
+    for (const file of files) failures.push(`${file}: ${candidate}`);
+  }
+  return failures.sort();
+}
+
+// Every file the gate reads, mirroring the `@source` globs in `studio.css`. Tests are excluded:
+// a fixture in a test is not markup.
+function studioSources(): Map<string, string> {
+  return listSourceFiles((file) => /\.tsx?$/.test(file) && !/\.test\.tsx?$/.test(file));
+}
+
+describe("token gate", () => {
+  it("names the file and the class when a class resolves to nothing", async () => {
+    // AE1: `rounded-hologram` looks like a token name but is defined nowhere. The map is named
+    // `buttonSizes`, not `sizeStyles`: the `cn()` that consumes it puts it in front of the gate.
+    const failures = await unresolved(
+      new Map([
+        [
+          "ui/Button.tsx",
+          `const buttonSizes = { md: "h-8 rounded-hologram text-mega" };
+           const Button = ({ size }) => <button className={cn(buttonSizes[size])} />;`,
+        ],
+      ]),
+    );
+
+    expect(failures).toEqual(["ui/Button.tsx: rounded-hologram", "ui/Button.tsx: text-mega"]);
+  });
+
+  it("accepts an arbitrary value and reports it as one", async () => {
+    const source = `<div className="text-[11px]" />`;
+
+    expect(await unresolved(new Map([["a.tsx", source]]))).toEqual([]);
+    expect(extractClassCandidates(source).filter((c) => c.arbitrary)).toHaveLength(1);
+  });
+
+  it("accepts variants, static utilities and Studio's own CSS classes", async () => {
+    // `timeline-clip` is a plain rule in `studio.css`, not a utility.
+    const source = `<div className="hover:bg-surface/50 text-center border-dashed timeline-clip" />`;
+
+    expect(await unresolved(new Map([["a.tsx", source]]))).toEqual([]);
+  });
+
+  it("leaves Studio's own hook prefix and Tailwind's variant markers alone", async () => {
+    const source = `<div className="group group/card peer hf-fx-node" />`;
+
+    expect(await unresolved(new Map([["a.tsx", source]]))).toEqual([]);
+  });
+
+  it("claims nothing for a template chunk that touches an interpolation", async () => {
+    expect(await unresolved(new Map([["a.tsx", "<div className={`w-${i}`} />"]]))).toEqual([]);
+  });
+
+  it("resolves every class Studio's own source claims", async () => {
+    expect(await unresolved(studioSources())).toEqual([]);
+  });
+});

package/src/utils/sourcePatcher.ts

@@ -3,7 +3,7 @@
  * Handles inline style updates, attribute changes, and text content.
  */
 
-function escapeRegex(s: string): string {
+export function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 

package/src/utils/studioHelpers.test.ts

@@ -2,6 +2,7 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
+  historyTooltipLabel,
   findMatchingTimelineElementId,
   findTimelineIdByAncestor,
   resolveDroppedAssetDimensions,
@@ -217,3 +218,20 @@ describe("resolveElementTrack", () => {
     expect(resolveElementTrack({ authoredTrack: undefined, track: 3.6 })).toBe(4);
   });
 });
+
+describe("historyTooltipLabel", () => {
+  // A disabled control gets no pointer events, so its tooltip cannot be opened
+  // to read. The wording is checked here instead of through the DOM.
+  it("names the action that would be undone", () => {
+    expect(historyTooltipLabel("undo", "Move layer")).toMatch(/^Undo Move layer \(.+\)$/);
+  });
+
+  it("names the action that would be redone", () => {
+    expect(historyTooltipLabel("redo", "Move layer")).toMatch(/^Redo Move layer \(.+\)$/);
+  });
+
+  it("keeps the shortcut when the history is empty", () => {
+    expect(historyTooltipLabel("undo", undefined)).toMatch(/^Undo \(.+\)$/);
+    expect(historyTooltipLabel("redo", null)).toMatch(/^Redo \(.+\)$/);
+  });
+});

package/src/utils/studioHelpers.ts

@@ -119,13 +119,23 @@ export function shouldIgnoreHistoryShortcut(target: EventTarget | null): boolean
   return isTypingTarget(target);
 }
 
-export function getHistoryShortcutLabel(action: "undo" | "redo"): string {
+function getHistoryShortcutLabel(action: "undo" | "redo"): string {
   const isMac =
     typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/i.test(navigator.platform);
   const modifier = isMac ? "Cmd" : "Ctrl";
   return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
 }
 
+/** The Undo / Redo tooltip: the shortcut always, the last action's name when there is one. */
+export function historyTooltipLabel(
+  action: "undo" | "redo",
+  lastAction: string | null | undefined,
+): string {
+  const shortcut = getHistoryShortcutLabel(action);
+  const verb = action === "undo" ? "Undo" : "Redo";
+  return lastAction ? `${verb} ${lastAction} (${shortcut})` : `${verb} (${shortcut})`;
+}
+
 export type ElementMatchSelection = Pick<
   DomEditSelection,
   | "id"

package/src/utils/studioUiPreferences.ts

@@ -1,3 +1,6 @@
+import type { SerializedDockview } from "dockview-react";
+import { parseDockLayout } from "../components/dock/dockLayoutSchema";
+
 export interface StoredPreviewZoomState {
   zoomPercent: number;
   panX: number;
@@ -47,6 +50,8 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
+  /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
+  dockLayout?: SerializedDockview;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -169,6 +174,8 @@ function readStorage(storage: Storage | null, key: string): StudioUiPreferences
     if (typeof parsed.agentToolsEnabled === "boolean") {
       preferences.agentToolsEnabled = parsed.agentToolsEnabled;
     }
+    const dockLayout = parseDockLayout(parsed.dockLayout);
+    if (dockLayout) preferences.dockLayout = dockLayout;
     return preferences;
   } catch {
     return {};

package/src/utils/timelineDropTrackInsert.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../player";
+import {
+  applyTrackRenumbers,
+  planDropTrackInsert,
+  resolveDropTrack,
+} from "./timelineDropTrackInsert";
+
+function clip(id: string, track: number, start: number): TimelineElement {
+  return {
+    id,
+    key: id,
+    tag: "div",
+    start,
+    duration: 2,
+    track,
+    authoredTrack: track,
+    hfId: `hf-${id}`,
+    domId: id,
+    // Main-document elements carry no sourceFile, as in production.
+  };
+}
+
+const trackOrder = [0, 1, 2];
+const dropped = { id: "new", tag: "img", start: 5, duration: 3 };
+const elements = [clip("a", 0, 0), clip("b", 1, 0), clip("c", 2, 0)];
+const source = elements
+  .map(
+    (e) =>
+      `<div data-hf-id="${e.hfId}" id="${e.id}" data-start="0" data-track-index="${e.track}"></div>`,
+  )
+  .join("\n");
+
+describe("planDropTrackInsert", () => {
+  it("opens a lane between two rows and pushes the lanes below down", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("opens a lane above the first row", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 0, dropped });
+    expect(plan?.track).toBe(0);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("still renumbers when the peers' own sourceFile is a real path, not undefined", () => {
+    const subComp = elements.map((e) => ({ ...e, sourceFile: "sub.html" }));
+    const plan = planDropTrackInsert({ elements: subComp, trackOrder, insertRow: 1, dropped });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+});
+
+describe("planDropTrackInsert against the display row order", () => {
+  it("counts an audio-group anchor row the way a clip drag does", () => {
+    // Rows shown: group anchor (-0.5), track 0, track 1. Row boundary 2 is between 0 and 1.
+    const grouped = elements.slice(0, 2).map((e) => (e.id === "a" ? { ...e, audioGroup: "g" } : e));
+    const plan = planDropTrackInsert({
+      elements: grouped,
+      trackOrder: [-0.5, 0, 1],
+      insertRow: 2,
+      dropped,
+    });
+    expect(plan?.track).toBe(1);
+    expect(plan?.renumbers.map((r) => [r.element.id, r.track])).toEqual([["b", 2]]);
+  });
+});
+
+describe("applyTrackRenumbers", () => {
+  it("rewrites only the renumbered clips' data-track-index", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    const out = applyTrackRenumbers(source, plan!);
+    const tracks = [...out.matchAll(/id="(\w)"[^>]*data-track-index="(\d+)"/g)].map((m) => [
+      m[1],
+      +m[2],
+    ]);
+    expect(tracks).toEqual([
+      ["a", 0],
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+
+  it("throws when a clip's opening tag is missing", () => {
+    const plan = planDropTrackInsert({ elements, trackOrder, insertRow: 1, dropped });
+    expect(() => applyTrackRenumbers("<div></div>", plan!)).toThrow(/Cannot renumber/);
+  });
+});
+
+describe("resolveDropTrack", () => {
+  it("keeps the aimed lane and the source when no insert is asked for", () => {
+    const out = resolveDropTrack({
+      source,
+      elements,
+      placement: { track: 2 },
+      dropped,
+    });
+    expect(out).toEqual({ source, track: 2 });
+  });
+
+  it("returns the new lane and the source with the lanes below pushed down", () => {
+    const out = resolveDropTrack({
+      source,
+      elements,
+      placement: { track: 1, insertRow: 1, trackOrder },
+      dropped,
+    });
+    expect(out.track).toBe(1);
+    expect(out.source).toContain('id="b" data-start="0" data-track-index="2"');
+  });
+
+  it("refuses to insert when a locked clip would have to move", () => {
+    const locked = elements.map((e) => (e.id === "b" ? { ...e, timelineLocked: true } : e));
+    expect(() =>
+      resolveDropTrack({
+        source,
+        elements: locked,
+        placement: { track: 1, insertRow: 1, trackOrder },
+        dropped,
+      }),
+    ).toThrow(/locked/);
+  });
+});

package/src/utils/timelineDropTrackInsert.ts

@@ -0,0 +1,83 @@
+import type { TimelineElement } from "../player";
+import { layoutAfterTrackInsert } from "../player/components/timelineDragLanding";
+import { canMoveTimelineElement } from "../player/components/timelineAuthoredMoveTarget";
+import type { TimelineDropPlacement } from "../player/components/timelineCallbacks";
+import { applyPatchByTarget, readAttributeByTarget } from "./sourcePatcher";
+import { buildPatchTarget } from "../hooks/timelineEditingHelpers";
+import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
+
+export interface DropTrackInsertPlan {
+  /** Lane the dropped clip is written on. */
+  track: number;
+  /** Existing clips whose lane changes to make room. */
+  renumbers: Array<{ element: TimelineElement; track: number }>;
+}
+
+/** Plan a new lane at boundary `insertRow` with the renumber a clip drag into a gutter uses.
+ *  Null when a locked clip would have to move. */
+export function planDropTrackInsert(input: {
+  elements: TimelineElement[];
+  /** The row order the timeline shows (anchor rows included), which `insertRow` indexes. */
+  trackOrder: readonly number[];
+  insertRow: number;
+  dropped: Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
+}): DropTrackInsertPlan | null {
+  const { elements, trackOrder, insertRow, dropped } = input;
+  const newElement: TimelineElement = {
+    ...dropped,
+    key: dropped.id,
+    // Parked on an existing lane so it adds no lane of its own to the topology.
+    track: elements[0]?.track ?? 0,
+    // sameSourceFile compares this raw field: borrow the peers' value, not the resolved path.
+    sourceFile: elements[0]?.sourceFile,
+  };
+  const layout = layoutAfterTrackInsert(newElement, dropped.start, insertRow, null, {
+    elements: [...elements, newElement],
+    trackOrder: [...trackOrder],
+  });
+  if (!layout) return null;
+  const byKey = new Map(elements.map((e) => [e.key ?? e.id, e]));
+  const renumbers: DropTrackInsertPlan["renumbers"] = [];
+  for (const norm of layout.normalized) {
+    const key = norm.key ?? norm.id;
+    if (key === dropped.id) continue;
+    const src = byKey.get(key);
+    if (!src || norm.track === (src.authoredTrack ?? src.track)) continue;
+    if (!canMoveTimelineElement(src)) return null;
+    renumbers.push({ element: src, track: norm.track });
+  }
+  const track = layout.normalized.find((n) => (n.key ?? n.id) === dropped.id)?.track;
+  return track == null ? null : { track, renumbers };
+}
+
+/** Rewrite `data-track-index` on each renumbered clip's opening tag, via the shared source patcher. */
+export function applyTrackRenumbers(source: string, plan: DropTrackInsertPlan): string {
+  let out = source;
+  for (const { element, track } of plan.renumbers) {
+    const target = buildPatchTarget(element);
+    if (!target || readAttributeByTarget(out, target, "track-index") === undefined) {
+      throw new Error(`Cannot renumber the track of "${element.id}" in the source`);
+    }
+    out = applyPatchByTarget(out, target, {
+      type: "attribute",
+      property: "track-index",
+      value: formatTimelineAttributeNumber(track),
+    });
+  }
+  return out;
+}
+
+/** The lane a dropped clip is written on and the source with any lanes pushed down to make room. */
+export function resolveDropTrack(input: {
+  source: string;
+  elements: TimelineElement[];
+  placement: TimelineDropPlacement;
+  dropped: Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
+}): { source: string; track: number } {
+  const { source, elements, placement, dropped } = input;
+  if (placement.insertRow == null) return { source, track: placement.track };
+  const { insertRow, trackOrder } = placement;
+  const plan = planDropTrackInsert({ elements, trackOrder, insertRow, dropped });
+  if (!plan) throw new Error("Cannot open a new track here: a locked clip would have to move.");
+  return { source: applyTrackRenumbers(source, plan), track: plan.track };
+}

package/src/utils/typingTarget.ts

@@ -33,6 +33,10 @@ const TYPING_SELECTOR = [
   "[role='textbox']",
   "[role='searchbox']",
   "[role='combobox']",
+  // A switch is a button in the DOM, but the native checkbox it replaces was an
+  // `input` and matched above. Without this row the shared Toggle would let a
+  // global shortcut claim Space instead of flipping the control (KTD13).
+  "[role='switch']",
   ".cm-editor",
 ].join(",");