@hyperframes/studio 0.8.19 → 0.8.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.19",
+  "version": "0.8.21",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.19",
-    "@hyperframes/parsers": "0.8.19",
-    "@hyperframes/player": "0.8.19",
-    "@hyperframes/sdk": "0.8.19",
-    "@hyperframes/studio-server": "0.8.19"
+    "@hyperframes/core": "0.8.21",
+    "@hyperframes/parsers": "0.8.21",
+    "@hyperframes/player": "0.8.21",
+    "@hyperframes/sdk": "0.8.21",
+    "@hyperframes/studio-server": "0.8.21"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.19"
+    "@hyperframes/producer": "0.8.21"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -433,6 +433,8 @@ export function StudioApp() {
     handleRedo: appHotkeys.handleRedo,
     renderQueue,
     compositionDimensions,
+    domEditSaveQueuePaused: previewPersistence.domEditSaveQueuePaused,
+    externalFileConflict: externalFileChanges.blocked !== null,
     waitForPendingDomEditSaves: previewPersistence.waitForPendingDomEditSaves,
     handlePreviewIframeRef,
     refreshPreviewDocumentVersion,

package/src/contexts/StudioContext.tsx

@@ -16,6 +16,13 @@ export interface StudioShellValue {
     undoLabel: string | undefined;
     redoLabel: string | undefined;
   };
+  /**
+   * Why a composition write would be refused right now, or null when writes
+   * are possible. Derived from the paused save queue and the external-file
+   * conflict state, both of which are otherwise banners with no lock behind
+   * them. One field rather than two, so there is one owner of the question.
+   */
+  writeBlockedReason: string | null;
   handleUndo: () => Promise<void>;
   handleRedo: () => Promise<void>;
   renderQueue: {
@@ -106,6 +113,7 @@ export function StudioShellProvider({
     showToast,
     previewIframeRef,
     editHistory,
+    writeBlockedReason,
     handleUndo,
     handleRedo,
     renderQueue,
@@ -122,6 +130,7 @@ export function StudioShellProvider({
       showToast,
       previewIframeRef,
       editHistory,
+      writeBlockedReason,
       handleUndo,
       handleRedo,
       renderQueue,
@@ -138,6 +147,7 @@ export function StudioShellProvider({
       setActiveCompPath,
       showToast,
       previewIframeRef,
+      writeBlockedReason,
       handleUndo,
       handleRedo,
       waitForPendingDomEditSaves,

package/src/hooks/useEditorSave.test.tsx

@@ -2,8 +2,15 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
+
+const trackStudioSaveFailure = vi.hoisted(() => vi.fn());
+vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/studioSaveDiagnostics")>()),
+  trackStudioSaveFailure,
+}));
+
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -11,6 +18,7 @@ type WriteProjectFile = (path: string, content: string, expectedContent?: string
 
 async function mountEditorSave(writeProjectFile: WriteProjectFile) {
   const captured: { handle: EditorSaveHandle | null } = { handle: null };
+  const showToast = vi.fn();
 
   function Probe() {
     captured.handle = useEditorSave({
@@ -21,7 +29,7 @@ async function mountEditorSave(writeProjectFile: WriteProjectFile) {
       recordEdit: vi.fn(async () => undefined),
       domEditSaveTimestampRef: { current: 0 },
       setRefreshKey: vi.fn(),
-      showToast: vi.fn(),
+      showToast,
     });
     return null;
   }
@@ -32,12 +40,14 @@ async function mountEditorSave(writeProjectFile: WriteProjectFile) {
 
   return {
     handle: captured.handle,
+    showToast,
     unmount: () => act(async () => root.unmount()),
   };
 }
 
 describe("useEditorSave pending work", () => {
   beforeEach(() => {
+    trackStudioSaveFailure.mockClear();
     vi.stubGlobal(
       "requestAnimationFrame",
       vi.fn(() => 41),
@@ -45,7 +55,10 @@ describe("useEditorSave pending work", () => {
     vi.stubGlobal("cancelAnimationFrame", vi.fn());
   });
 
-  afterEach(() => vi.unstubAllGlobals());
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
 
   it("exposes and flushes the latest rAF-buffered source candidate", async () => {
     const writeProjectFile = vi.fn(async () => undefined);
@@ -111,7 +124,72 @@ describe("useEditorSave pending work", () => {
       status: "conflict",
       error: conflict,
     });
+    expect(trackStudioSaveFailure).toHaveBeenCalledWith({
+      source: "code_editor",
+      error: conflict,
+      filePath: "index.html",
+    });
+
+    await mounted.unmount();
+  });
+
+  it("emits one identical failure per five-second burst", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const error = new Error("Load failed");
+    const mounted = await mountEditorSave(async () => {
+      throw error;
+    });
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    vi.spyOn(Date, "now").mockReturnValue(2_000);
+    act(() => mounted.handle.handleContentChange("second candidate"));
+    await mounted.handle.flushPendingSave();
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledOnce();
+    expect(mounted.showToast).toHaveBeenCalledOnce();
+    await mounted.unmount();
+  });
+
+  it("emits a changed failure immediately and repeats after the burst window", async () => {
+    const now = vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const writeProjectFile = vi
+      .fn<WriteProjectFile>()
+      .mockRejectedValueOnce(new Error("Load failed"))
+      .mockRejectedValueOnce(new Error("Failed to fetch"))
+      .mockRejectedValueOnce(new Error("Failed to fetch"));
+    const mounted = await mountEditorSave(writeProjectFile);
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    now.mockReturnValue(2_000);
+    act(() => mounted.handle.handleContentChange("second candidate"));
+    await mounted.handle.flushPendingSave();
+    now.mockReturnValue(8_000);
+    act(() => mounted.handle.handleContentChange("third candidate"));
+    await mounted.handle.flushPendingSave();
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledTimes(3);
+    await mounted.unmount();
+  });
+
+  it("emits the same failure again after a successful save", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const writeProjectFile = vi
+      .fn<WriteProjectFile>()
+      .mockRejectedValueOnce(new Error("Load failed"))
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error("Load failed"));
+    const mounted = await mountEditorSave(writeProjectFile);
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    act(() => mounted.handle.handleContentChange("successful candidate"));
+    await mounted.handle.flushPendingSave();
+    act(() => mounted.handle.handleContentChange("third candidate"));
+    await mounted.handle.flushPendingSave();
 
+    expect(trackStudioSaveFailure).toHaveBeenCalledTimes(2);
     await mounted.unmount();
   });
 

package/src/hooks/useEditorSave.ts

@@ -1,12 +1,15 @@
 import { useCallback, useRef } from "react";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
-import { trackStudioEvent } from "../utils/studioTelemetry";
 import {
   StudioFileConflictError,
+  buildStudioSaveFailureProperties,
+  trackStudioSaveFailure,
   type StudioSaveDrainResult,
 } from "../utils/studioSaveDiagnostics";
 
+const FAILURE_BURST_MS = 5_000;
+
 interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
@@ -58,19 +61,40 @@ export function useEditorSave({
   const refreshRafRef = useRef<number | null>(null);
   // One error toast per burst of failures — every keystroke retries the save,
   // and error toasts persist until dismissed, so don't stack duplicates.
-  const lastFailureToastAtRef = useRef(0);
+  const lastFailureToastAtRef = useRef<number | null>(null);
+  const lastFailureReportRef = useRef<{ fingerprint: string; emittedAt: number } | null>(null);
   const pendingCandidateRef = useRef<EditorSaveCandidate | null>(null);
   const inFlightRef = useRef<Promise<EditorSaveDrainResult> | null>(null);
   const inFlightCandidateRef = useRef<EditorSaveCandidate | null>(null);
 
   const reportFailure = useCallback(
     (path: string, error: unknown) => {
-      trackStudioEvent("save_failure", {
+      const now = Date.now();
+      const properties = buildStudioSaveFailureProperties({
         source: "code_editor",
-        error_message: error instanceof Error ? error.message : "unknown",
+        error,
+        filePath: path,
       });
-      const now = Date.now();
-      if (now - lastFailureToastAtRef.current > 5000) {
+      const errorName = error instanceof Error ? error.name : typeof error;
+      const fingerprint = JSON.stringify([
+        path,
+        errorName,
+        properties.error_message,
+        properties.status_code,
+      ]);
+      const previous = lastFailureReportRef.current;
+      if (
+        previous === null ||
+        previous.fingerprint !== fingerprint ||
+        now - previous.emittedAt >= FAILURE_BURST_MS
+      ) {
+        trackStudioSaveFailure({ source: "code_editor", error, filePath: path });
+        lastFailureReportRef.current = { fingerprint, emittedAt: now };
+      }
+      if (
+        lastFailureToastAtRef.current === null ||
+        now - lastFailureToastAtRef.current >= FAILURE_BURST_MS
+      ) {
         lastFailureToastAtRef.current = now;
         showToast(
           `Couldn't save ${path} — your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
@@ -95,6 +119,7 @@ export function useEditorSave({
       })
         .then<EditorSaveDrainResult>(() => {
           if (pendingCandidateRef.current === candidate) pendingCandidateRef.current = null;
+          lastFailureReportRef.current = null;
           if (refreshRafRef.current != null) cancelAnimationFrame(refreshRafRef.current);
           refreshRafRef.current = requestAnimationFrame(() => setRefreshKey((k) => k + 1));
           return { status: "clean" };

package/src/hooks/useGsapInteractionFailureTelemetry.test.tsx

@@ -1,32 +1,49 @@
 // @vitest-environment happy-dom
 
 import React, { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { GsapEditBlockedError } from "./gsapEditOutcome";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-const trackStudioSaveFailure = vi.hoisted(() => vi.fn());
-vi.mock("../utils/studioSaveDiagnostics", () => ({ trackStudioSaveFailure }));
+const { trackStudioEditBlocked, trackStudioSaveFailure } = vi.hoisted(() => ({
+  trackStudioEditBlocked: vi.fn(),
+  trackStudioSaveFailure: vi.fn(),
+}));
+vi.mock("../utils/studioSaveDiagnostics", () => ({
+  trackStudioEditBlocked,
+  trackStudioSaveFailure,
+}));
 
 import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
 
+const selection = {
+  id: "clip",
+  selector: "#clip",
+  element: document.createElement("div"),
+} as unknown as DomEditSelection;
+
+function mountFailureTelemetry(showToast: ReturnType<typeof vi.fn>) {
+  let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
+  function Harness() {
+    report = useGsapInteractionFailureTelemetry("index.html", showToast);
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  return { report, root };
+}
+
 describe("useGsapInteractionFailureTelemetry", () => {
-  it("surfaces the blocked reason instead of a generic save failure", () => {
+  beforeEach(() => {
+    trackStudioEditBlocked.mockClear();
+    trackStudioSaveFailure.mockClear();
+  });
+
+  it("tracks an expected edit block separately from save failures", () => {
     const showToast = vi.fn();
-    const selection = {
-      id: "clip",
-      selector: "#clip",
-      element: document.createElement("div"),
-    } as unknown as DomEditSelection;
-    let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
-    function Harness() {
-      report = useGsapInteractionFailureTelemetry("index.html", showToast);
-      return null;
-    }
-    const root = mountReactHarness(<Harness />);
+    const { report, root } = mountFailureTelemetry(showToast);
 
     act(() => report(new GsapEditBlockedError("unroll-required"), selection, "drag", "Move"));
 
@@ -34,9 +51,24 @@ describe("useGsapInteractionFailureTelemetry", () => {
       "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
       "error",
     );
-    expect(trackStudioSaveFailure).toHaveBeenCalledWith(
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(
       expect.objectContaining({ source: "gsap_commit", mutationType: "drag", targetId: "clip" }),
     );
+    expect(trackStudioSaveFailure).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("keeps unexpected GSAP persistence errors in save_failure", () => {
+    const showToast = vi.fn();
+    const { report, root } = mountFailureTelemetry(showToast);
+    const error = new Error("network dropped");
+
+    act(() => report(error, selection, "drag", "Move"));
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledWith(
+      expect.objectContaining({ source: "gsap_commit", error, mutationType: "drag" }),
+    );
+    expect(trackStudioEditBlocked).not.toHaveBeenCalled();
     act(() => root.unmount());
   });
 });

package/src/hooks/useGsapInteractionFailureTelemetry.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import { trackStudioEditBlocked, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { isGsapEditBlockedError } from "./gsapEditOutcome";
 
 export function useGsapInteractionFailureTelemetry(
@@ -9,7 +9,10 @@ export function useGsapInteractionFailureTelemetry(
 ) {
   return useCallback(
     (error: unknown, selection: DomEditSelection | null, mutationType: string, label: string) => {
-      trackStudioSaveFailure({
+      const report = isGsapEditBlockedError(error)
+        ? trackStudioEditBlocked
+        : trackStudioSaveFailure;
+      report({
         source: "gsap_commit",
         error,
         filePath: selection?.sourceFile ?? activeCompPath ?? "index.html",

package/src/hooks/useStudioContextValue.ts

@@ -25,6 +25,10 @@ interface StudioContextInput {
   // fields around it: the context type owns it.
   renderQueue: StudioContextValue["renderQueue"];
   compositionDimensions: { width: number; height: number } | null;
+  /** Message from `usePreviewPersistence` when auto-save is paused. */
+  domEditSaveQueuePaused: string | null;
+  /** True when an external edit to the open file is awaiting the user's decision. */
+  externalFileConflict: boolean;
   waitForPendingDomEditSaves: () => Promise<void>;
   handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
   refreshPreviewDocumentVersion: () => void;
@@ -46,6 +50,11 @@ export function buildStudioContextValue(input: StudioContextInput): StudioContex
     timelineElements: input.timelineElements,
     isPlaying: input.isPlaying,
     editHistory: input.editHistory,
+    // Conflict first: when both are true the conflict is the one the user has
+    // been asked to decide, and resolving it is what unblocks the queue.
+    writeBlockedReason: input.externalFileConflict
+      ? "an external change to this file is waiting to be resolved"
+      : input.domEditSaveQueuePaused,
     handleUndo: input.handleUndo,
     handleRedo: input.handleRedo,
     renderQueue: input.renderQueue,

package/src/player/hooks/timelineSyncHydration.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import {
+  collectSubCompositionDomChildren,
+  collectSubCompositionHostState,
+} from "./timelineSyncHydration";
+import type { ClipManifestClip } from "../lib/playbackTypes";
+
+const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
+  id: "x",
+  label: "x",
+  start: 0,
+  duration: 1,
+  track: 0,
+  kind: "element",
+  tagName: "div",
+  compositionId: null,
+  parentCompositionId: null,
+  compositionSrc: null,
+  assetUrl: null,
+  ...over,
+});
+
+/**
+ * The shape a storyboard scene actually publishes: the clip that carries
+ * `data-hidden` is a `<video>` one level BELOW an id'd region wrapper.
+ */
+function mountScene(): Document {
+  document.body.innerHTML = `
+    <div id="scene-2-slot" data-composition-id="scene-2" data-composition-src="scene-2.html">
+      <div data-hf-inner-root>
+        <div id="scene-2-video-region" class="hf-region">
+          <video id="scene-2-video" class="clip" data-start="0" data-hidden></video>
+        </div>
+        <div id="scene-2-title" class="clip" data-start="0" data-hidden></div>
+        <div id="scene-2-caption" class="clip" data-start="0" data-timeline-locked
+             data-timeline-role="caption" data-fx-chain="blur" data-automation="opacity"></div>
+      </div>
+    </div>`;
+  return document;
+}
+
+// A composition clip is keyed by its ELEMENT id, not its `data-composition-id`
+// (the runtime's clip tree publishes `scene-2-slot`), so the collector resolves
+// the host with getElementById(clip.id) exactly as the sibling walk does.
+const sceneClips = [clip({ id: "scene-2-slot", kind: "composition", compositionId: "scene-2" })];
+
+describe("collectSubCompositionHostState", () => {
+  it("reaches a clip nested below an id'd wrapper, which the sibling walk cannot", () => {
+    const doc = mountScene();
+
+    // The walk that defines rows stops at the first id'd descendant, so the
+    // video inside the region wrapper is never recorded there. That is why the
+    // eye on a hidden scene video had no state to read.
+    const siblings = collectSubCompositionDomChildren(doc, sceneClips, new Map());
+    expect(siblings.map((child) => child.id)).toEqual([
+      "scene-2-video-region",
+      "scene-2-title",
+      "scene-2-caption",
+    ]);
+
+    const state = collectSubCompositionHostState(doc, sceneClips);
+    expect(state.get("scene-2-video")?.hidden).toBe(true);
+  });
+
+  it("records every data-* attribute an expanded child row needs", () => {
+    const state = collectSubCompositionHostState(mountScene(), sceneClips);
+
+    expect(state.get("scene-2-title")).toEqual({ hidden: true });
+    expect(state.get("scene-2-caption")).toEqual({
+      timelineLocked: true,
+      timelineRole: "caption",
+      fxChain: "blur",
+      automation: "opacity",
+    });
+  });
+
+  it("omits elements carrying no state, so a visible child reads as visible", () => {
+    const state = collectSubCompositionHostState(mountScene(), sceneClips);
+
+    expect(state.has("scene-2-video-region")).toBe(false);
+    expect(state.get("scene-2-video")?.hidden).toBe(true);
+  });
+
+  it("returns empty without a document, rather than throwing", () => {
+    expect(collectSubCompositionHostState(null, sceneClips).size).toBe(0);
+  });
+
+  it("ignores clips that are not compositions", () => {
+    const doc = mountScene();
+    const state = collectSubCompositionHostState(doc, [clip({ id: "scene-2-slot" })]);
+
+    expect(state.size).toBe(0);
+  });
+});

package/src/player/hooks/timelineSyncHydration.ts

@@ -10,7 +10,7 @@
  */
 
 import { usePlayerStore } from "../store/playerStore";
-import type { TimelineElement, DomClipChild } from "../store/playerStore";
+import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { ClipTree } from "@hyperframes/core/runtime/clipTree";
 import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
@@ -137,6 +137,52 @@ export function collectSubCompositionDomChildren(
   return out;
 }
 
+/** The host-element `data-*` state one element carries, or null when it has none. */
+function readSubCompositionHostState(el: Element): SubCompositionHostState | null {
+  const state: SubCompositionHostState = {};
+  if (el.hasAttribute("data-hidden")) state.hidden = true;
+  if (el.hasAttribute("data-timeline-locked")) state.timelineLocked = true;
+  const timelineRole = el.getAttribute("data-timeline-role");
+  if (timelineRole) state.timelineRole = timelineRole;
+  const fxChain = el.getAttribute("data-fx-chain");
+  if (fxChain) state.fxChain = fxChain;
+  const automation = el.getAttribute("data-automation");
+  if (automation) state.automation = automation;
+  return Object.keys(state).length > 0 ? state : null;
+}
+
+/**
+ * Host-element state for every id'd element inside every sub-composition.
+ *
+ * This walk exists because nothing else in the pipeline can see these
+ * attributes. A clip whose parent composition is itself in the manifest is
+ * filtered out before the flat store is built, so an expanded child has no twin
+ * to inherit from, and the manifest carries timing rather than attributes.
+ *
+ * Deliberately separate from {@link collectSubCompositionDomChildren}: that walk
+ * defines which rows exist and writes `parentMap`, and it stops at the first
+ * id'd descendant. Scene footage commonly sits one level below an id'd region
+ * wrapper, so it is never reached there. This one descends the whole subtree and
+ * touches neither rows nor parentage.
+ */
+export function collectSubCompositionHostState(
+  iframeDoc: Document | null,
+  clips: readonly ClipManifestClip[],
+): Map<string, SubCompositionHostState> {
+  const out = new Map<string, SubCompositionHostState>();
+  if (!iframeDoc) return out;
+  for (const clip of clips) {
+    if (clip.kind !== "composition" || !clip.id) continue;
+    const hostEl = iframeDoc.getElementById(clip.id);
+    if (!hostEl) continue;
+    for (const el of Array.from(hostEl.querySelectorAll("[id]"))) {
+      const state = readSubCompositionHostState(el);
+      if (state) out.set(el.id, state);
+    }
+  }
+  return out;
+}
+
 /** An iframe's document, or null when reading it throws (cross-origin, or the
  *  frame is mid-navigation). */
 export function safeContentDocument(iframe: HTMLIFrameElement | null): Document | null {

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -270,6 +270,49 @@ describe("buildExpandedElements", () => {
     expect(child.timelineLocked).toBe(true);
   });
 
+  // The test above only covers a host with no compositionSrc, where the child's
+  // key falls back to the `index.html` scope and a flat store twin can exist. A
+  // REAL sub-composition scopes the child key to the sub-comp file, and clips
+  // whose parent composition is itself in the manifest are filtered out of the
+  // flat store before it is built (`processTimelineMessage`). So the twin never
+  // exists there and the inheritance above is dead code for the one case it was
+  // written for: the eye reported every hidden child visible, clicking it
+  // rewrote data-hidden, and nothing could be shown again.
+  it("reads hidden and locked off the live element when the child has no flat twin", () => {
+    // Only the host is in the flat store — exactly what the manifest filter leaves.
+    const elements = [
+      el({
+        id: "scene-2",
+        domId: "scene-2",
+        start: 3.25,
+        duration: 3.5,
+        compositionSrc: "scene-2.html",
+      }),
+    ];
+    const manifest = [
+      clip({ id: "scene-2", start: 3.25, duration: 3.5, compositionSrc: "scene-2.html" }),
+      clip({ id: "scene-2-video", start: 3.25, duration: 3.5, parentCompositionId: "scene-2" }),
+    ];
+    const parentMap = new Map([["scene-2-video", "scene-2"]]);
+    const hostState = new Map([["scene-2-video", { hidden: true, timelineLocked: true }]]);
+
+    const out = buildExpandedElements(
+      elements,
+      manifest,
+      parentMap,
+      "scene-2",
+      "scene-2",
+      [],
+      hostState,
+    );
+    const child = out.find((e) => e.domId === "scene-2-video")!;
+    // The child key is scoped to the sub-comp file, so no store element can match it.
+    expect(child.key).toBe("scene-2.html#scene-2-video");
+    expect(elements.some((element) => element.key === child.key)).toBe(false);
+    expect(child.hidden).toBe(true);
+    expect(child.timelineLocked).toBe(true);
+  });
+
   // Sub-comp internals (group + pills) have no data-start, so they're not in the
   // manifest. They arrive as DOM children and must still expand under their host.
   it("expands DOM-only sub-comp children (no manifest clip) under the host", () => {