@hyperframes/studio 0.8.51 → 0.8.52

package/src/components/dock/Dock.test.tsx

@@ -1,8 +1,10 @@
 // @vitest-environment happy-dom
 
-import React, { act } from "react";
+import React, { act, type ComponentProps } from "react";
+import type { DockviewApi } from "dockview-react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as dockLayout from "./dockLayout";
 import { Dock } from "./Dock";
 import { parseDockLayout } from "./dockLayoutSchema";
 import { useDockLayoutStore } from "./dockLayoutStore";
@@ -11,13 +13,45 @@ import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+let dockApi: DockviewApi | null = null;
+vi.mock("dockview-react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("dockview-react")>();
+  return {
+    ...actual,
+    DockviewReact: (props: ComponentProps<typeof actual.DockviewReact>) =>
+      React.createElement(actual.DockviewReact, {
+        ...props,
+        onReady: (event) => {
+          dockApi = event.api;
+          props.onReady(event);
+        },
+      }),
+  };
+});
+
+const liveObservers = new Set<{ callback: () => void; target?: Element }>();
 class ResizeObserverStub {
-  observe() {}
+  private readonly entry: { callback: () => void; target?: Element };
+  constructor(callback: () => void) {
+    this.entry = { callback };
+  }
+  observe(target: Element) {
+    this.entry.target = target;
+    liveObservers.add(this.entry);
+  }
   unobserve() {}
-  disconnect() {}
+  disconnect() {
+    liveObservers.delete(this.entry);
+  }
 }
 (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = ResizeObserverStub;
 
+vi.mock("./dockLayout", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./dockLayout")>();
+  return { ...actual, applySideMinimums: vi.fn(actual.applySideMinimums) };
+});
+const applySideMinimums = vi.mocked(dockLayout.applySideMinimums);
+
 let root: Root | null = null;
 
 function mount(projectId: string | null) {
@@ -38,6 +72,16 @@ function mount(projectId: string | null) {
   return host;
 }
 
+/** The persisted views of the group holding `id`, after the debounced write lands. */
+function persistedGroupOf(id: string): string | undefined {
+  act(() => {
+    vi.advanceTimersByTime(1000);
+  });
+  const grid = JSON.stringify(readStudioUiPreferences(undefined, "p1").dockLayout?.grid);
+  const groups = [...grid.matchAll(/"views":\[([^\]]*)\]/g)].map((m) => m[1]);
+  return groups.find((views) => views.includes(`"${id}"`));
+}
+
 beforeEach(() => {
   localStorage.clear();
   vi.useFakeTimers();
@@ -102,13 +146,7 @@ describe("Dock on React 19", () => {
     mount("p1");
     act(() => useDockLayoutStore.getState().closePanel("compositions"));
     act(() => useDockLayoutStore.getState().togglePanel("compositions"));
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
-    const grid = JSON.stringify(readStudioUiPreferences(undefined, "p1").dockLayout?.grid);
-    const groups = [...grid.matchAll(/"views":\[([^\]]*)\]/g)].map((m) => m[1]);
-    const home = groups.find((views) => views.includes('"compositions"'));
-    expect(home).toContain('"assets"');
+    expect(persistedGroupOf("compositions")).toContain('"assets"');
   });
 
   it("reopens a side panel next to the preview when its whole column was closed", () => {
@@ -125,12 +163,7 @@ describe("Dock on React 19", () => {
     mount("p1");
     act(() => useDockLayoutStore.getState().closePanel("timeline"));
     act(() => useDockLayoutStore.getState().togglePanel("timeline"));
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
-    const grid = JSON.stringify(readStudioUiPreferences(undefined, "p1").dockLayout?.grid);
-    const groups = [...grid.matchAll(/"views":\[([^\]]*)\]/g)].map((m) => m[1]);
-    expect(groups.find((views) => views.includes('"timeline"'))).not.toContain('"preview"');
+    expect(persistedGroupOf("timeline")).not.toContain('"preview"');
   });
 
   it("restores the stored layout on the next mount instead of rebuilding the default", () => {
@@ -157,6 +190,41 @@ describe("Dock on React 19", () => {
   });
 });
 
+describe("Dock wiring", () => {
+  it("re-applies the side minimums when a panel is dragged to another group", () => {
+    mount(null);
+    applySideMinimums.mockClear();
+    const preview = dockApi?.getPanel("preview");
+    const design = dockApi?.getPanel("design");
+    if (!preview || !design) throw new Error("default layout is missing panels");
+    act(() => design.api.moveTo({ group: preview.group }));
+    expect(applySideMinimums).toHaveBeenCalled();
+  });
+
+  it("makes the sashes keyboard-focusable separators", () => {
+    const host = mount(null);
+    const sashes = host.querySelectorAll<HTMLElement>('.dv-sash[role="separator"]');
+    expect(sashes.length).toBeGreaterThan(0);
+    for (const sash of sashes) expect(sash.tabIndex).toBe(0);
+  });
+
+  it("re-fits the side columns to the window width when it resizes", () => {
+    mount(null);
+    const innerWidth = window.innerWidth;
+    Object.defineProperty(window, "innerWidth", { value: 560, configurable: true });
+    try {
+      applySideMinimums.mockClear();
+      const dockObservers = [...liveObservers].filter(({ target }) =>
+        target?.classList.contains("hf-dock"),
+      );
+      act(() => dockObservers.forEach(({ callback }) => callback()));
+      expect(applySideMinimums).toHaveBeenCalledWith(expect.anything(), 560);
+    } finally {
+      Object.defineProperty(window, "innerWidth", { value: innerWidth, configurable: true });
+    }
+  });
+});
+
 describe("parseDockLayout", () => {
   it("rejects shapes that are not a dock layout", () => {
     expect(parseDockLayout(null)).toBeNull();

package/src/components/dock/Dock.tsx

@@ -15,7 +15,8 @@ import {
   type IDockviewPanelProps,
 } from "dockview-react";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
-import { addRegisteredPanel, buildEditLayout } from "./dockLayout";
+import { installDockAccessibility } from "./dockAccessibility";
+import { addRegisteredPanel, applySideMinimums, buildEditLayout } from "./dockLayout";
 import { DOCK_PANEL_COMPONENT } from "./dockLayoutSchema";
 import { useDockLayoutStore, type DockController, type DockSnapshot } from "./dockLayoutStore";
 import {
@@ -135,7 +136,14 @@ function Root({ projectId, children }: { projectId: string | null; children: Rea
 
   const onReady = useCallback(
     ({ api }: DockviewReadyEvent) => {
+      disposeRef.current();
       restoreOrBuild(api, projectId);
+      applySideMinimums(api);
+      const root = api.groups[0]?.element.closest<HTMLElement>(".hf-dock");
+      const disposeAccessibility = root ? installDockAccessibility(api, root) : () => {};
+      // The dock spans the window (buildEditLayout sizes against it too); its own box lags a resize.
+      const resizeObserver = new ResizeObserver(() => applySideMinimums(api, window.innerWidth));
+      if (root) resizeObserver.observe(root);
       const store = useDockLayoutStore.getState();
       store.attach(createController(api));
       store.sync(snapshot(api));
@@ -156,7 +164,14 @@ function Root({ projectId, children }: { projectId: string | null; children: Rea
         persist();
       };
       const subscriptions = [
-        api.onDidAddPanel(onDockChange),
+        api.onDidAddPanel(() => {
+          applySideMinimums(api);
+          onDockChange();
+        }),
+        api.onDidMovePanel(() => {
+          applySideMinimums(api);
+          onDockChange();
+        }),
         api.onDidRemovePanel(onDockChange),
         api.onDidActivePanelChange(onDockChange),
         api.onDidLayoutChange(onDockChange),
@@ -164,6 +179,8 @@ function Root({ projectId, children }: { projectId: string | null; children: Rea
       disposeRef.current = () => {
         clearTimeout(timer);
         for (const subscription of subscriptions) subscription.dispose();
+        disposeAccessibility();
+        resizeObserver.disconnect();
         useDockLayoutStore.getState().detach();
       };
     },

package/src/components/dock/dock.css

@@ -21,3 +21,8 @@
   --dv-tab-font-size: 11px;
   --dv-tabs-and-actions-container-font-size: 11px;
 }
+
+.hf-dock .dv-sash:focus-visible {
+  background-color: var(--dv-active-sash-color);
+  outline: none;
+}

package/src/components/dock/dockAccessibility.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment happy-dom
+
+import type { DockviewApi } from "dockview-react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mountBareDockview } from "./dockTestHarness";
+import { installDockAccessibility } from "./dockAccessibility";
+import { applySideMinimums, buildEditLayout } from "./dockLayout";
+
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = ResizeObserverStub;
+
+let host: HTMLElement;
+let api: DockviewApi;
+let dispose: () => void;
+
+beforeEach(() => {
+  ({ host, api } = mountBareDockview());
+  api.layout(1200, 700);
+  buildEditLayout(api, 1200);
+  applySideMinimums(api, 1200);
+  dispose = installDockAccessibility(api, host);
+});
+
+afterEach(() => {
+  dispose();
+  api.dispose();
+  document.body.innerHTML = "";
+});
+
+const sashes = () => [...host.querySelectorAll<HTMLElement>(".dv-sash")];
+const columnSash = (index: number) =>
+  sashes().filter((sash) => sash.getAttribute("aria-orientation") === "vertical")[
+    index
+  ] as HTMLElement;
+const widthOf = (panel: string) => api.getPanel(panel)?.group.width;
+const press = (target: Element, key: string, init: KeyboardEventInit = {}) =>
+  target.dispatchEvent(
+    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, ...init }),
+  );
+
+describe("dock sashes", () => {
+  it("are focusable separators with an orientation and a label", () => {
+    expect(sashes()).toHaveLength(3);
+    for (const sash of sashes()) {
+      expect(sash.getAttribute("role")).toBe("separator");
+      expect(sash.tabIndex).toBe(0);
+      const label = sash.getAttribute("aria-label");
+      const orientation = sash.getAttribute("aria-orientation");
+      expect(label).toBe(orientation === "vertical" ? "Resize columns" : "Resize rows");
+    }
+    expect(
+      sashes()
+        .map((sash) => sash.getAttribute("aria-orientation"))
+        .sort(),
+    ).toEqual(["horizontal", "vertical", "vertical"]);
+  });
+
+  it("are decorated again after a layout restore rebuilds them", () => {
+    api.fromJSON(api.toJSON());
+    expect(sashes()).toHaveLength(3);
+    for (const sash of sashes()) expect(sash.getAttribute("role")).toBe("separator");
+  });
+
+  it("resize the neighbouring groups by 16px per arrow press, 64px with Shift", () => {
+    const left = widthOf("compositions") as number;
+    const preview = widthOf("preview") as number;
+    const sash = columnSash(0);
+    press(sash, "ArrowRight");
+    expect(widthOf("compositions")).toBe(left + 16);
+    expect(widthOf("preview")).toBe(preview - 16);
+    press(sash, "ArrowRight", { shiftKey: true });
+    expect(widthOf("compositions")).toBe(left + 80);
+    press(sash, "ArrowLeft");
+    expect(widthOf("compositions")).toBe(left + 64);
+  });
+
+  it("stop at the panels' minimum sizes", () => {
+    const sash = columnSash(0);
+    for (let i = 0; i < 20; i++) press(sash, "ArrowLeft", { shiftKey: true });
+    expect(widthOf("compositions")).toBe(200);
+    for (let i = 0; i < 40; i++) press(sash, "ArrowRight", { shiftKey: true });
+    expect(widthOf("preview")).toBe(360);
+  });
+
+  it("ignore the arrow keys of the other axis and keys pressed anywhere else", () => {
+    const left = widthOf("compositions");
+    press(columnSash(0), "ArrowDown");
+    press(host, "ArrowRight");
+    press(document.body, "ArrowRight");
+    expect(widthOf("compositions")).toBe(left);
+  });
+
+  it("resize rows with the vertical arrows", () => {
+    const timeline = api.getPanel("timeline")?.group.height as number;
+    const rows = sashes().find((sash) => sash.getAttribute("aria-orientation") === "horizontal");
+    press(rows as HTMLElement, "ArrowUp");
+    expect(api.getPanel("timeline")?.group.height).toBe(timeline + 16);
+  });
+});
+
+describe("dock tab strips", () => {
+  const tabsOf = (panel: string) => [
+    ...(api.getPanel(panel)?.group.element.querySelectorAll<HTMLElement>('[role="tab"]') ?? []),
+  ];
+
+  it("keep dockview's tablist, tab and selected roles with one tab stop", () => {
+    const tabs = tabsOf("compositions");
+    expect(tabs).toHaveLength(4);
+    expect(tabs[0]?.closest('[role="tablist"]')).not.toBeNull();
+    expect(tabs.map((tab) => tab.getAttribute("aria-selected"))).toEqual([
+      "true",
+      "false",
+      "false",
+      "false",
+    ]);
+    expect(tabs.map((tab) => tab.tabIndex)).toEqual([0, -1, -1, -1]);
+  });
+
+  it("leave browser shortcuts alone when Alt, Ctrl or Meta is held", () => {
+    const sash = columnSash(0);
+    const left = widthOf("compositions");
+    const tab = tabsOf("compositions")[0] as HTMLElement;
+    const active = () => api.getPanel("compositions")?.group.activePanel?.id;
+    for (const init of [{ altKey: true }, { ctrlKey: true }, { metaKey: true }]) {
+      const onSash = new KeyboardEvent("keydown", {
+        key: "ArrowRight",
+        cancelable: true,
+        bubbles: true,
+        ...init,
+      });
+      sash.dispatchEvent(onSash);
+      press(tab, "ArrowRight", init);
+      expect(onSash.defaultPrevented).toBe(false);
+      expect(active()).toBe("compositions");
+    }
+    expect(widthOf("compositions")).toBe(left);
+  });
+
+  it("move focus and activate the neighbouring tab, wrapping at both ends", () => {
+    const tabs = tabsOf("compositions");
+    const active = () => api.getPanel("compositions")?.group.activePanel?.id;
+    (tabs[0] as HTMLElement).focus();
+    press(tabs[0] as HTMLElement, "ArrowRight");
+    expect(active()).toBe("assets");
+    expect(document.activeElement).toBe(tabs[1]);
+    press(tabs[1] as HTMLElement, "ArrowLeft");
+    press(tabs[0] as HTMLElement, "ArrowLeft");
+    expect(active()).toBe("catalog");
+    expect(document.activeElement).toBe(tabs[3]);
+    press(tabs[3] as HTMLElement, "ArrowRight");
+    expect(active()).toBe("compositions");
+  });
+
+  it("jump to the first and last tab with Home and End", () => {
+    const tabs = tabsOf("design");
+    press(tabs[0] as HTMLElement, "End");
+    expect(api.getPanel("design")?.group.activePanel?.id).toBe("variables");
+    expect(document.activeElement).toBe(tabs[3]);
+    press(tabs[3] as HTMLElement, "Home");
+    expect(api.getPanel("design")?.group.activePanel?.id).toBe("design");
+  });
+});

package/src/components/dock/dockAccessibility.ts

@@ -0,0 +1,98 @@
+import type { DockviewApi } from "dockview-react";
+
+const SASH_STEP = 16;
+const SASH_STEP_SHIFT = 64;
+
+type Axis = "horizontal" | "vertical";
+
+/** A horizontal split lays views left to right, so its sashes are vertical bars. */
+function splitAxis(sash: HTMLElement): Axis {
+  return sash.closest(".dv-split-view-container")?.classList.contains("dv-horizontal")
+    ? "horizontal"
+    : "vertical";
+}
+
+/** Dockview draws sashes as bare divs; make each one a focusable separator. */
+function decorateSashes(root: HTMLElement) {
+  for (const sash of root.querySelectorAll<HTMLElement>(".dv-sash")) {
+    const axis = splitAxis(sash);
+    sash.tabIndex = 0;
+    sash.setAttribute("role", "separator");
+    sash.setAttribute("aria-orientation", axis === "horizontal" ? "vertical" : "horizontal");
+    sash.setAttribute("aria-label", axis === "horizontal" ? "Resize columns" : "Resize rows");
+  }
+}
+
+/** Replays a pointer drag on the sash so dockview's own clamping to minimum sizes applies. */
+function nudgeSash(sash: HTMLElement, axis: Axis, delta: number) {
+  const at = (value: number) =>
+    axis === "horizontal" ? { clientX: value, clientY: 0 } : { clientX: 0, clientY: value };
+  const doc = sash.ownerDocument;
+  const fire = (target: EventTarget, type: string, value: number) =>
+    target.dispatchEvent(new MouseEvent(type, { ...at(value), bubbles: true, cancelable: true }));
+  fire(sash, "pointerdown", 0);
+  fire(doc, "pointermove", delta);
+  fire(doc, "pointerup", delta);
+}
+
+/** Browser and OS shortcuts (Alt+Left is Back) keep their meaning. */
+function hasShortcutModifier(event: KeyboardEvent) {
+  return event.altKey || event.ctrlKey || event.metaKey;
+}
+
+function onSashKeyDown(event: KeyboardEvent, sash: HTMLElement) {
+  if (hasShortcutModifier(event)) return;
+  const axis = splitAxis(sash);
+  const [less, more] =
+    axis === "horizontal" ? ["ArrowLeft", "ArrowRight"] : ["ArrowUp", "ArrowDown"];
+  if (event.key !== less && event.key !== more) return;
+  event.preventDefault();
+  const step = event.shiftKey ? SASH_STEP_SHIFT : SASH_STEP;
+  nudgeSash(sash, axis, event.key === more ? step : -step);
+}
+
+/** Wraps around and activates the tab it lands on, unlike dockview's focus-only arrows. */
+function onTabKeyDown(event: KeyboardEvent, tab: HTMLElement, api: DockviewApi) {
+  if (hasShortcutModifier(event)) return;
+  const tabs = [
+    ...(tab.closest('[role="tablist"]')?.querySelectorAll<HTMLElement>('[role="tab"]') ?? []),
+  ];
+  const index = tabs.indexOf(tab);
+  const last = tabs.length - 1;
+  const targets: Record<string, number> = {
+    ArrowRight: index === last ? 0 : index + 1,
+    ArrowLeft: index === 0 ? last : index - 1,
+    Home: 0,
+    End: last,
+  };
+  const target = tabs[targets[event.key] ?? -1];
+  if (!target) return;
+  event.preventDefault();
+  event.stopPropagation();
+  const panelId = target.dataset.tabPanelId;
+  if (panelId) api.getPanel(panelId)?.api.setActive();
+  target.focus();
+}
+
+/** Keyboard and ARIA support dockview 8.3 lacks for sashes and tab arrows. Returns a disposer. */
+export function installDockAccessibility(api: DockviewApi, root: HTMLElement): () => void {
+  const decorate = () => decorateSashes(root);
+  decorate();
+  const subscriptions = [
+    api.onDidLayoutChange(decorate),
+    api.onDidLayoutFromJSON(decorate),
+    api.onDidAddPanel(decorate),
+    api.onDidRemovePanel(decorate),
+  ];
+  // Capture phase so the tab handler runs before dockview's own focus-only arrows.
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (!(event.target instanceof HTMLElement)) return;
+    if (event.target.classList.contains("dv-sash")) onSashKeyDown(event, event.target);
+    else if (event.target.getAttribute("role") === "tab") onTabKeyDown(event, event.target, api);
+  };
+  root.addEventListener("keydown", onKeyDown, true);
+  return () => {
+    root.removeEventListener("keydown", onKeyDown, true);
+    for (const subscription of subscriptions) subscription.dispose();
+  };
+}

package/src/components/dock/dockLayout.test.ts

@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+
+import type { DockviewApi } from "dockview-react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  applySideMinimums,
+  buildEditLayout,
+  defaultSideWidths,
+  sideMinimumWidth,
+} from "./dockLayout";
+import { mountBareDockview } from "./dockTestHarness";
+
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = ResizeObserverStub;
+
+// Expected values are hand-derived from the old fitPanels rule: the preview keeps 360 first,
+// then each side column takes half of what remains, never above 200 or below 120.
+describe("sideMinimumWidth", () => {
+  it.each([
+    [1680, 200],
+    [1200, 200],
+    [860, 200],
+    [760, 200],
+    [700, 170],
+    [600, 120],
+    [560, 120],
+    [400, 120],
+  ])("is %ipx wide -> sides shrink to %ipx at most", (viewport, expected) => {
+    expect(sideMinimumWidth(viewport)).toBe(expected);
+  });
+});
+
+describe("defaultSideWidths", () => {
+  it.each([
+    [1680, 384, 424],
+    [1280, 329, 364],
+    [860, 221, 244],
+    [560, 120, 120],
+  ])("at %ipx gives %i / %i", (viewport, left, right) => {
+    expect(defaultSideWidths(viewport)).toEqual({ left, right });
+  });
+
+  it.each([1680, 1280, 1000, 860, 760, 700, 600, 560, 480])(
+    "leaves the preview its 360px floor at %ipx whenever the sides can shrink enough",
+    (viewport) => {
+      const { left, right } = defaultSideWidths(viewport);
+      const floor = sideMinimumWidth(viewport);
+      const overflow = left + right + 360 - viewport;
+      expect(overflow <= 0 || (left === floor && right === floor)).toBe(true);
+    },
+  );
+});
+
+describe("applySideMinimums", () => {
+  let api: DockviewApi;
+  beforeEach(() => {
+    ({ api } = mountBareDockview());
+  });
+  afterEach(() => {
+    api.dispose();
+    document.body.innerHTML = "";
+  });
+
+  it("lowers side groups' minimum on a narrow window and shrinks them, never touching the preview", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    applySideMinimums(api, 560);
+    expect(api.getPanel("compositions")?.group.minimumWidth).toBe(120);
+    expect(api.getPanel("design")?.group.minimumWidth).toBe(120);
+    expect(api.getPanel("compositions")?.group.width).toBe(120);
+    expect(api.getPanel("design")?.group.width).toBe(120);
+    expect(api.getPanel("preview")?.group.minimumWidth).toBe(360);
+  });
+
+  it("leaves a wide window's user-chosen widths alone", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    api.getPanel("compositions")?.group.api.setSize({ width: 300 });
+    applySideMinimums(api, 1200);
+    expect(api.getPanel("compositions")?.group.width).toBe(300);
+  });
+
+  it("keeps the preview's floor when a side panel is tabbed into the preview group", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    const preview = api.getPanel("preview");
+    const design = api.getPanel("design");
+    if (!preview || !design) throw new Error("default layout is missing panels");
+    design.api.moveTo({ group: preview.group, position: "center", index: 0 });
+    preview.api.setActive();
+    applySideMinimums(api, 560);
+    expect(preview.group.minimumWidth).toBe(360);
+  });
+
+  it("pins the preview floor when a side panel that was showing gets the preview dragged in", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    applySideMinimums(api, 560);
+    const preview = api.getPanel("preview");
+    const design = api.getPanel("design");
+    if (!preview || !design) throw new Error("default layout is missing panels");
+    preview.api.moveTo({ group: design.group });
+    applySideMinimums(api, 560);
+    expect(preview.group.minimumWidth).toBe(360);
+  });
+
+  it("rewrites the minimum of a group that is neither the preview nor side-only", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    const timeline = api.getPanel("timeline");
+    const compositions = api.getPanel("compositions");
+    if (!timeline || !compositions) throw new Error("default layout is missing panels");
+    timeline.api.moveTo({ group: compositions.group });
+    applySideMinimums(api, 560);
+    expect(compositions.group.minimumWidth).toBe(120);
+  });
+
+  it("drops the preview floor from a group the preview has left", () => {
+    api.layout(1200, 700);
+    buildEditLayout(api, 1200);
+    const preview = api.getPanel("preview");
+    const timeline = api.getPanel("timeline");
+    if (!preview || !timeline) throw new Error("default layout is missing panels");
+    preview.api.moveTo({ group: timeline.group });
+    applySideMinimums(api, 560);
+    preview.api.moveTo({ position: "right", group: api.getPanel("design")?.group });
+    applySideMinimums(api, 560);
+    expect(timeline.group.minimumWidth).toBe(120);
+  });
+});

package/src/components/dock/dockLayout.ts

@@ -1,18 +1,64 @@
 import type { Direction, DockviewApi } from "dockview-react";
 import { DOCK_PANEL_COMPONENT } from "./dockLayoutSchema";
-import { PANEL_DEFINITIONS, type PanelId } from "./panelRegistry";
+import { PANEL_DEFINITIONS, isPanelId, type PanelId } from "./panelRegistry";
 
 const MIN_PREVIEW_W = 360;
 const MIN_PREVIEW_H = 200;
 const MIN_TIMELINE_H = 100;
 const MIN_SIDE_W = 200;
+const MIN_SIDE_W_FLOOR = 120;
 const DEFAULT_TIMELINE_H = 360;
 
-function defaultSideWidths(viewportWidth: number) {
-  return {
-    left: Math.max(MIN_SIDE_W, Math.min(384, Math.round(viewportWidth * 0.257))),
-    right: Math.max(280, Math.min(424, Math.round(viewportWidth * 0.284))),
-  };
+/** Preferred side widths; when they overflow the preview's floor the right yields first, then the left. */
+export function defaultSideWidths(viewportWidth: number) {
+  const floor = sideMinimumWidth(viewportWidth);
+  const left = Math.max(floor, Math.min(384, Math.round(viewportWidth * 0.257)));
+  const right = Math.max(Math.min(280, floor), Math.min(424, Math.round(viewportWidth * 0.284)));
+  const excess = left + right - Math.max(0, viewportWidth - MIN_PREVIEW_W);
+  if (excess <= 0) return { left, right };
+  const shrunkRight = Math.max(floor, right - excess);
+  return { left: Math.max(floor, left - (excess - (right - shrunkRight))), right: shrunkRight };
+}
+
+/**
+ * Side groups keep MIN_SIDE_W while both fit beside the preview's floor, then shrink down to
+ * MIN_SIDE_W_FLOOR; below that the dock overflows and clips rather than squeezing the preview.
+ */
+export function sideMinimumWidth(dockWidth: number): number {
+  const fair = Math.floor((dockWidth - MIN_PREVIEW_W) / 2);
+  return Math.min(MIN_SIDE_W, Math.max(MIN_SIDE_W_FLOOR, fair));
+}
+
+function holdsPreview(group: DockviewApi["groups"][number]) {
+  return group.panels.some((panel) => panel.id === "preview");
+}
+
+/** The zone of a group whose every tab is a side panel, else null. */
+function sideZone(group: DockviewApi["groups"][number]): "left" | "right" | null {
+  const zones = group.panels.map((panel) =>
+    isPanelId(panel.id) ? PANEL_DEFINITIONS[panel.id].zone : "center",
+  );
+  const first = zones[0];
+  const allSide = zones.every((zone) => zone !== "center");
+  return allSide && first && first !== "center" ? first : null;
+}
+
+/** Idempotent; rewrites every group's minimum, since dockview keeps a constraint once set. */
+export function applySideMinimums(api: DockviewApi, dockWidth = window.innerWidth) {
+  const minimumWidth = sideMinimumWidth(dockWidth);
+  const cap = defaultSideWidths(dockWidth);
+  for (const group of api.groups) {
+    if (holdsPreview(group)) {
+      group.api.setConstraints({ minimumWidth: MIN_PREVIEW_W });
+      continue;
+    }
+    group.api.setConstraints({ minimumWidth });
+    const zone = sideZone(group);
+    const limit = zone === "right" ? cap.right : cap.left;
+    if (zone && minimumWidth < MIN_SIDE_W && group.width > limit) {
+      group.api.setSize({ width: limit });
+    }
+  }
 }
 
 function minimumSize(id: PanelId) {
@@ -52,6 +98,7 @@ export function buildEditLayout(api: DockviewApi, viewportWidth: number) {
   }
   api.getPanel("compositions")?.api.setActive();
   api.getPanel("design")?.api.setActive();
+  applySideMinimums(api, viewportWidth);
   api.getPanel("compositions")?.group.api.setSize({ width: widths.left });
   api.getPanel("design")?.group.api.setSize({ width: widths.right });
   api.getPanel("timeline")?.group.api.setSize({ height: DEFAULT_TIMELINE_H });