@hyperframes/studio 0.8.190 → 0.8.192

package/src/components/panels/MotionBlurPanel.test.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import { MotionBlurPanel } from "./MotionBlurPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const page = (attrs = "") =>
+  `<!DOCTYPE html><html><body><div data-composition-id="main" data-hf-root data-duration="5" data-width="1920" data-height="1080"${attrs}></div></body></html>`;
+
+const shell = {
+  activeCompPath: null as string | null,
+  previewIframeRef: { current: null as HTMLIFrameElement | null },
+  showToast: vi.fn(),
+};
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => shell,
+  useStudioPlaybackContext: () => ({ refreshKey: 0 }),
+}));
+
+const files: Record<string, string> = {};
+const writeProjectFile = vi.fn(async (path: string, content: string) => {
+  files[path] = content;
+});
+vi.mock("../../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile: async (path: string) => files[path] ?? "",
+    writeProjectFile,
+    compositions: ["index.html", "scene.html"],
+  }),
+}));
+
+let root: Root | null = null;
+const recordEdit = vi.fn(async () => {});
+
+function cleanup() {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+}
+
+afterEach(() => {
+  cleanup();
+  shell.activeCompPath = null;
+  shell.previewIframeRef.current = null;
+  vi.clearAllMocks();
+});
+
+async function mount(attrs = "") {
+  files["index.html"] = page(attrs);
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  const session = await openComposition(files["index.html"], { history: false });
+  await act(async () => {
+    root?.render(
+      <MotionBlurPanel
+        sdkSession={session}
+        publishSdkSession={vi.fn()}
+        reloadPreview={vi.fn()}
+        recordEdit={recordEdit}
+      />,
+    );
+  });
+  return host;
+}
+
+const settle = () => act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+const click = async (el: Element | null) => {
+  await act(async () => (el as HTMLElement).click());
+  await settle();
+};
+
+const radio = (host: HTMLElement, label: string) =>
+  [...host.querySelectorAll('[role="radio"]')].find((el) => el.textContent === label) ?? null;
+const checked = (host: HTMLElement) =>
+  [...host.querySelectorAll('[role="radio"]')]
+    .filter((el) => el.getAttribute("aria-checked") === "true")
+    .map((el) => el.textContent);
+
+describe("MotionBlurPanel", () => {
+  it("offers Off, Subtle and Strong and nothing else", async () => {
+    const host = await mount();
+    expect([...host.querySelectorAll('[role="radio"]')].map((el) => el.textContent)).toEqual([
+      "Off",
+      "Subtle",
+      "Strong",
+    ]);
+    expect(
+      host.querySelectorAll('[role="slider"], [role="switch"], [role="combobox"], input'),
+    ).toHaveLength(0);
+  });
+
+  it("shows the level the root is at", async () => {
+    expect(checked(await mount())).toEqual(["Off"]);
+    cleanup();
+    expect(checked(await mount(' data-motion-blur="on"'))).toEqual(["Subtle"]);
+    cleanup();
+    expect(
+      checked(
+        await mount(
+          ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"',
+        ),
+      ),
+    ).toEqual(["Strong"]);
+  });
+
+  it("Subtle writes data-motion-blur and leaves the default shutter off the root", async () => {
+    const host = await mount(
+      ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"',
+    );
+    await click(radio(host, "Subtle"));
+    const html = files["index.html"] ?? "";
+    expect(html).toContain('data-motion-blur="on"');
+    expect(html).not.toContain("data-motion-blur-shutter");
+    expect(html).not.toContain("data-motion-blur-samples");
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it("Strong writes the maximum shutter and samples", async () => {
+    const host = await mount();
+    await click(radio(host, "Strong"));
+    const html = files["index.html"] ?? "";
+    expect(html).toContain('data-motion-blur="on"');
+    expect(html).toContain('data-motion-blur-shutter="720"');
+    expect(html).toContain('data-motion-blur-samples="64"');
+  });
+
+  it("Off removes data-motion-blur and leaves every other setting on the root", async () => {
+    const host = await mount(
+      ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64" data-motion-blur-tier="filter" data-motion-blur-events="on"',
+    );
+    await click(radio(host, "Off"));
+    const html = files["index.html"] ?? "";
+    expect(html).not.toContain('data-motion-blur="on"');
+    for (const kept of ['shutter="720"', 'samples="64"', 'tier="filter"', 'events="on"']) {
+      expect(html).toContain(`data-motion-blur-${kept}`);
+    }
+  });
+
+  it("writes nothing when the chosen level is already set", async () => {
+    const host = await mount(' data-motion-blur="on"');
+    await click(radio(host, "Subtle"));
+    expect(writeProjectFile).not.toHaveBeenCalled();
+  });
+
+  it("follows the live preview over the session, so an undo or an outside edit shows", async () => {
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-motion-blur="on" data-motion-blur-shutter="720"></div>';
+    shell.previewIframeRef.current = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    expect(checked(await mount(' data-motion-blur="on"'))).toEqual(["Strong"]);
+  });
+
+  it("writes the level picked even when the preview and the file disagree", async () => {
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"></div>';
+    shell.previewIframeRef.current = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    const host = await mount();
+    await click(radio(host, "Subtle"));
+    expect(files["index.html"]).toContain('data-motion-blur="on"');
+    expect(files["index.html"]).not.toContain("data-motion-blur-samples");
+  });
+
+  it("is read-only for a sub-composition, which blur does not read", async () => {
+    shell.activeCompPath = "scene.html";
+    const host = await mount();
+    expect(host.textContent).toContain("read from the main composition");
+    expect(radio(host, "Strong")?.hasAttribute("disabled")).toBe(true);
+    expect(checked(host)).toEqual([]);
+  });
+});

package/src/components/panels/MotionBlurPanel.tsx

@@ -0,0 +1,163 @@
+import { memo, useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { MotionBlurSettings } from "@hyperframes/core/motion-blur-settings";
+import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import {
+  useVariablesPersist,
+  type UseVariablesPersistParams,
+} from "../../hooks/useVariablesPersist";
+import { resolveMasterCompositionPath } from "../../utils/studioUrlState";
+import { Button } from "../ui";
+import {
+  BLUR_LEVELS,
+  changedEdits,
+  findCompositionRoot,
+  levelOf,
+  patchForLevel,
+  readPreviewRootAttributes,
+  sameAttributes,
+  settingsOf,
+  withEdits,
+  type BlurLevel,
+  type RootAttributes,
+} from "./motionBlurPanelModel";
+
+export interface MotionBlurPanelProps {
+  sdkSession: Composition | null;
+  publishSdkSession?: UseVariablesPersistParams["publishSdkSession"];
+  reloadPreview: () => void;
+  recordEdit: UseVariablesPersistParams["recordEdit"];
+}
+
+const POLL_MS = 500;
+/** After a write the preview is reloading: keep what was just written instead of the old document. */
+const SETTLE_MS = 1500;
+
+/** Thrown from the edit when the file already holds the level, so nothing is written or recorded for undo. */
+class NothingToChange extends Error {}
+
+/** The preview's own root attributes, polled; `hold` pins an optimistic value until the preview catches up. */
+function useLivePreviewAttributes(
+  previewIframeRef: { current: HTMLIFrameElement | null },
+  refreshKey: number,
+) {
+  const [live, setLive] = useState<RootAttributes | null>(null);
+  const holdUntil = useRef(0);
+  useEffect(() => {
+    const read = () => {
+      const found = readPreviewRootAttributes(previewIframeRef.current);
+      if (found && Date.now() >= holdUntil.current) {
+        setLive((current) => (sameAttributes(current, found) ? current : found));
+      }
+    };
+    read();
+    const timer = setInterval(read, POLL_MS);
+    return () => clearInterval(timer);
+  }, [previewIframeRef, refreshKey]);
+  const hold = useCallback((next: (current: RootAttributes | null) => RootAttributes) => {
+    holdUntil.current = Date.now() + SETTLE_MS;
+    setLive(next);
+  }, []);
+  return [live, hold] as const;
+}
+
+export const MotionBlurPanel = memo(function MotionBlurPanel({
+  sdkSession,
+  publishSdkSession,
+  reloadPreview,
+  recordEdit,
+}: MotionBlurPanelProps) {
+  const { activeCompPath, previewIframeRef, showToast } = useStudioShellContext();
+  const { refreshKey } = useStudioPlaybackContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
+  const [, rerender] = useReducer((n: number) => n + 1, 0);
+  const [live, hold] = useLivePreviewAttributes(previewIframeRef, refreshKey);
+
+  useEffect(() => sdkSession?.on("change", rerender), [sdkSession]);
+
+  const root = sdkSession ? findCompositionRoot(sdkSession.getRootElements()) : null;
+  // The preview's own root is the truth after an undo or an outside edit, which the shared session does not follow.
+  const attributes = live ?? root?.attributes ?? null;
+  const settings = useMemo(() => (attributes ? settingsOf(attributes) : null), [attributes]);
+  const isMain =
+    activeCompPath == null || activeCompPath === resolveMasterCompositionPath(compositions);
+  const persist = useVariablesPersist({
+    sdkSession,
+    activeCompPath,
+    readProjectFile,
+    writeProjectFile,
+    recordEdit,
+    reloadPreview,
+    publishSdkSession,
+  });
+
+  const apply = useCallback(
+    async (patch: Partial<MotionBlurSettings>) => {
+      if (!attributes) return;
+      // The write lands on the file's own root, so the edits are worked out there, not from the preview.
+      let applied: Array<{ name: string; value: string | null }> = [];
+      try {
+        await persist("Edit motion blur", (session) => {
+          const target = findCompositionRoot(session.getRootElements());
+          if (!target) return;
+          const next = { ...settingsOf(target.attributes), ...patch };
+          applied = changedEdits(target.attributes, next);
+          if (applied.length === 0) throw new NothingToChange();
+          for (const e of applied) {
+            session.dispatch({
+              type: "setAttribute",
+              target: target.id,
+              name: e.name,
+              value: e.value,
+            });
+          }
+        });
+        hold((current) => withEdits(current ?? attributes, applied));
+        rerender();
+      } catch (err) {
+        if (err instanceof NothingToChange) return;
+        showToast(err instanceof Error ? err.message : String(err), "error");
+      }
+    },
+    [attributes, persist, hold, showToast],
+  );
+
+  if (!settings) {
+    return (
+      <p className="p-3 text-[10px] leading-relaxed text-neutral-500">
+        Open a composition to set up motion blur.
+      </p>
+    );
+  }
+  const locked = !isMain;
+  // A sub-composition's own root is not the setting being edited, so no level is shown while locked.
+  const current = locked ? null : levelOf(settings);
+
+  return (
+    <div className="flex h-full flex-col gap-3 overflow-y-auto p-3 text-[11px] text-neutral-300">
+      <span className="text-[12px] font-medium text-neutral-100">Motion blur</span>
+      <div role="radiogroup" aria-label="Motion blur" className="flex gap-1.5">
+        {BLUR_LEVELS.map(({ level, label }) => (
+          <Button
+            key={level}
+            role="radio"
+            aria-checked={current === level}
+            size="sm"
+            variant={current === level ? "secondary" : "ghost"}
+            className="flex-1"
+            disabled={locked}
+            onClick={() => void apply(patchForLevel(level as BlurLevel))}
+          >
+            {label}
+          </Button>
+        ))}
+      </div>
+      {locked ? (
+        <p className="text-[10px] leading-relaxed text-amber-400/90">
+          Motion blur is read from the main composition. Open it to change this setting.
+        </p>
+      ) : null}
+    </div>
+  );
+});

package/src/components/panels/motionBlurPanelModel.test.ts

@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import {
+  changedEdits,
+  findCompositionRoot,
+  readPreviewRootAttributes,
+  sameAttributes,
+  levelOf,
+  patchForLevel,
+  settingsOf,
+  withEdits,
+} from "./motionBlurPanelModel";
+
+const html = (attrs = "") =>
+  `<!DOCTYPE html><html><body><div data-composition-id="main" data-hf-root data-duration="5" data-width="1920" data-height="1080"${attrs}></div></body></html>`;
+
+async function rootOf(attrs?: string) {
+  const session = await openComposition(html(attrs), { history: false });
+  const root = findCompositionRoot(session.getRootElements());
+  if (!root) throw new Error("no root");
+  return root;
+}
+
+describe("findCompositionRoot and settingsOf", () => {
+  it("finds the composition root and reads its settings", async () => {
+    const root = await rootOf(' data-motion-blur="on" data-motion-blur-shutter="360"');
+    expect(settingsOf(root.attributes)).toMatchObject({
+      enabled: true,
+      shutterDeg: 360,
+      tier: "auto",
+    });
+  });
+
+  it("reads defaults from a root that has no blur attributes", async () => {
+    expect(settingsOf((await rootOf()).attributes)).toMatchObject({
+      enabled: false,
+      shutterDeg: 240,
+    });
+  });
+
+  it("is null for a document with nothing in it", async () => {
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>", {
+      history: false,
+    });
+    expect(findCompositionRoot(session.getRootElements())).toBeNull();
+  });
+});
+
+describe("changedEdits", () => {
+  it("lists only the attributes that would change", async () => {
+    const root = await rootOf(' data-motion-blur="on"');
+    const base = settingsOf(root.attributes);
+    expect(changedEdits(root.attributes, base)).toEqual([]);
+    expect(changedEdits(root.attributes, { ...base, shutterDeg: 360, tier: "filter" })).toEqual([
+      { name: "data-motion-blur-shutter", value: "360" },
+      { name: "data-motion-blur-tier", value: "filter" },
+    ]);
+    expect(changedEdits(root.attributes, { ...base, enabled: false })).toEqual([
+      { name: "data-motion-blur", value: null },
+    ]);
+  });
+});
+
+describe("withEdits and sameAttributes", () => {
+  it("applies sets and removals without touching the input", () => {
+    const before = { "data-motion-blur": "on", "data-motion-blur-shutter": "360" };
+    const after = withEdits(before, [
+      { name: "data-motion-blur-shutter", value: null },
+      { name: "data-motion-blur-tier", value: "filter" },
+    ]);
+    expect(after).toEqual({ "data-motion-blur": "on", "data-motion-blur-tier": "filter" });
+    expect(before).toEqual({ "data-motion-blur": "on", "data-motion-blur-shutter": "360" });
+  });
+
+  it("compares attribute sets by content", () => {
+    expect(sameAttributes({ a: "1" }, { a: "1" })).toBe(true);
+    expect(sameAttributes({ a: "1" }, { a: "2" })).toBe(false);
+    expect(sameAttributes({ a: "1" }, {})).toBe(false);
+    expect(sameAttributes(null, {})).toBe(false);
+    expect(sameAttributes(null, null)).toBe(true);
+  });
+});
+
+describe("readPreviewRootAttributes", () => {
+  it("reads only the blur attributes from the preview's composition root", () => {
+    const doc = document.implementation.createHTMLDocument("p");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-width="1920" data-motion-blur="on" data-motion-blur-shutter="360"></div>';
+    const frame = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    expect(readPreviewRootAttributes(frame)).toEqual({
+      "data-motion-blur": "on",
+      "data-motion-blur-shutter": "360",
+    });
+  });
+
+  it("is null when there is no preview, no root, or the document cannot be read", () => {
+    expect(readPreviewRootAttributes(null)).toBeNull();
+    const empty = document.implementation.createHTMLDocument("p");
+    expect(
+      readPreviewRootAttributes({ contentDocument: empty } as unknown as HTMLIFrameElement),
+    ).toBeNull();
+    const blocked = {
+      get contentDocument(): never {
+        throw new Error("cross-origin");
+      },
+    } as unknown as HTMLIFrameElement;
+    expect(readPreviewRootAttributes(blocked)).toBeNull();
+  });
+});
+
+describe("levelOf and patchForLevel", () => {
+  const on = (shutterDeg: number, enabled = true) => ({
+    enabled,
+    shutterDeg,
+    samples: null,
+    events: false,
+    tier: "auto" as const,
+  });
+
+  it("reads off, subtle and strong from the root's settings", () => {
+    expect(levelOf(on(240, false))).toBe("off");
+    expect(levelOf(on(240))).toBe("subtle");
+    expect(levelOf(on(180))).toBe("subtle");
+    expect(levelOf(on(360))).toBe("subtle");
+    expect(levelOf(on(480))).toBe("subtle");
+    expect(levelOf(on(481))).toBe("strong");
+    expect(levelOf(on(720))).toBe("strong");
+  });
+
+  it("sets Subtle to the default blur and Strong to the maximum, and leaves the rest alone for Off", () => {
+    expect(patchForLevel("subtle")).toEqual({ enabled: true, shutterDeg: 240, samples: null });
+    expect(patchForLevel("strong")).toEqual({ enabled: true, shutterDeg: 720, samples: 64 });
+    expect(patchForLevel("off")).toEqual({ enabled: false });
+  });
+
+  it("reads back as the level that was chosen", () => {
+    for (const level of ["subtle", "strong"] as const) {
+      expect(levelOf({ ...on(300), ...patchForLevel(level) })).toBe(level);
+    }
+  });
+});

package/src/components/panels/motionBlurPanelModel.ts

@@ -0,0 +1,98 @@
+/** What the Motion blur panel reads from and writes to a composition root, and how it describes the preview. */
+
+import type { ElementSnapshot } from "@hyperframes/sdk";
+import {
+  MOTION_BLUR_ATTR,
+  MOTION_BLUR_LIMITS,
+  type MotionBlurSettings,
+  motionBlurAttributeEdits,
+  readMotionBlurSettings,
+} from "@hyperframes/core/motion-blur-settings";
+
+export interface CompositionRoot {
+  id: string;
+  attributes: Readonly<Record<string, string>>;
+}
+
+/** The composition's own root: the top-level element that names a composition, else the first. */
+export function findCompositionRoot(roots: readonly ElementSnapshot[]): CompositionRoot | null {
+  const root = roots.find((el) => "data-composition-id" in el.attributes) ?? roots[0];
+  return root ? { id: root.id, attributes: root.attributes } : null;
+}
+
+export type RootAttributes = Readonly<Record<string, string>>;
+
+export const settingsOf = (attributes: RootAttributes): MotionBlurSettings =>
+  readMotionBlurSettings((name) => attributes[name] ?? null);
+
+/** Only the attributes whose value would change, so a no-op edit writes nothing. */
+export function changedEdits(
+  attributes: RootAttributes,
+  next: MotionBlurSettings,
+): Array<{ name: string; value: string | null }> {
+  return Object.entries(motionBlurAttributeEdits(next))
+    .filter(([name, value]) => (attributes[name] ?? null) !== value)
+    .map(([name, value]) => ({ name, value }));
+}
+
+/** `attributes` with `edits` applied: a value sets, null removes. */
+export function withEdits(
+  attributes: RootAttributes,
+  edits: ReadonlyArray<{ name: string; value: string | null }>,
+): RootAttributes {
+  const next: Record<string, string> = { ...attributes };
+  for (const { name, value } of edits) {
+    if (value === null) delete next[name];
+    else next[name] = value;
+  }
+  return next;
+}
+
+/** The blur attributes on the live preview's composition root: what actually runs, after an undo or an outside edit too. */
+export function readPreviewRootAttributes(iframe: HTMLIFrameElement | null): RootAttributes | null {
+  try {
+    const root = iframe?.contentDocument?.querySelector("[data-composition-id]");
+    if (!root) return null;
+    const found: Record<string, string> = {};
+    for (const name of Object.values(MOTION_BLUR_ATTR)) {
+      const value = root.getAttribute(name);
+      if (value !== null) found[name] = value;
+    }
+    return found;
+  } catch {
+    return null;
+  }
+}
+
+export const sameAttributes = (a: RootAttributes | null, b: RootAttributes | null): boolean =>
+  a === b ||
+  (a !== null && b !== null && Object.keys({ ...a, ...b }).every((name) => a[name] === b[name]));
+
+export type BlurLevel = "off" | "subtle" | "strong";
+
+export const BLUR_LEVELS: ReadonlyArray<{ level: BlurLevel; label: string }> = [
+  { level: "off", label: "Off" },
+  { level: "subtle", label: "Subtle" },
+  { level: "strong", label: "Strong" },
+];
+
+/** Subtle is the default blur; Strong opens the shutter and the samples as far as they go. */
+const LEVEL_SETTINGS = {
+  subtle: { shutterDeg: MOTION_BLUR_LIMITS.shutterDeg.default, samples: null },
+  strong: {
+    shutterDeg: MOTION_BLUR_LIMITS.shutterDeg.max,
+    samples: MOTION_BLUR_LIMITS.samples.max,
+  },
+} as const;
+/** Halfway between the two shutters: above it a root reads as Strong, so a hand-set 360 reads as Subtle. */
+const STRONG_ABOVE = (LEVEL_SETTINGS.subtle.shutterDeg + LEVEL_SETTINGS.strong.shutterDeg) / 2;
+
+export function levelOf(settings: MotionBlurSettings): BlurLevel {
+  if (!settings.enabled) return "off";
+  return settings.shutterDeg > STRONG_ABOVE ? "strong" : "subtle";
+}
+
+/** What choosing `level` changes; Off leaves the shutter, samples and every other setting where they were. */
+export function patchForLevel(level: BlurLevel): Partial<MotionBlurSettings> {
+  return level === "off" ? { enabled: false } : { enabled: true, ...LEVEL_SETTINGS[level] };
+}

package/src/components/ui/Tooltip.test.tsx

@@ -108,3 +108,35 @@ it("wraps its child in a box-less span so a disabled child still gets hover", ()
   expect(trigger.parentElement?.className).toBe("contents");
   expect(trigger.parentElement?.parentElement?.parentElement).toBe(document.body);
 });
+
+it("keeps a label on one line unless it is given lines", async () => {
+  const trigger = mount();
+  act(() => trigger.focus());
+  await settle();
+
+  expect(bubble()?.className).toContain("whitespace-nowrap");
+  expect(bubble()?.querySelector("span")).toBeNull();
+});
+
+it("wraps a long label at a reading width and cuts it at its lines", async () => {
+  const label = "Make a 30 second launch promo for the spring release. ".repeat(6).trim();
+  const host = mountHost(
+    <Tooltip label={label} delay={0} lines={3}>
+      <button type="button" data-testid="long">
+        P
+      </button>
+    </Tooltip>,
+  );
+  act(() => host.querySelector<HTMLElement>('[data-testid="long"]')?.focus());
+  await settle();
+
+  const tip = bubble();
+  expect(tip?.className).toContain("whitespace-normal");
+  expect(tip?.className, "a long URL or path breaks too").toContain("break-words");
+  expect(tip?.className).toContain("max-w-[300px]");
+  expect(tip?.className).not.toContain("whitespace-nowrap");
+  const text = tip?.querySelector<HTMLElement>("span");
+  expect(text?.textContent).toBe(label);
+  expect(text?.className).toBe("line-clamp-(--tooltip-lines)");
+  expect(text?.style.getPropertyValue("--tooltip-lines")).toBe("3");
+});

package/src/components/ui/Tooltip.tsx

@@ -4,7 +4,14 @@
  */
 
 import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
-import { cloneElement, useId, useRef, useState, type ReactElement } from "react";
+import {
+  cloneElement,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+} from "react";
 import { cn } from "./cn";
 import { floatingMotion, POPUP_LAYER } from "./Menu";
 
@@ -16,6 +23,8 @@ interface TooltipProps {
   delay?: number;
   disabled?: boolean;
   side?: "top" | "bottom" | "left" | "right";
+  /** Wraps a long label at a reading width and cuts it at this many lines with an ellipsis. Unset, one line. */
+  lines?: number;
 }
 
 /** Matches the old bubble's gap from its trigger, and its viewport margin. */
@@ -28,6 +37,7 @@ export function Tooltip({
   delay = 400,
   side = "top",
   disabled = false,
+  lines,
 }: TooltipProps) {
   const [open, setOpen] = useState(false);
   const boxRef = useRef<HTMLSpanElement>(null);
@@ -52,11 +62,21 @@ export function Tooltip({
             id={tooltipId}
             role="tooltip"
             className={cn(
-              "pointer-events-none rounded-md border border-border-input bg-surface px-2 py-1 text-step-10 font-medium text-text-1 whitespace-nowrap shadow-menu",
+              "pointer-events-none rounded-md border border-border-input bg-surface px-2 py-1 text-step-10 font-medium text-text-1 shadow-menu",
+              lines ? "max-w-[300px] whitespace-normal break-words" : "whitespace-nowrap",
               floatingMotion("duration-tooltip"),
             )}
           >
-            {label}
+            {lines ? (
+              <span
+                className="line-clamp-(--tooltip-lines)"
+                style={{ "--tooltip-lines": lines } as CSSProperties}
+              >
+                {label}
+              </span>
+            ) : (
+              label
+            )}
           </BaseTooltip.Popup>
         </BaseTooltip.Positioner>
       </BaseTooltip.Portal>

package/src/hooks/usePanelLayout.test.ts

@@ -105,7 +105,7 @@ describe("usePanelLayout over the dock", () => {
     act(() => view.layout.setRightCollapsed(true));
     const hidden = vi.mocked(controller.setGroupVisible).mock.calls;
     expect(hidden.map(([id]) => id).sort()).toEqual(
-      ["design", "layers", "renders", "slideshow", "variables"].sort(),
+      ["design", "layers", "motionBlur", "renders", "slideshow", "variables"].sort(),
     );
     expect(hidden.every(([, visible]) => visible === false)).toBe(true);
   });