@hyperframes/studio 0.8.20 → 0.8.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.20",
+  "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.20",
-    "@hyperframes/sdk": "0.8.20",
-    "@hyperframes/player": "0.8.20",
-    "@hyperframes/studio-server": "0.8.20",
-    "@hyperframes/parsers": "0.8.20"
+    "@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.20"
+    "@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/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", () => {

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -1,5 +1,10 @@
 import { useMemo } from "react";
-import { usePlayerStore, type TimelineElement, type DomClipChild } from "../store/playerStore";
+import {
+  usePlayerStore,
+  type TimelineElement,
+  type DomClipChild,
+  type SubCompositionHostState,
+} from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
 import { buildTimelineElementKey, splitTimelineElementKey } from "../lib/timelineElementHelpers";
@@ -131,18 +136,6 @@ interface DisplayBounds {
   track: number;
 }
 
-/**
- * State that lives on the live host element, not in the clip manifest:
- * `data-hidden`, `data-timeline-locked`, `data-timeline-role`. A child row is
- * built from a manifest clip with no hostEl to read, so
- * createTimelineElementFromManifestClip cannot see any of it. The flat store
- * element for the same child WAS built with one, so it is inherited from there.
- *
- * Without this the eye on an expanded child always reported the row visible, so
- * clicking it wrote data-hidden again instead of removing it, and a hidden child
- * could never be shown again (not even after a reload, since the attribute is in
- * the source).
- */
 /**
  * Audio-group membership for an expanded child, from whichever source has it.
  *
@@ -169,20 +162,34 @@ function childGroupState(
   };
 }
 
-function hostElementState(flat: TimelineElement | undefined): Partial<TimelineElement> {
-  if (!flat) return {};
-  return {
-    hidden: flat.hidden,
-    timelineLocked: flat.timelineLocked,
-    timelineRole: flat.timelineRole,
-    // Same reason as the three above: these are read off the host element, which
-    // an expanded child is built without. Missing them, an audio child inside a
-    // sub-composition reserved no automation height and drew no lanes, while the
-    // property panel — reading the live DOM selection rather than this row —
-    // still showed the chain and its toggles.
-    fxChain: flat.fxChain,
-    automation: flat.automation,
-  };
+/**
+ * State that lives on the live host element, not in the clip manifest:
+ * `data-hidden`, `data-timeline-locked`, `data-timeline-role`, `data-fx-chain`,
+ * `data-automation`. A child row is built from a manifest clip with no hostEl to
+ * read, so createTimelineElementFromManifestClip cannot see any of it.
+ *
+ * `live` is the reading taken off the element itself and is authoritative. For a
+ * child of a REAL sub-composition it is also the only source: such a clip is
+ * filtered out of the manifest before the flat store is built, so no twin exists
+ * to inherit from. The flat twin still covers the phantom-wrapper case, where
+ * the child does keep a store entry of its own.
+ *
+ * Without a reading of the element, the eye on an expanded child always reported
+ * the row visible, so clicking it wrote data-hidden again instead of removing
+ * it, and a hidden child could never be shown again (not even after a reload,
+ * since the attribute is in the source). Missing fxChain and automation, an
+ * audio child inside a sub-composition reserved no automation height and drew no
+ * lanes, while the property panel, which reads the live DOM selection rather
+ * than this row, still showed the chain and its toggles.
+ */
+function hostElementState(
+  flat: TimelineElement | undefined,
+  live: SubCompositionHostState | undefined,
+): Partial<TimelineElement> {
+  if (!flat) return { ...live };
+  const { hidden, timelineLocked, timelineRole, fxChain, automation } = flat;
+  // `live` last: it is the reading off the element, so it wins wherever it has one.
+  return { hidden, timelineLocked, timelineRole, fxChain, automation, ...live };
 }
 
 // `display` bounds come from the top-level scene clip (where the expanded row is
@@ -196,6 +203,7 @@ function buildChildElements(
   expandedHostKey: string,
   elements: readonly TimelineElement[],
   domChildrenById: ReadonlyMap<string, DomClipChild>,
+  hostStateById: ReadonlyMap<string, SubCompositionHostState>,
 ): TimelineElement[] {
   const result: TimelineElement[] = [];
   for (const child of siblings) {
@@ -223,7 +231,10 @@ function buildChildElements(
     });
     result.push({
       ...base,
-      ...hostElementState(elements.find((element) => element.key === key)),
+      ...hostElementState(
+        elements.find((element) => element.key === key),
+        domId ? hostStateById.get(domId) : undefined,
+      ),
       ...childGroupState(
         elements.find((element) => element.key === key),
         domId ? domChildrenById.get(domId) : undefined,
@@ -309,6 +320,7 @@ export function buildExpandedElements(
   topLevelId: string,
   siblingParentId: string,
   domClipChildren: DomClipChild[] = [],
+  subCompositionHostState: ReadonlyMap<string, SubCompositionHostState> = new Map(),
 ): TimelineElement[] {
   const topLevelElement = elements.find((el) => el.id === topLevelId || el.domId === topLevelId);
   if (!topLevelElement) return filterToTopLevel(elements, parentMap);
@@ -348,6 +360,7 @@ export function buildExpandedElements(
     parentKey,
     elements,
     domChildrenById,
+    subCompositionHostState,
   );
   if (expanded.length === 0) return filterToTopLevel(elements, parentMap);
 
@@ -391,6 +404,7 @@ export function useExpandedTimelineElements(): TimelineElement[] {
   const clipManifest = usePlayerStore((s) => s.clipManifest);
   const clipParentMap = usePlayerStore((s) => s.clipParentMap);
   const domClipChildren = usePlayerStore((s) => s.domClipChildren);
+  const subCompositionHostState = usePlayerStore((s) => s.subCompositionHostState);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
 
@@ -432,6 +446,15 @@ export function useExpandedTimelineElements(): TimelineElement[] {
       topLevel,
       immediateParent,
       domClipChildren,
+      subCompositionHostState,
     );
-  }, [elements, clipManifest, clipParentMap, domClipChildren, rawId, selectedRawId]);
+  }, [
+    elements,
+    clipManifest,
+    clipParentMap,
+    domClipChildren,
+    subCompositionHostState,
+    rawId,
+    selectedRawId,
+  ]);
 }

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -19,6 +19,7 @@ import {
   buildTimelineElementsFromClips,
   clipTreeParentMap,
   collectSubCompositionDomChildren,
+  collectSubCompositionHostState,
   hydrateTimelineFromPreview,
   isPreviewReadinessMessage,
   safeContentDocument,
@@ -131,6 +132,9 @@ export function useTimelineSyncCallbacks({
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
+        usePlayerStore
+          .getState()
+          .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
         // cross-origin or __clipTree not available — maps stay empty
       }

package/src/player/store/playerStore.ts

@@ -23,9 +23,13 @@ import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
 
-import type { TimelineElement, TimelineElementPatch } from "./timelineElement";
+import type {
+  TimelineElement,
+  TimelineElementPatch,
+  SubCompositionHostState,
+} from "./timelineElement";
 
-export type { TimelineElement };
+export type { TimelineElement, SubCompositionHostState };
 export type ZoomMode = "fit" | "manual";
 type TimelineTool = "select" | "razor";
 
@@ -212,6 +216,14 @@ interface PlayerState
    */
   domClipChildren: DomClipChild[];
   setDomClipChildren: (children: DomClipChild[]) => void;
+  /**
+   * Host-element state for every id'd element inside a sub-composition, keyed by
+   * dom id. Collected from the live preview because it is the only place that
+   * sees it: these elements are filtered out of `elements` before the flat store
+   * is built, and the clip manifest carries timing, not attributes.
+   */
+  subCompositionHostState: Map<string, SubCompositionHostState>;
+  setSubCompositionHostState: (state: Map<string, SubCompositionHostState>) => void;
 }
 
 /** A sub-comp DOM-only timeline child (no data-start) and its nesting context. */
@@ -284,6 +296,7 @@ export function createTimelineResetState() {
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
     domClipChildren: [],
+    subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };
 }
 
@@ -430,6 +443,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipParentMap: (map) => set({ clipParentMap: map }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
+  subCompositionHostState: new Map(),
+  setSubCompositionHostState: (state) => set({ subCompositionHostState: state }),
 
   setIsPlaying: (playing) => {
     if (get().isPlaying === playing) return;

package/src/player/store/timelineElement.ts

@@ -118,3 +118,24 @@ export type TimelineElementPatch = Partial<
     | "audioGroupAutomation"
   >
 >;
+
+/**
+ * The `data-*` state an expanded sub-composition child needs but cannot reach.
+ *
+ * A child row is synthesized from a manifest clip with no element to read, and
+ * for a real sub-composition it has no flat store twin either: such clips are
+ * dropped before the flat store is built. Read off the live preview instead
+ * (`collectSubCompositionHostState`) and carried on the store by dom id.
+ *
+ * Without it the eye reported every hidden child visible, so clicking it wrote
+ * `data-hidden` a second time instead of removing it, and the element could
+ * never be shown again, not even after a reload, since the attribute is in the
+ * source.
+ */
+export interface SubCompositionHostState {
+  hidden?: boolean;
+  timelineLocked?: boolean;
+  timelineRole?: string;
+  fxChain?: string;
+  automation?: string;
+}