@hyperframes/studio 0.7.57 → 0.7.59

package/src/components/editor/PropertyPanelFlatFooter.tsx

@@ -0,0 +1,73 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+
+export function PropertyPanelFlatFooter({
+  onAskAgent,
+  recordingState,
+  recordingDuration,
+  onToggleRecording,
+}: {
+  onAskAgent?: () => void;
+  recordingState?: "idle" | "recording" | "preview";
+  recordingDuration?: number;
+  onToggleRecording?: () => void;
+}) {
+  const track = useTrackDesignInput();
+  const recording = recordingState === "recording";
+  const recordTitle = recording
+    ? `Stop recording ${(recordingDuration ?? 0).toFixed(1)}s`
+    : "Record gesture (R)";
+
+  return (
+    // No border-t here: every possible element immediately above this footer
+    // in the new fixed-headers + scrollable-open-section layout (a collapsed
+    // FlatGroupHeader, or the open group's scrollable body wrapper) already
+    // draws its own border-b in normal document flow — nothing here is
+    // `position: sticky` anymore, so there's no rounding seam to seal (see
+    // p11-scrollable-open-section-report.md).
+    <div className="flex items-center justify-between bg-panel-bg px-4 py-[11px]">
+      <button
+        type="button"
+        data-flat-footer-ask="true"
+        onClick={() => {
+          track("button", "Ask agent");
+          onAskAgent?.();
+        }}
+        disabled={!onAskAgent}
+        className="flex items-center gap-[7px] text-[11px] font-medium text-panel-text-2 disabled:cursor-not-allowed"
+      >
+        <svg
+          width="13"
+          height="13"
+          viewBox="0 0 16 16"
+          fill="currentColor"
+          className="text-panel-accent"
+        >
+          <path d="M8 1l1.4 4.6L14 7l-4.6 1.4L8 13l-1.4-4.6L2 7l4.6-1.4z" />
+        </svg>
+        Ask agent about this element
+      </button>
+      {onToggleRecording && (
+        <button
+          type="button"
+          data-flat-footer-record="true"
+          aria-label={recordTitle}
+          title={recordTitle}
+          onMouseDown={(e) => e.preventDefault()}
+          onClick={() => {
+            track("button", "Gesture recording");
+            onToggleRecording();
+          }}
+          className={recording ? "text-panel-danger animate-pulse" : "text-panel-danger"}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            {recording ? (
+              <rect x="2" y="2" width="10" height="10" rx="1.5" />
+            ) : (
+              <circle cx="7" cy="7" r="6" />
+            )}
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PropertyPanelFlatHeader } from "./PropertyPanelFlatHeader";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function renderHeader(overrides: Partial<Parameters<typeof PropertyPanelFlatHeader>[0]> = {}) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const props = {
+    name: "Mono Label",
+    meta: ".mono-label · div",
+    elementKind: "text" as const,
+    hidden: false,
+    copied: false,
+    onCopy: vi.fn(),
+    onClear: vi.fn(),
+    showUngroup: false,
+    ...overrides,
+  };
+  act(() => {
+    root.render(<PropertyPanelFlatHeader {...props} />);
+  });
+  return { host, root, props };
+}
+
+describe("PropertyPanelFlatHeader", () => {
+  it("renders name, meta, and the mint text-type icon", () => {
+    const { host, root } = renderHeader();
+    expect(host.textContent).toContain("Mono Label");
+    expect(host.textContent).toContain(".mono-label · div");
+    const icon = host.querySelector('[data-flat-header-icon="true"]');
+    expect(icon?.className).toContain("text-panel-accent");
+    act(() => root.unmount());
+  });
+
+  it("colors the media icon cyan and the other icon amber", () => {
+    const { host: mediaHost, root: mediaRoot } = renderHeader({ elementKind: "media" });
+    expect(mediaHost.querySelector('[data-flat-header-icon="true"]')?.className).toContain(
+      "text-panel-media",
+    );
+    act(() => mediaRoot.unmount());
+
+    const { host: otherHost, root: otherRoot } = renderHeader({ elementKind: "other" });
+    expect(otherHost.querySelector('[data-flat-header-icon="true"]')?.className).toContain(
+      "text-panel-container",
+    );
+    act(() => otherRoot.unmount());
+  });
+
+  it("fires onCopy and onClear from their action buttons", () => {
+    const { host, root, props } = renderHeader();
+    const copy = host.querySelector<HTMLButtonElement>(
+      '[aria-label="Copy element info to clipboard"]',
+    );
+    const clear = host.querySelector<HTMLButtonElement>('[aria-label="Clear selection"]');
+    act(() => copy?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    act(() => clear?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(props.onCopy).toHaveBeenCalledTimes(1);
+    expect(props.onClear).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+
+  it("only renders Ungroup when showUngroup is true", () => {
+    const { host: without } = renderHeader({ showUngroup: false });
+    expect(without.querySelector('[aria-label="Ungroup"]')).toBeNull();
+
+    const { host: withUngroup } = renderHeader({ showUngroup: true, onUngroup: vi.fn() });
+    expect(withUngroup.querySelector('[aria-label="Ungroup"]')).not.toBeNull();
+  });
+});

package/src/components/editor/PropertyPanelFlatHeader.tsx

@@ -0,0 +1,112 @@
+import { Eye, EyeSlash } from "@phosphor-icons/react";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import { ClipboardList, Film, Square, Type, X } from "../../icons/SystemIcons";
+
+const ICON_BY_KIND = { text: Type, media: Film, other: Square } as const;
+const ICON_COLOR_BY_KIND = {
+  text: "text-panel-accent",
+  media: "text-panel-media",
+  other: "text-panel-container",
+} as const;
+
+export function PropertyPanelFlatHeader({
+  name,
+  meta,
+  elementKind,
+  hidden,
+  onToggleHidden,
+  copied,
+  onCopy,
+  onClear,
+  onUngroup,
+  showUngroup,
+}: {
+  name: string;
+  meta: string;
+  elementKind: "text" | "media" | "other";
+  hidden: boolean;
+  onToggleHidden?: () => void;
+  copied: boolean;
+  onCopy: () => void;
+  onClear: () => void;
+  onUngroup?: () => void;
+  showUngroup: boolean;
+}) {
+  const track = useTrackDesignInput();
+  const Icon = ICON_BY_KIND[elementKind];
+  const visibilityLabel = hidden ? "Show element" : "Hide element";
+
+  return (
+    <div className="flex items-center gap-2.5 border-b border-panel-hairline px-4 py-3">
+      <Icon
+        size={15}
+        data-flat-header-icon="true"
+        className={`flex-shrink-0 ${ICON_COLOR_BY_KIND[elementKind]}`}
+      />
+      <div className="flex min-w-0 flex-1 items-baseline gap-2">
+        <span className="truncate text-[13px] font-semibold text-panel-text-0">{name}</span>
+        <span className="truncate font-mono text-[10px] text-panel-text-4">{meta}</span>
+      </div>
+      <div className="flex flex-shrink-0 items-center gap-2.5 text-panel-text-3">
+        {showUngroup && (
+          <button
+            type="button"
+            aria-label="Ungroup"
+            title="Ungroup (⌘⇧G)"
+            onClick={() => {
+              track("button", "Ungroup");
+              onUngroup?.();
+            }}
+          >
+            <svg
+              width="13"
+              height="13"
+              viewBox="0 0 16 16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+            >
+              <rect x="1.5" y="1.5" width="7" height="7" rx="1" />
+              <rect x="7.5" y="7.5" width="7" height="7" rx="1" />
+            </svg>
+          </button>
+        )}
+        {onToggleHidden && (
+          <button
+            type="button"
+            aria-label={visibilityLabel}
+            title={visibilityLabel}
+            onClick={() => {
+              track("toggle", "Element visibility");
+              onToggleHidden();
+            }}
+          >
+            {hidden ? <EyeSlash size={13} weight="bold" /> : <Eye size={13} weight="bold" />}
+          </button>
+        )}
+        <button
+          type="button"
+          aria-label="Copy element info to clipboard"
+          title={copied ? "Copied!" : "Copy element info for any AI agent"}
+          onClick={() => {
+            track("button", "Copy element info");
+            onCopy();
+          }}
+          className={copied ? "text-panel-accent" : undefined}
+        >
+          <ClipboardList size={13} />
+        </button>
+        <button
+          type="button"
+          aria-label="Clear selection"
+          onClick={() => {
+            track("button", "Clear selection");
+            onClear();
+          }}
+        >
+          <X size={13} />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/editor/canvasContextMenuZOrder.test.ts

@@ -6,6 +6,7 @@ import {
   parseZIndex,
   resolveCrossedNeighbor,
   resolveZOrderChange,
+  resolveZOrderReposition,
   type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
@@ -617,3 +618,59 @@ describe("isZOrderActionEnabled", () => {
     }
   });
 });
+
+describe("resolveZOrderReposition (Layers-panel arbitrary drop)", () => {
+  it("multi-position jump with distinct z resolves to ONE between-z write", () => {
+    // Render order bottom→top today: target(1), a(3), b(5). Drop target between
+    // a and b → single write: z strictly between 3 and 5.
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    const patches = resolveZOrderReposition(target, [byId.a, target, byId.b]);
+    expect(patches).toEqual([{ element: target, zIndex: 4 }]);
+  });
+
+  it("jump to the very top writes one z above the previous top", () => {
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    const patches = resolveZOrderReposition(target, [byId.a, byId.b, target]);
+    expect(patches).toEqual([{ element: target, zIndex: 6 }]);
+  });
+
+  it("no-op drop (unchanged order) returns null", () => {
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    expect(resolveZOrderReposition(target, [target, byId.a, byId.b])).toBeNull();
+  });
+
+  it("tied z values renumber the scoped set minimally (band-safe)", () => {
+    const { target, byId } = makeFamily("2", [
+      ["a", "2"],
+      ["b", "2"],
+    ]);
+    // All tied at 2; DOM order target,a,b → render bottom→top target,a,b.
+    // Move target to the top: scoped renumber within the band.
+    const patches = resolveZOrderReposition(target, [byId.a, byId.b, target]);
+    expect(patches).not.toBeNull();
+    const z = new Map(patches!.map((p) => [(p.element as HTMLElement).id, p.zIndex]));
+    const zOf = (id: string) => z.get(id) ?? 2;
+    expect(zOf("a")).toBeLessThan(zOf("b"));
+    expect(zOf("b")).toBeLessThan(zOf("target"));
+  });
+
+  it("rejects elements that are not painting siblings of the target", () => {
+    const { target, byId } = makeFamily("1", [["a", "3"]]);
+    const stranger = makeEl("stranger", "2");
+    expect(resolveZOrderReposition(target, [stranger, target, byId.a])).toBeNull();
+  });
+
+  it("returns null for sets too small to reorder", () => {
+    const { target } = makeFamily("1", []);
+    expect(resolveZOrderReposition(target, [target])).toBeNull();
+  });
+});

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -42,6 +42,7 @@
  */
 
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { readLayerRevealPriorZ } from "../../player/lib/timelineElementHelpers";
 
 export type ZOrderAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
@@ -107,8 +108,11 @@ export function parseZIndex(value: string | null | undefined): number {
   return Number.isFinite(n) ? n : 0;
 }
 
-/** Read the effective z-index for an element (inline style preferred). */
+/** Read the effective z-index for an element (inline style preferred).
+ *  Reveal-lift transparent: an active Layers-panel lift reports the TRUE z. */
 export function readEffectiveZIndex(el: HTMLElement): number {
+  const prior = readLayerRevealPriorZ(el);
+  if (prior != null) return prior;
   const inline = el.style.zIndex;
   if (inline && inline !== "auto") return parseZIndex(inline);
   try {
@@ -439,6 +443,41 @@ export function resolveZOrderChange(
   return realizeOrder(order, desired, target, entries);
 }
 
+/**
+ * Realize an ARBITRARY repositioning of `target` within a scoped sibling set —
+ * the Layers-panel drag, which can jump several siblings in one drop, unlike
+ * the menu's four fixed actions. `desiredOrderBottomToTop` is the scoped set
+ * (target included at its new slot) in the intended render order. Reuses the
+ * menu's minimal-write realization (realizeOrder): one between-z write when a
+ * strict gap exists, band-safe scoped renumber otherwise — replacing the old
+ * LayersPanel computeReorderZValues path that stamped EVERY sibling.
+ *
+ * Null when nothing changes, the set is too small, or an element in the
+ * desired order is not actually a painting sibling of `target`.
+ */
+export function resolveZOrderReposition(
+  target: HTMLElement,
+  desiredOrderBottomToTop: readonly HTMLElement[],
+): ZOrderPatch[] | null {
+  const { entries } = getFamily(target);
+  if (entries.length < 2) return null;
+  const byElement = new Map(entries.map((entry) => [entry.element, entry]));
+  const desired: RenderEntry[] = [];
+  for (const el of desiredOrderBottomToTop) {
+    const entry = byElement.get(el);
+    if (!entry) return null;
+    desired.push(entry);
+  }
+  if (desired.length < 2 || !desired.some((entry) => entry.element === target)) return null;
+  const currentOrder = toRenderOrder(desired);
+  // A drop back into the same slot is a no-op. The menu actions guard this via
+  // their position checks before realizeOrder; an arbitrary reposition must
+  // compare the orders itself — realizeOrder would otherwise "normalize" an
+  // end-of-set target to a fresh z value it doesn't need.
+  if (currentOrder.every((entry, i) => entry.element === desired[i].element)) return null;
+  return realizeOrder(currentOrder, desired, target, entries);
+}
+
 /**
  * The sibling a forward/backward step crosses: the visible overlapping
  * neighbor directly above (bring-forward) or below (send-backward) the target

package/src/components/editor/domEditingDom.ts

@@ -4,6 +4,7 @@
  * No imports from other domEditing* modules — safe to import from anywhere.
  */
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { CURATED_STYLE_PROPERTIES } from "./domEditingTypes";
 
 // ─── Type guard ───────────────────────────────────────────────────────────────
@@ -296,11 +297,9 @@ export function getSelectorIndex(
 ): number | undefined {
   if (!selector?.startsWith(".")) return undefined;
 
-  const candidates = querySelectorAllSafely(doc, selector).filter(
-    (candidate): candidate is HTMLElement =>
-      isHtmlElement(candidate) &&
-      getSourceFileForElement(candidate, activeCompositionPath).sourceFile === sourceFile,
+  return getSourceScopedSelectorIndex(doc, el, selector, sourceFile, (candidate) =>
+    isHtmlElement(candidate)
+      ? getSourceFileForElement(candidate, activeCompositionPath).sourceFile
+      : undefined,
   );
-  const index = candidates.indexOf(el);
-  return index >= 0 ? index : undefined;
 }

package/src/components/editor/domEditingElement.ts

@@ -246,45 +246,28 @@ export function findElementForSelection(
   selection: FindElementSelection,
   activeCompositionPath: string | null = null,
 ): HTMLElement | null {
+  const sourceMatches = (candidate: Element): candidate is HTMLElement =>
+    isHtmlElement(candidate) &&
+    (!selection.sourceFile ||
+      getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
+        selection.sourceFile);
+  const findAll = (selector: string): HTMLElement[] =>
+    querySelectorAllSafely(doc, selector).filter(sourceMatches);
+
   if (selection.hfId) {
-    const byHfId = doc.querySelector(`[data-hf-id="${CSS.escape(selection.hfId)}"]`);
-    if (isHtmlElement(byHfId)) return byHfId;
+    const byHfId = findAll(`[data-hf-id="${escapeCssString(selection.hfId)}"]`)[0];
+    if (byHfId) return byHfId;
   }
 
   if (selection.id) {
-    const byId = doc.getElementById(selection.id);
-    if (
-      isHtmlElement(byId) &&
-      (!selection.sourceFile ||
-        getSourceFileForElement(byId, activeCompositionPath).sourceFile === selection.sourceFile)
-    ) {
-      return byId;
-    }
+    // Flattened sub-compositions can repeat authored ids. getElementById returns
+    // only the first document match, so filter every id match by source first.
+    const byId = findAll(`[id="${escapeCssString(selection.id)}"]`)[0];
+    if (byId) return byId;
   }
 
   if (!selection.selector) return null;
-
-  // fallow-ignore-next-line code-duplication
-  if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
-    const matches = querySelectorAllSafely(doc, selection.selector).filter(
-      (candidate): candidate is HTMLElement =>
-        isHtmlElement(candidate) &&
-        (!selection.sourceFile ||
-          getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
-            selection.sourceFile),
-    );
-    return matches[selection.selectorIndex] ?? null;
-  }
-
-  // fallow-ignore-next-line code-duplication
-  const matches = querySelectorAllSafely(doc, selection.selector).filter(
-    (candidate): candidate is HTMLElement =>
-      isHtmlElement(candidate) &&
-      (!selection.sourceFile ||
-        getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
-          selection.sourceFile),
-  );
-  return matches[0] ?? null;
+  return findAll(selection.selector)[selection.selectorIndex ?? 0] ?? null;
 }
 
 // fallow-ignore-next-line complexity

package/src/components/editor/gsapAnimationCallbacks.ts

@@ -34,3 +34,30 @@ export interface GsapAnimationEditCallbacks {
   /** Unroll a computed (helper/loop) tween into literal tweens so it edits directly. */
   onUnroll?: (animationId: string) => void;
 }
+
+// User-facing control label for each animation-meta field. The ease control is
+// labelled "Speed" in the card UI, so ease/easeEach map there.
+const ANIMATION_META_LABELS: Record<string, { control: string; name: string }> = {
+  duration: { control: "metric", name: "Length" },
+  position: { control: "metric", name: "Starts at" },
+  ease: { control: "select", name: "Speed" },
+  easeEach: { control: "select", name: "Speed" },
+};
+
+/**
+ * Emit design-input telemetry for an `onUpdateMeta` payload, attributing each
+ * changed field to the control the user actually touched. Iterates the real keys
+ * present rather than falling through to a single placeholder — so a meta field
+ * added later is attributed honestly by its own key instead of poisoning another
+ * control's usage count.
+ */
+export function trackAnimationMetaUpdate(
+  track: (control: string, name: string) => void,
+  updates: Record<string, unknown>,
+): void {
+  for (const key of Object.keys(updates)) {
+    const mapped = ANIMATION_META_LABELS[key];
+    if (mapped) track(mapped.control, mapped.name);
+    else track("select", key);
+  }
+}

package/src/components/editor/gsapLivePreview.ts

@@ -0,0 +1,34 @@
+import type { DomEditSelection } from "./domEditingTypes";
+
+/**
+ * Build the "live preview" callback the 3D-transform sub-view fires while a
+ * value is being dragged: apply a gsap.set() to the matching node inside the
+ * preview iframe so the edit is reflected immediately, before it's committed.
+ *
+ * Extracted so the identical closure exists once — shared by the legacy
+ * PropertyPanel Layout section and the flat Layout group (PropertyPanelFlat).
+ */
+// Resolve by id when unique, otherwise by selector + selectorIndex — a bare
+// querySelector(selector) always hits the FIRST match, so dragging on the
+// second of two same-selector siblings would animate the wrong element.
+function resolvePreviewNode(
+  doc: Document | null | undefined,
+  el: DomEditSelection,
+): Element | null {
+  if (!doc) return null;
+  if (el.id) return doc.querySelector(`#${el.id}`);
+  if (!el.selector) return null;
+  return doc.querySelectorAll(el.selector)[el.selectorIndex ?? 0] ?? null;
+}
+
+export function createGsapLivePreview(iframeRef: { readonly current: HTMLIFrameElement | null }) {
+  return (el: DomEditSelection, props: Record<string, number>) => {
+    const iframe = iframeRef.current;
+    const win = iframe?.contentWindow as
+      | { gsap?: { set: (t: Element, v: Record<string, number>) => void } }
+      | null
+      | undefined;
+    const node = resolvePreviewNode(iframe?.contentDocument, el);
+    if (win?.gsap && node) win.gsap.set(node, props);
+  };
+}

package/src/components/editor/layersPanelSort.ts

@@ -0,0 +1,80 @@
+import type { DomEditLayerItem } from "./domEditingTypes";
+import { getElementZIndex } from "../../player/lib/layerOrdering";
+
+interface CollapsedState {
+  [key: string]: boolean;
+}
+
+// ── Pure helpers ──────────────────────────────────────────────────────
+
+// fallow-ignore-next-line complexity
+export function sortLayersByZIndex(layers: DomEditLayerItem[]): DomEditLayerItem[] {
+  if (layers.length <= 1) return layers;
+
+  const minDepth = layers[0].depth;
+  for (let i = 1; i < layers.length; i++) {
+    if (layers[i].depth < minDepth) return layers;
+  }
+
+  const chunks: Array<{ root: DomEditLayerItem; children: DomEditLayerItem[]; domIndex: number }> =
+    [];
+
+  for (let i = 0; i < layers.length; i++) {
+    if (layers[i].depth === minDepth) {
+      const children: DomEditLayerItem[] = [];
+      let j = i + 1;
+      while (j < layers.length && layers[j].depth > minDepth) {
+        children.push(layers[j]);
+        j++;
+      }
+      chunks.push({ root: layers[i], children, domIndex: chunks.length });
+    }
+  }
+
+  if (chunks.length <= 1) {
+    if (chunks.length === 1 && chunks[0].children.length > 0) {
+      const sorted = sortLayersByZIndex(chunks[0].children);
+      return [chunks[0].root, ...sorted];
+    }
+    return layers;
+  }
+
+  chunks.sort((a, b) => {
+    const zA = getElementZIndex(a.root.element);
+    const zB = getElementZIndex(b.root.element);
+    if (zA !== zB) return zB - zA;
+    return b.domIndex - a.domIndex;
+  });
+
+  const result: DomEditLayerItem[] = [];
+  for (const chunk of chunks) {
+    result.push(chunk.root);
+    if (chunk.children.length > 0) {
+      result.push(...sortLayersByZIndex(chunk.children));
+    }
+  }
+  return result;
+}
+
+export function getVisibleLayers(
+  layers: DomEditLayerItem[],
+  collapsed: CollapsedState,
+): DomEditLayerItem[] {
+  if (Object.keys(collapsed).length === 0) return layers;
+
+  const result: DomEditLayerItem[] = [];
+  let skipDepth = -1;
+
+  for (const layer of layers) {
+    if (skipDepth >= 0 && layer.depth > skipDepth) continue;
+    skipDepth = -1;
+
+    result.push(layer);
+
+    if (collapsed[layer.key] && layer.childCount > 0) {
+      skipDepth = layer.depth;
+    }
+  }
+
+  return result;
+}

package/src/components/editor/manualEditingAvailability.test.ts

@@ -105,4 +105,14 @@ describe("manual editing availability", () => {
     expect(resolveStudioBooleanEnvFlag({ EMPTY: "" }, ["EMPTY"], true)).toBe(true);
     expect(resolveStudioBooleanEnvFlag({ UNKNOWN: "maybe" }, ["UNKNOWN"], false)).toBe(false);
   });
+
+  it("defaults the flat inspector flag to false and honors an explicit override", async () => {
+    const off = await loadAvailabilityWithEnv({});
+    expect(off.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(false);
+
+    const on = await loadAvailabilityWithEnv({
+      VITE_STUDIO_FLAT_INSPECTOR_ENABLED: "true",
+    });
+    expect(on.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(true);
+  });
 });

package/src/components/editor/manualEditingAvailability.ts

@@ -97,4 +97,13 @@ export const STUDIO_SDK_RESOLVER_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
   true,
 );
 
+// Studio inspector redesign ("Ledger, flat" — design_handoff_studio_inspector):
+// flat identity header/footer/groups behind a flag for incremental review.
+// Default false; enable via VITE_STUDIO_FLAT_INSPECTOR_ENABLED=true.
+export const STUDIO_FLAT_INSPECTOR_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_ENABLE_FLAT_INSPECTOR", "VITE_STUDIO_FLAT_INSPECTOR_ENABLED"],
+  false,
+);
+
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";