@hyperframes/studio 0.8.46 → 0.8.48

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

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveStudioBooleanEnvFlag } from "./manualEditingAvailability";
+import { STUDIO_SDK_OPERATION_FAMILIES } from "../../utils/sdkCutoverPolicy";
 
 async function loadAvailabilityWithEnv(env: Record<string, string | undefined>) {
   vi.resetModules();
@@ -88,4 +89,22 @@ describe("manual editing availability", () => {
     });
     expect(off.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(false);
   });
+
+  it("defaults SDK cutover on for every family", async () => {
+    const all = await loadAvailabilityWithEnv({});
+    expect(all.STUDIO_SDK_CUTOVER_ENABLED).toBe(true);
+    expect(all.STUDIO_SDK_CUTOVER_FAMILIES).toEqual(new Set(STUDIO_SDK_OPERATION_FAMILIES));
+  });
+
+  it("honors the SDK cutover kill switches", async () => {
+    const off = await loadAvailabilityWithEnv({ VITE_STUDIO_SDK_CUTOVER_ENABLED: "false" });
+    expect(off.STUDIO_SDK_CUTOVER_ENABLED).toBe(false);
+    expect(off.STUDIO_SDK_CUTOVER_FAMILIES.size).toBe(0);
+
+    const subset = await loadAvailabilityWithEnv({
+      VITE_STUDIO_SDK_CUTOVER_FAMILIES: "dom,timing",
+    });
+    expect(subset.STUDIO_SDK_CUTOVER_ENABLED).toBe(true);
+    expect(subset.STUDIO_SDK_CUTOVER_FAMILIES).toEqual(new Set(["dom", "timing"]));
+  });
 });

package/src/components/editor/manualEditingAvailability.ts

@@ -38,16 +38,20 @@ const runtimeEnv =
     : {};
 const env = { ...(import.meta.env ?? {}), ...runtimeEnv } as StudioFeatureFlagEnv;
 
-// Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch
-// instead of the server patch-element API. Default false; enable via
-// VITE_STUDIO_SDK_CUTOVER_ENABLED=true. Requires SDK session to be open.
+// Stage 7 SDK cutover — routes Studio edits through SDK dispatch instead of the
+// server patch/mutation routes. Default TRUE as of the flip release (spec:
+// 2026-09-17-studio-sdk-cutover-flip-design.md). Kill switch:
+// VITE_STUDIO_SDK_CUTOVER_ENABLED=false (works at runtime via __HF_STUDIO_ENV__).
 export const STUDIO_SDK_CUTOVER_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_SDK_CUTOVER_ENABLED"],
-  false,
+  true,
 );
 
-/** Explicit per-operation-family canary selection; the master flag alone enables nothing. */
+/**
+ * Per-family selection. Unset = every family (the master alone enables all).
+ * Set `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing` to RESTRICT to a subset.
+ */
 export const STUDIO_SDK_CUTOVER_FAMILIES = resolveEnabledSdkFamilies(
   env,
   STUDIO_SDK_CUTOVER_ENABLED,

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

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import type { HfAutomation } from "@hyperframes/core/audio-automation";
-import { automationAttrValue, withLane, withoutLane } from "./propertyPanelAutomation.js";
+import {
+  automationAttrValue,
+  withLane,
+  withoutLane,
+  withPointAt,
+} from "./propertyPanelAutomation.js";
 
 const carved = (): HfAutomation => ({
   version: 1,
@@ -45,6 +50,82 @@ describe("withLane", () => {
   });
 });
 
+// A panel control has no drag gesture of its own, so a commit has to land on
+// the same point the timeline envelope's double-click would have produced.
+describe("withPointAt", () => {
+  it("adds a point to an existing lane, keeping the others", () => {
+    const next = withPointAt(carved(), "volume", 5, 0.3);
+    const volume = next.lanes.find((l) => l.target === "volume");
+    expect(volume?.points).toEqual([
+      { t: 0, v: 0.8 },
+      { t: 5, v: 0.3 },
+    ]);
+  });
+
+  it("replaces the nearby point instead of stacking a second one on top of it", () => {
+    const automation: HfAutomation = {
+      version: 1,
+      lanes: [
+        {
+          target: "volume",
+          points: [
+            { t: 0, v: 0.8 },
+            { t: 5, v: 0.3 },
+          ],
+        },
+      ],
+    };
+    const next = withPointAt(automation, "volume", 5.01, 0.6);
+    const volume = next.lanes.find((l) => l.target === "volume");
+    expect(volume?.points).toEqual([
+      { t: 0, v: 0.8 },
+      { t: 5.01, v: 0.6 },
+    ]);
+  });
+
+  it("keeps points sorted after an insert earlier than the last one", () => {
+    const automation: HfAutomation = {
+      version: 1,
+      lanes: [
+        {
+          target: "volume",
+          points: [
+            { t: 0, v: 0.2 },
+            { t: 10, v: 0.9 },
+          ],
+        },
+      ],
+    };
+    const next = withPointAt(automation, "volume", 4, 0.5);
+    expect(next.lanes.find((l) => l.target === "volume")?.points.map((p) => p.t)).toEqual([
+      0, 4, 10,
+    ]);
+  });
+
+  it("seeds the start when writing to an empty lane away from t=0", () => {
+    // A single point would be a constant jump the instant playback crosses it,
+    // not the envelope a fresh keyframe should produce.
+    const automation: HfAutomation = { version: 1, lanes: [{ target: "volume", points: [] }] };
+    const next = withPointAt(automation, "volume", 5, 0.3);
+    expect(next.lanes.find((l) => l.target === "volume")?.points).toEqual([
+      { t: 0, v: 0.3 },
+      { t: 5, v: 0.3 },
+    ]);
+  });
+
+  it("does not seed a second point when writing at the start of an empty lane", () => {
+    const automation: HfAutomation = { version: 1, lanes: [{ target: "volume", points: [] }] };
+    const next = withPointAt(automation, "volume", 0, 0.4);
+    expect(next.lanes.find((l) => l.target === "volume")?.points).toEqual([{ t: 0, v: 0.4 }]);
+  });
+
+  it("leaves sibling lanes untouched", () => {
+    const next = withPointAt(carved(), "fx.n1.gain", 3, -2);
+    expect(next.lanes.find((l) => l.target === "fx.n2.gain")?.points).toEqual([{ t: 0, v: -9 }]);
+    expect(next.lanes.find((l) => l.target === "volume")?.points).toEqual([{ t: 0, v: 0.8 }]);
+  });
+});
+
 describe("withoutLane", () => {
   it("takes one lane and leaves the rest", () => {
     // A node removed without its lane leaves an orphan driving a parameter that

package/src/components/editor/propertyPanelAutomation.ts

@@ -17,6 +17,7 @@ import {
   type HfAutomation,
 } from "@hyperframes/core/audio-automation";
 import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { mergeInsertPoint } from "../../player/components/automationLaneGeometry";
 
 const EMPTY: HfAutomation = { version: 1, lanes: [] };
 
@@ -89,6 +90,20 @@ export function withLane(automation: HfAutomation, lane: HfAutomationLane): HfAu
   };
 }
 
+/** Insert or replace the point nearest `t` on `target`'s lane — reuses the
+ * timeline envelope's own double-click merge rule, so a panel control with no
+ * drag gesture of its own can still write into an automated parameter the
+ * same way. */
+export function withPointAt(
+  automation: HfAutomation,
+  target: string,
+  t: number,
+  v: number,
+): HfAutomation {
+  const points = automation.lanes.find((lane) => lane.target === target)?.points ?? [];
+  return withLane(automation, { target, points: mergeInsertPoint(points, t, v) });
+}
+
 /** The attribute value for an automation set; empty when nothing is automated. */
 export function automationAttrValue(automation: HfAutomation): string {
   return automation.lanes.length > 0 ? serializeAutomation(automation) : "";

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

@@ -189,6 +189,41 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
     act(() => root.unmount());
   });
 
+  it("writes through the envelope instead of the attribute once volume is automated", () => {
+    const onSetAttribute = vi.fn();
+    const onCommitVolumeAt = vi.fn();
+    const element = makeVideoElement({ dataAttributes: { volume: "1" } });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <FlatMediaSection
+          projectDir={null}
+          element={element}
+          styles={{}}
+          onSetStyle={vi.fn()}
+          onSetAttribute={onSetAttribute}
+          onSetHtmlAttribute={vi.fn()}
+          volumeAutomated
+          onCommitVolumeAt={onCommitVolumeAt}
+        />,
+      );
+    });
+    const volumeTrack = host.querySelectorAll('[data-flat-slider-track="true"]')[0];
+    Object.defineProperty(volumeTrack, "getBoundingClientRect", {
+      value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
+    });
+    act(() => {
+      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 100 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 100 }));
+    });
+    expect(onCommitVolumeAt).toHaveBeenCalledTimes(1);
+    expect(onCommitVolumeAt.mock.calls[0][0]).toBeCloseTo(3.981072, 6);
+    expect(onSetAttribute).not.toHaveBeenCalledWith("volume", expect.anything());
+    act(() => root.unmount());
+  });
+
   it("commits a new rate value on slider track pointerdown", () => {
     const onSetAttribute = vi.fn();
     const element = makeVideoElement();

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -34,6 +34,8 @@ export function FlatMediaSection({
   volumeAutomated,
   onAutomateVolume,
   onRemoveVolumeAutomation,
+  onCommitVolumeAt,
+  automatedVolumeValue,
 }: {
   projectDir: string | null;
   element: DomEditSelection;
@@ -41,10 +43,12 @@ export function FlatMediaSection({
   onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
-  /** A volume lane in the timeline drives the level; the slider cannot. */
+  /** A volume lane in the timeline drives the level; the slider writes a keyframe instead. */
   volumeAutomated?: boolean;
   onAutomateVolume?: () => void;
   onRemoveVolumeAutomation?: () => void;
+  onCommitVolumeAt?: (v: number) => void;
+  automatedVolumeValue?: number;
   onRemoveBackground?: (
     inputPath: string,
     options: {
@@ -61,7 +65,13 @@ export function FlatMediaSection({
   const isVisualMedia = isVideo || isImage;
   const el = element.element;
 
-  const volume = parseNumericValue(element.dataAttributes.volume ?? "") ?? 1;
+  // While a lane owns the level, the envelope's live value at the playhead is
+  // what the slider must show — the static attribute is only what the engine
+  // falls back to outside automation.
+  const volume =
+    volumeAutomated && automatedVolumeValue !== undefined
+      ? automatedVolumeValue
+      : (parseNumericValue(element.dataAttributes.volume ?? "") ?? 1);
   const volumeFaderPosition = audioGainToFaderPosition(volume);
   const mediaStart =
     Number.parseFloat(
@@ -213,9 +223,9 @@ export function FlatMediaSection({
       )}
       {(isVideo || isAudio) && (
         <>
-          {/* The slider is disabled while a lane owns the level: a value set
-              here would be overwritten by the envelope on the next tick. The
-              toggle beside it carries the tooltip. */}
+          {/* While a lane owns the level, a commit writes a keyframe at the
+              playhead instead of the plain attribute — same slider, same
+              gesture, the write just goes through the envelope. */}
           <div
             className="hf-volume-row flex items-center gap-1"
             data-volume-automated={volumeAutomated ? "" : undefined}
@@ -228,11 +238,15 @@ export function FlatMediaSection({
                 max={AUDIO_GAIN_FADER_MAX}
                 tier={volume === 1 ? "default" : "explicitCustom"}
                 displayValue={audioGainToText(volume)}
-                disabled={volumeAutomated}
                 centerTick
-                onCommit={(next) =>
-                  void onSetAttribute("volume", formatAudioGain(audioFaderPositionToGain(next)))
-                }
+                onCommit={(next) => {
+                  const gain = audioFaderPositionToGain(next);
+                  if (volumeAutomated) {
+                    onCommitVolumeAt?.(gain);
+                  } else {
+                    void onSetAttribute("volume", formatAudioGain(gain));
+                  }
+                }}
               />
             </div>
             <AutomationToggle

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

@@ -7,12 +7,15 @@ import type { DomEditSelection } from "./domEditingTypes";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-function bind(dataAttributes: Record<string, string>) {
+// The clip-local playhead time the hook derives is `currentTime - data-start`,
+// clamped to `data-duration`: tests that care about it set both attributes.
+function bind(dataAttributes: Record<string, string>, currentTime = 0) {
   const onSetAttributeQuiet = vi.fn();
   const captured: { current: VolumeAutomationBinding | null } = { current: null };
   function Probe() {
     captured.current = useVolumeAutomation(
       { dataAttributes } as unknown as DomEditSelection,
+      currentTime,
       onSetAttributeQuiet,
     );
     return null;
@@ -29,6 +32,14 @@ function bind(dataAttributes: Record<string, string>) {
 const volumeLane = (v: number) =>
   JSON.stringify({ version: 1, lanes: [{ target: "volume", points: [{ t: 0, v }] }] });
 
+const writtenAutomation = (onSetAttributeQuiet: ReturnType<typeof vi.fn>) =>
+  JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1]));
+
+const writtenVolumePoints = (onSetAttributeQuiet: ReturnType<typeof vi.fn>) =>
+  writtenAutomation(onSetAttributeQuiet).lanes.find(
+    (l: { target: string }) => l.target === "volume",
+  ).points;
+
 describe("useVolumeAutomation", () => {
   it("reports an unautomated track", () => {
     expect(bind({ volume: "0.55" }).binding.volumeAutomated).toBe(false);
@@ -61,7 +72,7 @@ describe("useVolumeAutomation", () => {
   it("treats a missing data-volume as unity", () => {
     const { binding, onSetAttributeQuiet } = bind({});
     act(() => binding.onAutomateVolume());
-    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+    expect(writtenAutomation(onSetAttributeQuiet).lanes[0].points[0].v).toBe(1);
   });
 
   it("keeps FX lanes when adding the volume one", () => {
@@ -72,9 +83,7 @@ describe("useVolumeAutomation", () => {
     const { binding, onSetAttributeQuiet } = bind({ volume: "0.4", automation });
     act(() => binding.onAutomateVolume());
     expect(
-      JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes.map(
-        (l: { target: string }) => l.target,
-      ),
+      writtenAutomation(onSetAttributeQuiet).lanes.map((l: { target: string }) => l.target),
     ).toEqual(["fx.n1.frequency", "volume"]);
   });
 
@@ -89,9 +98,7 @@ describe("useVolumeAutomation", () => {
     const { binding, onSetAttributeQuiet } = bind({ volume: "0.4", automation });
     act(() => binding.onRemoveVolumeAutomation());
     expect(
-      JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes.map(
-        (l: { target: string }) => l.target,
-      ),
+      writtenAutomation(onSetAttributeQuiet).lanes.map((l: { target: string }) => l.target),
     ).toEqual(["fx.n1.frequency"]);
   });
 
@@ -102,6 +109,70 @@ describe("useVolumeAutomation", () => {
     expect(onSetAttributeQuiet).toHaveBeenCalledWith("data-automation", null);
   });
 
+  it("writes a keyframe at the playhead instead of the flat attribute", () => {
+    // The slider used to be disabled while automated; this is what replaces
+    // that: a commit lands in the envelope, not on `data-volume`.
+    const { binding, onSetAttributeQuiet } = bind(
+      { volume: "0.4", automation: volumeLane(0.2), start: "0", duration: "10" },
+      5,
+    );
+    act(() => binding.onCommitVolumeAt(0.7));
+    expect(writtenVolumePoints(onSetAttributeQuiet)).toEqual([
+      { t: 0, v: 0.2 },
+      { t: 5, v: 0.7 },
+    ]);
+  });
+
+  it("clamps the playhead to the clip's own span, not the composition's", () => {
+    // A playhead past the clip's end must still land the keyframe at the
+    // clip's own last instant, not off the end of its automation lane.
+    const { binding, onSetAttributeQuiet } = bind(
+      { volume: "0.4", automation: volumeLane(0.2), start: "10", duration: "4" },
+      50,
+    );
+    act(() => binding.onCommitVolumeAt(0.9));
+    expect(writtenVolumePoints(onSetAttributeQuiet)).toEqual([
+      { t: 0, v: 0.2 },
+      { t: 4, v: 0.9 },
+    ]);
+  });
+
+  it("moves the existing point instead of stacking a new one when committing near it", () => {
+    const { binding, onSetAttributeQuiet } = bind(
+      { volume: "0.4", automation: volumeLane(0.2), start: "0", duration: "10" },
+      0,
+    );
+    act(() => binding.onCommitVolumeAt(0.9));
+    expect(writtenVolumePoints(onSetAttributeQuiet)).toEqual([{ t: 0, v: 0.9 }]);
+  });
+
+  it("reports the envelope's own value at the playhead, not the static attribute", () => {
+    const { binding } = bind(
+      { volume: "0.4", automation: volumeLane(0.2), start: "0", duration: "10" },
+      0,
+    );
+    expect(binding.automatedVolumeValue).toBe(0.2);
+  });
+
+  it("translates to clip-local time, not composition time, for a clip that starts mid-timeline", () => {
+    // start=10 keeps this inside the clip's own duration either way, so the
+    // duration clamp can't mask a missing `currentTime - elStart` subtraction
+    // the way start=0 cases elsewhere in this file do.
+    const { binding, onSetAttributeQuiet } = bind(
+      { volume: "0.4", automation: volumeLane(0.2), start: "10", duration: "20" },
+      15,
+    );
+    act(() => binding.onCommitVolumeAt(0.9));
+    expect(writtenVolumePoints(onSetAttributeQuiet)).toEqual([
+      { t: 0, v: 0.2 },
+      { t: 5, v: 0.9 },
+    ]);
+  });
+
+  it("reports no automated value when the track is not automated", () => {
+    expect(bind({ volume: "0.4" }).binding.automatedVolumeValue).toBeUndefined();
+  });
+
   it("reads an unreadable attribute as no automation", () => {
     expect(bind({ volume: "0.55", automation: "{not json" }).binding.volumeAutomated).toBe(false);
   });
@@ -111,12 +182,12 @@ describe("useVolumeAutomation", () => {
     // engine read the same empty attribute as unity.
     const { binding, onSetAttributeQuiet } = bind({ volume: "" });
     act(() => binding.onAutomateVolume());
-    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+    expect(writtenAutomation(onSetAttributeQuiet).lanes[0].points[0].v).toBe(1);
   });
 
   it("seeds at unity when data-volume is not a number", () => {
     const { binding, onSetAttributeQuiet } = bind({ volume: "loud" });
     act(() => binding.onAutomateVolume());
-    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+    expect(writtenAutomation(onSetAttributeQuiet).lanes[0].points[0].v).toBe(1);
   });
 });

package/src/components/editor/useVolumeAutomation.ts

@@ -6,24 +6,36 @@
  * rather than a second interpretation of the attribute.
  */
 
-import { HF_AUDIO_AUTOMATION_DATA_KEY, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
+import {
+  HF_AUDIO_AUTOMATION_DATA_KEY,
+  sampleAutomationLane,
+  VOLUME_TARGET,
+} from "@hyperframes/core/audio-automation";
 import type { DomEditSelection } from "./domEditingTypes";
 import {
   automationAttrValue,
   HF_AUDIO_AUTOMATION_ATTR,
   readPanelAutomation,
   withoutLane,
+  withPointAt,
   withSeededLane,
 } from "./propertyPanelAutomation";
+import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
+import { clampNumber } from "../../utils/studioHelpers";
 
 export interface VolumeAutomationBinding {
   volumeAutomated: boolean;
   onAutomateVolume: () => void;
   onRemoveVolumeAutomation: () => void;
+  /** Write `v` as a keyframe at the playhead instead of the disabled fallback. */
+  onCommitVolumeAt: (v: number) => void;
+  /** The envelope's own value at the playhead, so the slider tracks it live. */
+  automatedVolumeValue: number | undefined;
 }
 
 export function useVolumeAutomation(
   element: DomEditSelection,
+  currentTime: number,
   onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
 ): VolumeAutomationBinding {
   // The chain is not needed to resolve a volume lane — volume is always a valid
@@ -32,6 +44,12 @@ export function useVolumeAutomation(
     element.dataAttributes?.[HF_AUDIO_AUTOMATION_DATA_KEY],
     undefined,
   );
+  // ponytail: no GSAP animations passed — a media clip always carries an
+  // explicit data-duration, so `deriveElementTiming` never infers from animations here.
+  // `currentTime` comes from the caller's own `useLivePlayheadTime()` — a second
+  // subscription here would race the same re-render the caller already triggers.
+  const { start: elStart, duration: elDuration } = deriveElementTiming(element);
+  const clipTimeSec = clampNumber(currentTime - elStart, 0, elDuration > 0 ? elDuration : Infinity);
   const write = (next: Parameters<typeof automationAttrValue>[0]): void => {
     // Quiet: clicking the toggle used to reload the preview and restart every
     // playing track, while the same click on an effect parameter did not.
@@ -43,12 +61,15 @@ export function useVolumeAutomation(
   const raw = element.dataAttributes?.["volume"];
   const parsed = raw ? Number(raw) : 1;
   const current = Number.isFinite(parsed) ? parsed : 1;
+  const volumeLane = automation.lanes.find((lane) => lane.target === VOLUME_TARGET);
   return {
-    volumeAutomated: automation.lanes.some((lane) => lane.target === VOLUME_TARGET),
+    volumeAutomated: volumeLane !== undefined,
+    automatedVolumeValue: volumeLane ? sampleAutomationLane(volumeLane, clipTimeSec) : undefined,
     // Seeded at the level the slider already shows, so automating the track does
     // not change how loud it is.
     onAutomateVolume: () =>
       write(withSeededLane(automation, VOLUME_TARGET, Number.isFinite(current) ? current : 1)),
     onRemoveVolumeAutomation: () => write(withoutLane(automation, VOLUME_TARGET)),
+    onCommitVolumeAt: (v: number) => write(withPointAt(automation, VOLUME_TARGET, clipTimeSec, v)),
   };
 }

package/src/components/panels/VariablesPanel.tsx

@@ -256,15 +256,12 @@ export const VariablesPanel = memo(function VariablesPanel({
 }: VariablesPanelProps) {
   const { activeCompPath, showToast } = useStudioShellContext();
   const { refreshKey } = useStudioPlaybackContext();
-  const { readProjectFile, writeProjectFile, fileTree } = useFileManagerContext();
+  const { readProjectFile, writeProjectFile, fileTree, compositions } = useFileManagerContext();
   const { domEditSelection } = useDomEditContext();
-  // On the master view (no activeCompPath) the panel targets the project's real
-  // main composition — the first .html in the tree — not a hardcoded index.html
-  // that may not exist. This same path is used for the persist write target (so
-  // an edit never lands in a phantom index.html) AND the handoff render command.
-  // Null only when the project has no composition yet, in which case sdkSession
-  // is also null and the panel is inert.
-  const effectiveCompPath = activeCompPath ?? resolveMasterCompositionPath(fileTree);
+  // Master view (no activeCompPath) targets the real main composition, not a
+  // hardcoded index.html — used for both the persist write target and the
+  // handoff render command. Null only when the project has no composition.
+  const effectiveCompPath = activeCompPath ?? resolveMasterCompositionPath(compositions);
   const previewValues = usePreviewVariablesStore((s) => s.values);
   const setPreviewValues = usePreviewVariablesStore((s) => s.setValues);
 

package/src/components/sidebar/CompositionsTab.rootBadge.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { resolveMasterCompositionPath } from "../../utils/studioUrlState";
+import { CompositionsTab } from "./CompositionsTab";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+(
+  window as unknown as { happyDOM: { settings: { disableIframePageLoading: boolean } } }
+).happyDOM.settings.disableIframePageLoading = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ thumbnailContentRevision: 0 });
+});
+
+function mount(compositions: string[], masterCompositionPath: string | null) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(
+      <CompositionsTab
+        projectId="demo"
+        compositions={compositions}
+        activeComposition={null}
+        masterCompositionPath={masterCompositionPath}
+        onSelect={vi.fn()}
+      />,
+    );
+  });
+  return host;
+}
+
+describe("CompositionsTab root badge", () => {
+  it("marks the composition matching masterCompositionPath as root", () => {
+    const compositions = ["index.html", "compositions/headline.html"];
+    const host = mount(compositions, resolveMasterCompositionPath(compositions));
+    const cards = host.querySelectorAll<HTMLElement>('[draggable="true"]');
+    expect(cards).toHaveLength(2);
+    expect(cards[0]?.textContent).toContain("Root");
+    expect(cards[1]?.textContent).not.toContain("Root");
+  });
+
+  it("marks nothing as root when masterCompositionPath is null", () => {
+    const compositions = ["compositions/hero.html", "compositions/outro.html"];
+    const host = mount(compositions, null);
+    const cards = host.querySelectorAll<HTMLElement>('[draggable="true"]');
+    expect(cards[0]?.textContent).not.toContain("Root");
+    expect(cards[1]?.textContent).not.toContain("Root");
+  });
+});

package/src/components/sidebar/CompositionsTab.tsx

@@ -10,6 +10,8 @@ interface CompositionsTabProps {
   projectId: string;
   compositions: string[];
   activeComposition: string | null;
+  /** The project's root composition (same value App.tsx auto-opens on load), or null if none. */
+  masterCompositionPath?: string | null;
   onSelect: (comp: string) => void;
   onRenderComposition?: (comp: string) => void;
   onAddToTimeline?: (comp: string) => void;
@@ -117,6 +119,7 @@ function CompCard({
   projectId,
   comp,
   isActive,
+  isRoot,
   onSelect,
   onRender,
   isRendering,
@@ -127,6 +130,7 @@ function CompCard({
   projectId: string;
   comp: string;
   isActive: boolean;
+  isRoot: boolean;
   onSelect: () => void;
   onRender?: () => void;
   isRendering?: boolean;
@@ -298,6 +302,15 @@ function CompCard({
       >
         <div className="flex items-center gap-1">
           <span className="text-[11px] font-medium text-neutral-300 truncate">{name}</span>
+          {isRoot && (
+            <span
+              aria-label="Root composition — opens automatically on load"
+              title="Root composition — opens automatically on load"
+              className="flex-shrink-0 rounded-full bg-neutral-700/60 px-1.5 py-px text-[8px] font-bold uppercase tracking-wide text-neutral-300"
+            >
+              Root
+            </span>
+          )}
           {lintInfo && lintInfo.count > 0 && (
             <span
               aria-label={`${lintInfo.count} lint finding${lintInfo.count === 1 ? "" : "s"}`}
@@ -368,6 +381,7 @@ export const CompositionsTab = memo(function CompositionsTab({
   projectId,
   compositions,
   activeComposition,
+  masterCompositionPath = null,
   onSelect,
   onRenderComposition,
   onAddToTimeline,
@@ -391,6 +405,7 @@ export const CompositionsTab = memo(function CompositionsTab({
           projectId={projectId}
           comp={comp}
           isActive={activeComposition === comp}
+          isRoot={comp === masterCompositionPath}
           onSelect={() => onSelect(comp)}
           onRender={onRenderComposition ? () => onRenderComposition(comp) : undefined}
           onAddToTimeline={onAddToTimeline ? () => onAddToTimeline(comp) : undefined}