@hyperframes/studio 0.8.55 → 0.8.56

package/src/components/editor/DomEditOverlayHover.test.tsx

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { expect, it, vi } from "vitest";
 import type { DomEditSelection } from "./domEditing";
+import "./domEditOverlayTestMocks";
 import { DomEditOverlay } from "./DomEditOverlay";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -33,21 +34,6 @@ vi.mock("./useDomEditOverlayRects", () => ({
   }),
 }));
 
-vi.mock("./useDomEditCompositionRect", () => ({
-  useDomEditCompositionRect: () => ({
-    left: 0,
-    top: 0,
-    width: 800,
-    height: 450,
-    scaleX: 1,
-    scaleY: 1,
-  }),
-}));
-
-vi.mock("./offCanvasIndicatorRefresh", () => ({
-  startOffCanvasIndicatorRefresh: () => () => undefined,
-}));
-
 function renderHover(angle: number): string {
   hoverState.angle = angle;
   const host = document.createElement("div");

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -6,6 +6,7 @@ import type { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGes
 import { DomEditCropHandles } from "./DomEditCropHandles";
 import { DomEditRotateHandle } from "./DomEditRotateHandle";
 import { resolveRotatedResizeCursor } from "./domEditResizeLocal";
+import { usePreviewReadOnly } from "./previewReadOnlyContext";
 
 // Corner resize handles, Canva-style: one per corner, diagonal cursors.
 // Corners scale about the element center; the translate keeps the center
@@ -75,6 +76,7 @@ export function DomEditGroupChrome({
   onBoxMouseDown,
   onBoxClick,
 }: DomEditGroupChromeProps) {
+  const canManipulate = allowCanvasMovement && !usePreviewReadOnly();
   return (
     <>
       {groupOverlayItems.map((item) => (
@@ -98,10 +100,10 @@ export function DomEditGroupChrome({
           top: groupBounds.top,
           width: groupBounds.width,
           height: groupBounds.height,
-          cursor: allowCanvasMovement && groupCanMove ? "move" : "default",
+          cursor: canManipulate && groupCanMove ? "move" : "default",
         }}
         onPointerDown={(e) => {
-          if (!allowCanvasMovement || !groupCanMove || e.shiftKey) return;
+          if (!canManipulate || !groupCanMove || e.shiftKey) return;
           gestures.startGroupDrag(e);
         }}
         onMouseDown={onBoxMouseDown}
@@ -164,6 +166,8 @@ export function DomEditSelectionChrome({
   // into: left interactive, it swallows every press, so the caret can never be
   // moved and characters can never be selected by dragging.
   const editing = inlineText?.editing ?? false;
+  const readOnly = usePreviewReadOnly();
+  const canManipulate = allowCanvasMovement && !readOnly;
 
   return (
     <>
@@ -174,7 +178,7 @@ export function DomEditSelectionChrome({
           transform: overlayRect.angle ? `rotate(${overlayRect.angle}deg)` : undefined,
         }}
       >
-        {allowCanvasMovement && !editing && selection.capabilities.canApplyManualRotation && (
+        {canManipulate && !editing && selection.capabilities.canApplyManualRotation && (
           <DomEditRotateHandle
             overlayRect={overlayRect}
             cropOutlineInsetPx={cropOutlineInsetPx}
@@ -196,9 +200,7 @@ export function DomEditSelectionChrome({
             height: overlayRect.height,
             clipPath: boxClipPath,
             cursor:
-              allowCanvasMovement && selection.capabilities.canApplyManualOffset
-                ? "move"
-                : "default",
+              canManipulate && selection.capabilities.canApplyManualOffset ? "move" : "default",
           }}
           onPointerDown={(e) => {
             // A second press opens the element's text for editing, and must be
@@ -211,7 +213,7 @@ export function DomEditSelectionChrome({
               e.stopPropagation();
               return;
             }
-            if (!allowCanvasMovement || e.shiftKey) return;
+            if (!canManipulate || e.shiftKey) return;
             if (selection.capabilities.canApplyManualOffset) {
               gestures.startGesture("drag", e);
               return;
@@ -245,7 +247,7 @@ export function DomEditSelectionChrome({
           children, so they paint strictly above the box border. Each handle
           is positioned relative to the overlay container using the
           overlayRect origin, matching the old child-relative offsets. */}
-        {allowCanvasMovement &&
+        {canManipulate &&
           !editing &&
           selection.capabilities.canApplyManualSize &&
           RESIZE_HANDLE_DEFS.map((def) =>
@@ -271,7 +273,7 @@ export function DomEditSelectionChrome({
       </div>
       {/* Crop owns its element-local oriented frame. Keep it outside the chrome's
           rotated plane or a rotated selection applies the angle twice. */}
-      {selection.capabilities.canCrop && !editing && groupSelectionCount <= 1 && (
+      {selection.capabilities.canCrop && !editing && !readOnly && groupSelectionCount <= 1 && (
         <DomEditCropHandles
           selection={selection}
           overlayRect={overlayRect}

package/src/components/editor/PropertyPanel.deselect.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { PropertyPanel } from "./PropertyPanel";
+import type { PropertyPanelProps } from "./propertyPanelHelpers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("../../contexts/StudioContext", async () => {
+  const actual = await vi.importActual<typeof import("../../contexts/StudioContext")>(
+    "../../contexts/StudioContext",
+  );
+  return { ...actual, useStudioShellContext: () => ({ showToast: vi.fn() }) };
+});
+
+function selectedElement(): NonNullable<PropertyPanelProps["element"]> {
+  return {
+    element: document.createElement("div"),
+    id: "el",
+    selector: "#el",
+    label: "El",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 10, height: 10 },
+    textContent: "",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+describe("PropertyPanel deselect", () => {
+  it("re-renders to the empty state on deselect without a hooks-order crash", () => {
+    const props = {
+      element: selectedElement(),
+      assets: [],
+      onSetStyle: vi.fn(),
+      onSetText: vi.fn(),
+      onSetAttributeLive: vi.fn(),
+      onClearSelection: vi.fn(),
+    } as unknown as PropertyPanelProps;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => root.render(<PropertyPanel {...props} />));
+
+    // A same-instance re-render with no element — Escape, clicking empty canvas,
+    // or "Clear selection" — must not change which hooks ran.
+    expect(() => {
+      act(() => root.render(<PropertyPanel {...props} element={null} />));
+    }).not.toThrow();
+
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/PropertyPanel.tsx

@@ -37,6 +37,7 @@ import { GestureRecordPanelButton } from "./GestureRecordControl";
 import { PropertyPanelEmptyState } from "./PropertyPanelEmptyState";
 import { DesignPanelInputProvider } from "../../contexts/DesignPanelInputContext";
 import { isAudioDomElement } from "../../utils/timelineInspector";
+import { useManualEditDisabledFlags } from "./previewReadOnlyContext";
 
 // Re-export helpers that external consumers import from this module
 export {
@@ -175,6 +176,9 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     scale: 1,
     transformPerspective: 0,
   };
+  // Unconditional like the hooks above: must not sit behind the `!element` return below.
+  const { manualOffsetEditingDisabled, manualSizeEditingDisabled, manualRotationEditingDisabled } =
+    useManualEditDisabledFlags(element?.capabilities);
 
   if (!element) {
     return (
@@ -189,9 +193,6 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     );
   }
 
-  const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
-  const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
-  const manualRotationEditingDisabled = !element.capabilities.canApplyManualRotation;
   const sourceLabel = element.id ? `#${element.id}` : (element.selector ?? "");
   // Capabilities are already resolved on the selection; recompute only sections,
   // feeding the live GSAP tween count (arrives on the gsapAnimations prop, not the

package/src/components/editor/SnapToolbar.test.tsx

@@ -54,6 +54,7 @@ function AppHotkeyHarness() {
     handleDuplicate: vi.fn(async () => false),
     onResetKeyframes: vi.fn(() => false),
     onDeleteSelectedKeyframes: vi.fn(),
+    readOnlyPreview: false,
   });
 
   return null;

package/src/components/editor/domEditOverlayTestMocks.ts

@@ -0,0 +1,16 @@
+import { vi } from "vitest";
+
+vi.mock("./useDomEditCompositionRect", () => ({
+  useDomEditCompositionRect: () => ({
+    left: 0,
+    top: 0,
+    width: 800,
+    height: 450,
+    scaleX: 1,
+    scaleY: 1,
+  }),
+}));
+
+vi.mock("./offCanvasIndicatorRefresh", () => ({
+  startOffCanvasIndicatorRefresh: () => () => undefined,
+}));

package/src/components/editor/previewReadOnly.overlay.test.tsx

@@ -0,0 +1,260 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { makeSelection } from "../../hooks/domSelectionTestHarness";
+import { CANVAS_NUDGE_COMMIT_DEBOUNCE_MS } from "./domEditNudge";
+import { __resetForTests } from "../../utils/canvasNudgeGate";
+import { PreviewReadOnlyProvider } from "./previewReadOnlyContext";
+import "./domEditOverlayTestMocks";
+import { DomEditOverlay } from "./DomEditOverlay";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const RECT = { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 };
+const layout = vi.hoisted(() => ({ group: [] as unknown[] }));
+
+vi.mock("./useDomEditOverlayRects", () => ({
+  useDomEditOverlayRects: () => ({
+    overlayRect: { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+    overlayRectRef: {
+      current: { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+    },
+    setOverlayRect: () => undefined,
+    hoverRect: null,
+    groupOverlayItems: layout.group,
+    groupOverlayItemsRef: { current: layout.group },
+    setGroupOverlayItems: () => undefined,
+    childRects: [],
+  }),
+}));
+const BOX = '[data-dom-edit-selection-box="true"]';
+let root: Root;
+let host: HTMLElement;
+
+function textElement(id: string): HTMLElement {
+  const element = document.createElement("h1");
+  element.id = id;
+  element.textContent = "Title";
+  document.body.append(element);
+  return element;
+}
+
+function fixture(
+  overrides: Partial<React.ComponentProps<typeof DomEditOverlay>> = {},
+  readOnly = false,
+) {
+  const spies = {
+    onCanvasMouseDown: vi.fn(),
+    onSelectionChange: vi.fn(),
+    onManualDragStart: vi.fn(),
+    onBlockedMove: vi.fn(),
+    onPathOffsetCommit: vi.fn(),
+    onGroupPathOffsetCommit: vi.fn(),
+    onBoxSizeCommit: vi.fn(),
+    onRotationCommit: vi.fn(),
+    onStyleCommit: vi.fn(),
+    onDeleteSelection: vi.fn(),
+    onApplyZIndex: vi.fn(),
+  };
+  const selection = makeSelection("Title", textElement("title"));
+  selection.capabilities.canApplyManualRotation = true;
+  selection.textFields = [{ key: "text", label: "Text", value: "Title" }] as never;
+  const props = {
+    iframeRef: { current: document.createElement("iframe") },
+    activeCompositionPath: null,
+    selection,
+    hoverSelection: null,
+    onCanvasPointerMove: () => Promise.resolve(selection),
+    onCanvasPointerLeave: () => undefined,
+    ...spies,
+    ...overrides,
+  };
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() =>
+    root.render(
+      <PreviewReadOnlyProvider readOnly={readOnly}>
+        <DomEditOverlay {...props} />
+      </PreviewReadOnlyProvider>,
+    ),
+  );
+  return { spies, selection, overlay: host.firstElementChild as HTMLElement };
+}
+
+const fire = (target: Element, type: string, init: MouseEventInit = {}) => {
+  const event = new MouseEvent(type, { bubbles: true, cancelable: true, button: 0, ...init });
+  act(() => {
+    target.dispatchEvent(event);
+  });
+  return event;
+};
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  __resetForTests();
+  HTMLElement.prototype.setPointerCapture = () => undefined;
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  document.body.innerHTML = "";
+  layout.group = [];
+  vi.useRealTimers();
+});
+
+describe("DomEditOverlay with the preview read-only", () => {
+  it("control: with the flag off a press on the box starts a move", () => {
+    const { spies, overlay } = fixture();
+    fire(overlay.querySelector(BOX)!, "pointerdown");
+    expect(spies.onManualDragStart).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses to start a move from the selection box", () => {
+    const { spies, overlay } = fixture({}, true);
+    const box = overlay.querySelector(BOX)!;
+    fire(box, "pointerdown");
+    fire(box, "pointermove", { clientX: 40 });
+    fire(box, "pointerup");
+    expect(spies.onManualDragStart).not.toHaveBeenCalled();
+    expect(spies.onBlockedMove).not.toHaveBeenCalled();
+    expect(spies.onPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no resize dots, and none can start a resize", () => {
+    const off = fixture();
+    expect(off.overlay.querySelectorAll("div.h-4.w-4")).toHaveLength(4);
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelectorAll("div.h-4.w-4")).toHaveLength(0);
+    expect(spies.onBoxSizeCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no rotate handle", () => {
+    const off = fixture();
+    expect(off.overlay.querySelector('[aria-label="Rotate selection"]')).not.toBeNull();
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelector('[aria-label="Rotate selection"]')).toBeNull();
+    expect(spies.onRotationCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no crop handles, so clip-path is never committed", () => {
+    const off = fixture();
+    expect(off.overlay.querySelector("[data-dom-edit-crop-frame]")).not.toBeNull();
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelector("[data-dom-edit-crop-frame]")).toBeNull();
+    expect(spies.onStyleCommit).not.toHaveBeenCalled();
+  });
+
+  it("does not drag a multi-selection", () => {
+    const members = ["a", "b"].map((id) => {
+      const selection = makeSelection(id, textElement(id));
+      return { key: id, selection, element: selection.element, rect: RECT };
+    });
+    layout.group = members;
+    const { spies, overlay } = fixture(
+      {
+        selection: null,
+        groupSelections: members.map((m) => m.selection),
+      },
+      true,
+    );
+    fire(overlay.querySelector(BOX)!, "pointerdown");
+    expect(spies.onManualDragStart).not.toHaveBeenCalled();
+    expect(spies.onGroupPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  const nudge = () => {
+    const event = new KeyboardEvent("keydown", {
+      key: "ArrowRight",
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      window.dispatchEvent(event);
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+    return event;
+  };
+
+  it("control: with the flag off an arrow key nudges", () => {
+    const { spies } = fixture();
+    expect(nudge().defaultPrevented).toBe(true);
+    expect(spies.onPathOffsetCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("neither nudges on an arrow key nor swallows it", () => {
+    const { spies } = fixture({}, true);
+    expect(nudge().defaultPrevented).toBe(false);
+    expect(spies.onPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  const pressEnter = (overlay: HTMLElement) =>
+    act(() => {
+      overlay.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }),
+      );
+    });
+
+  it("control: with the flag off Enter opens the text for editing", () => {
+    const { selection, overlay } = fixture();
+    pressEnter(overlay);
+    expect(selection.element.hasAttribute("contenteditable")).toBe(true);
+  });
+
+  it("does not open text for editing on Enter", () => {
+    const { selection, overlay } = fixture({}, true);
+    pressEnter(overlay);
+    expect(selection.element.hasAttribute("contenteditable")).toBe(false);
+  });
+
+  const rightClick = async (overlay: HTMLElement) => {
+    await act(async () => {
+      overlay.dispatchEvent(
+        new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 5, clientY: 5 }),
+      );
+    });
+  };
+
+  it("control: with the flag off right-click offers delete and z-order", async () => {
+    const { overlay } = fixture();
+    await rightClick(overlay);
+    expect(document.body.textContent).toContain("Delete");
+  });
+
+  it("offers no delete or z-order on right-click when read-only", async () => {
+    // Same fixture as the control test above (a real, already-selected element) so the
+    // context menu actually opens; `selection: null` here would close it via
+    // useCanvasContextMenuState's own deselect effect, before read-only ever mattered.
+    const { spies, overlay } = fixture({}, true);
+    await rightClick(overlay);
+    expect(document.body.textContent).not.toContain("Delete");
+    expect(spies.onDeleteSelection).not.toHaveBeenCalled();
+    expect(spies.onApplyZIndex).not.toHaveBeenCalled();
+  });
+
+  it("still selects and reports to the host on right-click of an unselected element", async () => {
+    const { spies, overlay } = fixture({ selection: null }, true);
+    await rightClick(overlay);
+    expect(spies.onSelectionChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("still selects and reports to the host on a click", () => {
+    const { spies, overlay } = fixture({ selection: null }, true);
+    fire(overlay, "mousedown");
+    expect(spies.onCanvasMouseDown).toHaveBeenCalledTimes(1);
+  });
+
+  it("still selects on a click of the selection box", () => {
+    const { spies, overlay } = fixture({}, true);
+    fire(overlay.querySelector(BOX)!, "click");
+    expect(spies.onCanvasMouseDown).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/editor/previewReadOnlyContext.tsx

@@ -0,0 +1,59 @@
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../../utils/hmrStableContext";
+
+interface PreviewReadOnlyValue {
+  readOnly: boolean;
+  reason: string;
+}
+
+const DEFAULT_REASON = "Preview is read-only.";
+
+// Real default (not a throwing required-provider context): most existing
+// mounts render with no wrapper at all and must stay editable, exactly as today.
+const PreviewReadOnlyContext = createStableContext<PreviewReadOnlyValue>("PreviewReadOnlyContext", {
+  readOnly: false,
+  reason: DEFAULT_REASON,
+});
+
+export function PreviewReadOnlyProvider({
+  readOnly,
+  reason,
+  children,
+}: {
+  readOnly: boolean;
+  reason?: string;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ readOnly, reason: reason ?? DEFAULT_REASON }), [readOnly, reason]);
+  return <PreviewReadOnlyContext value={value}>{children}</PreviewReadOnlyContext>;
+}
+
+export function usePreviewReadOnly(): boolean {
+  return useContext(PreviewReadOnlyContext).readOnly;
+}
+
+/** Short host-supplied text for why a hand-edit control is disabled. */
+export function usePreviewReadOnlyReason(): string {
+  return useContext(PreviewReadOnlyContext).reason;
+}
+
+interface ManualEditCapabilities {
+  canApplyManualOffset: boolean;
+  canApplyManualSize: boolean;
+  canApplyManualRotation: boolean;
+}
+
+/**
+ * The manual X/Y/W/H/rotation fields' disabled state: capability, or preview read-only.
+ * Call unconditionally, even with no selection — `capabilities` may be null/undefined.
+ */
+export function useManualEditDisabledFlags(
+  capabilities: ManualEditCapabilities | null | undefined,
+) {
+  const { readOnly } = useContext(PreviewReadOnlyContext);
+  return {
+    manualOffsetEditingDisabled: !capabilities?.canApplyManualOffset || readOnly,
+    manualSizeEditingDisabled: !capabilities?.canApplyManualSize || readOnly,
+    manualRotationEditingDisabled: !capabilities?.canApplyManualRotation || readOnly,
+  };
+}

package/src/components/editor/propertyPanelFlatLayoutSection.tsx

@@ -5,6 +5,7 @@ import { formatPxMetricValue } from "./propertyPanelHelpers";
 import { resolveValueTier } from "./propertyPanelValueTier";
 import { PropertyPanel3dTransform } from "./propertyPanel3dTransform";
 import type { DomEditSelection } from "./domEditingTypes";
+import { usePreviewReadOnly, usePreviewReadOnlyReason } from "./previewReadOnlyContext";
 
 type KeyframeEntry = Array<{
   percentage: number;
@@ -119,6 +120,9 @@ export function LayoutGeometryRows({
   onRemoveKeyframe,
   onConvertToKeyframes,
 }: GeometryRowsProps) {
+  const readOnlyPreview = usePreviewReadOnly();
+  const readOnlyPreviewReason = usePreviewReadOnlyReason();
+  const readOnlyTooltip = readOnlyPreview ? readOnlyPreviewReason : undefined;
   const gutterProps = {
     element,
     gsapAnimId,
@@ -137,6 +141,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayX)}
         tier={displayX === 0 ? "default" : "explicitCustom"}
         disabled={manualOffsetEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualOffset("x", next)}
         suffix={<KeyframeGutter property="x" displayValue={displayX} {...gutterProps} />}
       />
@@ -145,6 +150,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayY)}
         tier={displayY === 0 ? "default" : "explicitCustom"}
         disabled={manualOffsetEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualOffset("y", next)}
         suffix={<KeyframeGutter property="y" displayValue={displayY} {...gutterProps} />}
       />
@@ -153,6 +159,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayW)}
         tier="default"
         disabled={manualSizeEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualSize("width", next)}
         suffix={<KeyframeGutter property="width" displayValue={displayW} {...gutterProps} />}
       />
@@ -161,6 +168,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayH)}
         tier="default"
         disabled={manualSizeEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualSize("height", next)}
         suffix={<KeyframeGutter property="height" displayValue={displayH} {...gutterProps} />}
       />
@@ -169,6 +177,7 @@ export function LayoutGeometryRows({
         value={`${displayR}°`}
         tier="default"
         disabled={manualRotationEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualRotation(next.replace("°", ""))}
         suffix={<KeyframeGutter property="rotation" displayValue={displayR} {...gutterProps} />}
       />

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -19,6 +19,7 @@ export function FlatRow({
   value,
   tier,
   disabled,
+  tooltip,
   liveCommit,
   suffix,
   dropdown,
@@ -30,6 +31,8 @@ export function FlatRow({
   value: string;
   tier: PropertyValueTier;
   disabled?: boolean;
+  /** Shown as a title attribute, e.g. why the row is disabled. */
+  tooltip?: string;
   liveCommit?: boolean;
   suffix?: ReactNode;
   /** Renders a trailing 10px caret-down, for select-backed rows. */
@@ -40,7 +43,7 @@ export function FlatRow({
 }) {
   const track = useTrackDesignInput();
   return (
-    <div className="group flex min-h-[30px] items-center justify-between gap-3">
+    <div className="group flex min-h-[30px] items-center justify-between gap-3" title={tooltip}>
       <span className={`text-[11px] ${VALUE_TIER_LABEL_CLASS[tier]}`}>{label}</span>
       <span className="flex min-w-0 shrink-0 items-center gap-1.5">
         <span

package/src/components/editor/propertyPanelInputCoverage.test.tsx

@@ -459,12 +459,7 @@ function representativeElement() {
 describe("classic PropertyPanel input coverage", () => {
   it("emits only named, known-section events across body inputs and header/footer chrome", async () => {
     vi.resetModules();
-    vi.doMock("./manualEditingAvailability", async () => {
-      const actual = await vi.importActual<typeof import("./manualEditingAvailability")>(
-        "./manualEditingAvailability",
-      );
-      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: false };
-    });
+    vi.doMock("./manualEditingAvailability", () => ({ STUDIO_FLAT_INSPECTOR_ENABLED: false }));
     const { PropertyPanel } = await import("./PropertyPanel");
     const host = render(
       <PropertyPanel
@@ -524,18 +519,13 @@ describe("classic PropertyPanel input coverage", () => {
     expect(sections.has("header")).toBe(true);
     expect(sections.has("footer")).toBe(true);
     expect(sections.size).toBeGreaterThan(2);
-  });
+  }, 15000);
 });
 
 describe("flat PropertyPanel input coverage", () => {
   it("emits only named flat events from known sections for every visible layout input", async () => {
     vi.resetModules();
-    vi.doMock("./manualEditingAvailability", async () => {
-      const actual = await vi.importActual<typeof import("./manualEditingAvailability")>(
-        "./manualEditingAvailability",
-      );
-      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: true };
-    });
+    vi.doMock("./manualEditingAvailability", () => ({ STUDIO_FLAT_INSPECTOR_ENABLED: true }));
     const { PropertyPanel } = await import("./PropertyPanel");
     const host = render(
       <PropertyPanel