@hyperframes/studio 0.8.33 → 0.8.34

package/src/player/components/timelineDragDrop.test.tsx

@@ -2,7 +2,7 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { TIMELINE_ASSET_MIME, TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
 import { usePlayerStore } from "../store/playerStore";
 import { createTimelineRowGeometry } from "./timelineLayout";
@@ -37,9 +37,9 @@ function assetTransfer(payload: string): DropTransfer {
 }
 
 function renderHarness(
-  onAssetDrop: ReturnType<typeof vi.fn>,
+  onAssetDrop: Mock,
   sessionEpoch = 1,
-  options: { onBlockDrop?: ReturnType<typeof vi.fn>; strict?: boolean } = {},
+  options: { onBlockDrop?: Mock; strict?: boolean } = {},
 ) {
   const tracks = Array.from({ length: 100 }, (_, index) => index);
   const geometry = createTimelineRowGeometry(

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -87,6 +87,42 @@ describe("scrubPreviewAudio", () => {
     expect(audio.volume).toBeCloseTo(0.1);
     stopScrubPreviewAudio();
   });
+
+  /**
+   * The preview document is a different realm, so `instanceof HTMLAudioElement`
+   * is false for every node in it. That threw the `musicId` hint away and left
+   * the first `<audio>` in the document as the only route — and the first
+   * `<audio>` is often the voiceover, so scrubbing previewed the wrong track.
+   * Two elements, music second, is what tells the two paths apart: with one
+   * element the fallback reaches the right node by accident.
+   */
+  it("previews the track named by musicId, not the first audio in the document", () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const previewDoc = iframe.contentDocument;
+    if (!previewDoc?.body) throw new Error("expected an iframe document");
+
+    const voiceover = previewDoc.createElement("audio");
+    voiceover.id = "voiceover";
+    voiceover.play = vi.fn(async () => {});
+    voiceover.pause = vi.fn();
+
+    const music = previewDoc.createElement("audio");
+    music.id = "music-bed";
+    music.play = vi.fn(async () => {});
+    music.pause = vi.fn();
+
+    previewDoc.body.append(voiceover, music);
+
+    // The node really is cross-realm; this is the condition, not a contrivance.
+    expect(music instanceof HTMLAudioElement).toBe(false);
+
+    scrubPreviewAudio(iframe, 0.5, "music-bed", 1);
+
+    expect(music.play).toHaveBeenCalled();
+    expect(voiceover.play).not.toHaveBeenCalled();
+    stopScrubPreviewAudio();
+  });
 });
 
 describe("applyPreviewAudioFlags", () => {

package/src/player/lib/timelineIframeHelpers.ts

@@ -218,10 +218,26 @@ let scrubPrevVolume: number | null = null;
 // Resolve the SAME element the store identified as music: prefer its id, then
 // the role attribute, and only fall back to the first <audio> (which could be a
 // voiceover, so the id hint matters).
+/**
+ * `doc` is the preview iframe's document, so its `<audio>` nodes are instances of
+ * the IFRAME's `HTMLAudioElement`, never this module's. `instanceof
+ * HTMLAudioElement` here is false for every one of them, which silently threw the
+ * `musicId` hint away and fell through to "first `<audio>` in the document" — the
+ * very thing the comment above warns can be a voiceover. Ask what the node IS.
+ * Same rule and same reasoning as packages/core/src/runtime/domRealm.ts.
+ */
+function isAudioNode(node: Element | null): node is HTMLAudioElement {
+  return (
+    node !== null &&
+    node.namespaceURI === "http://www.w3.org/1999/xhtml" &&
+    node.localName === "audio"
+  );
+}
+
 function resolveScrubAudioEl(doc: Document, musicId?: string | null): HTMLAudioElement | null {
   if (musicId) {
     const byId = doc.getElementById(musicId);
-    if (byId instanceof HTMLAudioElement) return byId;
+    if (isAudioNode(byId)) return byId;
   }
   return (
     doc.querySelector<HTMLAudioElement>("audio[data-timeline-role='music']") ??

package/src/test-setup.ts

@@ -4,3 +4,11 @@ if (typeof globalThis.CSS === "undefined") {
 if (typeof CSS.escape !== "function") {
   CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
 }
+
+// happy-dom does not implement `window.confirm`. Vitest 3 let `vi.spyOn` invent
+// a missing property; Vitest 4 refuses with "can only spy on a function", so the
+// environment has to supply a real one for the guard tests to replace. Declining
+// is the safe default: no test calls it without stubbing a return value first.
+if (typeof globalThis.confirm !== "function") {
+  (globalThis as Record<string, unknown>).confirm = () => false;
+}

package/src/utils/blockInstaller.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "./projectRouting";
 import type { RegistryItem } from "@hyperframes/core/registry";
 import type { TimelineElement } from "../player";
 import {
@@ -64,7 +65,7 @@ async function installRegistryItem({
   block: RegistryItem;
   compositionFile: string;
 } | null> {
-  const response = await fetch(`/api/projects/${projectId}/registry/install`, {
+  const response = await fetch(buildProjectApiPath(projectId, `/registry/install`), {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ blockName }),

package/src/utils/projectRouting.test.ts

@@ -9,6 +9,15 @@ import {
 } from "./projectRouting";
 
 describe("project routing utilities", () => {
+  it.each(["C:", "C:demo", ".", "..", "../sessions", "a/b", "a\\b", "a\u0000b", "a\nb"])(
+    "rejects unsafe decoded project IDs: %s",
+    (id) => {
+      expect(parseProjectIdFromHash(`#project/${encodeURIComponent(id)}`)).toBeNull();
+      expect(() => buildProjectApiPath(id, "/files/index.html")).toThrow("Invalid project ID");
+      expect(() => buildProjectHash(id)).toThrow("Invalid project ID");
+    },
+  );
+
   it("decodes project ids from hash routes before building capture URLs", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-05-01T12:00:00Z"));

package/src/utils/projectRouting.ts

@@ -5,6 +5,19 @@ export interface ProjectHashRoute {
   params: URLSearchParams;
 }
 
+/** Project names are single path segments, including when received from a hash or server. */
+export function isValidProjectId(value: string): boolean {
+  return (
+    value.length > 0 &&
+    value !== "." &&
+    value !== ".." &&
+    !value.includes(":") &&
+    !value.includes("/") &&
+    !value.includes("\\") &&
+    !Array.from(value).some((char) => char.charCodeAt(0) < 32)
+  );
+}
+
 function decodeHashProjectId(value: string): string {
   try {
     return decodeURIComponent(value);
@@ -28,6 +41,7 @@ function normalizeHashParams(
 }
 
 export function encodeProjectId(projectId: string): string {
+  if (!isValidProjectId(projectId)) throw new Error("Invalid project ID");
   return encodeURIComponent(projectId);
 }
 
@@ -47,9 +61,12 @@ export function parseProjectHashRoute(hash: string): ProjectHashRoute | null {
   const encodedProjectId = queryIndex >= 0 ? route.slice(0, queryIndex) : route;
   if (!encodedProjectId || encodedProjectId.includes("/")) return null;
 
+  const projectId = decodeHashProjectId(encodedProjectId);
+  if (!isValidProjectId(projectId)) return null;
+
   const rawParams = queryIndex >= 0 ? route.slice(queryIndex + 1) : "";
   return {
-    projectId: decodeHashProjectId(encodedProjectId),
+    projectId,
     params: new URLSearchParams(rawParams),
   };
 }

package/src/utils/razorSplitTransaction.test.ts

@@ -103,7 +103,7 @@ describe("runAtomicCutTransaction", () => {
     const synchronize = vi.fn();
 
     const result = await runAtomicCutTransaction({
-      projectId: "launch/demo",
+      projectId: "launch#demo",
       intents: buildAtomicCutIntents([element()], 2, "index.html"),
       label: "Split timeline clip",
       writeProjectFile,
@@ -114,8 +114,8 @@ describe("runAtomicCutTransaction", () => {
 
     expect(requests.filter((request) => request.url.includes("split-batch"))).toHaveLength(1);
     expect(requests.map((request) => request.url)).toEqual([
-      "/api/projects/launch%2Fdemo/files/index.html",
-      "/api/projects/launch%2Fdemo/file-mutations/split-batch",
+      "/api/projects/launch%23demo/files/index.html",
+      "/api/projects/launch%23demo/file-mutations/split-batch",
     ]);
     const splitRequest = requests.find((request) => request.url.includes("split-batch"));
     const writeToken = new Headers(splitRequest?.headers).get("X-Hyperframes-Write-Token");

package/src/utils/sourceScopedSelectorIndex.test.ts

@@ -0,0 +1,148 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { getSourceScopedSelectorIndex, withSelectorIndexPass } from "./sourceScopedSelectorIndex";
+
+// The per-element algorithm this helper used before it grew a per-pass index,
+// transcribed verbatim. It is the independent source the memoized results are
+// checked against — including the misses, which are `indexOf` returning -1.
+function referenceIndex(
+  doc: Document,
+  el: Element,
+  selector: string | undefined,
+  sourceFile: string | undefined,
+  resolveSourceFile: (candidate: Element) => string | undefined,
+): number | undefined {
+  if (!selector || selector.startsWith("#") || selector.startsWith("[data-composition-id=")) {
+    return undefined;
+  }
+  try {
+    const scope = sourceFile ?? "index.html";
+    const matches = Array.from(doc.querySelectorAll(selector)).filter(
+      (candidate) => (resolveSourceFile(candidate) ?? "index.html") === scope,
+    );
+    const matchIndex = matches.indexOf(el);
+    return matchIndex >= 0 ? matchIndex : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const bySourceFile = (candidate: Element): string | undefined =>
+  candidate.closest("[data-composition-file]")?.getAttribute("data-composition-file") ?? undefined;
+
+// Two source files sharing one class, plus an unscoped element, is the case
+// source-file scoping exists for: raw document order would number these 0..4.
+function mixedSourceDocument(): Document {
+  const doc = document.implementation.createHTMLDocument("mixed");
+  doc.body.innerHTML = `
+    <div data-composition-id="root">
+      <section data-composition-file="a.html">
+        <p class="box" id="a0">a0</p>
+        <p class="box" id="a1">a1</p>
+      </section>
+      <section data-composition-file="b.html">
+        <p class="box" id="b0">b0</p>
+        <p class="box" id="b1">b1</p>
+      </section>
+      <p class="box" id="root0">root0</p>
+    </div>
+  `;
+  return doc;
+}
+
+describe("getSourceScopedSelectorIndex", () => {
+  it("numbers occurrences within each source file, not across the flattened document", () => {
+    const doc = mixedSourceDocument();
+    const read = (id: string, sourceFile: string | undefined) =>
+      getSourceScopedSelectorIndex(doc, doc.getElementById(id)!, ".box", sourceFile, bySourceFile);
+
+    expect(read("a0", "a.html")).toBe(0);
+    expect(read("a1", "a.html")).toBe(1);
+    expect(read("b0", "b.html")).toBe(0);
+    expect(read("b1", "b.html")).toBe(1);
+    expect(read("root0", undefined)).toBe(0);
+    // Asking for an element under the wrong scope is a miss, not a neighbour's index.
+    expect(read("b0", "a.html")).toBeUndefined();
+  });
+
+  it("matches the per-element reference for every element, inside a pass and outside it", () => {
+    const doc = mixedSourceDocument();
+    const boxes = Array.from(doc.querySelectorAll(".box"));
+    const scopes = [undefined, "index.html", "a.html", "b.html", "missing.html"];
+    const cases = boxes.flatMap((el) => scopes.map((scope) => ({ el, scope })));
+
+    const expected = cases.map(({ el, scope }) =>
+      referenceIndex(doc, el, ".box", scope, bySourceFile),
+    );
+
+    const outsidePass = cases.map(({ el, scope }) =>
+      getSourceScopedSelectorIndex(doc, el, ".box", scope, bySourceFile),
+    );
+    const insidePass = withSelectorIndexPass(doc, () =>
+      cases.map(({ el, scope }) =>
+        getSourceScopedSelectorIndex(doc, el, ".box", scope, bySourceFile),
+      ),
+    );
+
+    expect(outsidePass).toEqual(expected);
+    expect(insidePass).toEqual(expected);
+  });
+
+  it("returns undefined for the selectors that carry their own identity", () => {
+    const doc = mixedSourceDocument();
+    const el = doc.getElementById("a0")!;
+    for (const selector of [undefined, "#a0", '[data-composition-id="root"]']) {
+      expect(
+        getSourceScopedSelectorIndex(doc, el, selector, "a.html", bySourceFile),
+      ).toBeUndefined();
+      expect(
+        withSelectorIndexPass(doc, () =>
+          getSourceScopedSelectorIndex(doc, el, selector, "a.html", bySourceFile),
+        ),
+      ).toBeUndefined();
+    }
+  });
+
+  it("returns undefined for an invalid selector rather than throwing", () => {
+    const doc = mixedSourceDocument();
+    const el = doc.getElementById("a0")!;
+    expect(getSourceScopedSelectorIndex(doc, el, ".((", "a.html", bySourceFile)).toBeUndefined();
+    expect(
+      withSelectorIndexPass(doc, () =>
+        getSourceScopedSelectorIndex(doc, el, ".((", "a.html", bySourceFile),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("does not reuse one document's index for another, and restores the outer pass", () => {
+    const inner = mixedSourceDocument();
+    const outer = mixedSourceDocument();
+    // A nested pass over a different document must not answer from, or poison,
+    // the outer document's index.
+    const nested = withSelectorIndexPass(outer, () =>
+      withSelectorIndexPass(inner, () =>
+        getSourceScopedSelectorIndex(
+          inner,
+          inner.getElementById("b1")!,
+          ".box",
+          "b.html",
+          bySourceFile,
+        ),
+      ),
+    );
+    expect(nested).toBe(1);
+
+    const afterNested = withSelectorIndexPass(outer, () => {
+      withSelectorIndexPass(inner, () => undefined);
+      return getSourceScopedSelectorIndex(
+        outer,
+        outer.getElementById("a1")!,
+        ".box",
+        "a.html",
+        bySourceFile,
+      );
+    });
+    expect(afterNested).toBe(1);
+  });
+});

package/src/utils/sourceScopedSelectorIndex.ts

@@ -5,6 +5,60 @@
  * `querySelectorAll` index is not a stable source-file identity. Callers supply
  * their existing source resolver; this helper alone owns occurrence scoping.
  */
+
+/** Every element matching one selector, mapped to the source file it belongs to
+ *  and its occurrence index within that file. One document query fills it. */
+type SelectorOccurrences = Map<Element, { scope: string; index: number }>;
+
+interface SelectorIndexPass {
+  doc: Document;
+  bySelector: Map<string, SelectorOccurrences>;
+}
+
+let activePass: SelectorIndexPass | null = null;
+
+/**
+ * Share one occurrence index per selector across every
+ * `getSourceScopedSelectorIndex` call made synchronously inside `run`.
+ *
+ * Unshared, each call runs its own whole-document `querySelectorAll(selector)`
+ * and resolves the source file of every match. A rebuild that walks n elements
+ * sharing a selector therefore does n whole-document queries and n² resolver
+ * calls — a composition of repeated cards or tiles is exactly that shape. One
+ * index per selector makes the same pass linear.
+ *
+ * Correctness rests on the pass being ONE synchronous walk of a document that
+ * does not change under it: nothing invalidates the index, so `run` must not
+ * mutate `doc`, and every call inside it must resolve source files the same way
+ * (the resolver may be a fresh closure per call, as long as it answers the
+ * same). Outside a pass the index is per-call, exactly as before.
+ */
+export function withSelectorIndexPass<T>(doc: Document, run: () => T): T {
+  const previous = activePass;
+  activePass = { doc, bySelector: new Map() };
+  try {
+    return run();
+  } finally {
+    activePass = previous;
+  }
+}
+
+function buildOccurrences(
+  doc: Document,
+  selector: string,
+  resolveSourceFile: (candidate: Element) => string | undefined,
+): SelectorOccurrences {
+  const occurrences: SelectorOccurrences = new Map();
+  const counts = new Map<string, number>();
+  for (const candidate of doc.querySelectorAll(selector)) {
+    const scope = resolveSourceFile(candidate) ?? "index.html";
+    const index = counts.get(scope) ?? 0;
+    counts.set(scope, index + 1);
+    occurrences.set(candidate, { scope, index });
+  }
+  return occurrences;
+}
+
 export function getSourceScopedSelectorIndex(
   doc: Document,
   el: Element,
@@ -17,12 +71,16 @@ export function getSourceScopedSelectorIndex(
   }
 
   try {
-    const scope = sourceFile ?? "index.html";
-    const matches = Array.from(doc.querySelectorAll(selector)).filter(
-      (candidate) => (resolveSourceFile(candidate) ?? "index.html") === scope,
-    );
-    const matchIndex = matches.indexOf(el);
-    return matchIndex >= 0 ? matchIndex : undefined;
+    const pass = activePass?.doc === doc ? activePass : null;
+    let occurrences = pass?.bySelector.get(selector);
+    if (!occurrences) {
+      occurrences = buildOccurrences(doc, selector, resolveSourceFile);
+      pass?.bySelector.set(selector, occurrences);
+    }
+    // An element outside the requested scope is not in that scope's occurrence
+    // run at all, which is the `indexOf` miss the filtered form returned before.
+    const hit = occurrences.get(el);
+    return hit && hit.scope === (sourceFile ?? "index.html") ? hit.index : undefined;
   } catch {
     return undefined;
   }

package/src/utils/studioFileHistory.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "./projectRouting";
 import type { MutableRefObject } from "react";
 import type { EditHistoryKind } from "./editHistory";
 import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
@@ -52,7 +53,7 @@ interface SaveProjectFilesWithHistoryInput {
 }
 
 export async function readProjectFileContent(pid: string, path: string): Promise<string> {
-  const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+  const response = await fetch(buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`));
   if (!response.ok) {
     throw await createStudioSaveHttpError(response, `Failed to read ${path}`);
   }

package/src/utils/studioHelpers.test.ts

@@ -165,9 +165,13 @@ describe("resolveDroppedAssetDimensions", () => {
       naturalWidth: 0,
       src: "",
     };
+    // Vitest 4 refuses to `new` an arrow-function mock, and the code under test
+    // constructs the probe with `new Image()`.
     vi.stubGlobal(
       "Image",
-      vi.fn(() => probe),
+      vi.fn(function () {
+        return probe;
+      }),
     );
 
     const result = resolveDroppedAssetDimensions("demo", "assets/hung.png", "image");

package/src/utils/studioHelpers.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "./projectRouting";
 import { isTypingTarget } from "./typingTarget";
 import type { TimelineElement } from "../player/store/playerStore";
 import type { DomEditSelection } from "../components/editor/domEditing";
@@ -306,7 +307,7 @@ export async function resolveDroppedAssetDuration(
 
   const media = document.createElement(kind === "video" ? "video" : "audio");
   media.preload = "metadata";
-  media.src = `/api/projects/${projectId}/preview/${assetPath}`;
+  media.src = buildProjectApiPath(projectId, `/preview/${assetPath}`);
 
   const duration = await new Promise<number>((resolve) => {
     const timeout = window.setTimeout(() => resolve(DEFAULT_TIMELINE_ASSET_DURATION[kind]), 3000);
@@ -343,7 +344,7 @@ export async function resolveDroppedAssetDimensions(
   kind: TimelineAssetKind,
 ): Promise<{ width: number; height: number } | null> {
   if (kind === "audio") return null;
-  const src = `/api/projects/${projectId}/preview/${assetPath}`;
+  const src = buildProjectApiPath(projectId, `/preview/${assetPath}`);
 
   if (kind === "image") {
     return new Promise((resolve) => {

package/src/utils/timelineCompositionInsert.test.ts

@@ -33,7 +33,7 @@ describe("commitTimelineCompositionInsertion", () => {
     const refresh = vi.fn();
 
     await commitTimelineCompositionInsertion({
-      projectId: "launch/demo",
+      projectId: "launch#demo",
       targetPath: "index.html",
       sourcePath: "headline.html",
       start: 4,
@@ -48,8 +48,8 @@ describe("commitTimelineCompositionInsertion", () => {
 
     expect(fetchMock).toHaveBeenCalledTimes(2);
     expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([
-      "/api/projects/launch%2Fdemo/files/index.html",
-      "/api/projects/launch%2Fdemo/file-mutations/insert-composition/index.html",
+      "/api/projects/launch%23demo/files/index.html",
+      "/api/projects/launch%23demo/file-mutations/insert-composition/index.html",
     ]);
     expect(recordEdit).toHaveBeenCalledOnce();
     expect(writeFile).not.toHaveBeenCalled();