@hyperframes/studio 0.8.190 → 0.8.191

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.190",
+  "version": "0.8.191",
   "description": "",
   "repository": {
     "type": "git",
@@ -59,12 +59,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.190",
-    "@hyperframes/parsers": "0.8.190",
-    "@hyperframes/sdk": "0.8.190",
-    "@hyperframes/player": "0.8.190",
-    "@hyperframes/shader-transitions": "0.8.190",
-    "@hyperframes/studio-server": "0.8.190"
+    "@hyperframes/core": "0.8.191",
+    "@hyperframes/parsers": "0.8.191",
+    "@hyperframes/player": "0.8.191",
+    "@hyperframes/shader-transitions": "0.8.191",
+    "@hyperframes/studio-server": "0.8.191",
+    "@hyperframes/sdk": "0.8.191"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.190"
+    "@hyperframes/producer": "0.8.191"
   },
   "peerDependencies": {
     "react": "19",

package/src/captions/parser.dom.test.ts

@@ -0,0 +1,126 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { generateCaptionHtml } from "./generator";
+import { parseCaptionComposition } from "./parser";
+
+const transcript = "We asked what you needed. Forty-seven percent".split(" ").map((text, i) => ({
+  id: `word-${i}`,
+  text,
+  start: i * 0.5,
+  end: i * 0.5 + 0.4,
+}));
+const source = `const TRANSCRIPT = ${JSON.stringify(transcript)};`;
+
+function createCaptionDocument(
+  groupSizes: number[],
+  groupClass = "caption-group",
+  wordClass = "word",
+) {
+  const doc = document.implementation.createHTMLDocument();
+  let offset = 0;
+  for (const size of groupSizes) {
+    const group = doc.createElement("div");
+    group.className = groupClass;
+    for (const word of transcript.slice(offset, offset + size)) {
+      const span = doc.createElement("span");
+      span.className = wordClass;
+      span.textContent = word.text;
+      group.appendChild(span);
+    }
+    doc.body.appendChild(group);
+    offset += size;
+  }
+  return doc;
+}
+
+function importCaptions(doc: Document, captionSource = source) {
+  const model = parseCaptionComposition(doc, window, captionSource, 1920, 1080, 4);
+  expect(model).not.toBeNull();
+  if (!model) throw new Error("Expected a caption model");
+  const groups = model.groupOrder.map((id) =>
+    model.groups.get(id)?.segmentIds.map((segmentId) => model.segments.get(segmentId)?.text),
+  );
+  return { model, groups };
+}
+
+describe("parseCaptionComposition grouping", () => {
+  it.each([{ sizes: [5, 2] }, { sizes: [2, 4, 1] }])(
+    "preserves authored group sizes $sizes",
+    ({ sizes }) => {
+      const { model, groups } = importCaptions(createCaptionDocument(sizes));
+      expect(groups.map((group) => group?.length)).toEqual(sizes);
+      expect(groups.flat()).toEqual(transcript.map((word) => word.text));
+      expect(
+        [...model.segments.values()].map(({ wordId, text, start, end }) => ({
+          id: wordId,
+          text,
+          start,
+          end,
+        })),
+      ).toEqual(transcript);
+      for (const group of model.groups.values()) {
+        expect(group.segmentIds.map((id) => model.segments.get(id)?.groupIndex)).toEqual(
+          group.segmentIds.map((_, index) => index),
+        );
+      }
+    },
+  );
+
+  it.each(["caption-line", "caption-block"])(
+    "supports %s with caption-word spans",
+    (groupClass) => {
+      const { groups } = importCaptions(
+        createCaptionDocument([2, 4, 1], groupClass, "caption-word"),
+      );
+      expect(groups.map((group) => group?.length)).toEqual([2, 4, 1]);
+    },
+  );
+
+  it("does not count nested caption lines as additional groups", () => {
+    const doc = createCaptionDocument([2, 4, 1]);
+    for (const group of doc.querySelectorAll(".caption-group")) {
+      const line = doc.createElement("div");
+      line.className = "caption-line";
+      line.append(...group.childNodes);
+      group.appendChild(line);
+    }
+    expect(importCaptions(doc).groups.map((group) => group?.length)).toEqual([2, 4, 1]);
+  });
+
+  it.each([
+    { name: "absent", sizes: [] },
+    { name: "incomplete", sizes: [2, 1] },
+    { name: "empty", sizes: [0, 0] },
+  ])("uses default grouping without losing words when DOM groups are $name", ({ sizes }) => {
+    const { groups } = importCaptions(createCaptionDocument(sizes));
+    expect(groups).toEqual([
+      transcript.slice(0, 5).map((word) => word.text),
+      transcript.slice(5).map((word) => word.text),
+    ]);
+  });
+
+  it("keeps authored boundaries when generated captions are imported again", () => {
+    const original = importCaptions(createCaptionDocument([2, 4, 1]));
+    const html = generateCaptionHtml(original.model);
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = html;
+    const template = doc.querySelector("template");
+    if (!template) throw new Error("Expected generated caption template");
+    doc.body.replaceChildren(template.content.cloneNode(true));
+    const script = doc.querySelector("script")?.textContent;
+    if (!script) throw new Error("Expected generated caption script");
+    // Execute only our generator's output to create its real group and word elements.
+    new Function("document", "window", "gsap", script)(
+      doc,
+      {},
+      {
+        timeline: () => ({ to() {} }),
+      },
+    );
+    expect(importCaptions(doc, html).groups).toEqual([
+      transcript.slice(0, 2).map((word) => word.text),
+      transcript.slice(2, 6).map((word) => word.text),
+      transcript.slice(6).map((word) => word.text),
+    ]);
+  });
+});

package/src/captions/parser.ts

@@ -38,23 +38,32 @@ export function buildCaptionModel(
   transcript: TranscriptWord[],
   options: BuildOptions,
 ): CaptionModel {
-  const { width, height, duration, wordsPerGroup = 5 } = options;
+  const { wordsPerGroup = 5 } = options;
+  const wordGroups: TranscriptWord[][] = [];
+  for (let offset = 0; offset < transcript.length; offset += wordsPerGroup) {
+    wordGroups.push(transcript.slice(offset, offset + wordsPerGroup));
+  }
+  return buildGroupedCaptionModel(wordGroups, options);
+}
 
+function buildGroupedCaptionModel(
+  wordGroups: TranscriptWord[][],
+  { width, height, duration }: BuildOptions,
+): CaptionModel {
   const segments = new Map<string, CaptionSegment>();
   const groups = new Map<string, CaptionGroup>();
   const groupOrder: string[] = [];
 
-  // Chunk the transcript into groups of wordsPerGroup
-  for (let groupIdx = 0; groupIdx < transcript.length; groupIdx += wordsPerGroup) {
-    const chunk = transcript.slice(groupIdx, groupIdx + wordsPerGroup);
-    const groupId = `group-${groupIdx / wordsPerGroup}`;
+  for (const chunk of wordGroups) {
+    const groupId = `group-${groups.size}`;
     const segmentIds: string[] = [];
 
     chunk.forEach((word, wordIdx) => {
-      const segmentId = `segment-${groupIdx + wordIdx}`;
+      const segmentIndex = segments.size;
+      const segmentId = `segment-${segmentIndex}`;
       const segment: CaptionSegment = {
         id: segmentId,
-        wordId: word.id ?? `w${groupIdx + wordIdx}`,
+        wordId: word.id ?? `w${segmentIndex}`,
         text: word.text,
         start: word.start,
         end: word.end,
@@ -96,6 +105,24 @@ export function buildCaptionModel(
   };
 }
 
+const GROUP_SELECTOR = ".caption-group, .caption-line, .caption-block";
+const WORD_SELECTOR = ".word, .caption-word";
+
+/** Read outer groups in transcript order; return null if their word counts do not match. */
+function readTranscriptGroups(transcript: TranscriptWord[], groupEls: NodeListOf<Element>) {
+  const wordGroups: TranscriptWord[][] = [];
+  let offset = 0;
+  for (const group of groupEls) {
+    // Caption templates can nest layout lines inside a single timed group.
+    if (group.parentElement?.closest(GROUP_SELECTOR)) continue;
+    const size = group.querySelectorAll(WORD_SELECTOR).length;
+    if (size === 0) continue;
+    wordGroups.push(transcript.slice(offset, offset + size));
+    offset += size;
+  }
+  return offset === transcript.length ? wordGroups : null;
+}
+
 /**
  * Extracts a transcript word array from caption composition source code.
  *
@@ -130,7 +157,8 @@ export function extractTranscript(source: string): TranscriptWord[] {
  * from the source and reading computed styles from rendered elements.
  *
  * Runs in the Studio (outside the iframe). Reads computed styles from iframe DOM
- * elements to build a fully-styled CaptionModel.
+ * elements to build a fully-styled CaptionModel. Preserves DOM group boundaries
+ * when they account for every transcript word; otherwise uses default grouping.
  *
  * Returns null if no transcript is found in the source.
  */
@@ -149,25 +177,19 @@ export function parseCaptionComposition(
   }
 
   // Step 2: Look for grouping and word elements in the iframe DOM
-  const groupEls = iframeDoc.querySelectorAll(".caption-group, .caption-line, .caption-block");
-  const wordEls = iframeDoc.querySelectorAll(".word, .caption-word");
-
-  // Step 3: Infer wordsPerGroup from element counts
-  let wordsPerGroup = 5; // default
-  if (groupEls.length > 0 && wordEls.length > 0) {
-    wordsPerGroup = Math.round(wordEls.length / groupEls.length);
-    if (wordsPerGroup < 1) {
-      wordsPerGroup = 1;
-    }
-  }
+  const groupEls = iframeDoc.querySelectorAll(GROUP_SELECTOR);
+  const wordEls = iframeDoc.querySelectorAll(WORD_SELECTOR);
 
-  // Step 4: Build the caption model with inferred grouping
-  const model = buildCaptionModel(transcript, {
+  // Preserve authored boundaries when the DOM accounts for the complete transcript.
+  const wordGroups = readTranscriptGroups(transcript, groupEls);
+  const options = {
     width: compositionWidth,
     height: compositionHeight,
     duration: compositionDuration,
-    wordsPerGroup,
-  });
+  };
+  const model = wordGroups
+    ? buildGroupedCaptionModel(wordGroups, options)
+    : buildCaptionModel(transcript, options);
 
   // Step 5: Read computed styles from the first word or group element
   const firstWordEl = wordEls.item(0) as Element | null;

package/src/components/StudioRightPanels.tsx

@@ -8,6 +8,7 @@ import { BlockParamsPanel } from "./editor/BlockParamsPanel";
 import { RenderQueuePanel } from "./renders/RenderQueuePanel";
 import { SlideshowPanel } from "./panels/SlideshowPanel";
 import { VariablesPanel } from "./panels/VariablesPanel";
+import { MotionBlurPanel } from "./panels/MotionBlurPanel";
 import { Dock } from "./dock/Dock";
 import { useDockLayoutStore } from "./dock/dockLayoutStore";
 import type { RenderJob } from "./renders/useRenderQueue";
@@ -300,6 +301,14 @@ export const StudioRightPanels = memo(function StudioRightPanels({
           recordEdit={recordEdit}
         />
       </Dock.Panel>
+      <Dock.Panel id="motionBlur">
+        <MotionBlurPanel
+          sdkSession={sdkSession}
+          publishSdkSession={publishSdkSession}
+          reloadPreview={reloadPreview}
+          recordEdit={recordEdit}
+        />
+      </Dock.Panel>
       <Dock.Panel id="slideshow">
         <SlideshowPanel
           scenes={slideshowScenes}

package/src/components/dock/DockTab.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useSyncExternalStore } from "react";
 import {
+  Aperture,
   BracketsCurly,
   ChartBarHorizontal,
   Code,
@@ -29,6 +30,7 @@ const TAB_ICONS: Record<PanelId, Icon> = {
   renders: FilmSlate,
   variables: BracketsCurly,
   slideshow: Presentation,
+  motionBlur: Aperture,
 };
 
 /**

package/src/components/dock/dockAccessibility.test.ts

@@ -158,9 +158,9 @@ describe("dock tab strips", () => {
   it("jump to the first and last tab with Home and End", () => {
     const tabs = tabsOf("design");
     press(tabs[0] as HTMLElement, "End");
-    expect(api.getPanel("design")?.group.activePanel?.id).toBe("variables");
-    expect(document.activeElement).toBe(tabs[3]);
-    press(tabs[3] as HTMLElement, "Home");
+    expect(api.getPanel("design")?.group.activePanel?.id).toBe("motionBlur");
+    expect(document.activeElement).toBe(tabs[4]);
+    press(tabs[4] as HTMLElement, "Home");
     expect(api.getPanel("design")?.group.activePanel?.id).toBe("design");
   });
 });

package/src/components/dock/dockLayout.ts

@@ -9,7 +9,7 @@ const MIN_SIDE_W = 200;
 const MIN_SIDE_W_FLOOR = 120;
 const DEFAULT_TIMELINE_H = 360;
 const DEFAULT_LEFT = ["compositions", "assets", "code", "catalog"] as const;
-const DEFAULT_RIGHT = ["design", "layers", "renders", "variables"] as const;
+const DEFAULT_RIGHT = ["design", "layers", "renders", "variables", "motionBlur"] as const;
 
 /** Preferred side widths; when they overflow the preview's floor the right yields first, then the left. */
 export function defaultSideWidths(viewportWidth: number) {

package/src/components/dock/panelRegistry.ts

@@ -12,6 +12,7 @@ export const PANEL_IDS = [
   "renders",
   "variables",
   "slideshow",
+  "motionBlur",
 ] as const;
 
 export type PanelId = (typeof PANEL_IDS)[number];
@@ -56,6 +57,11 @@ export const PANEL_DEFINITIONS = {
   renders: { title: "Renders", zone: "right", reopen: { near: "design", direction: "within" } },
   variables: { title: "Variables", zone: "right", reopen: { near: "design", direction: "within" } },
   slideshow: { title: "Slideshow", zone: "right", reopen: { near: "design", direction: "within" } },
+  motionBlur: {
+    title: "Blur",
+    zone: "right",
+    reopen: { near: "design", direction: "within" },
+  },
 } as const satisfies Record<PanelId, PanelDefinition>;
 
 export function isPanelId(value: unknown): value is PanelId {

package/src/components/panels/MotionBlurPanel.test.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import { MotionBlurPanel } from "./MotionBlurPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const page = (attrs = "") =>
+  `<!DOCTYPE html><html><body><div data-composition-id="main" data-hf-root data-duration="5" data-width="1920" data-height="1080"${attrs}></div></body></html>`;
+
+const shell = {
+  activeCompPath: null as string | null,
+  previewIframeRef: { current: null as HTMLIFrameElement | null },
+  showToast: vi.fn(),
+};
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => shell,
+  useStudioPlaybackContext: () => ({ refreshKey: 0 }),
+}));
+
+const files: Record<string, string> = {};
+const writeProjectFile = vi.fn(async (path: string, content: string) => {
+  files[path] = content;
+});
+vi.mock("../../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile: async (path: string) => files[path] ?? "",
+    writeProjectFile,
+    compositions: ["index.html", "scene.html"],
+  }),
+}));
+
+let root: Root | null = null;
+const recordEdit = vi.fn(async () => {});
+
+function cleanup() {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+}
+
+afterEach(() => {
+  cleanup();
+  shell.activeCompPath = null;
+  shell.previewIframeRef.current = null;
+  vi.clearAllMocks();
+});
+
+async function mount(attrs = "") {
+  files["index.html"] = page(attrs);
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  const session = await openComposition(files["index.html"], { history: false });
+  await act(async () => {
+    root?.render(
+      <MotionBlurPanel
+        sdkSession={session}
+        publishSdkSession={vi.fn()}
+        reloadPreview={vi.fn()}
+        recordEdit={recordEdit}
+      />,
+    );
+  });
+  return host;
+}
+
+const settle = () => act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+const click = async (el: Element | null) => {
+  await act(async () => (el as HTMLElement).click());
+  await settle();
+};
+
+const radio = (host: HTMLElement, label: string) =>
+  [...host.querySelectorAll('[role="radio"]')].find((el) => el.textContent === label) ?? null;
+const checked = (host: HTMLElement) =>
+  [...host.querySelectorAll('[role="radio"]')]
+    .filter((el) => el.getAttribute("aria-checked") === "true")
+    .map((el) => el.textContent);
+
+describe("MotionBlurPanel", () => {
+  it("offers Off, Subtle and Strong and nothing else", async () => {
+    const host = await mount();
+    expect([...host.querySelectorAll('[role="radio"]')].map((el) => el.textContent)).toEqual([
+      "Off",
+      "Subtle",
+      "Strong",
+    ]);
+    expect(
+      host.querySelectorAll('[role="slider"], [role="switch"], [role="combobox"], input'),
+    ).toHaveLength(0);
+  });
+
+  it("shows the level the root is at", async () => {
+    expect(checked(await mount())).toEqual(["Off"]);
+    cleanup();
+    expect(checked(await mount(' data-motion-blur="on"'))).toEqual(["Subtle"]);
+    cleanup();
+    expect(
+      checked(
+        await mount(
+          ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"',
+        ),
+      ),
+    ).toEqual(["Strong"]);
+  });
+
+  it("Subtle writes data-motion-blur and leaves the default shutter off the root", async () => {
+    const host = await mount(
+      ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"',
+    );
+    await click(radio(host, "Subtle"));
+    const html = files["index.html"] ?? "";
+    expect(html).toContain('data-motion-blur="on"');
+    expect(html).not.toContain("data-motion-blur-shutter");
+    expect(html).not.toContain("data-motion-blur-samples");
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it("Strong writes the maximum shutter and samples", async () => {
+    const host = await mount();
+    await click(radio(host, "Strong"));
+    const html = files["index.html"] ?? "";
+    expect(html).toContain('data-motion-blur="on"');
+    expect(html).toContain('data-motion-blur-shutter="720"');
+    expect(html).toContain('data-motion-blur-samples="64"');
+  });
+
+  it("Off removes data-motion-blur and leaves every other setting on the root", async () => {
+    const host = await mount(
+      ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64" data-motion-blur-tier="filter" data-motion-blur-events="on"',
+    );
+    await click(radio(host, "Off"));
+    const html = files["index.html"] ?? "";
+    expect(html).not.toContain('data-motion-blur="on"');
+    for (const kept of ['shutter="720"', 'samples="64"', 'tier="filter"', 'events="on"']) {
+      expect(html).toContain(`data-motion-blur-${kept}`);
+    }
+  });
+
+  it("writes nothing when the chosen level is already set", async () => {
+    const host = await mount(' data-motion-blur="on"');
+    await click(radio(host, "Subtle"));
+    expect(writeProjectFile).not.toHaveBeenCalled();
+  });
+
+  it("follows the live preview over the session, so an undo or an outside edit shows", async () => {
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-motion-blur="on" data-motion-blur-shutter="720"></div>';
+    shell.previewIframeRef.current = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    expect(checked(await mount(' data-motion-blur="on"'))).toEqual(["Strong"]);
+  });
+
+  it("writes the level picked even when the preview and the file disagree", async () => {
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64"></div>';
+    shell.previewIframeRef.current = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    const host = await mount();
+    await click(radio(host, "Subtle"));
+    expect(files["index.html"]).toContain('data-motion-blur="on"');
+    expect(files["index.html"]).not.toContain("data-motion-blur-samples");
+  });
+
+  it("is read-only for a sub-composition, which blur does not read", async () => {
+    shell.activeCompPath = "scene.html";
+    const host = await mount();
+    expect(host.textContent).toContain("read from the main composition");
+    expect(radio(host, "Strong")?.hasAttribute("disabled")).toBe(true);
+    expect(checked(host)).toEqual([]);
+  });
+});