@hyperframes/studio 0.7.58 → 0.7.60

package/src/utils/studioFileVersion.ts

@@ -0,0 +1,23 @@
+/** Browser-safe SHA-256 version matching studio-server's strong ETag format. */
+export async function studioFileContentVersion(content: string): Promise<string> {
+  const bytes = new TextEncoder().encode(content);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(
+    "",
+  );
+  return `"sha256:${hex}"`;
+}
+
+/** Prefer an explicit content precondition, then the version observed during the read. */
+export async function studioExpectedFileVersion(
+  versions: ReadonlyMap<string, string | null>,
+  path: string,
+  expectedContent?: string,
+): Promise<string | null | undefined> {
+  if (expectedContent !== undefined) return studioFileContentVersion(expectedContent);
+  return versions.get(path);
+}
+
+export function createStudioWriteToken(): string {
+  return globalThis.crypto.randomUUID();
+}

package/src/utils/studioHelpers.test.ts

@@ -48,6 +48,51 @@ describe("findMatchingTimelineElementId", () => {
   it("returns null for an unmatched element in index.html", () => {
     expect(findMatchingTimelineElementId({ id: "ghost", sourceFile: "index.html" }, [])).toBe(null);
   });
+
+  it("resolves the correct repeated composition host by domId, not the first host sharing the same compositionSrc", () => {
+    // Two hosts import the SAME sub-composition — only compositionSrc alone
+    // can't tell them apart, but each still has its own domId (as any
+    // element does). Selecting the SECOND host must not collapse to the
+    // first one just because an earlier, unrelated element also happens to
+    // share its compositionSrc.
+    const els = [
+      el({ id: "host-a", domId: "host-a", sourceFile: "index.html", compositionSrc: "scene.html" }),
+      el({ id: "host-b", domId: "host-b", sourceFile: "index.html", compositionSrc: "scene.html" }),
+    ];
+    expect(
+      findMatchingTimelineElementId(
+        {
+          id: "host-b",
+          sourceFile: "index.html",
+          compositionSrc: "scene.html",
+          isCompositionHost: true,
+        },
+        els,
+      ),
+    ).toBe("host-b");
+  });
+
+  it("falls back to compositionSrc-only matching when the host selection has neither a domId nor a selector", () => {
+    const els = [
+      el({
+        id: "host-only",
+        domId: undefined,
+        sourceFile: "index.html",
+        compositionSrc: "scene.html",
+      }),
+    ];
+    expect(
+      findMatchingTimelineElementId(
+        {
+          id: undefined,
+          sourceFile: "index.html",
+          compositionSrc: "scene.html",
+          isCompositionHost: true,
+        },
+        els,
+      ),
+    ).toBe("host-only");
+  });
 });
 
 describe("findTimelineIdByAncestor", () => {

package/src/utils/studioHelpers.ts

@@ -161,25 +161,34 @@ function matchesBySelector(selection: ElementMatchSelection, element: TimelineEl
   );
 }
 
-function elementMatchesSelection(
-  selection: ElementMatchSelection,
-  element: TimelineElement,
-  selectionSourceFile: string,
-): boolean {
-  return (
-    matchesByDomId(selection, element, selectionSourceFile) ||
-    matchesByCompositionHost(selection, element) ||
-    matchesBySelector(selection, element)
-  );
-}
-
 export function findMatchingTimelineElementId(
   selection: ElementMatchSelection,
   elements: TimelineElement[],
 ): string | null {
   const selectionSourceFile = selection.sourceFile || "index.html";
-  const match = elements.find((el) => elementMatchesSelection(selection, el, selectionSourceFile));
-  if (match) return match.key ?? match.id;
+  // Priority matters, not just "any of the three": a composition-host
+  // selection always carries its OWN id/selector too (computed generically
+  // for any element), so two repeated hosts sharing the same compositionSrc
+  // are still individually addressable by id/selector. Checking
+  // matchesByCompositionHost with equal priority in a single OR-per-element
+  // scan let `.find()` stop at an EARLIER, unrelated host that merely shares
+  // the compositionSrc, before the scan ever reached the correct id/selector
+  // match further down the list — collapsing every repeated host to the
+  // first one. Try id, then selector, across the WHOLE list first; only fall
+  // back to the coarser compositionSrc-only match when neither identifies a
+  // specific element.
+  const byId = selection.id
+    ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile))
+    : undefined;
+  if (byId) return byId.key ?? byId.id;
+
+  const bySelector = selection.selector
+    ? elements.find((el) => matchesBySelector(selection, el))
+    : undefined;
+  if (bySelector) return bySelector.key ?? bySelector.id;
+
+  const byHost = elements.find((el) => matchesByCompositionHost(selection, el));
+  if (byHost) return byHost.key ?? byHost.id;
 
   // Child inside a sub-composition: return a qualified ID so the expansion
   // hook can resolve the child via clipParentMap even though no timeline
@@ -237,6 +246,28 @@ export function resolveTimelineIdForSelection(
   );
 }
 
+/**
+ * Resolve every multi-selected element to its scope-qualified timeline key
+ * (dropping unresolvable ones). Selections carry bare DOM ids/selectors, but
+ * the visibility toggle matches keys like "index.html#hero" — and callers must
+ * hide all keys in ONE call so the file is patched in a single atomic write
+ * (per-element calls would clobber each other's reads).
+ */
+export function timelineKeysForSelections(
+  selections: readonly DomEditSelection[],
+  elements: TimelineElement[],
+  activeCompPath: string | null,
+): string[] {
+  return selections
+    .map((selection) => resolveTimelineIdForSelection(selection, elements, activeCompPath))
+    .filter((key): key is string => key !== null);
+}
+
+export type ToggleHiddenHandler = (
+  elementKey: string | readonly string[],
+  hidden: boolean,
+) => Promise<void> | void;
+
 export function resolveTimelineSelectionSeekTime(
   currentTime: number,
   element: Pick<TimelineElement, "start" | "duration"> | null | undefined,

package/src/utils/studioSaveDiagnostics.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import {
+  StudioFileConflictError,
   StudioSaveHttpError,
   StudioSaveNetworkError,
   buildStudioSaveFailureProperties,
@@ -8,6 +9,23 @@ import {
 } from "./studioSaveDiagnostics";
 
 describe("studio save diagnostics", () => {
+  it("preserves conflict versions and both sides for explicit recovery UI", () => {
+    const error = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: '"sha256:new"',
+      currentContent: "external",
+      attemptedContent: "local",
+    });
+
+    expect(getStudioSaveStatusCode(error)).toBe(409);
+    expect(error).toMatchObject({
+      filePath: "index.html",
+      currentVersion: '"sha256:new"',
+      currentContent: "external",
+      attemptedContent: "local",
+    });
+  });
+
   it("builds save_failure properties with stable diagnostics", () => {
     const error = new StudioSaveHttpError("Failed to save index.html (503)", 503);
 

package/src/utils/studioSaveDiagnostics.ts

@@ -35,6 +35,27 @@ export class StudioSaveNetworkError extends Error {
   }
 }
 
+export class StudioFileConflictError extends StudioSaveHttpError {
+  readonly filePath: string;
+  readonly currentVersion: string | null;
+  readonly currentContent: string | null;
+  readonly attemptedContent: string;
+
+  constructor(input: {
+    filePath: string;
+    currentVersion: string | null;
+    currentContent: string | null;
+    attemptedContent: string;
+  }) {
+    super(`Save conflict: ${input.filePath} changed outside this Studio session`, 409);
+    this.name = "StudioFileConflictError";
+    this.filePath = input.filePath;
+    this.currentVersion = input.currentVersion;
+    this.currentContent = input.currentContent;
+    this.attemptedContent = input.attemptedContent;
+  }
+}
+
 function readNumericProperty(value: object, key: string): number | undefined {
   const record = value as Record<string, unknown>;
   const property = record[key];
@@ -71,6 +92,23 @@ export function getStudioSaveErrorMessage(error: unknown): string {
   return "Unknown save failure";
 }
 
+export function markStudioSaveErrorAlreadyToasted<T>(error: T): T {
+  if (!error || typeof error !== "object") return error;
+  try {
+    Object.defineProperty(error, "alreadyToasted", { value: true, configurable: true });
+  } catch {
+    // Best effort: failure reporting must not replace the original save error.
+  }
+  return error;
+}
+
+export function isStudioSaveErrorAlreadyToasted(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  if ((error as { alreadyToasted?: unknown }).alreadyToasted === true) return true;
+  const cause = (error as { cause?: unknown }).cause;
+  return cause !== error && isStudioSaveErrorAlreadyToasted(cause);
+}
+
 export function getStudioSaveStatusCode(error: unknown): number | undefined {
   if (!error || typeof error !== "object") return undefined;
   const direct =