@hyperframes/studio 0.7.60 → 0.7.62

package/src/components/editor/PropertyPanel.tsx

@@ -197,11 +197,11 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
   const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
   const manualRotationEditingDisabled = !element.capabilities.canApplyManualRotation;
   const sourceLabel = element.id ? `#${element.id}` : (element.selector ?? "");
-  const showEditableSections = element.capabilities.canEditStyles;
   // Capabilities are already resolved on the selection; recompute only sections,
   // feeding the live GSAP tween count (arrives on the gsapAnimations prop, not the
   // selection) so the Timing section shows for pure-GSAP elements with no data-start.
   const sections = resolveEditingSections(domEditSelectionToFacts(element, gsapAnimations.length));
+  const showEditableSections = element.capabilities.canEditStyles && sections.style;
   const manualOffset = readStudioPathOffset(element.element);
   const manualSize = readStudioBoxSize(element.element);
   const resolvedWidth =
@@ -385,161 +385,163 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
           />
         )}
 
-        <Section title="Layout" icon={<Move size={15} />}>
-          <div className={RESPONSIVE_GRID}>
-            <div className="flex items-center gap-1">
-              <div className="flex-1">
-                <MetricField
-                  label="X"
-                  value={formatPxMetricValue(displayX)}
-                  disabled={manualOffsetEditingDisabled}
-                  scrub
-                  onCommit={(next) => commitManualOffset("x", next)}
-                />
+        {sections.layout && (
+          <Section title="Layout" icon={<Move size={15} />}>
+            <div className={RESPONSIVE_GRID}>
+              <div className="flex items-center gap-1">
+                <div className="flex-1">
+                  <MetricField
+                    label="X"
+                    value={formatPxMetricValue(displayX)}
+                    disabled={manualOffsetEditingDisabled}
+                    scrub
+                    onCommit={(next) => commitManualOffset("x", next)}
+                  />
+                </div>
+                {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
+                  <KeyframeNavigation
+                    property="x"
+                    keyframes={navKeyframes}
+                    currentPercentage={currentPct}
+                    onSeek={seekFromKfPct}
+                    onAddKeyframe={() =>
+                      onCommitAnimatedProperty &&
+                      void onCommitAnimatedProperty(element, "x", displayX)
+                    }
+                    onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("x"), pct)}
+                    onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("x"))}
+                  />
+                )}
               </div>
-              {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
-                <KeyframeNavigation
-                  property="x"
-                  keyframes={navKeyframes}
-                  currentPercentage={currentPct}
-                  onSeek={seekFromKfPct}
-                  onAddKeyframe={() =>
-                    onCommitAnimatedProperty &&
-                    void onCommitAnimatedProperty(element, "x", displayX)
-                  }
-                  onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("x"), pct)}
-                  onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("x"))}
-                />
-              )}
-            </div>
-            <div className="flex items-center gap-1">
-              <div className="flex-1">
-                <MetricField
-                  label="Y"
-                  value={formatPxMetricValue(displayY)}
-                  disabled={manualOffsetEditingDisabled}
-                  scrub
-                  onCommit={(next) => commitManualOffset("y", next)}
-                />
+              <div className="flex items-center gap-1">
+                <div className="flex-1">
+                  <MetricField
+                    label="Y"
+                    value={formatPxMetricValue(displayY)}
+                    disabled={manualOffsetEditingDisabled}
+                    scrub
+                    onCommit={(next) => commitManualOffset("y", next)}
+                  />
+                </div>
+                {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
+                  <KeyframeNavigation
+                    property="y"
+                    keyframes={navKeyframes}
+                    currentPercentage={currentPct}
+                    onSeek={seekFromKfPct}
+                    onAddKeyframe={() =>
+                      onCommitAnimatedProperty &&
+                      void onCommitAnimatedProperty(element, "y", displayY)
+                    }
+                    onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("y"), pct)}
+                    onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("y"))}
+                  />
+                )}
               </div>
-              {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
-                <KeyframeNavigation
-                  property="y"
-                  keyframes={navKeyframes}
-                  currentPercentage={currentPct}
-                  onSeek={seekFromKfPct}
-                  onAddKeyframe={() =>
-                    onCommitAnimatedProperty &&
-                    void onCommitAnimatedProperty(element, "y", displayY)
-                  }
-                  onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("y"), pct)}
-                  onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("y"))}
-                />
-              )}
-            </div>
-            <div className="flex items-center gap-1">
-              <div className="flex-1">
-                <MetricField
-                  label="W"
-                  value={formatPxMetricValue(displayW)}
-                  disabled={manualSizeEditingDisabled}
-                  scrub
-                  onCommit={(next) => commitManualSize("width", next)}
-                />
+              <div className="flex items-center gap-1">
+                <div className="flex-1">
+                  <MetricField
+                    label="W"
+                    value={formatPxMetricValue(displayW)}
+                    disabled={manualSizeEditingDisabled}
+                    scrub
+                    onCommit={(next) => commitManualSize("width", next)}
+                  />
+                </div>
+                {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
+                  <KeyframeNavigation
+                    property="width"
+                    keyframes={navKeyframes}
+                    currentPercentage={currentPct}
+                    onSeek={seekFromKfPct}
+                    onAddKeyframe={() =>
+                      onCommitAnimatedProperty &&
+                      void onCommitAnimatedProperty(element, "width", displayW)
+                    }
+                    onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("width"), pct)}
+                    onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("width"))}
+                  />
+                )}
               </div>
-              {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
-                <KeyframeNavigation
-                  property="width"
-                  keyframes={navKeyframes}
-                  currentPercentage={currentPct}
-                  onSeek={seekFromKfPct}
-                  onAddKeyframe={() =>
-                    onCommitAnimatedProperty &&
-                    void onCommitAnimatedProperty(element, "width", displayW)
-                  }
-                  onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("width"), pct)}
-                  onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("width"))}
-                />
-              )}
-            </div>
-            <div className="flex items-center gap-1">
-              <div className="flex-1">
-                <MetricField
-                  label="H"
-                  value={formatPxMetricValue(displayH)}
-                  disabled={manualSizeEditingDisabled}
-                  scrub
-                  onCommit={(next) => commitManualSize("height", next)}
-                />
+              <div className="flex items-center gap-1">
+                <div className="flex-1">
+                  <MetricField
+                    label="H"
+                    value={formatPxMetricValue(displayH)}
+                    disabled={manualSizeEditingDisabled}
+                    scrub
+                    onCommit={(next) => commitManualSize("height", next)}
+                  />
+                </div>
+                {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
+                  <KeyframeNavigation
+                    property="height"
+                    keyframes={navKeyframes}
+                    currentPercentage={currentPct}
+                    onSeek={seekFromKfPct}
+                    onAddKeyframe={() =>
+                      onCommitAnimatedProperty &&
+                      void onCommitAnimatedProperty(element, "height", displayH)
+                    }
+                    onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("height"), pct)}
+                    onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("height"))}
+                  />
+                )}
               </div>
-              {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
-                <KeyframeNavigation
-                  property="height"
-                  keyframes={navKeyframes}
-                  currentPercentage={currentPct}
-                  onSeek={seekFromKfPct}
-                  onAddKeyframe={() =>
-                    onCommitAnimatedProperty &&
-                    void onCommitAnimatedProperty(element, "height", displayH)
-                  }
-                  onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("height"), pct)}
-                  onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("height"))}
-                />
-              )}
-            </div>
-            <div className="flex items-center gap-1">
-              <div className="flex-1">
-                <MetricField
-                  label="R"
-                  value={`${displayR}°`}
-                  disabled={manualRotationEditingDisabled}
-                  onCommit={(next) => commitManualRotation(next.replace("°", ""))}
-                />
+              <div className="flex items-center gap-1">
+                <div className="flex-1">
+                  <MetricField
+                    label="R"
+                    value={`${displayR}°`}
+                    disabled={manualRotationEditingDisabled}
+                    onCommit={(next) => commitManualRotation(next.replace("°", ""))}
+                  />
+                </div>
+                {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
+                  <KeyframeNavigation
+                    property="rotation"
+                    keyframes={navKeyframes}
+                    currentPercentage={currentPct}
+                    onSeek={seekFromKfPct}
+                    onAddKeyframe={() =>
+                      onCommitAnimatedProperty &&
+                      void onCommitAnimatedProperty(element, "rotation", displayR)
+                    }
+                    onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("rotation"), pct)}
+                    onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("rotation"))}
+                  />
+                )}
               </div>
-              {STUDIO_KEYFRAMES_ENABLED && gsapAnimId && (
-                <KeyframeNavigation
-                  property="rotation"
-                  keyframes={navKeyframes}
-                  currentPercentage={currentPct}
-                  onSeek={seekFromKfPct}
-                  onAddKeyframe={() =>
-                    onCommitAnimatedProperty &&
-                    void onCommitAnimatedProperty(element, "rotation", displayR)
-                  }
-                  onRemoveKeyframe={(pct) => onRemoveKeyframe?.(animIdForProp("rotation"), pct)}
-                  onConvertToKeyframes={() => onConvertToKeyframes?.(animIdForProp("rotation"))}
-                />
-              )}
             </div>
-          </div>
-          <PropertyPanel3dTransform
-            gsapRuntimeValues={gsap3dValues}
-            gsapAnimId={gsapAnimId}
-            resolveAnimIdForProp={animIdForProp}
-            gsapKeyframes={navKeyframes}
-            currentPct={currentPct}
-            elStart={elStart}
-            elDuration={elDuration}
-            element={element}
-            onCommitAnimatedProperty={onCommitAnimatedProperty}
-            onCommitAnimatedProperties={onCommitAnimatedProperties}
-            onSeekToTime={onSeekToTime}
-            onRemoveKeyframe={onRemoveKeyframe}
-            onConvertToKeyframes={onConvertToKeyframes}
-            onLivePreviewProps={createGsapLivePreview(iframeRef)}
-          />
-          <div className="mt-3">
-            <div className="mb-2 text-[10px] font-medium uppercase tracking-wider text-neutral-600">
-              Stacking
-            </div>
-            <MetricField
-              label="Z-index"
-              value={String(parseInt(styles["z-index"] || "auto", 10) || 0)}
-              scrub
-              onCommit={(next) => onSetStyle("z-index", next)}
+            <PropertyPanel3dTransform
+              gsapRuntimeValues={gsap3dValues}
+              gsapAnimId={gsapAnimId}
+              resolveAnimIdForProp={animIdForProp}
+              gsapKeyframes={navKeyframes}
+              currentPct={currentPct}
+              elStart={elStart}
+              elDuration={elDuration}
+              element={element}
+              onCommitAnimatedProperty={onCommitAnimatedProperty}
+              onCommitAnimatedProperties={onCommitAnimatedProperties}
+              onSeekToTime={onSeekToTime}
+              onRemoveKeyframe={onRemoveKeyframe}
+              onConvertToKeyframes={onConvertToKeyframes}
+              onLivePreviewProps={createGsapLivePreview(iframeRef)}
             />
-          </div>
-        </Section>
+            <div className="mt-3">
+              <div className="mb-2 text-[10px] font-medium uppercase tracking-wider text-neutral-600">
+                Stacking
+              </div>
+              <MetricField
+                label="Z-index"
+                value={String(parseInt(styles["z-index"] || "auto", 10) || 0)}
+                scrub
+                onCommit={(next) => onSetStyle("z-index", next)}
+              />
+            </div>
+          </Section>
+        )}
 
         {STUDIO_GSAP_PANEL_ENABLED &&
           onUpdateGsapProperty &&

package/src/components/editor/PropertyPanelFlat.tsx

@@ -78,6 +78,7 @@ export function PropertyPanelFlat({
   onClearSelection,
   onUngroup,
   onSetStyle,
+  onPreviewStyle,
   onSetAttribute,
   onSetAttributes,
   onSetAttributeLive,
@@ -86,6 +87,7 @@ export function PropertyPanelFlat({
   onRemoveBackground,
   onSetText,
   onSetTextFieldStyle,
+  onPreviewTextFieldStyle,
   onAddTextField,
   onRemoveTextField,
   onAskAgent,
@@ -147,6 +149,7 @@ export function PropertyPanelFlat({
   | "onClearSelection"
   | "onUngroup"
   | "onSetStyle"
+  | "onPreviewStyle"
   | "onSetAttribute"
   | "onSetAttributes"
   | "onSetAttributeLive"
@@ -155,6 +158,7 @@ export function PropertyPanelFlat({
   | "onRemoveBackground"
   | "onSetText"
   | "onSetTextFieldStyle"
+  | "onPreviewTextFieldStyle"
   | "onAddTextField"
   | "onRemoveTextField"
   | "onAskAgent"
@@ -360,6 +364,7 @@ export function PropertyPanelFlat({
           onImportFonts={onImportFonts}
           onSetText={onSetText}
           onSetTextFieldStyle={onSetTextFieldStyle}
+          onPreviewTextFieldStyle={onPreviewTextFieldStyle}
           onAddTextField={onAddTextField}
           onRemoveTextField={onRemoveTextField}
         />
@@ -382,54 +387,57 @@ export function PropertyPanelFlat({
           styles={styles}
           assets={assets}
           onSetStyle={onSetStyle}
+          onPreviewStyle={onPreviewStyle}
           onImportAssets={onImportAssets}
           gsapBorderRadius={gsapBorderRadius}
         />
       ),
     });
   }
-  groups.push({
-    id: "layout",
-    title: "Layout",
-    // No scrub accessory: FlatRow/CommitField has no pointer-drag scrubbing
-    // (wheel/arrow keys only) — advertising "drag values to scrub" here lies.
-    summary: `${formatPxMetricValue(displayX)},${formatPxMetricValue(displayY)} · ${Math.round(displayW)}×${Math.round(displayH)}`,
-    content: (
-      <FlatLayoutSection
-        element={element}
-        styles={styles}
-        onSetStyle={onSetStyle}
-        disabled={!element.capabilities.canEditStyles}
-        displayX={displayX}
-        displayY={displayY}
-        displayW={displayW}
-        displayH={displayH}
-        displayR={displayR}
-        manualOffsetEditingDisabled={manualOffsetEditingDisabled}
-        manualSizeEditingDisabled={manualSizeEditingDisabled}
-        manualRotationEditingDisabled={manualRotationEditingDisabled}
-        commitManualOffset={commitManualOffset}
-        commitManualSize={commitManualSize}
-        commitManualRotation={commitManualRotation}
-        gsapAnimId={gsapAnimId}
-        navKeyframes={navKeyframes}
-        currentPct={currentPct}
-        seekFromKfPct={seekFromKfPct}
-        animIdForProp={animIdForProp}
-        resolveAnimIdForProp={animIdForProp}
-        gsapRuntimeValues={gsapRuntimeValues}
-        gsapKeyframes={navKeyframes}
-        elStart={elStart}
-        elDuration={elDuration}
-        onCommitAnimatedProperty={onCommitAnimatedProperty}
-        onCommitAnimatedProperties={onCommitAnimatedProperties}
-        onSeekToTime={onSeekToTime}
-        onRemoveKeyframe={onRemoveKeyframe}
-        onConvertToKeyframes={onConvertToKeyframes}
-        onLivePreviewProps={createGsapLivePreview(previewIframeRef ?? { current: null })}
-      />
-    ),
-  });
+  if (sections.layout) {
+    groups.push({
+      id: "layout",
+      title: "Layout",
+      // No scrub accessory: FlatRow/CommitField has no pointer-drag scrubbing
+      // (wheel/arrow keys only) — advertising "drag values to scrub" here lies.
+      summary: `${formatPxMetricValue(displayX)},${formatPxMetricValue(displayY)} · ${Math.round(displayW)}×${Math.round(displayH)}`,
+      content: (
+        <FlatLayoutSection
+          element={element}
+          styles={styles}
+          onSetStyle={onSetStyle}
+          disabled={!element.capabilities.canEditStyles}
+          displayX={displayX}
+          displayY={displayY}
+          displayW={displayW}
+          displayH={displayH}
+          displayR={displayR}
+          manualOffsetEditingDisabled={manualOffsetEditingDisabled}
+          manualSizeEditingDisabled={manualSizeEditingDisabled}
+          manualRotationEditingDisabled={manualRotationEditingDisabled}
+          commitManualOffset={commitManualOffset}
+          commitManualSize={commitManualSize}
+          commitManualRotation={commitManualRotation}
+          gsapAnimId={gsapAnimId}
+          navKeyframes={navKeyframes}
+          currentPct={currentPct}
+          seekFromKfPct={seekFromKfPct}
+          animIdForProp={animIdForProp}
+          resolveAnimIdForProp={animIdForProp}
+          gsapRuntimeValues={gsapRuntimeValues}
+          gsapKeyframes={navKeyframes}
+          elStart={elStart}
+          elDuration={elDuration}
+          onCommitAnimatedProperty={onCommitAnimatedProperty}
+          onCommitAnimatedProperties={onCommitAnimatedProperties}
+          onSeekToTime={onSeekToTime}
+          onRemoveKeyframe={onRemoveKeyframe}
+          onConvertToKeyframes={onConvertToKeyframes}
+          onLivePreviewProps={createGsapLivePreview(previewIframeRef ?? { current: null })}
+        />
+      ),
+    });
+  }
   if (showMotionGroup) {
     groups.push({
       id: "motion",

package/src/components/editor/compositionReliabilityFixture.integration.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { patchElementInHtml } from "@hyperframes/studio-server/source-mutation";
+import { describe, expect, it } from "vitest";
+import { buildDomEditStylePatchOperation } from "./domEditing";
+
+const fixtureDir = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../tests/e2e/fixtures/composition-reliability",
+);
+
+function fixture(path: string): string {
+  return readFileSync(join(fixtureDir, path), "utf8");
+}
+
+function parse(html: string): Document {
+  return new DOMParser().parseFromString(html, "text/html");
+}
+
+function inTemplate(document: Document, selector: string): Element | null {
+  for (const template of Array.from(document.querySelectorAll("template"))) {
+    const match = template.content.querySelector(selector);
+    if (match) return match;
+  }
+  return null;
+}
+
+describe("composition reliability acceptance fixture", () => {
+  const indexSource = fixture("index.html");
+  const titleSource = fixture("compositions/title-card.html");
+  const nestedSource = fixture("compositions/nested-shell.html");
+
+  it("owns repeated root hosts, a nested host, transparent headline topology, and collisions", () => {
+    const index = parse(indexSource);
+    const repeated = Array.from(
+      index.querySelectorAll('[data-composition-src="compositions/title-card.html"]'),
+    );
+    expect(repeated).toHaveLength(2);
+    expect(repeated.map((host) => host.getAttribute("data-start"))).toEqual(["0", "4"]);
+    expect(
+      index.querySelector('[data-composition-src="compositions/nested-shell.html"]'),
+    ).toBeTruthy();
+
+    const nested = parse(nestedSource);
+    const nestedHost = inTemplate(nested, '[data-composition-src="title-card.html"]');
+    expect(nestedHost).toBeTruthy();
+    const nestedDependency = nestedHost?.getAttribute("data-composition-src");
+    expect(
+      nestedDependency ? existsSync(resolve(fixtureDir, "compositions", nestedDependency)) : false,
+    ).toBe(true);
+
+    const title = parse(titleSource);
+    const mask = inTemplate(title, ".hl-mask");
+    const headline = inTemplate(title, ".hl-mask > .hl-text");
+    expect(mask?.textContent).toContain("Reliable compositions");
+    expect(inTemplate(title, "style")?.textContent).toMatch(
+      /\.hl-mask\s*\{[^}]*overflow:\s*hidden;[^}]*background:\s*transparent;/,
+    );
+    expect(headline?.tagName).toBe("H1");
+
+    const collisionA = index.querySelector('[data-hf-id="collision-a"]')!;
+    const collisionB = index.querySelector('[data-hf-id="collision-b"]')!;
+    const layered = index.querySelector('[data-hf-id="layer-overlap"]')!;
+    expect(collisionA.getAttribute("data-track-index")).toBe(
+      collisionB.getAttribute("data-track-index"),
+    );
+    expect(
+      Number(collisionA.getAttribute("data-start")) +
+        Number(collisionA.getAttribute("data-duration")),
+    ).toBe(Number(collisionB.getAttribute("data-start")));
+    expect(layered.getAttribute("data-start")).toBe(collisionB.getAttribute("data-start"));
+    expect(layered.getAttribute("data-track-index")).not.toBe(
+      collisionB.getAttribute("data-track-index"),
+    );
+  });
+
+  it("keeps timeline host edits in the root source and headline color in the template source", () => {
+    const moved = patchElementInHtml(indexSource, { hfId: "title-host-a" }, [
+      { type: "attribute", property: "start", value: "5" },
+      { type: "attribute", property: "duration", value: "2" },
+    ]);
+    expect(moved.matched).toBe(true);
+    expect(moved.html).toContain('data-hf-id="title-host-a"');
+    expect(moved.html).toContain('data-start="5"');
+    expect(moved.html).toContain('data-duration="2"');
+    expect(moved.html).not.toContain('data-hf-id="title-text"');
+    expect(titleSource).not.toContain("#12b886");
+
+    const recolored = patchElementInHtml(titleSource, { hfId: "title-text" }, [
+      buildDomEditStylePatchOperation("color", "#12b886"),
+    ]);
+    expect(recolored.matched).toBe(true);
+    const recoloredDocument = parse(recolored.html);
+    expect(
+      inTemplate(recoloredDocument, '[data-hf-id="title-text"]')?.getAttribute("style"),
+    ).toContain("color: #12b886");
+    expect(
+      inTemplate(recoloredDocument, '[data-hf-id="title-mask"]')?.getAttribute("style"),
+    ).toBeNull();
+    expect(recolored.html).not.toContain('data-hf-id="title-host-a"');
+    expect(indexSource).not.toContain("#12b886");
+  });
+});

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

@@ -739,6 +739,40 @@ describe("resolveDomEditSelection", () => {
     expect(selection?.selector).toBe("#copy");
   });
 
+  it("keeps a transparent overflow mask structural when directly selecting its headline", async () => {
+    const document = createDocument(`
+      <template id="source-template"></template>
+      <section class="hl-block">
+        <div class="hl-mask" style="overflow: hidden; background: transparent">
+          <h1 class="hl-text">Launch title</h1>
+        </div>
+      </section>
+    `);
+    const headline = document.querySelector<HTMLElement>(".hl-text")!;
+    setElementRect(headline, { left: 44, top: 52, width: 220, height: 48 });
+    const selection = await resolveDomEditSelection(headline, {
+      activeCompositionPath: "index.html",
+      isMasterView: false,
+      preferClipAncestor: false,
+    });
+
+    expect(selection?.element).toBe(headline);
+    expect(selection?.selector).toBe(".hl-text");
+    expect(selection?.textFields).toMatchObject([{ source: "self", tagName: "h1" }]);
+    expect(selection?.boundingBox).toEqual({ x: 44, y: 52, width: 220, height: 48 });
+    // Explicit layer navigation remains free to resolve the structural mask.
+    const mask = document.querySelector<HTMLElement>(".hl-mask")!;
+    expect(
+      (
+        await resolveDomEditSelection(mask, {
+          activeCompositionPath: "index.html",
+          isMasterView: false,
+          preferClipAncestor: false,
+        })
+      )?.element,
+    ).toBe(mask);
+  });
+
   // fallow-ignore-next-line code-duplication
   it("collects simple child text blocks as separate editable fields", async () => {
     const document = createDocument(`

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

@@ -106,13 +106,13 @@ describe("manual editing availability", () => {
     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);
+  it("defaults the flat inspector flag to true and honors an explicit override", async () => {
+    const on = await loadAvailabilityWithEnv({});
+    expect(on.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(true);
 
-    const on = await loadAvailabilityWithEnv({
-      VITE_STUDIO_FLAT_INSPECTOR_ENABLED: "true",
+    const off = await loadAvailabilityWithEnv({
+      VITE_STUDIO_FLAT_INSPECTOR_ENABLED: "false",
     });
-    expect(on.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(true);
+    expect(off.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(false);
   });
 });